Skip to content

Commit 33d4d1e

Browse files
committed
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 <dsk@google.com>
1 parent 0b7f364 commit 33d4d1e

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

README.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,29 +15,29 @@ This is based on portions of [ThunderboltPatcher](https://github.com/osy/Thunder
1515

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

18-
## Note about macOS 12
18+
## Note about macOS versions 12 and up
1919

20-
To have access to the serial console device on macOS Monterey (12), you need to disable the `AppleSerialShim` extension.
20+
To have access to the serial console device on macOS Monterey (12) or any later version, you need to disable the `AppleSerialShim` kernel extension.
2121

2222
**Note:** This requires downgrading the system security and may cause problems with upgrades. Use it at your own risk!
2323

24-
Start by generating a new kernel cache, without the `AppleSerialShim` extension:
24+
Start by booting into 1TR:
25+
26+
1. Power off your Mac
27+
2. Press and hold the Power button until the boot menu appears
28+
3. Select “Options”, then (if necessary) select your macOS volume and enter your administrative password.
29+
30+
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.
31+
32+
Back in macOS, generate a new kernel cache without the `AppleSerialShim` extension:
2533

2634
```
2735
sudo kmutil create -n boot -a arm64e -B /Library/KernelCollections/kc.noshim.macho -V release -k /System/Library/Kernels/kernel.release.<soc> -r /System/Library/Extensions -r /System/Library/DriverExtensions -x $(kmutil inspect -V release --no-header | awk '!/AppleSerialShim/ { print " -b "$1; }')
2836
```
2937

3038
Replace `<soc>` 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_<soc>`).
3139

32-
Then, enter 1TR:
33-
34-
1. Power off your Mac
35-
2. Press and hold the Power button until the boot menu appears
36-
3. Select “Options”, then (if necessary) select your macOS volume and enter your administrative password.
37-
38-
Select Utilities>Startup security and switch the macOS installation to reduced security. Exit Startup security.
39-
40-
Select Utilities>Terminal and install your custom kernel:
40+
Go back to 1TR, select Utilities>Terminal and install your custom kernel:
4141

4242
```
4343
kmutil configure-boot -c /Volume/<volume>/Library/KernelCollections/kc.noshim.macho -C -v /Volume/<volume>
@@ -47,7 +47,7 @@ Replace `<volume>` with the name of your boot volume.
4747

4848
You can now reboot: macOS should start as normal, and the serial device `/dev/cu.debug-console` should be available.
4949

50-
To revert back to the default kernel, enter 1TR again, access Utilities>Startup security and switch to full or reduced security.
50+
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`.
5151

5252
## Building
5353

@@ -60,6 +60,8 @@ Connect the two devices via their DFU ports. That's:
6060
- the port next to the MagSafe connector on the 14" and 16" MacBook Pro
6161
- the port nearest to the power plug on Mac Mini
6262

63+
([This list of ports](https://support.apple.com/en-us/111336#connect) might also be useful for other hardware not listed here.)
64+
6365
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.
6466

6567
Run it as root (`sudo ./macvdmtool`).
@@ -74,6 +76,6 @@ Commands:
7476
nop - do nothing
7577
```
7678

77-
Use `/dev/cu.debug_console` on the local machine as your serial device. To use it with m1n1, `export M1N1DEVICE=/dev/cu.debug-console`.
79+
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`.
7880

7981
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.

0 commit comments

Comments
 (0)