Kernel Debugging on Apple Silicon

Notes on how I was able to debug my kernel extension on a 2020 M1 Mini.

As of Mar 2021, kernel debugging on Apple Silicon is rather primitive compared to Intel. All you can do right now is inspect the current state of the kernel when it has halted due to a panic or non maskable interrupt (NMI). You can’t set breakpoints, step into code or continue post NMI.

Setup

You need two Macs.

The target device is the Mac that runs the code you want to debug.

The host device is the Mac that runs the debugger.

Download the appropriate Kernel Debug Kit (KDK) from Apple. Make sure that the build number matches the build number of the target device(is your friend). Install the KDK on your host device. Make sure to print out the instructions that come up as part of the installer. Read the docs carefully at least once from end to end. I hate to waste trees, but I found it nice to be able to take notes on the doc, and to have them to review while I was rebooting (multiple times).

Not all KDKs are created equal. I found that some versions of the KDK didn’t contain the kernel I needed for the M1 Mini. The KDK installs the kernels it will work for in . You will find multiple kernels in there. For my stock M1 I needed to have the version. You can determine the version you need be running on the target machine. If the KDK doesn’t have the version you need, you may need to install a different OS on your target machine.

I set up my debugging setup with a direct ethernet cable from my host to target machine.

Host:

  • Configure IPv4: Manually
  • IP Address: 10.0.0.1
  • Subnet Mask: 255.255.255.0

Target:

  • Configure IPv4: Manually
  • IP Address: 10.0.0.2
  • Subnet Mask: 255.255.255.0

The rest of the instructions in the are pretty good and I won’t repeat them here. It is worth noting though that they never mention the NMI keyboard sequence which is:

Also not mentioned in the read me is that there are a bunch of very useful macros that you are going to want to use. Python version 3 is not supported for these macros, so you need to configure to use python 2 before you launch .

Once you’ve loaded (and before you hit an NMI/panic or load a core file) you will also want

so that the macros are loaded for you automatically. This is worth considering adding to your file so it happens by default. If you don’t set this before you load the core file it may not symbolicate correctly for you.

Make sure that the for your kext is available to on your host machine.

Core files take a while to transfer (multiple minutes). You will need to them and extract them appropriately once they’ve transferred.

Once you’ve hit the panic, or loaded the core file make sure to run to see all the extra macros you now have in . The source for the macros is available in

Kernel variants

The Readme claims these don’t work on Apple Silicon, but I’ve noticed that they are included in my version of the KDK. Please let me know if you try them out.