Add a document on Metalkit debugging

doc/debugging.txt

@@ -0,0 +1,69 @@
+Debugging Metalkit Apps
+-----------------------
+
+Using VMware's gdb stub, you can get source-level debugging for your
+Metalkit apps.
+
+Add these three config options to your .vmx file:
+
+    debugStub.listen.guest32 = "TRUE"
+    debugStub.hideBreakpoints = "TRUE"
+    monitor.debugOnStartGuest32 = "TRUE"
+
+Now run your VM. It should hang just after power on, before showing
+the BIOS. If you can see your VM's stdout, you should see a message
+about attaching gdb. Now we can attach gdb. You'll need the .elf file
+which matches the .img you're running in the VM. Metalkit's default
+makefiles compile ELF versions of your binary with full debug symbols.
+
+    micah@micah-64:~/metalkit/examples/apm-test$ gdb -q apm-test.elf
+    No symbol table is loaded.  Use the "file" command.
+    Using host libthread_db library "/lib/libthread_db.so.1".
+    (gdb) set arch i386
+    The target architecture is assumed to be i386
+    (gdb) target remote localhost:8832
+    Remote debugging using localhost:8832
+    [New Thread 1]
+    0x000ffff0 in ?? ()
+    (gdb) break main
+    Breakpoint 1 at 0x100ba2: file main.c, line 11.
+    (gdb) cont
+    Continuing.
+
+Now you should see the VM boot. If you need to stop earlier, to debug
+the bootloader, you can set a breakpoint at *0x7c00 instead. Usually
+starting at main() is quite sufficient. As soon as Metalkit loads, you
+should hit this breakpoint. From here on, all the normal gdb debug-fu
+should work.
+
+    Breakpoint 1, main () at main.c:11
+    11      {
+    (gdb) list
+    6       #include "keyboard.h"
+    7       #include "apm.h"
+    8
+    9       int
+    10      main(void)
+    11      {
+    12         ConsoleVGA_Init();
+    13         Intr_Init();
+    14         Intr_SetFaultHandlers(Console_UnhandledFault);
+    15         Keyboard_Init();
+    (gdb) next
+    main () at main.c:12
+    12         ConsoleVGA_Init();
+    (gdb)
+    13         Intr_Init();
+    (gdb)
+    14         Intr_SetFaultHandlers(Console_UnhandledFault);
+    (gdb)
+    15         Keyboard_Init();
+    (gdb) p gConsole
+    $1 = {beginPanic = 0x1005ef <ConsoleVGABeginPanic>,
+          clear = 0x1004d2 <ConsoleVGAClear>,
+          moveTo = 0x1004c1 <ConsoleVGAMoveTo>,
+          writeChar = 0x100511 <ConsoleVGAWriteChar>,
+          flush = 0x100482 <ConsoleVGAMoveHardwareCursor>}
+    (gdb)
+
+---