El Capitan Kernel Extension Debugging

, , , , ,

Just a bit back I needed to do some kernel module extension debugging on OS X El Capitan (10.11.x). Below are some quick notes on the subject for future refence. Perhaps they will be of interest to someone else.

Basic steps

If you’re doing this for development, I highly suggest you set up a VM image. This will allow you to take a snapshot with everything ready to go that you can revert to. Otherwise, ye shall suffer.

Disable System Integrity

El Capitan ships with System Integrity enabled by default. We’ll need to disable this:

  • Reboot to recovery mode (⌥ + R)

  • Enter the console and enter the following:

    csrutil disable

  • Reboot again

Install Kernel Symbols

Next, we need to install Kernel debug or development symbols. From the system to be debugged:

Determine the system’s build ID

From terminal: 

system_profiler SPSoftwareDataType

The build ID is in parenthesis on the “System Version” line. For example, “System Version: OS X 10.11 (15A284)”

Download & install symbols

Download and install the appropriate symbol package (matching the build ID obtained above) from https://developer.apple.com/downloads/

Install debug kernel

Copy kernel.debug or kernel.development depending on your needs (generally .development) from /Library/Developer/KDKs/XXXXX/System/Library/Kernels/ ( to /System/Library/Kernels/)

Update boot args

sudo nvram boot-args="-v kcsuffix=development debug=0x14e"

(or kcsuffix=debug; this must match the kernel you copied above). This instructs the system to use the new development or debug kernel, and to wait for a debugger when something goes wrong. See Building and Deubgging Kernels for additional flags and their meaning.
5. Invalidate cache: 

sudo kextcache -invalidate /Volumes/<target>

(where <target> is replaced with the volume of your OS X installation.)

This is a good place to save a snapshot of your VM!

Your Kernel Extension

Next, if you haven’t already build your Kernel Extension with dynamic symbol (.dSYM) support enabled. To prepare the system, copy your .kext to it’s usual path and the .dSYM along side it (e.g. in the same directory).

Debug!

Now that your snapshot is ready and your Kernel Extension + .dSYM symbols are in place, reboot the VM/machine to be debugged and wait for errors.

Once one hits, the system will enter a text mode and wait for the debugger. You can attach and debug as such (from a different machine on the network):

lldb  
(lldb) kdb-remote <the IP address>

Replacing with the appopriate IP of course.

Happy debugging!