Debugging Methods

Remote Debugging with gdb

The Concept

Writing or porting a debugger to a new operating system is a difficult and lengthy process, and most likely you will want to use a debugger well before you're ready to host one. It would be great if you could use gdb or a similar debugger running on another machine, while your operating system ran on the target machine.

Setting Up the Remote Debugging Environment

On the debugging (host) machine, you need to:

install a copy of gdb, compiled to cross-debug for your target system;
setup the serial port to run at 9600 bps, 8/N/1, raw; and
plug in one end of a serial cable.

On the target kernel and machine, you need to:

compile and link the stub routines for the target system into the kernel;
add the init_serial(); and set_debug_traps(); calls to the kernel, to be executed after you set up exception handling; and
plug in the other end of the serial cable.

The gdb stub routines that you need to provide may have been partially provided for you. They include polling serial routines to read and write a character, and a routine to flush the instruction cache (usually just a jmp instruction). You still need to fill in the exceptionHandler() and memset() routines, and feel free to rewrite any part of the example stub routines.

Using the Remote Debugger

Once you have the debug traps installed and working correctly, your operating system will appear to hang whenever it encounters an exception. However, it is merely waiting in the polling serial driver for a response from the host machine. To debug the kernel in this state, start up the gdb cross-debugger, and at the prompt, type:

target remote /dev/tty0

where /dev/tty0 is the name of the serial port on the host machine. gdb will then try to connect to the target machine, and if all goes well it will display where the fault occurred. You should then be able to use gdb just as though you were debugging a local program.

For More Information

For more information, read gdb's manual pages on remote debugging

Stub Routines

Stubs provided with gdb for different platforms:

i386

Example stub code that needs to be tailored to your OS:

i386

The i386-stub.c file has been slightly modified to clean up unresolved references and comment out some unimplemented libc functions (namely, fprintf() and printf()).