	kdebug -- a kernel debugging interface for gdb

Kdebug uses gdb's "remote debugging" interface to allow limited
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 current kernel context.

Key features:

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

  -- Kernel functions can be invoked using the gdb "call" command, and
     can be used in expressions.

  -- The debugger state can be initialized using a kernel trap report.

Breakpoints are not supported.

INSTALLATION

To really take advantage of the debugger, you will need to compile
your kernel and/or loadable modules with "-g" to get full symbolic
debugging information.  To build a kernel with debugging enabled, edit
/usr/src/linux/Makefile and find the definition of CFLAGS.  Change
from:

    CFLAGS = -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer

to:

    CFLAGS = -Wall -Wstrict-prototypes -O2 -g

There is also a small kernel patch (called mm.patch) that you should
install, as it prevents gdb from segmentation faulting if you happen
to stumble over a bad address.

Build the kdebug module by just running "make".  Install the kdebug
module and the kgdb script with "make install".  The kgdb script loads
the kdebug module, creates a device file for talking to gdb, fires up
gdb, and loads the kernel symbol table and module symbol tables.

EXAMPLE

~# kgdb
...
(gdb) p jiffies
$1 = 5653193
(gdb) call printk(linux_banner)
Linux version 1.1.64 (root@cloudsrest) (gcc version 2.5.8) #14 Fri Nov 18 20:42:55 PST 1994

The kgdb script will optionally parse a Linux kernel trap report, and
initialize the debugger state to the state at the time of the trap.
This includes setting up all registers, and setting up the top part of
the stack.  To use this, invoke kgdb as "kgdb -t trapfile".

	-- David Hinds
	   dhinds@allegro.stanford.edu
