XKDEBUG
a kernel debugging interface for gdb
release 951016



Xkdebug uses gdb's "remote debugging" interface to allow symbolic
debugging of a running kernel.  Gdb behaves as if it is passing
commands to a remote machine, but in fact, those commands are executed
in the kernel on another process.

Key features:

  -- Kernel data structures can be read and modified using the usual
     gdb commands for manipulating program variables.

  -- The debugger state can be initialized using a kernel trap report,
     or with the current state of a process that is blocked in the
     kernel.

  -- Breakpoints can be set in kernel code to observe the status of
     the world at a particular point of time.

  -- Kernel code can be single-stepped.

  -- Kernel functions can be invoked using the gdb "call" command, and
     can be used in expressions.   [WARNING:  This feature is broken in
     the current alpha release of xkdebug.  I'm working at putting it
     back. --johnh]

  -- Requires only a single computer.


INSTALLATION

Apply the appropriate patch to your kernel and rebuild:

	cd /usr/src/linux
	patch -p <kernel-1.3.30.patch
	# (check for rejects)
	find . -name \*.rej -print
	# (if you have rejects:  deal)
	# ...
	make clean
	mv include/linux/modules/ksyms.ver{,-}
	make config
	# (answer yes to the question "Kernel debugging support")
	make

Currently I only have patches against the 1.3.30 kernel.
These patches should be easy to adapt to other 1.[23].* kernels.
If you do so, please send me the patches for your kernel and I'll
include them in future releases.

If you wish to debug dynamically loadable modules, must compile them
with "-g".

Note that a kernel configured for debugging is compiled with -g and
frame-pointers.  Frame pointers mean that GCC cannot make use of the
EBP register, so you get a less-efficient kernel on your register-poor
x86.  You should therefore not run a debugging kernel in production
use.  (Unless, of course, you want to debug it :-).

You also must build and install the xkdebug module (hint: type "make;
make install").  The xkgdb script loads the xkdebug module, creates a
device file for talking to gdb, fires up gdb, and loads the kernel
symbol table and module symbol tables.

Kdebug was written by David Hinds <dhinds@allegro.stanford.edu> and
modified by John Heidemann <johnh@isi.edu> to support single-stepping
and breakpointing.  Most of the credit should therefore go to David,
while John takes responsibility for most of the bugs.



TECHNICAL WARNINGS

This kernel debugger should be considered ``alpha'' quality,
since it saw significant changes and has been running in its current
form since all of October 14th, 1995.

The kernel is multi-threaded.  The debugger (or at least the stub) is
not.  If multiple processes stack up on one breakpoint, I make no
guarantees.

The debugger also substantially changes the kernels mutlithreading
syncronization.  Most uniprocessor Unix kernels are not pre-emptable
when in kernel mode.  The authors code assuming that context switches
occur only when they do things which might sleep.  The kernel will
sleep a process on a breakpoint, so if you put one where in the middle
of code the author thought was ``atomic'' you can break things.  Big
things.  Make sure you didn't introduce the bug before you report it.



PHILOSOPHICAL WARNING

Linus has expressed reservations about a kernel debugger.
A quote for part of his post to the linux-kernel mailing list:

	...
	I'm afraid that I've seen too many people fix bugs
	by looking at debugger output, and that almost
	inevitably leads to fixing the symptoms rather than
	the underlying problems. 
	...
	"Use the Source, Luke, use the Source.  Be one with
	the code.".  Think of Luke Skywalker discarding the
	automatic firing system when closing on the deathstar,
	and firing the proton torpedo (or whatever) manually.
	_Then_ do you have the right mindset for fixing kernel
	bugs.
	...

The debugger is a tool.  Use it wisely.  Remember what happened to
Biggs.



OTHER KERNEL DEVELOPMENT AIDS

I added single-stepping/breakpointing to kdebug to convince Geoff
Kuenning to port kitrace to Linux.  Once he does (hint, hint), I
recommend you check out that excellent tool (perhaps at
<http://ficus-www.cs.ucla.edu/ficus-members/geoff/kitrace.html>).



OBTAINING XKDEBUG

New versions of xkdebug can be obtained by http from
<http://www.isi.edu/~johnh/SOFTWARE/xkdebug.html>.
If kdebug and xkdebug merge, another location may become
``authorative'', but I'll keep a pointer here.

Xkdebug is a modification of kdebug-1.2,
available from <ftp://cb-iris.stanford.edu/


   -John Heidemann
    <johnh@isi.edu>