Debugging Exclaim

Filed under: Exclaim Kernel

Exclaim supports two methods of debugging, via a serial port and using an internal debugger. You can use neither if you are not using a debug kernel.

You can use any terminal software that supports serial ports. The settings for communicating are:

• Speed: 38400 Baud
• Bits: 8 Bits
• Stop Bits: 1 Stop Bit
• Parity: None
• Flow Control: Hardware/None

(Note: not for Windows). VirtualBox does not support outputting serial data to a file, but it does support outputting data to a named pipe. First, install the “socat” application, which will be in your repository or MacPorts. Now open VirtualBox, go to your Virtual Machine preferences, and set up a Serial port. Set the port type to a Host Pipe, and enter a path to a file for your pipe; e.g. /home/user/pipe. This file should not exist. Then tick Create Pipe. You can now start your VM.

When you get the VirtualBox BIOS or the GRUB menu, run socat with the following parameters, replacing <path> with what you entered into VirtualBox:

socat <path> stdout

You should now get serial output on the console. socat will quit automatically when your VM closes. If you want, you can replace stdout with another file to redirect the output there. The pipe file will be automatically deleted after use.

The Exclaim kernel has a built-in debugger that allows you to easily look at kernel data structures and examine the state of the system if a Fatal Error or BUG occurs. Currently, to enter the debugger, you can either press Escape on the keyboard, or wait for a Fatal Error or a BUG. The debugger is only available if KDBG was set to 1 in build.conf.

Upon entry to the debugger, the following prompt appears:

Entered KDBG
KDBG>

From here, you can obtain a list of commands by typing help and pressing Enter.

Currently, the following commands are available:

Print a backtrace.

Exits KDBG and continues execution. If KDBG was entered due to a Fatal Error, then it is not possible to use this command.

Usage: ksym <address>
       ksym <name>

Looks up a symbol name/offset from an address, or an address from a symbol name.

Dumps a list of all kernel symbols.

Usage: process <pid>
       process <address>

Dumps information about a process. If a PID is specified, the process will be looked up in the process table, else it will attempt to access the specified address as a process.

Dumps the contents of the process table.

Usage: readh <bits> <addr>

Reads the specified number of bits from the address specified, and prints it as hexadecimal.

Usage: readi <bits> <addr>

Reads the specified number of bits from the address specified, and prints it as an integer.

Usage: reads <limit> <addr>

Reads at most limit bytes from addr and prints the bytes read as a string.

Usage: regs [<register>]

Display the value of a single register or all registers if no argument supplied.

Usage: thread <pid> <tid>
       thread <address>

Dumps information about a thread. If a PID/TID is specified, the thread will be looked up in the process table, else it will attempt to access the specified address as a thread.

Usage: threads <pid>

Dumps a list of all threads in the specified process.