kadb(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | FILES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | WARNINGS | NOTES

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 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.

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 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 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 specified 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:

• 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.

• 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).

• Detection of an access breakpoint occurs after completion of the instruction that caused it.

• There are a limited number (4) of hardware breakpoint registers, and, when set, this uses one.

• As this breakpoint does not modify memory locations, 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 continued.

---

: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 executed.

: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.

$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:

---

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 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 breakpoint, 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 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 then re-enter a correct breakpoint. Strict scoping is enforced, so kadb does not look at any other module than the one specified 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 attributes:

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 register.

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).

SunOS 5.9  Last Revised 22 Mar 2001

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | FILES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | WARNINGS | NOTES