KernelDebugging

1. summary How to debug with a two-machine setup

In order to do any kind of debugging on the Mac OS X ZFS implementation, you need to be able to set up a secondary machine in order to debug into the code. This explains how to set up such a system.

Requirements

You need two machines, both running exactly the same version of OSX (e.g. 10.5.8 and 10.5.8, or 10.6.2 and 10.6.2). It helps if they're the same architecture, but this isn't strictly necessary.

You'll need to download the OSX Kernel Debug SDK for the OS version you're currently using/targeting. When mounted, it will show up as `/Volumes/KernelDebugKit` for whatever version you're using.

You need a mechanism for transferring files between the two computers. One way of doing this is to export a common directory over NFS; another is to use `rsync`. For the purposes of this document, I'll assume that you have a directory `/target` and that the machine is called `target` as well, so that `rsync -cav . target:/target` will copy your files across.

Steps

  # `cd /path/to/maczfs`
  # `rm -rf build`
  # `xcodebuild -configuration Debug`
  # `cd build/Debug`
  # `rsync -cav . target:/target`
  # `ssh target sudo chown -R root:wheel /target`
  # `ssh target sudo kextload -s /target zfs.kext`
  # `rsync -cav target:/target/*.sym .`
  # `gdb -arch i386 /Volumes/KernelDebugKit/mach_kernel`

The debugger can be set up as follows:

  # `source /Volumes/KernelDebugKit/kgmacros`
  # `target remote-kdp`
  # `add-kext zfs.kext`
  # `attach target`

This should wait until the debugger kicks in.