Kernel Execution Control

This chapter describes the MDB features for execution control of the live operating system kernel available when running kmdb. kmdb is a version of MDB specifically designed for kernel execution control and live kernel debugging. Using kmdb, the kernel can be controlled and observed in much the same way that a user process can be controlled and observed using mdb. The kernel execution control functionality includes instruction-level control of kernel threads executing on each CPU, enabling developers to single-step the kernel and inspect data structures in real time.

Both mdb and kmdb share the same user interface. All of the execution control functionality described in Execution Control is available in kmdb, and is identical to the set of commands used to control user processes. The commands used to inspect kernel state, described in MDB Language Syntax and Built-In Commands, are also available when using kmdb. Finally, the commands specific to the illumos kernel implementation, described in Kernel Debugging Modules, are available unless otherwise noted. This chapter describes the remaining features that are specific to kmdb.

7.1. Booting, Loading, and Unloading

To facilitate the debugging of kernel startup, kmdb can be loaded during the earliest stages of the boot process, before control has passed from the kernel runtime linker (krtld) to the kernel. kmdb may be loaded at boot using the -k boot flag, the kmdb boot file, or the kadb boot file (for compatibility). If kmdb is loaded at boot, the debugger cannot be unloaded until the system subsequently reboots. Some functionality will not be immediately available during the earliest stages of boot. In particular, debugging modules will not be loaded until the kernel module subsystem has initialized. Processor-specific functionality will not be enabled until the kernel has completed the processor identification process.

If you boot your system using the -k option, kmdb will automatically load during the boot process. You can use the -d boot option to request a debugger breakpoint prior to starting the kernel. This feature works with the default kernel as well as alternate kernels. For example, to boot a SPARC system with kmdb and request immediate entry to the debugger, type any of the following commands: 

ok boot -kd
ok boot kmdb -d
ok boot kadb -d

To boot an x86 system in the same manner, type any of the following commands: 

Select (b)oot or (i)nterpreter: b -kd
Select (b)oot or (i)nterpreter: b kmdb -d
Select (b)oot or (i)nterpreter: b kadb -d

To boot a SPARC system with kmdb and load an alternate 64–bit kernel, type the following command: 

ok boot kernel.test/sparcv9/unix -k

To boot an x86 system with  kmdb and load an alternate 64–bit kernel, type the following command: 

Select (b)oot or (i)nterpreter: b kernel.test/amd64/unix -k

If the boot file is set to the string kmdb or kadb and you want to boot an alternate kernel, use the -D option to specify the name of the kernel to boot. To boot a SPARC system in this manner, type the following command: 

ok boot kmdb -D kernel.test/sparcv9/unix

To boot a 32–bit x86 system in this manner, type the following command: 

Select (b) or (i)nterpreter: b kmdb -D kernel.test/unix

To boot a 64–bit x86 system in this manner, type the following command: 

Select (b) or (i)nterpreter: b kmdb -D kernel.test/amd64/unix

To debug a system that has already booted, use the mdb -K option to load kmdb and stop kernel execution. When the debugger is loaded using this method, it can be subsequently unloaded. You can unload kmdb when you are done debugging by specifying the -u option to the ::quit dcmd. Alternatively, you can resume execution of the operating system using the command mdb -U.

7.2. Terminal Handling

kmdb always uses the system console for interaction. kmdb will determine the appropriate terminal type according to the following rules:

You can use the ::term dcmd from within kmdb to display the terminal type.

7.3. Debugger Entry

The operating system kernel will implicitly stop executing and enter kmdb when a breakpoint is reached or according to the other execution control settings described in Execution Control. You can use the mdb -K option or an appropriate keyboard break sequence to request explicit entry to kmdb. On a SPARC system console, use the STOP-A key sequence to send a break and enter kmdb. On an x86 system console, use the F1–A key sequence to send a break and enter kmdb. You can use the kbd command to customize the escape sequence on your illumos system. To enter kmdb on a system with a serial console, use the appropriate serial console command to send a break sequence.

7.4. Processor-Specific Features

Some kmdb functionality is specific to an individual processor architecture. For example, various x86 processors support a hardware branch tracing capability that is not found on some other processor architectures. Access to processor-specific features is provided through processor-specific dcmds that are only present on systems that support them. The availability of processor-specific support will be indicated in the output of the ::status dcmd. The debugger relies upon the kernel to determine the processor type. Therefore, even though the debugger may provide features for a given processor architecture, this support will not be exposed until the kernel has progressed to the point where processor identification has completed.