Skip to content

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

USB-C DisplayPort alt mode — MacBook Pro 13" M1 (j293) on Asahi

Enables external display output over USB-C by turning on dcpext (the SoC's second display controller) and binding it to the Type-C PHY of the front-left port.

Port: the LOWER USB-C connector on the left edge — of the two, the one further from the hinge. It is the only one with DisplayPort wired up. The device tree calls it USB-C Left-front (usb-pd@3f); "front" is relative between the two, not relative to the laptop. Check it without guessing: ./whichport.sh.

Validated on one machine only. See ENVIRONMENT.md for the exact hardware, kernel and firmware versions, and REPLICATION.md for what to check before assuming it transfers to yours. Current status, including one unresolved bug, is in STATUS.md.


The core of the problem

Almost all of the M1 DP alt mode support is already merged in Asahi 7.1.6. The PHY does DP mode, the display crossbar is wired, drm/apple accepts a second coprocessor, and the cd321x driver already registers port altmodes, switches the mux and reads DP status. Nothing obvious is missing.

And yet nothing happens when you plug a monitor in. The reason is that the chain from "a display was plugged in" to "DRM lights it up" is broken in three separate places, and every one of them fails silently — no error, no warning, nothing in dmesg. That silence is the whole difficulty: each break looks exactly like the one before it from userspace.

Here is the chain, with the breaks marked:

  monitor plugged in
        |
        v
  cd321x firmware negotiates DP alt mode by itself      <- works, always did
        |                                                  (DP_CONNECTION|HPD_LEVEL, pinout C)
        v
  crossbar switches the PHY to the display controller   <- works
        |                                                  ("Switched dpphy to dispext0,0")
        v
  [BREAK 3] the driver never tells DRM about the HPD    <- kmod/
        |
        v
  drm_connector_oob_hotplug_event()
        |
        v
  [BREAK 2] no connector matches the fwnode, event dropped   <- displayport = <&dcpext>
        |
        v
  apple_connector_oob_hotplug() -> dcp_dptx_connect_oob()
        |
        v
  [BREAK 1] there is no dcpext to connect to           <- the DTS overlay
        |
        v
  display lights up

Break 1 — the second display controller is switched off. The M1 has two display controllers. The internal panel uses dcp; external DP needs dcpext, and no t8103 device tree enables it, not even in asahi-wip-7.2. Without it there is no DRM connector for an external display to appear on at all.

Break 2 — the hotplug event has nowhere to land. With dcpext enabled the event is now generated, but dp_altmode_probe() resolves the target DRM connector through the displayport property on the USB-C connector node. That property does not exist, so the code falls through to its "embedded DP" path and keeps the fwnode of the USB-C connector itself — while apple_drv.c registered the DRM connector under the fwnode of the dcp node. drm_connector_find_by_fwnode() matches nothing and the event is discarded without a word. This one costs the most time to find, because everything upstream of it looks perfect.

Break 3 — nobody sends the event in the first place. This is the counter-intuitive one. typec_displayport, the generic driver that would normally forward the HPD, never binds: it needs a partner altmode, and it drives a state machine expecting Enter → Status Update → Configure. On this hardware Apple's firmware enters alt mode on its own, so that VDM exchange never happens and the handshake never even starts. The first attempt at this project went down that road and it is a dead end — the analysis is kept in kmod/attic/. The controller does know about the HPD; it sits in two bits of its own data_status register, and nothing reads them out to DRM.

There is a fourth problem that only appears once the first three are fixed and you unplug the cable: iomfb_poweroff() waits 50 ms for a "clear swap" reply and, on timeout, sets dcp->crashed = true silently. From then on every atomic commit is rejected with -EINVAL, permanently — the external display never comes back until you reboot. The DCP has not actually crashed; it keeps renegotiating the link and publishing modes perfectly well. This one is not fixed upstream either, in any branch.


How it was hacked

The important practical point: the kernel is never rebuilt. A full Asahi kernel build to change 21 lines is not a reasonable ask of anyone testing this. Instead each break is closed at the cheapest layer that can close it:

Break Fixed by Cost to apply
1 — dcpext off Device tree overlay appended to the DTS and compiled into a DTB sudo ./install.sh + reboot
2 — event dropped One property, displayport = <&dcpext>, in the same overlay (same)
3 — HPD not forwarded 21-line backport, rebuilt as an out-of-tree module ./kmod/build.sh
4 — DCP latched crashed 17-line fix, rebuilt as an out-of-tree module ./kmod-drm/install.sh

Two tricks make that possible:

Getting a patched device tree into the boot chain without touching m1n1. update-m1n1 builds boot.bin by concatenating m1n1 with a set of DTBs, and it sources /etc/default/update-m1n1 before it picks the default DTB path. So writing one line there —

DTBS="/usr/local/lib/dpalt-dtbs/*.dtb"

— redirects it at a directory of patched DTBs. m1n1, U-Boot and the kernel stay completely stock, boot.bin regenerates correctly on its own after a package update, and sudo ./revert.sh undoes the whole thing by deleting one file.

Rebuilding single modules instead of the kernel. Both changed files (drivers/usb/typec/tipd/core.c and drivers/gpu/drm/apple/iomfb_template.c) belong to modules, and the symbol the fix needs — drm_connector_oob_hotplug_event — already lives in vmlinux because DRM is built in. So the modules can be compiled out of tree against the installed headers, gaining no new dependencies, and swapped in with insmod for a live test that writes nothing to disk and is undone by a reboot.

The result is a change that a reviewer can apply, verify and completely reverse in a few minutes, without a single kernel compile.

What is upstreamable and what is not

Being honest about this, because the three pieces are not equal:

  • The tipd HPD forwarding is not ours. It is Janne Grunau's and Sven Peter's work on the fairydust branch, backported unchanged. After applying it, the files are byte-for-byte identical to fairydust's — deliberately, so there is nothing to reconcile when it lands.
  • The appledrm poweroff fix is original and is the one genuinely new finding here. It is prepared as a proper git-format patch in kmod-drm/upstream/.
  • The device tree overlay is the actual hack and is not upstreamable as-is. Asahi marks DP alt mode on M1 as WIP; when it lands officially the right move is sudo ./revert.sh and dropping this repository entirely.

Check it yourself before trusting any of it

Two things are worth running before reading further.

The offline test suite — no root, no hardware, no Apple machine required. It covers the port-resolution logic (including the case where sysfs renumbers the ports between boots, which really happens), the install/uninstall paths, and the backup handling:

./test/run.sh          # 64 checks

The environment report — run it on your own machine and diff it against the one recorded here. The rows that differ are exactly the ones that decide whether any of this transfers:

./collect-env.sh > /tmp/mine.md
diff ENVIRONMENT.md /tmp/mine.md

Every script in this repository is written to be run in this order and to refuse to do anything dangerous out of order: install.sh will not install a DTB whose stock base does not match the running kernel, hotswap.sh swap writes nothing to disk, and verify.sh needs no root at all. See REPLICATION.md for the ten checkpoints and what each one proves.


Usage

./status.sh                 # what state you are in
sudo ./install.sh           # apply (rewrites boot.bin, backs it up first)
# reboot
./verify.sh                 # did it work?
sudo ./dpdiag.sh start      # fine-grained trace of the USB-C negotiation

./whichport.sh              # which USB-C is the cable in? is it the right one?

sudo ./kmod/hotswap.sh swap # 2nd piece: patched tps6598x module (see below)
sudo ./kmod/hotswap.sh status
sudo ./kmod/hotswap.sh install    # make it permanent (regenerates the initramfs)
sudo ./kmod/hotswap.sh uninstall  # back to the stock module

sudo ./revert.sh            # undo the device tree
./rebuild.sh                # regenerate the DTB after a kernel update

Both pieces are required: the device tree (install.sh) and the patched tps6598x-core module (kmod/). With only the first, the DP link comes up at the hardware level but no image ever appears.

None of these scripts touch ~/.config or any Omarchy configuration.


What it actually does

DP alt mode support for the M1 is already complete in the Asahi 7.1.6 kernel. This was checked driver by driver against Janne Grunau's dcp/dp-alt-6.12.8 branch:

Piece State in 7.1.6
phy-apple-atc: DP mode + lpdptx registers already merged
mux-apple-display-crossbar for t8103 already merged and wired
drm/apple: MAX_COPROCESSORS 3 already merged
drm/apple: treat phys as dcpext already merged
tipd/cd321x: port altmodes (cd321x_register_port_altmodes) already merged
tipd/cd321x: mux switching (cd321x_typec_update_mode) already merged
tipd/cd321x: reading DP_SID status already merged
tipd/cd321x: forwarding HPD to DRM (drm_connector_oob_hotplug_event) missing — see kmod/
DTS: enable dcpext and bind it to atcphy1 missing — this is the patch
DTS: displayport = <&dcpext> on the typec1 connector missing — without it there is no connector_fwnode

Apple's firmware enters alt mode on its own, so there is no VDM exchange to take the HPD from. That is why typec_displayport plays no part here: its state machine expects an Enter → Status Update → Configure that never happens on this hardware. (That was the first attempt, and it is documented in kmod/attic/.)

Upstream solves this on the fairydust branch of AsahiLinux/linux by reading the two HPD bits out of the controller's own data_status and calling drm_connector_oob_hotplug_event() on the fwnode of the connector's displayport phandle:

#define CD321X_DATA_STATUS_HPD_IRQ   BIT(14)
#define CD321X_DATA_STATUS_HPD_LEVEL BIT(15)

typec_partner_register_altmode() is not used at all. The tipd sources in 7.1.6 are identical to fairydust's except for those 21 lines, so kmod/fairydust-hpd.diff is a straight backport; after applying it, core.c and tps6598x.h are byte-for-byte identical to fairydust's.

There is no need to rebuild the whole kernel: replacing the device tree and rebuilding a single module (tps6598x-core) out of tree is enough.

Note: drm_connector_oob_hotplug_event lives in vmlinux (DRM is built into the kernel), so the module gains no new dependencies.

The patch (patch/dp-altmode-t8103.dtsi.append) adds:

  • the dcpext alias — this is the load-bearing part: m1n1 keys off that alias to inject apple,firmware-compat (without it the driver aborts with -ENODEV) and to reserve the dcpext_reserved_regions_t8103 memory carveouts
  • dcpext: status okay, apple,connector-type = "DP", apple,dptx-phy = <1>, phys = <&atcphy1 PHY_TYPE_DP>, mux-controls = <&atcphy1_xbar 0>
  • enables dispext0_dart, dcpext_dart, dcpext_mbox, dpaudio1
  • adds dispext0_dart to the display-subsystem's iommus

Why displayport = <&dcpext> is required

This is the property that links the USB-C connector to the DRM connector, and without it video never comes up even when everything else works. The HPD chain is:

cd321x (firmware negotiates DP)
  -> displayport.c: dp_altmode_probe() resolves connector_fwnode
  -> drm_connector_oob_hotplug_event()
  -> apple_connector_oob_hotplug()  [apple_drv.c]
  -> dcp_dptx_connect_oob()         <- the only thing that lights up external DP

dp_altmode_probe() takes connector_fwnode from the connector node's displayport property. If it is absent, it falls through to the "embedded DP" path and keeps the fwnode of the USB-C connector itself, while apple_drv.c registered the drm_connector with the fwnode of the dcp node. drm_connector_find_by_fwnode() then finds nothing and the event is dropped silently.

Exact symptom: the firmware negotiates correctly (cd321x_data_status: DATA_CONNECTION|USB2_CONNECTION|DP_CONNECTION|HPD_LEVEL, DP pinout C), the crossbar switches (Switched dpphy to dispext0,0), but DP-1 stays disconnected and the printk in apple_connector_oob_hotplug never appears in the log. Use ./dpdiag.sh to watch this.

Note: with pinout C all four lanes go to DisplayPort, so the monitor's USB drops to 2.0 and SuperSpeed disappears. That is expected, not a bad cable.

This is a backport of jannau's 1fc720de plus the dd1b0cc and c88c9f3 fixups (kept in patch/ for reference), adapted: the half that touched t8103.dtsi is already merged in 7.1.6.

Second piece: the tps6598x-core module (kmod/)

Apple's PD controller (cd321x) negotiates DP alt mode in firmware; the driver only reads the Data Status register. 7.1.6 already registers the port altmodes, switches the mux and reads DP_SID status. The one thing nobody does is tell DRM a display is there, and without that notification dcpext never starts.

kmod/fairydust-hpd.diff adds exactly that: 21 lines backported from the fairydust branch of AsahiLinux/linux. The HPD comes from two bits of the controller's own data_status and is forwarded with drm_connector_oob_hotplug_event() on the fwnode of the connector's displayport phandle.

After applying it, kmod/build/core.c and kmod/build/tps6598x.h are byte-for-byte identical to fairydust's. That identity is deliberate: it is not worth diverging from upstream here.

Quick check of which module you have loaded:

# On disk: the patched one imports the DRM symbol, the stock one never touches DRM.
nm -u "$(modinfo -n tps6598x_core)" | grep drm_connector_oob_hotplug_event

# At runtime: the patch adds no global symbols, so kallsyms is no help.
# Per-module taint is: 'O' = out-of-tree = built by this repo.
cat /sys/module/tps6598x_core/taint

# And to tell "from the package" from "ours", the intree marker (the file must
# end in .ko or modinfo rejects it):
modinfo -F intree "$(modinfo -n tps6598x_core)"   # Y = from the package

Testing it without touching the disk

sudo ./kmod/hotswap.sh swap      # unloads the original and inserts the patched one
# unplug the USB-C cable, wait 3 s, plug it back in
sudo ./kmod/hotswap.sh status    # what happened

swap writes nothing: a reboot brings the usual module back. There is also restore to revert live. Unloading the module cuts USB-C for a few seconds and interrupts charging, so do it with enough battery.

Limits of the hot-swap. It is good for checking that the module loads and that the HPD path fires, but not for judging whether there is an image. On reloading tps6598x the xhci controller sometimes fails to come up:

xhci-hcd xhci-hcd.2.auto: can't setup: -110

With that, the link renegotiates into a degraded state (usb_mode=usb3, no DP) and the crossbar no longer switches. verify.sh detects that -110 and warns that the reading is inconclusive. For the real test: hotswap.sh install and reboot, which is when the firmware negotiates DP cold.

If it works, sudo ./kmod/hotswap.sh install copies it over the system module (saving the original as <mod>.ko.stock; .orig-<date> from older installs is still read for compatibility). Careful: a kernel update overwrites it and you have to rebuild with ./kmod/build.sh.

Rebuilding it (kmod/build.sh)

./kmod/build.sh          # no sudo; needs linux-asahi-headers

Builds against the running kernel's headers and verifies with nm that the module calls drm_connector_oob_hotplug_event — the patch adds no global symbols, so that import is the only witness — and that vermagic matches the running kernel.

If the kernel changed, it first downloads that version's tipd sources and compares them with kmod/base/ (the stock sources of the version the patch was adapted against). If upstream touched tipd, it warns and asks for confirmation: the right move then is to take the new sources and reapply kmod/fairydust-hpd.diff, which is the complete adaptation in patch form (core.c and tps6598x.h; applied on kmod/build/ with patch -p1).

Success signals, in order (all in dmesg):

  1. #### oob_hotplug status:0x1 #### — the patch notified DRM (0x1 = connected, 0x2 = disconnected)
  2. apple-dcp ...: dcp_dptx_connect(port=0) — the DCP accepts the connection
  3. mode_set_gated(...): 3440x1440@59 Hz link: 1 and set_digital_out_mode finished
  4. card*-DP-1 flips to connected and modes is no longer empty
  5. hyprctl monitors shows the monitor at its real resolution (not 0x0@60)

If you stall at step 3 with 0x0@60 in Hyprland and EINVAL in the aquamarine log, that is the hot-plug bug: see the limitations section.

Historical note: DP_CAP_RECEPTACLE

The first attempt (partner altmode) ran into the typec_dp.h macros, which invert which field they read from depending on the DP_CAP_RECEPTACLE bit. It no longer applies: the current approach registers no partner altmode at all. The full analysis is in kmod/attic/README.md.

Recovery if Linux will not boot

Only the device tree changes; m1n1, U-Boot and the kernel are stock.

From Linux (if it boots)

sudo ~/dp-altmode/revert.sh && sudo reboot

From macOS (if Linux will not boot)

  1. Shut down fully (hold the power button).

  2. Hold the power button until "Loading startup options".

  3. Boot macOS (not the Linux volume).

  4. In Terminal:

    diskutil list                 # look for "EFI - OMARC" (~500 MB), usually disk0s4
    diskutil mount disk0s4
    cd "/Volumes/EFI - OMARC/m1n1"
    ls -l                         # you will see boot.bin.prepatch-YYYYMMDD-HHMMSS
    cp boot.bin.prepatch-<date> boot.bin

    boot.bin.old, which update-m1n1 leaves with the previous version, works too.

  5. Reboot into Linux and run sudo ~/dp-altmode/revert.sh to clean up (otherwise the next update-m1n1 would put the patched one back).


Kernel updates — important

While the patch is installed, update-m1n1 uses DTBs frozen at the version they were generated for. After a kernel update:

./rebuild.sh              # regenerate the DTB for the new kernel (validates the base)
sudo ./install.sh         # put it into boot.bin
./kmod/build.sh           # rebuild the tps6598x-core module
sudo ./kmod/hotswap.sh install

Both pieces: the DTB and the module. A kernel update takes out both.

install.sh refuses to install if the kernel's stock DTB does not match the patch's base, so it cannot slip you a DTB from another version by accident. If you would rather not deal with it, sudo ./revert.sh before updating.


Upstream status

Asahi marks DP Alt Mode on M1 as WIP. No t8103 DTS enables dcpext yet, not even in asahi-wip-7.2. When it lands officially, run sudo ./revert.sh and drop this workaround.

Known limitations of this route (reported by people using it): a single port with DP, no multiple USB-C displays, and quirks when hot-plugging.


Repository layout

Path Contents
patch/ Device tree overlay and the upstream commits it derives from
kmod/ tps6598x-core HPD backport: .diff, pinned base sources, build and hot-swap scripts
kmod-drm/ appledrm poweroff fix (original finding) and the patch prepared for upstream
validacion/ Hot-plug validation run and the bug 2 capture
captures/ Raw kernel log with DRM debug enabled
test/ Offline test suite — no root, no hardware needed
docs/es/ Original Spanish documents, kept verbatim

Credits and licence

The kernel changes derive from AsahiLinux/linux and are GPL-2.0, like the sources they patch. The tipd HPD backport is Janne Grunau's and Sven Peter's work from the fairydust branch, carried over unchanged; the appledrm poweroff fix is original to this repository and is offered upstream in kmod-drm/upstream/0001-drm-apple-don-t-latch-crashed-on-poweroff-swap-timeout.patch.

The helper scripts in this repository are provided as-is, with no warranty. They rewrite boot.bin on the EFI partition; read the recovery section before running them.

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages