Two-box osx kernel debugging

osx_kernel_debug_two_boxes.md

Two-box osx kernel development

This is an officially unsupported two-box setup, suitable for real kernel (and sometimes kext) development.

Target box setup w/ development kernel

Make sure the box has plenty, but not too much, ram, unless you enjoy wasting time doing either virtual or actual paging.

1. Install OSX by dragging the Install OS X *.app onto VMware Fusion new VM wizard dialog.

2. Install the Kernel Debug Kit (KDK) of this box'es kernel.

3. Run the following to change from release to development kernel: NOTE: debug flag 0x001 pauses bootup until the host debugger attaches

    # 10.10+
   

   sudo cp /Library/Developer/KDKs/*/System/Library/Kernels/kernel.development /System/Library/Kernels/

   <= 10.9

   sudo cp /Library/Developer/KDKs/*/mach_kernel.development /

   sudo nvram boot-args="pmuflags=1 debug=0x166 kext-dev-mode=1 kcsuffix=development -v" sudo kextcache -invalidate / sudo reboot

4. If debugging the kernel with the debug flag 0x001, verbose mode should now show when the host's llvm debugger connects:

    ip address: (TARGET_BOX_IP_ADDR)
    
    Waiting for remote debugger connection.
   

Host box setup

1. Install Xcode and Xcode CLT.

2. Install the same KDK of the target box'es kernel.

3. Append or create the following to ~/.lldbinit-lldb

   settings set target.load-script-from-symbol-file true 
   

4. Run this to start the remote debugger:

   # 10.10+ TARGET : use development kernel instead of release
   lldb /Library/Developer/KDKs/*/System/Library/Kernels/kernel.development
   # <= 10.9 TARGET: use release kernel, DEBUG might be too slow
   # lldb /Library/Developer/KDKs/*/mach_kernel 
   

5. At the '(lldb)' prompt, run:

   (lldb) kdp-remote TARGET_BOX_IP_ADDR

6. This should boot the kernel, and the target box should now say:

    Connected to remote debugger.
   

7. To boot the box "normally", just run this:

    (lldb) continue
   

References

1. /Library/Developer/KDKs/*.kdk/ReadMe.html
2. LLDB Quick Start Guide
3. Apple's GDB -> LLDB command map
4. kernel debug flags