SunOS man pages : kadb (1)
Maintenance Commands kadb(1M)
NAME
kadb - a kernel debugger
SYNOPSIS
SPARC
ok boot device_specifier kadb [ -d ] [ boot-flags ]
> b kadb [ -d ] [ boot-flags ]
IA
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 stan-
dalone program, so it shares many resources with that pro-
gram. The debugger is cognizant of and able to control mul-
tiple processors, 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 key-
board facilities (CTRL-C, CTRL-S, and CTRL-Q) are simu-
lated.
SunOS 5.8 Last change: 30 Jul 1998 1
Maintenance Commands kadb(1M)
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 capa-
bility 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
SunOS 5.8 Last change: 30 Jul 1998 2
Maintenance Commands kadb(1M)
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
IA based systems).
] Performs the same function as :s in adb(1), but
requires only one keystroke and no RETURN (ENTER on
IA 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
command 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.
SunOS 5.8 Last change: 30 Jul 1998 3
Maintenance Commands kadb(1M)
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 ? com-
mands. 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 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 con-
tinued.
: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 IA I/O space.
See :a.
:w Sets a write hardware access breakpoint using the
processor 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.
SunOS 5.8 Last change: 30 Jul 1998 4
Maintenance Commands kadb(1M)
$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.
IA
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:
SunOS 5.8 Last change: 30 Jul 1998 5
Maintenance Commands kadb(1M)
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 dis-
abled. Once enabled, the 0::more command disables the
scroll control 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:
SunOS 5.8 Last change: 30 Jul 1998 6
Maintenance Commands kadb(1M)
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 sym-
bol, it generates an error message and returns to the com-
mand 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.
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:
SunOS 5.8 Last change: 30 Jul 1998 7
Maintenance Commands kadb(1M)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcar |
|_____________________________|_____________________________|
SEE ALSO
adb(1), more(1), uname(1), boot(1M), kernel(1M), attributes(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.
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).
SunOS 5.8 Last change: 30 Jul 1998 8
|
 |
|
|
