From 33d4d1efe6e197af998153eb569dea2cbabbceed Mon Sep 17 00:00:00 2001 From: 3405691582 Date: Thu, 13 Jun 2024 19:41:07 -0400 Subject: [PATCH] Update README.md after various lessons learned. Namely: * `AppleSerialShim` must be disabled not just for Monterey but any older macOS version; emphasize that point, * SIP must be disabled; while the user is there, you might as well have them run through the startup security downgrade steps while they are there, * the list of "except" ports on https://support.apple.com/en-us/111336 seems to be a hint to which are the DFU ports, add the link for reference in case this is true, * `cu` on macOS doesn't work well for the debug console port; this slightly adjusted `picocom` invocation found from the IRC archives works much better. The commit also makes some other light wording tweaks. This doc could be further improved still, but it's a start. Signed-off-by: 3405691582 --- README.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a2774c4..1e9c139 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,21 @@ This is based on portions of [ThunderboltPatcher](https://github.com/osy/Thunder Thanks to t8012.dev and mrarm for assistance with the VDM and Ace2 host interface commands. -## Note about macOS 12 +## Note about macOS versions 12 and up -To have access to the serial console device on macOS Monterey (12), you need to disable the `AppleSerialShim` extension. +To have access to the serial console device on macOS Monterey (12) or any later version, you need to disable the `AppleSerialShim` kernel extension. **Note:** This requires downgrading the system security and may cause problems with upgrades. Use it at your own risk! -Start by generating a new kernel cache, without the `AppleSerialShim` extension: +Start by booting into 1TR: + +1. Power off your Mac +2. Press and hold the Power button until the boot menu appears +3. Select “Options”, then (if necessary) select your macOS volume and enter your administrative password. + +Disable System Integrity Protection (SIP). Select Utilities > Terminal and run `csrutil disable`. While you are here, select Utilities > Startup security and switch the macOS installation to reduced security. + +Back in macOS, generate a new kernel cache without the `AppleSerialShim` extension: ``` sudo kmutil create -n boot -a arm64e -B /Library/KernelCollections/kc.noshim.macho -V release -k /System/Library/Kernels/kernel.release. -r /System/Library/Extensions -r /System/Library/DriverExtensions -x $(kmutil inspect -V release --no-header | awk '!/AppleSerialShim/ { print " -b "$1; }') @@ -29,15 +37,7 @@ sudo kmutil create -n boot -a arm64e -B /Library/KernelCollections/kc.noshim.mac Replace `` with `t8101` on M1 Macs and `t6000` on M1 Pro/Max Macs. If you’re unsure, `uname -v` and look at the end of the version string (`RELEASE_ARM64_`). -Then, enter 1TR: - -1. Power off your Mac -2. Press and hold the Power button until the boot menu appears -3. Select “Options”, then (if necessary) select your macOS volume and enter your administrative password. - -Select Utilities>Startup security and switch the macOS installation to reduced security. Exit Startup security. - -Select Utilities>Terminal and install your custom kernel: +Go back to 1TR, select Utilities>Terminal and install your custom kernel: ``` kmutil configure-boot -c /Volume//Library/KernelCollections/kc.noshim.macho -C -v /Volume/ @@ -47,7 +47,7 @@ Replace `` with the name of your boot volume. You can now reboot: macOS should start as normal, and the serial device `/dev/cu.debug-console` should be available. -To revert back to the default kernel, enter 1TR again, access Utilities>Startup security and switch to full or reduced security. +To revert back to the default kernel, enter 1TR again, access Utilities>Startup security and switch to full or reduced security, as well as reenabling SIP with `csrutil enable`. ## Building @@ -60,6 +60,8 @@ Connect the two devices via their DFU ports. That's: - the port next to the MagSafe connector on the 14" and 16" MacBook Pro - the port nearest to the power plug on Mac Mini +([This list of ports](https://support.apple.com/en-us/111336#connect) might also be useful for other hardware not listed here.) + 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. Run it as root (`sudo ./macvdmtool`). @@ -74,6 +76,6 @@ Commands: nop - do nothing ``` -Use `/dev/cu.debug_console` on the local machine as your serial device. To use it with m1n1, `export M1N1DEVICE=/dev/cu.debug-console`. +Use `/dev/cu.debug_console` on the local machine as your serial device. To use it with m1n1, `export M1N1DEVICE=/dev/cu.debug-console`. `picocom` generally works better than `cu` for this; use something like `sudo picocom -q --omap crlf --imap lfcrlf -b 115200 /dev/cu.debug-console`. For typical development, the command you want to use is `macvdmtool reboot serial`. This will reboot the target, and immediately put it back into serial mode, with the right timing to make it work.