GDB

GDB is the standard debugger on Linux and other Unices. It is source level, rather than machine level, like the Bochs debugger; this could be good or bad, depending on your viewpoint.

While debugging system code is not its intended use, it does a fine job of it; it can be used directly with some emulators, without modifying your code at all, or it can be used over a serial line. The latter option involves implementing a Remote Serial Protocol stub in your operating system.

Remote Debugging

We are interested in remote debugging facility of GDB. From GDB manual, “If you are trying to debug a program running on a machine that cannot run GDB in the usual way, it is often useful to use remote debugging. For example, you might use remote debugging on an operating system kernel, or on a small system which does not have a general purpose operating system powerful enough to run a full-featured debugger.”

For remote debugging, remote stub should be implemented in the remote program that needs debugging. That means, the kernel should contain the remote stub to talk to the host gdb during the debug session. This requires kernel source change and it is must if you are running your kernel on a test(real) machine and debugging from other machine. If you are using an emulator(bochs or qemu), then you can use the gdb-stub complied into the emulator.

Implementing GDB Stub

To debug (using GDB) a kernel running on a real machine, the kernel needs to contain GDB stub. For i386 platform, GDB source includes a reference implementation of gdb-stub.c. It requires the following three functions from kernel to read/write from serial port and to setup the exception handlers.

  getDebugChar() – to read character from serial port
  putDebugChar(int) – to write a character to serial port
  exceptionHandler(int exception_number, void *exception_address) – to set exception handler

Implement the above functions in kernel and include the gdb-stub.c in the compilation and also call the following functions during kernel start to connect to the gdb host.

  InitSerialPort(sys_gdb_port, 9600, UART_DATA_BIT_8, UART_PARITY_NONE, UART_STOP_BIT_1);   /*set up the serial port*/
  set_debug_traps();   /*setup exception handlers*/
  kprintf("Waiting for GDB(0x%X) : ", sys_gdb_port );
  __asm__("int3");   /*break point exception to sync with GDB host*/

Now start your test machine and your kernel will wait for GDB host connection.

Using Emulator Stubs

Qemu - GDB can be connected to QEMU by simply starting qemu with the -s -S command line switches.

Bochs - For GDB to be able to interface with Bochs, Bochs will need to be configured with the --enable-gdb-stub argument. The bochssrc (or whatever configuration script is being used) will need to have the gdbstub line set to something like gdbstub: enabled=1, port=1234, text_base=0, data_base=0, bss_base=0

Starting GDB

After an emulator/kernel is configured it will then wait for a connection from GDB. GDB on the host machine can be started like this:

$ gdb YOUR-KERNEL
.
.
.
(gdb) target remote :1234
Remote debugging using :1234
0x0000fff0 in ?? ()
(gdb)

If you are debugging a kernel running on a real machine then use target remote /dev/tty2 instead of the network port.

If it prompts you after the "target remote" line asking whether to kill a program that is already being debugged answer "n".

If you are using 64 bit kernel, you may need to setup the address size using set command.

Virtual Serial Ports

If you have gdbstub inside your kernel and run your kernel inside a emulator, you can use a COM Port redirector to create virtual serial port. After creating a virtual serail port, one port in the pair should be used for the emulator; the other one should specified in the gdb for remote debugging.

com0com can be used in Windows and pseudo terminal might be used in Linux to create virtual serial port pairs.