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 ] [ b-flags ]
select (b)oot or (i)nterpreter: i kadb [ −d ] [ b-flags ]
DESCRIPTION
The utility kadb is an interactive debugger with a user interface similar to that of 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 processors, should they be present in a system.
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’) 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.
In the case of the UNIX system kernel, the keyboard abort sequence will suspend kernel operations and break into the debugger. This behavior may be disabled via the kbd(1) command and may not be the current default on all systems. See kb(7M) for more information.
On a SPARC based system, the keyboard abort sequence is L1-A for the console, and BREAK for a serial line. On an x86 based system, the keyboard abort sequence is CTRL-ALT-D for the console. kadb gives the prompt:
kadb[#]
where # is the CPU it is currently executing on.
Since the kernel is composed of the core image file (kernel/unix) and the set of loadable modules already in memory, kadb has the capability 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 will set the ’−d’ flag by default so the program being debugged can tell it is being watched. If this flag is not given, kadb will load and immediately run the default kernel .
On a SPARC based system, device-specifier specifies the device from which to load. See monitor(1M).
On an x86 based system, select boot (b kadb) or interpreter (i kadb).
Most adb(1) commands function in kadb as expected. As with ‘adb −k’, $p works when debugging kernels. The verbs ? and / are equivalent in kadb, since there is only one address space in use.
Additional Commands
kadb has the following additional commands. Note: for the general syntax of adb commands, see adb(1).
[ 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.
:a Sets a hardware access (read or write) breakpoint using the processor hardware facilities. The syntax and action for this is the same as :b in adb(1), with the following exceptions:
• The breakpoint will trigger if any bytes from the breakpoint for length bytes are being accessed. See $l below for setting the length of a hardware breakpoint.
• 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 (long).
• For an access to be detected, it must complete the instruction that caused the access. This means that this breakpoint will stop after the access, not before.
• There are a limited number (4) of hardware breakpoint registers and, when set, this will use one.
• Since this breakpoint does not modify memory locations, this will work on locations that are not in core at the time the breakpoint is set.
:w Like :a above, but will only breakpoint on a write to the specified address.
:p Like :a above, but will only breakpoint when an instruction at the specified address is run. Note that the $l operation has no effect on this type of breakpoint. This breakpoint will occur before the instruction is executed.
$l Sets the default data length for an access or write breakpoint. The syntax for this command is [length]$l. The length can be set to 1 for byte, 2 for short, and 4 for long word accesses. If length is left off, byte will be assumed. Once set, this value will affect any newly set access or write breakpoints, but will not affect ones set before this operation.
$b Has two additional columns that adb(1) does not have. 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.
Additional x86 Commands
:i Will input a byte for display from the address-specified I/O port. For example, 330:i will input from address port 330.
:o Will output a byte to the address-specified I/O port. [address],[data]:o will output data byte to address I/O port. For example 330,80:o will output 80 to address port 330.
Additional UltraSparc Commands
<N>:x Switch the active CPU to <N>. Thereafter, commands such as $r and $c will display the registers and stack of the new CPU.
Deferred Breakpoint Feature
Deferred breakpoints may be set by telling kadb the module and the location within the module at which the break point is to be set. The command syntax to set or to delete a deferred breakpoint is:
module_name#location:
This syntax, which is implemented for kadb only and not adb, utilizes existing breakpoint commands. For example,
ufs#ufs_open:b
or
ufs#ufs_open+4,5:b
If the module has been loaded, kadb will try 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 will not resolve the location. Instead, it sends a message to the user and sets a deferred breakpoint.
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 convert the deferred breakpoint to a regular breakpoint; it removes it from the breakpoint table. The user may re-enter a correct breakpoint at this time. Strict scoping is enforced, so kadb will not look at any other module than the one specified with the location.
The output from the the $b command will indicate whether the breakpoint is of type "deferred" (defr) or is another type.
OPTIONS
The following options are supported:
−d Interactive startup. If this flag is given, kadb will stop after it is loaded and display the prompt as kadb: and the name of the default program to debug.
For example:
kadb: kernel/unix
The user may either press RETURN to use the default, or BACK SPACE and type in the name of another program to debug.
boot-flags
You can specify boot flags as arguments when invoking kadb. Boot flags are passed to the program being debugged. See the manual page boot(1M) for relevant boot flags.
USAGE
Kernel Macros
As with adb(1), macros can be used with kadb, but they cannot be read from a file at runtime. The kadb command $M lists all the macros built into kadb.
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 kernel
/platform/hardware-class-name/kernel/unix
alternative default kernel for some platforms
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Availability | SUNWcar |
SEE ALSO
adb(1), uname(1), boot(1M), attributes(5), kb(7M)
SPARC Only
kbd(1), kernel(1M), 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 register.
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).
x86 Only
When using the x86 platform, the kadb -d command halts execution at _start if there is not enough thread or cpu information available from which to set a deferred breakpoint. To attempt to set a deferred breakpoint from this point results in a non-fatal trap by kadb. The user may continue without ill effects. However, it is recommended that the user on an x86 platform place a second breakpoint after _start at main. Setting a deferred breakpoint will be successful when this breakpoint is hit.
SunOS 5.6 — Last change: 2 Jun 1997