This document describes the KDB Kernel Debugger and kdb command. It is important to understand that the KDB Kernel Debugger and the kdb command are two separate entities. The KDB Kernel Debugger is a debugger for use in debugging the kernel, device drivers, and other kernel extensions. The kdb command is primarily a tool for viewing data contained in system image dumps. However, the kdb command can be run on an active system to view system data.
The reason that the KDB Kernel Debugger and kdb command are covered together is that they share a large number of subcommands. This provides for ease of use when switching from between the kernel debugger and command. Most subcommands for viewing kernel data structures are included in both. However, the KDB Kernel Debugger includes additional subcommands for execution control (breakpoints, step commands, etc...) and processor control (start/stop CPUs, reboot, etc...). The kdb command also has subcommands that are unique; these involve manipulation of system image dumps.
The following sections outline how to invoke the KDB Kernel Debugger and kdb command.
The kdb command is an interactive tool that allows examination of an operating system image. An operating system image is held in a system dump file; either as a file or on the dump device. The kdb command can also be used on an active system for viewing the contents of system structures. This is a useful tool for device driver development and debugging. The syntax for invoking the kdb command is:
kdb [SystemImageFile [KernelFile]]
The SystemImageFile parameter specifies the file that contains the system image. The default SystemImageFile is /dev/pmem. The KernelFile parameter contains the kernel symbol definitions. The default for the KernelFile is /unix.
Root permissions are required for execution of the kdb command on the active system. This is required because the special file /dev/pmem is used. To run the kdb command on the active system, type:
kdb
To invoke the kdb command on a system image file, type:
kdb SystemImageFile
where SystemImageFile is either a file name or the name of the dump device. When invoked to view data from a SystemImageFile the kdb command sets the default thread to the thread running at the time the SystemImageFile was created.
The complete list of subcommands available for the KDB Kernel Debugger and kdb command are included in Subcommands for the KDB Kernel Debugger and kdb Command.
The KDB Kernel Debugger is used for debugging the kernel, device drivers, and other kernel extensions. The KDB Kernel Debugger provides the following functions:
When the KDB Kernel Debugger is invoked, it is the only running program. All processes are stopped and interrupts are disabled. The KDB Kernel Debugger runs with its own Machine State Save Area (mst) and a special stack. In addition, the KDB Kernel Debugger does not run operating system routines. Though this requires that kernel code be duplicated within KDB, it is possible to break anywhere within the kernel code. When exiting the KDB Kernel Debugger, all processes continue to run unless the debugger was entered via a system halt.
The KDB Kernel debugger must be loaded and started before it can accept commands. Once in the debugger, use the commands to investigate and make alterations. See Subcommands for the KDB Kernel Debugger and kdb Command for lists and descriptions of the subcommands.
Register values can be referenced by the KDB Kernel Debugger and kdb command. Register values can be used in subcommands by preceding the register name with an "@" character. This character is also used to dereference addresses as described in Expressions. The list of registers that can be referenced include:
| asr | Address space register |
| cr | Condition register |
| ctr | Count register |
| dar | Data address register |
| dec | Decrementer |
| dsisr | Data storage interrupt status register |
| fp0-fp31 | Floating point registers 0 through 31 |
| fpscr | Floating point status and control register |
| iar | Instruction address register |
| lr | Link register |
| mq | Multiply quotient |
| msr | Machine State register |
| r0-r31 | General Purpose Registers 0 through 31 |
| rtcl | Real Time clock (nanoseconds) |
| rtcu | Real Time clock (seconds) |
| s0-s15 | Segment registers |
| sdr0 | Storage description register 0 |
| sdr1 | Storage description register 1 |
| srr0 | Machine status save/restore 0 |
| srr1 | Machine status save/restore 1 |
| tbl | Time base register, lower |
| tbu | Time base register, upper |
| tid | Transaction register (fixed point) |
| xer | Exception register (fixed point) |
Other special purposes registers that can be referenced, if supported on the hardware, include: sprg0, sprg1, sprg2, sprg3, pir, fpecr, ear, pvr, hid0, hid1, iabr, dmiss, imiss, dcmp, icmp, hash1, hash2, rpa, buscsr, l2cr, l2sr, mmcr0, mmcr1, pmc1-pmc8, sia, and sda.
The KDB Kernel Debugger and kdb command do not provide full expression processing. Expressions can only contain symbols, hexadecimal constants, references to register or memory locations, and operators. Furthermore, symbols are only allowed as the first operand of an expression. Supported operators include:
| Operator | Definition |
|---|---|
| + | Addition |
| - | Subtraction |
| * | Multiplication |
| / | Division |
| @ | Dereferencing |
The dereference operator indicates that the value at the location indicated by the next operand is to be used in the calculation of the expression. For example, @f000 would indicate that the value at address 0x0000f000 should be used in evaluation of the expression. The dereference operator is also used to access the contents of register. For example, @r1 references the contents of general purpose register 1. Recursive dereferencing is allowed. As an example, @@r1 references the value at the address pointed to by the value at the address contained in general purpose register 1.
Expressions are processed from left to right only. There is no operator precedence.
| Valid Expressions | Results |
|---|---|
| dw @r1 | displays data at the location pointed to by r1 |
| dw @@r1 | displays data at the location pointed to by value at location pointed to by r1 |
| dw open | displays data at the address beginning of the open routine |
| dw open+12 | displays data twelve bytes past the beginning of the open routine |
| Invalid Expressions | Problem |
| dw @r1+open | symbols can only be the first operand |
| dw r1 | must include @ to reference the contents of r1, if a symbol r1 existed this would be valid |
| dw @r1+(4*3) | parentheses are not supported |
The KDB Kernel Debugger must be loaded at boot time. This requires that a boot image be created with the debugger enabled. To enable the KDB Kernel Debugger, the bosboot command must be invoked with a KDB kernel specified and options set to enable the KDB Kernel Debugger. KDB kernels are shipped as /usr/lib/boot/unix_kdb for UP systems and /usr/lib/boot/unix_mp_kdb for MP systems; as opposed to the normal kernels of /usr/lib/boot/unix_up and /usr/lib/boot/unix_mp. The specific kernel to be used in creation of the boot image can be specified using the -k option of bosboot. The kernel debugger must also be enabled using either the -I or -D options of bosboot.
Example bosboot commands:
The previous commands build boot images using the KDB Kernel for a UP system having the following characteristics:
Execution of bosboot builds the boot image only; the boot image is not used until the machine is restarted. The file /usr/lib/boot/unix_mp_kdb would be used instead of /usr/lib/boot/unix_kdb for an MP system.
The links /usr/lib/boot/unix and /unix are not changed by bosboot. However, these links are used by user commands such as sar and others to read symbol information for the kernel. Therefore, if these commands are to be used with a KDB boot image /unix and /usr/lib/boot/unix must point to the kernel specified for bosboot. This can be done by removing and recreating the links. This must be done as root. For the previous bosboot examples, the following would set up the links correctly:
Similarly, if you chose to quit using a KDB Kernel then the links for /unix and /usr/lib/boot/unix should be modified to point to the kernel specified to bosboot.
Note that /unix is the default kernel used by bosboot. Therefore, if this link is changed to point to a KDB kernel, following bosboot commands which do not have a kernel specified will use the KDB kernel unless this link is changed.
For AIX 5.1 and subsequent releases, the KDB Kernel Debugger is the standard kernel debugger and is included in the unix_up and unix_mp kernels, which may be found in /usr/lib/boot.
The KDB Kernel Debugger must be loaded at boot time. This requires that a boot image be created with the debugger enabled. To enable the KDB Kernel Debugger, the bosboot command must be invoked with options set to enable the KDB Kernel Debugger. The kernel debugger can be enabled using either the -I or -D options of bosboot.
Examples of bosboot commands:
The previous commands build boot images using the KDB Kernel Debugger having the following characteristics:
Execution of bosboot builds the boot image only; the boot image is not used until the machine is restarted.
It is possible to enter the KDB Kernel Debugger using one of the following procedures:
brkpoint();
If the kernel debug program is not available (nothing happens when you type in the previous key sequence), you must load it. To do this, refer to Loading and Starting the KDB Kernel Debugger in AIX 4.3.3 or Loading and Starting the KDB Kernel Debugger in AIX 5.1 and Subsequent Releases.
# kdb (0)> dw kdb_avail (0)> dw kdb_wantedIf either of the previous dw subcommands returns a 0, the KDB Kernel Debugger is not available.
Once the KDB Kernel Debugger has been invoked, the subcommands detailed in Subcommands for the KDB Kernel Debugger and kdb Command are available.
The KDB Kernel Debugger opens an asynchronous ASCII terminal when it is first started, and subsequently upon being started due to a system halt. Native serial ports are checked sequentially starting with port 0 (zero). Each port is configured at 9600 bps, 8 bits, and no parity. If carrier detect is asserted within 1/10 seconds, then the port is used. Otherwise, the next available native port is checked. This process continues until a port is opened or until every native port available on the machine has been checked. If no native serial port is opened successfully, then the result is unpredictable.
The KDB Kernel Debugger only supports display to an ASCII terminal connected to a native serial port. Displays connected to graphics adapters are not supported. The KDB Kernel Debugger has its own device driver for handling the display terminal. It is possible to connect a serial line between two machines and define the serial line port as the port for the console. In that case, the cu command can be used to connect to the target machine and run the KDB Kernel Debugger.
On multiprocessor systems, entering the KDB Kernel Debugger stops all processors (except the current processor running the debug program itself). The prompt on multiprocessor systems indicates the current processor. For example:
In addition to the change in the prompt for multiprocessor systems, there are also subcommands that are unique to these systems. Refer to SMP Subcommands for details.
The trcpeek feature of KDB allows users to perform a system trace. It allows users to break into KDB and start, stop and display a system trace. For more information on system trace, see Trace Facility in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
If the system is in a working state, it is best to use the system trace facility and the trace command. trcpeek is most useful when the system is hung and will not respond to terminal input, or when the system is initializing and the trace kernel extension has not been loaded. trcpeek can be useful to determine where the kernel code is looping. It is also helpful in early system initialization debugging. For more information, see the trace command in AIX 5L Version 5.2 Commands Reference, Volume 5.
Only one trace event can be active at a time. A trace can be started from either the system trace facility at the shell prompt, or from KBD at the KDB debugger prompt. If a trace is started from KDB and the system crashes, trace information can be extracted from the dump using the trcdead command. For more information, see the trcdead command in AIX 5L Version 5.2 Commands Reference, Volume 5.
trcpeek consists of the trcstart, trcstop and trace subcommands. For more information, see trcstart Subcommand, trcstop Subcommand, and trace Subcommand.