KGDB

Remote Debugging Using KGDB
The Kernel.org's KGDB HowTo is quite confusing and mixes destination/target terminology, so I started this wiki once I got KGDB working on my boxes.

From what I hear, Kernel Developers would like to see debugging done with KGDB, but it's a daunting task to debug via serial!

Once it's setup though, it's good to go and is an invaluable tool, whether you simply export a console via serial or use this thing called KGDB.

Using KGDB requires two computers. One, the Development Computer and the second being the Monitoring Computer using gdb. (Make sure you "emerge gdb" onto this computer.)

I'll reiterate the two computer names and their requisites:

1) Development Computer = The computer to either debug or develop kernel code on. This is the computer we want to monitor via a remote computer using gdb on the remote computer.  We need a kernel configured with KGDB and boot kernel parameters set on this one.

2) Monitor Computer = The computer used to only monitor the above Development Computer. This computer requires gdb and a copy of the above computer's /usr/src/linux/vmlinux image file.


 * I'll forewarn you, using the kernel.org HowTo will confuse readers with it's mixed terminology of computer designations! Extra care is taken above to define each computer and the requirements of each computer.  (Feel free to edit for readability.)

A serial (DB9) cable is also required. (Further documented below.)

Configure the Development Computer
This is the box you want to export logging data from because it is either unstable or you're working on kernel coding.

Kernel Config
Activate the KGDB code within the "Kernel Hacking" section.

Include more kernel debug output with the following within the "Kernel Hacking" section:

There's a host of other debug options within this section. Feel free to document other useful options!

Grub (Kernel Parameters)
This needs work. I've finally figured out the options that enable KGDB via the kernel.org HowTo page. In futility, I simply just added them all! (Feel free to undocument the not needed KGDB kernel parameters.)

Cable Requirements and Port Settings
For serial (/dev/ttyS0) options, I've pretty much left things at the default within the BIOS settings and simply connected a "null" serial (DB9) cable from the COM1 (/dev/ttyS0) on the Development Computer to the COM1 (/dev/ttyS0) Monitoring Computer. (A null cable is a cable with one or two wires swapped. My setup details two DB9 radio shack cables with a null square adapter in the middle.  If you want 115200bps, make sure you keep your cable short enough for this capability -- See Serial HowTo for specifics on cable lengths.)

If you find your serial port settings are not as reliable as mine, see Linsyssoft's Quick Start Page (url at the bottom of this wiki) for extensive resetting of your ports.

You can also debug using Ethernet, but I have yet to try this method as the network is the first thing to go with some kernel freezes. Serial tends to be a little more stable sometimes. (Again, feel free to hack in Ethernet configuration & Ethernet usage!)

Copy Kernel VMLINUX Image File
The computer monitoring the Development Computer needs a copy of it's /usr/src/linux/vmlinux image file. Simply copy it over to the Monitoring Computer, or do as I do, and just mirror the whole tree over to the Monitoring Computer. (Rsync is used quite a bit around here.)

Start Remotely Monitoring with GDB
1) Reboot or boot the Development Computer with the newly configured kernel. It should "wait" after initializing the kernel...  waiting for gdb connection.  This is the desired effect for debugging over serial console.  (Boot wait isn't needed for debugging with ethernet.)

2) On the other computer that you are using to monitor, the Monitor Computer, login as root and type:

And then type:

You will get the following bug output: Remote debugging using /dev/ttyS0 breakpoint at kernel/kgdb.c:1212 1212           atomic_set(&kgdb_setting_breakpoint, 0); warning: shared library handler failed to enable breakpoint (gdb)

At this point, simply type the following and you should see the remote Development Computer start booting from it's slated wait state.