Icebox: Linux Kernel Debugger

CS 134c Final Project

David Moore
June 12, 2002


Icebox is a kernel-level debugger for kernel version 2.4 (it may work with other versions but is untested) on the x86 architecture. The code should be considered alpha quality, and in fact the debugger will probably not be very useful for you. In any case, the code here is available under the GPL and anyone is free to tinker, provided they don't expect any support from me. Icebox supports the following features:

Installation Instructions

The installation scripts assume that the running version of your kernel sources are in /usr/src/linux. If this is not the case, first edit /src/, changing the include path near the beginning of the file to your correct location. Then, run:

If /usr/src/linux is the correct location, skip those steps. Once you are ready to compile, run

to prepare the makefiles. You then to generate a header file for the current version of your kernel symbols. Use the following command:

Replace the first path with the version of that matches your running kernel. It is imperative that this file matches your kernel or the debugger will probably crash and bring your system down with it.

Once that is done, you are ready to compile. Type 'make' to do so.

If it completes successfully, a file called 'debug.o' will appear in the src/ directory. This is the kernel module. You can install it directly into the running kernel by running 'make install'.


Before using icebox, you will need to enable the Magic SysRq capability so that the kernel can intercept certain hotkey combinations. Ensure that it was enabled during the compilation of the running kernel. If not, configure the kernel to enable support for Magic SysRq and recompile/reboot. Once the support is available, the capability is enabled with the following command:

Once that is complete, icebox can be started by pressing Alt-SysRq-d on a text- based console. The UI should appear. To quit icebox, press Alt-SysRq. If icebox is invoked while X-windows is on the screen, it will detect this condition and avoid starting. This is because it cannot take over the display gracefully from X without knowledge of the video card. If a breakpoint is encountered while X is running, it will be ignored.

Icebox supports two ways of command execution: the command line, and shortcut keys. The available shortcut keys depend on what state the UI is in. When it starts, you will be in command line mode. Type 'help' or press F1 to see a list of commands that can be typed in this mode. Some of these commands may also list a function key such as F2. These function keys can be pressed at any time in icebox to execute the corresponding command. The TAB key cycles between the three windows in icebox: the command line, the code/data view, and the topmost pane (call trace or IDT). In the top two windows, the arrow keys can be used to scroll up and down in the display. There are also extra commands available which will be listed in the lower right of the screen. For example, when in the code/data window, the 'b' key sets or unsets a breakpoint at the current line of code. In the call trace or IDT windows, the right arrow key takes you to the address listed on that line.

Code Overview

Here is a listing of the important source files and their contents:

The main loop for the debugger and the module initialization functions.
Breakpoint management, including special versions of the int1 and int3 handlers that are installed into the kernel.
The display routines for printing the dissassembly and memory contents.
A fairly complete x86 dissassembler.
The low-level screen management routines, since we don't have ncurses or anything like that in a kernel module.
Code to display the interrupt descriptor table.
Routines for safe memory access and code to compute the call trace.
Symbol querying functions.
Routines for handling the keyboard input and translated scancodes.
Lowest level functions for accessing the VGA text framebuffer.

Implementation Details

I'll discuss some of the main accomplishments that went in to making this debugger work.

Taking over the kernel

Keyboard and screen control

Breakpoints and single-stepping

Detecting X-windows

© David Moore, 2002