kadb(1M)
NAME
kadb - a kernel debugger
SYNOPSIS
SPARC
ok boot device_specifier kadb [-d] [boot-flags]
> b kadb [-d] [boot-flags]
x86
select (b)oot or (i)nterpreter: b kadb [-d] [boot-flags]
select (b)oot or (i)nterpreter: i kadb [-d] [boot-flags]
DESCRIPTION
kadb is an interactive kernel debugger with a user interface
similar to adb(1), the assembly language debugger.
kadb must be loaded prior to the standalone program it is to
debug. kadb runs with the same environment as the standalone
program, so it shares many resources with that program. The
debugger is cognizant of and able to control multiple pro-
cessors, should they be present in a system.
When kadb is started, it requests the default filename from
boot(1M), and if loaded non-interactively (without the -d
option), it loads the default filename.
On systems which support both 32-bit and 64-bit operating
system, boot(1M) chooses an appropriate default filename for
that system. If loaded interactively (by specifying the -d
option), kadb prompts with the default filename, which can
be changed before continuing. The default filename can be
specified on the boot(1M) command line. See boot(1M) for
details.
Before loading the 64-bit kernel explicitly, review the
information in boot(1M) for restrictions on running the 64-
bit kernel on certain configurations.
Unlike adb(1), 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 co-
process that cannot be killed (no :k command as in adb) or
rerun (no :r command as in adb). There is no signal control
(no :i, :t, or $i commands as in adb), although the keyboard
facilities (CTRL-C, CTRL-S, and CTRL-Q) are simulated.
In the case of the UNIX system kernel, the keyboard abort
sequence suspends kernel operations and breaks into the
debugger. This behavior may be disabled by way of the kbd(1)
command and may not be the current default on all systems.
See kb(7M) for more information.
As the kernel is composed of the core image file and the set
of loadable modules already in memory, kadb has the capabil-
ity of debugging all of these by traversing special data
structures. kadb makes use of this feature to allow it to
reference any kernel data structure, even if it resides in a
loadable module. kadb sets the -d flag by default so the
program being debugged can tell it is being watched. If this
flag is not given, kadb loads and immediately runs the
default kernel .
Most adb(1) commands function in kadb as they do in adb. As
with adb -k, $p works when debugging kernels. The verbs ?
and / are equivalent in kadb, as there is only one address
space in use.
The keyboard abort sequence is L1+A on keyboards with an
<L1> key, and F1+A on keyboards with no <L1> key. On serial
lines, the default abort sequence is a BREAK signal, but
this can be changed to the sequence ``carriage return,
tilde, control-B'' using:
kbd -a alternate
See kbd(1).
Once aborted, kadb responds with the following:
kadb[cpu]:
where cpu is the number of the CPU on which kadb is
currently executing.
OPTIONS
The following options are supported:
-d Interactive startup. If specified, kadb stops after
loading and displays the kadb: prompt, followed by the
name of the default program to debug.
The user may either press RETURN to debug the default
program, or BACK SPACE followed by the name of another
program to debug.
OPERANDS
The following operands are supported:
boot-flags
Specifies boot flags as arguments to kadb. The speci-
fied boot-flags are passed to the program being
debugged. See boot(1M) for available boot-flags.
SPARC Only
device-specifier
Specifies the device from which to load. See
monitor(1M).
USAGE
Kernel Macros
As with adb(1), kernel macros can be used with kadb, but
they cannot be read from a file at runtime. Use the kadb $M
command to list all of the built-in kadb macros.
Commands
kadb reads commands from the standard input and displays
responses on the standard output. kadb supports the majority
of the adb(1) commands. kadb does not support the following
adb commands: :k, :r, :i, :t, or $i. See adb(1).
Additionally, kadb supports the following commands:
[ Performs the same function as :e in adb(1), but
requires only one keystroke and no RETURN (ENTER on
x86 based systems).
] Performs the same function as :s in adb(1), but
requires only one keystroke and no RETURN (ENTER on
x86 based systems).
:a Sets a hardware access (read or write) breakpoint
using the processor hardware facilities. The syntax
and action for this command is the same as the :b com-
mand in adb, with the following exceptions:
o The breakpoint triggers if any bytes from the
breakpoint for length bytes are being accessed.
See $l below for setting the length of a
hardware breakpoint.
o Breakpoints should be aligned for the length
specified. Any address is valid for length 1.
Addresses divisible by 2 should be used for
length 2 (short). Addresses divisible by 4
should be used for length 4 (int).
o Detection of an access breakpoint occurs after
completion of the instruction that caused it.
o There are a limited number (4) of hardware
breakpoint registers, and, when set, this uses
one.
o As this breakpoint does not modify memory loca-
tions, this command will work on locations that
are not in core at the time the breakpoint is
set.
@fmt Used in the same manner as the adb / and ? commands.
Specify @ as a physical memory address as opposed to
the normal virtual address. Specify fmt as any of the
formats used with the adb / command. This command is
useful for displaying memory that may not be mapped,
for example, kernel page tables or buffers used for
DMA by device drivers.
function:: call arg1, arg2, arg3, ...
Invokes kernel functions with 0 or more arguments.
Using this command results in a response such as:
retval = function(arg1,arg2,arg3,...);
where retval is the return value of the function. This
feature can be error prone, as functions may have side
effects that cause failures if the kernel is contin-
ued.
:p Sets a hardware access (read or write) breakpoint
using the processor hardware facilities when an
instruction at the specified address is run. The $l
operation has no effect on this type of breakpoint.
This breakpoint occurs before the instruction is exe-
cuted.
:P Works as :a, but this command will only breakpoint
when an access is made to the address in x86 I/O
space. See :a.
:w Sets a write hardware access breakpoint using the pro-
cessor hardware facilities.
[length]$l
Sets the default data length for an access or write
breakpoint. length can be set to 1 for byte, 2 for
short, and 4 for int word accesses. If length is not
specified, 1 byte is assumed. Once set, this value
affects any newly set access or write breakpoints, but
does not affect ones set before this operation.
$b Displays two additional columns that adb does not. The
first is the type column which indicates soft for a
normal breakpoint, access for an access hardware
breakpoint, write for a write hardware breakpoint, and
inst for an instruction hardware breakpoint. The
second is the len column which for access and write
breakpoints indicate the length of the operation to
break on.
SPARC
$q Gives control to the boot prom, from which you may
reboot the system.
cpu:x Switches the active CPU to cpu. Thereafter, commands
such as $r and $c displays the registers and stack of
the new CPU, cpu.
x86
port:i
Inputs a byte for display from port. port is an
address-specified I/O port. For example, 330:i inputs
from address port 330.
port:i8
Same as the :i command. See :i.
port:i16
Inputs two bytes for display from port. port is an
address-specified I/O port.
port:i32
Inputs four bytes for display from port. port is an
address-specified I/O port.
port,data:o
Outputs a byte to port. port is an address-specified
I/O port. [address],[data]:o outputs the value data to
address I/O port. For example, 330,80:o outputs 80 to
address port 330.
port,data:o8
Same as the :o command. See port,data:o.
port,data:o16
Outputs two bytes to port. port is an address-
specified I/O port.
port,data:o32
Outputs four bytes to port. port is an address-
specified I/O port.
$q Prompts the user with:
Type 'y' if you really want to reboot.
Responding with a y or Y causes the system to reboot.
Responding with anything other than a y or Y returns
control to kadb. Use this feature when you cannot
press the reset switch on your machine. Because using
$q may result in data loss, this command should only
be used when you would press the reset switch or power
off your system.
Online Help Commands
::help
Displays the formats of kadb commands and extended
commands.
::? Same as the ::help command. See ::help.
::morehelp
Displays additional information about commonly used
commands and provides an explanation of data formats.
Scroll Control Feature
num::more
A common problem with using kadb is that scrolling is
sometimes too fast and that CTRL-s and CTRL-q are
inexact controls. A conditional scroll control feature
similar to more(1) has been added to kadb. To enable
this feature, the user specifies the number of lines
to be displayed, followed by ::more. For example, the
command 14::more displays 14 (current radix) lines,
followed by the --More-- prompt. At this prompt,
press: ENTER or RETURN to display one more line. Press
c, C, or CTRL-c to interrupt the display. Press any
other key to display the next num number of specified
lines (14 in this example). The command ::more
displays the current setting for the number of lines
that kadb displays before printing the --More--
prompt. The initial scroll control value of this
feature is 0, meaning that scrolling is disabled. Once
enabled, the 0::more command disables the scroll con-
trol feature.
Deferred Breakpoint Feature
Since the kernel is dynamically loaded, not all modules may
be loaded when a breakpoint is set kadb can set deferred
breakpoints which will be dynamically inserted when the
corresponding module is loaded. The module and the location
must both be specified when referring to a deferred break-
point, as follows:
module_name#location:
This syntax is implemented for kadb only and uses existing
breakpoint commands (for example, ufs#ufs_open:b or
ufs#ufs_open+4,5:b).
If the module has been loaded, kadb attempts to find the
symbol in the module specified. If kadb finds the symbol, it
sets a regular breakpoint. If it does not find the symbol,
it generates an error message and returns to the command
line without setting a breakpoint.
If kadb fails to find the module on the list of currently
loaded modules, it does not resolve the location. Instead,
it sends a message to the user and sets a deferred break-
point.
When the specified module is loaded, kadb tries to resolve
the location. If the location can be resolved, the deferred
breakpoint is converted to a regular breakpoint. If kadb
cannot resolve the location, a message is sent to the user,
and kadb halts execution. In this case, kadb does not con-
vert the deferred breakpoint to a regular breakpoint; it
removes it from the breakpoint table. The user may then re-
enter a correct breakpoint. Strict scoping is enforced, so
kadb does not look at any other module than the one speci-
fied with the location.
When specifying a deferred breakpoint in which the module
name contains a hyphen, you must escape the hyphen. For
example, for a module named pci-ide, enter:
pci\-ide#_init:b
The output from the the $b command indicates whether the
breakpoint is of type "deferred" (defr) or is another type.
FILES
/platform/platform-name/kadb
primary debugger path
/platform/hardware-class-name/kadb
alternative debugger path for some platforms
/platform/platform-name/kernel/unix
primary default 32-bit kernel
/platform/hardware-class-name/kernel/unix
alternative default 32-bit kernel for some platforms
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcar |
|_____________________________|_____________________________|
SEE ALSO
adb(1), more(1), uname(1), boot(1M), kernel(1M), attri-
butes(5), kb(7M)
SPARC Only
kbd(1), monitor(1M), obpsym(1M)
DIAGNOSTICS
When there is no current command or format, kadb comments
about syntax errors, abnormal termination of commands, and
the like.
WARNINGS
SPARC Only
On a SPARC based system, kadb cannot reliably single-step
over instructions which change the processor status regis-
ter.
SPARC and IA
If a breakpoint or watchpoint is triggered while the console
frame buffer is powered off, the system can crash and be
left in a state from which it is difficult to recover. If
one of these is triggered while the monitor is powered off,
you will not be able to see the debugger output.
NOTES
platform-name can be found using the -i option of uname(1).
hardware-class-name can be found using the -m option of
uname(1).
Man(1) output converted with
man2html