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 may be run on an active system to view system data.
The reason that the KDB Kernel Debugger and kdb command are both 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 which are unique; these involve manipulation of system image dumps.
The following sections outline how to invoke the KDB Kernel Debugger and kdb command. They also describe features which are unique to each.
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 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 may 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/mem. The KernelFile parameter contains the kernel symbol definitions. The default for the KernelFile is /usr/lib/boot/unix.
Root permissions are required for execution of the kdb command on the active system. This is required because the special file /dev/mem is used. To run the kdb command on the active system, enter:
kdb
To invoke the kdb command on a system image file, enter:
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.
Notes:
- When using the kdb command a kernel file must be available.
- Stack tracing of the current process on a running system does not work
The KDB Kernel Debugger is used for debugging the kernel, device drivers, and other kernel extensions. The KDB Kernel Debugger provides the following functions:
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 bosdebug and bosboot commands must be used. The first step in preparing a boot image to include the KDB Kernel Debugger is to set an indicator that the KDB Kernel is to be used in building the boot image, this indicator is checked by the bosboot command which actually builds the boot images. To set the indicator that a KDB Kernel is to be used in building building boot images is accomplished by executing the following command:
bosdebug -K
This indicator may be turned off by executing the following command:
bosdebug -o
Note, execution of the above command clears all flags set by previous invocations of bosdebug. Therefore, it may be necessary to execute additional bosdebug commands if there are debug options which need to be enabled.
To complete the task of building a boot image with the KDB Kernel, the bosboot command must be executed. The following commands may be used to build a boot image using a KDB Kernel:
The above commands build boot images using the KDB Kernel (if previously selected by bosdebug) having the following characteristics: 1) KDB Kernel debugger is disabled, 2) KDB Kernel Debugger is enabled but is not invoked during system initialization, 3) KDB Kernel Debugger is enabled and is invoked during system initialization. Note, execution of the bosboot builds the boot image only; the boot image is not used until the machine is restarted.
Notes:
- External interrupts are disabled while the KDB Kernel Debugger is active
- If invoked during system initialization the g subcommand must be issued to continue the initialization process.
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 may be used to connect to the target machine and run the KDB Kernel Debugger.
Attention: If a serial device, other than a terminal connected to a native serial port, is selected by the kernel debugger, the system may appear to hang up.
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 above key sequence), you must load it. To do this, see Loading and Starting the KDB Kernel Debugger.
Note: You can use the kdb command to determine whether the KDB Kernel Debugger is available. Use the dw subcommand:# kdb (0)> dw kdb_avail (0)> dw kdb_wantedIf either of the above 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.
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 which are unique to these systems. Refer to SMP Subcommands for details.
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 AIX 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.
The KDB Kernel Debugger creates a table of breakpoints that it maintains. When a breakpoint is set, the debugger temporarily replaces the corresponding instruction with the trap instruction. The instruction overlaid by the breakpoint operates when you issue any subcommand that would cause that instruction to be executed.
For more information on setting/clearing breakpoints and execution control see Breakpoints/Steps Subcommands and Setting Breakpoints.