Apple Silicon to Apple Silicon VDM tool

This tool lets you get a serial console on an Apple Silicon device and reboot it remotely, using only another Apple Silicon device running Linux and a standard Type C cable.

Copyright

This is based on macvdmtool without replicating portions of ThunderboltPatcher and licensed under Apache-2.0.

• Copyright (C) 2019 osy86. All rights reserved.
• Copyright (C) 2021 The Asahi Linux Contributors

Thanks to t8012.dev and mrarm for assistance with the VDM and Ace2 host interface commands.

Building

Install Rust cargo and type cargo build.

Usage

Connect the two devices via their DFU ports. That's:

• the rear port on MacBook Air and 13" MacBook Pro
• the port next to the MagSafe connector on the 14" and 16" MacBook Pro
• the port nearest to the power plug on Mac Mini (M1 and M2)

You need to use a USB 3.0 compatible (SuperSpeed) Type C cable. USB 2.0-only cables, including most cables meant for charging, will not work, as they do not have the required pins. Thunderbolt cables work too.

Note that the numbering of the i2c busses is not stable and the default bus /dev/i2c-0 will be wrong randomly. To find the correct buse use grep cd321x /sys/class/i2c-dev/i2c-?/device/?-0038/name.

Alternatively the --connector parameter will find a controller by matching its argument against the USB-C connector labels. Use grep -a 'USB-C ' /sys/class/i2c-dev/i2c-?/device/*/of_node/connector/label to list all USB-C connectors.

Run it as root (sudo ./tuxvdmtool).

On hosts whose USB-C controllers are not on i2c (SN201202x on SPMI, M3 and later), tuxvdmtool uses the kernel tipd driver's debugfs interface, /sys/kernel/debug/usb/tipd/<device>/{command,regs}, which needs a kernel with that interface. --connector selects it when the connector's controller is not an i2c device. Without --connector, --bus or --address, it is used automatically if no CD321x exists on i2c and exactly one controller offers the interface; tuxvdmtool never falls back to /dev/i2c-0 there. A controller that is already in DBMa mode (for example because the boot loader keeps Apple Debug USB armed on it) is used as it is and left in DBMa. reset-controller needs raw register writes and is not available through the kernel interface.

USAGE:
    linuxvdmtool [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -a, --address [<ADDRESS>...]    i2c target address of the USB-C controller device. [default:
                                    0x38]
    -b, --bus [<BUS>...]            i2c bus of the USB-C controller device. [default: /dev/i2c-0]
    -c, --connector [<CONNECTOR>...]    (Partial) connector label of the USB-C controller device.
    -h, --help                    Print help information
    -V, --version                 Print version information

SUBCOMMANDS:
    debugusb         enter Debug USB mode on the target
    dfu              put the target into DFU mode
    help             Print this message or the help of the given subcommand(s)
    nop              Do nothing
    reboot           reboot the target
    reboot debugusb  reboot the target and enter Debug USB mode
    reboot serial    reboot the target and enter serial mode
    reset-controller soft-reset only the selected host USB-C PD controller
    serial           enter serial mode on both ends

Use /dev/ttySAC0 on the local machine as your serial device. To use it with m1n1, export M1N1DEVICE=/dev/ttySAC0.

For typical development, the command you want to use is tuxvdmtool reboot serial. This will reboot the target, and immediately put it back into serial mode, with the right timing to make it work.

For DebugUSB/KIS, use tuxvdmtool reboot debugusb. On Linux, success means the Apple Debug USB device (05ac:1881) actually appeared in sysfs; a PD-level VDM acknowledgement alone is not considered success. If Linux has stale Type-C state, tuxvdmtool reprobes only the selected HPM and retries the DebugUSB arm once. It does not reset the host USB controller or reboot the target a second time.