Getting serial on modern Macs

serial.md

Getting serial on modern Macs

Modern devices default to serial output over DockChannel by default, which is why macvdmtool serial doesn't work. In order to use legacy UART:

On the target device:

1. Disable SIP
2. Disable boot-arg filtering
3. Set the following boot args:

• serial=3 (or serial=7 or whatever)

• If the device is on macOS 14 or below: use-legacy-uart=1

• If the device is on macOS 15 or above, it gets more complicated. Apple rewrote serial_init and this boot arg no longer exists. Instead:

  1. Download an IPSW for your device

  2. Get the DeviceTree for your device

  3. Look for the uart0 node, and find the value for AAPL,phandle (the outer one, not the one for debug-console). Example for J413AP:

     

     Note that this is model specific, so you can't copy from my screenshot.

  4. Add serial-device=[value of AAPL,phandle] (ie. serial-device=163)

  Bonus info

  If you look for the serial-device property (defaults node), you'll notice that its value is the same as AAPL,phandle for dockchannel-uart, which is where the default comes from (at least for 15+).

  

4. Reboot, make sure the boot args set properly
5. Set up your cable between host and target, use the correct DFU port (on both machines!), etc

You can now run macvdmtool reboot serial on your host device. Enjoy! Remember that if your host is on Monterey or above, you will need to remove AppleSerialShim from the boot KC.

If you're wondering what to actually use to see the logs, something like sudo picocom -q --omap crlf --imap lfcrlf -b 115200 /dev/tty.debug-console would work.

Bonus - running macvdmtool on iOS

My desperate attempt to test this without rebuilding my KC. Spoiler, /dev/cu.debug-console does not exist on iOS

Jailbreak required obviously

1. Compile stacksmashing's macvdmtool fork (iphone15 branch) for iOS

• If you have a SDK with private headers (ie. from Theos), just set the target in the Makefile, xcrun -sdk iphoneos make, and enjoy
• If not:
  1. cp "$(xcrun --show-sdk-path)/System/Library/Frameworks/IOKit.framework/Versions/A/Headers/IOCFPlugIn.h" .
  2. Fix the import in AppleHPMLib.h
  3. sed -i '' 's/kIOMasterPortDefault/kIOMainPortDefault/g' main.cpp
  4. Set the target in the Makefile
  5. xcrun -sdk iphoneos make
• Or the cursed option:
  1. Build normally for macOS
  2. vtool -set-build-version ios 15.0 15.0 -replace -output macvdmtool_ios macvdmtool
  3. install_name_tool -change /System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation /System/Library/Frameworks/CoreFoundation.framework/CoreFoundation macvdmtool_ios
  4. install_name_tool -change /System/Library/Frameworks/IOKit.framework/Versions/A/IOKit /System/Library/Frameworks/IOKit.framework/IOKit macvdmtool_ios

2. Sign with the following entitlements:

• com.apple.security.iokit-user-client-class: AppleHPMUserClient

• com.apple.USBCEntitlement: true

  These entitlements are the same as /usr/bin/hpmdiagnose

3. Profit

You won't be able to use serial, but actions such as DFU and reboot will work:

You can use serial over USB on iOS with usbselfserial/(compiled for rootful). I know that it does work with rootless jailbreaks, but probably requires recompilation.