Skip to content

Commit

Permalink
Update README.md after various lessons learned.
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
3405691582 committed Jun 14, 2024
1 parent 0b7f364 commit b70f43f
Showing 1 changed file with 16 additions and 14 deletions.
30 changes: 16 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,29 +15,29 @@ 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.<soc> -r /System/Library/Extensions -r /System/Library/DriverExtensions -x $(kmutil inspect -V release --no-header | awk '!/AppleSerialShim/ { print " -b "$1; }')
```

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>`).

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/<volume>/Library/KernelCollections/kc.noshim.macho -C -v /Volume/<volume>
Expand All @@ -47,7 +47,7 @@ Replace `<volume>` 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

Expand All @@ -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`).
Expand All @@ -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.

0 comments on commit b70f43f

Please sign in to comment.