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)

---