NAME

kadb − adb-like kernel and standalone-program debugger

SYNOPSIS

> b kadb [ −d ] [ boot-flags ]

DESCRIPTION

kadb is an interactive debugger that is similar in operation to adb(1), and runs as a standalone program under the PROM monitor.  You can use kadb to debug the kernel, or to debug any standalone program. 

Unlike adb, kadb runs in the same supervisor virtual address space as the program being debugged — although it maintains a separate context.  The debugger runs as a coprocess that cannot be killed (no ‘:k’) or rerun (no ‘:r’).  There is no signal control (no ‘:i’, ‘:t’, or ‘$i’), although the keyboard facilities (CTRL−C, CTRL−S, and CTRL−Q) are simulated. 

While the kernel is running under kadb, the abort sequence (L1-A or BREAK) drops the system into kadb for debugging — as will a system panic.  When running other standalone programs under kadb, the abort sequence will pass control to the PROM monitor.  kadb is then invoked from the monitor by jumping to the starting address for kadb found in /usr/include/debug/debug.h (currently this can be done for both Sun-2 and Sun-3 system machines with the monitor command ‘g fd00000’, and with the monitor command ‘g fe005000’ for Sun386i systems).  kadb’s user interface is similar to adb.  Note: kadb prompts with

kadb>

Most adb commands function in kadb as expected.  Typing an abort sequence in response to the prompt returns you to the PROM monitor, from which you can examine control spaces that are not accessible within adb or kadb.  The PROM monitor command c will return control to kadb.  As with “adb −k”, $p works when debugging kernels (by actually mapping in new user pages).  The verbs ?  and / are equivalent in kadb , since there is only one address space in use. 

Sun386i System Operations

kadb on the Sun386i system can also be used to debug loadable modules.  To do so, use the -sym option to the modload command.  If you need to debug the module entry point routine, be sure to set a breakpoint on the kernel routine vd_entry.  This is the routine that calls the module entry point routine. When kadb hits the breakpoint, the symbols for the module are usable and a breakpoint can be set in the module itself. 

Care must be taken to remove kadb breakpoints before unloading modules.  Since kadb inserts bpt instructions in the module itself, unloading and loading new modules while breakpoints are set can cause kadb to insert bpt instructions at incorrect places.  This may cause the system to crash. 

The symbol "vddebug" can be set to -1 to enable all kernel printf’s in the pseudo-driver (/dev/vd).  These printf’s may be helpful when trying to load or unload modules. 

OPTIONS

kadb is booted from the PROM monitor as a standalone program.  If you omit the −d flag, kadb automatically loads and runs vmunix from the filesystem kadb was loaded from.  The kadb vmunix variable can be patched to change the default program to be loaded. 

−d Interactive startup.  Prompts with

kadb:

for a file to be loaded.  From here, you can enter a boot sequence line to load a standalone program.  Boot flags entered in response to this prompt are included with those already set and passed to the program.  If you type a RETURN only, kadb loads vmunix from the filesystem that kadb was loaded from. 

boot-flags
You can specify boot flags as arguments when invoking kadb.  Note: kadb always sets the −d (debug) boot flag, and passes it to the program being debugged. 

USAGE

Refer to adb in Debugging Tools. 

Kernel Macros

As with adb, kernel macros are supported.  With kadb, however, the macros are compiled into the debugger itself, rather than being read in from the filesystem.  The kadb command $M lists macros known to kadb. 

Setting Breakpoints

Self-relocating programs such as the SunOS kernel need to be relocated before breakpoints can be used.  To set the first breakpoint for such a program, start it with ‘:s’; kadb is then entered after the program is relocated (when the system initializes its interrupt vectors).  Thereafter, ‘:s’ single-steps as with adb.  Otherwise, use ‘:c’ to start up the program. 

Sun386i System Commands

The Sun386i system version of kadb has the following additional commands.  Note, for the general syntax of adb commands, see adb(1). 

:i Read a byte (with the INB instruction) in from the port at address.

:o Send a byte (with the OUTB instruction) containing count out through the port at address.

:p Like :b in adb(1), but sets a breakpoint using the hardware debug register instead of the breakpoint instruction.  The advantage of using :p is that when setting breakpoints with the debug register it is not necessary to have write access to the breakpoint location.  Four (4) breakpoints can be set with the hardware debug registers. 

$S Switch I/O from the console to the serial port or vice versa. 

[ Like :e in adb(1), but requires only one keystroke and no RETURN character. 

] Like :s in adb(1), but requires only one keystroke and no RETURN character. 

Automatic Rebooting with kadb

You can set up your workstation to automatically reboot kadb by patching the vmunix variable in /boot with the string kadb.  (Refer to adb in Debugging Tools for details on how to patch executables.) 

FILES

/vmunix

/boot

/kadb

/usr/include/debug/debug.h

SEE ALSO

adb(1), boot(8S), modload(8), modunload(8)

Debugging Tools
Writing Device Drivers

BUGS

There is no floating-point support, except on Sun386i systems. 

kadb cannot reliably single-step over instructions that change the status register. 

When sharing the keyboard with the operating system the monitor’s input routines can leave the keyboard in a confused state.  If this should happen, disconnect the keyboard momentarily and then reconnect it.  This forces the keyboard to reset as well as initiating an abort sequence. 

Most of the bugs listed in adb(1) also apply to kadb. 

Sun Release 4.0  —  Last change: 5 October 1988