User Commands kmdb(1)
NAME
kmdb - in situ kernel debugger
SYNOPSIS
Boot-time Loading
SPARCok boot [device-specifier] -k [-d] [boot-flags]
ok boot [device-specifier] kmdb [-d] [boot-flags]
x86kernel$ /platform/i86pc/kernel/$ISADIR/unix -k [-d] [boot-flags]
Runtime Loadingmdb -K
DESCRIPTION
kmdb is an interactive kernel debugger which implements the
user interface and functionality of mdb(1) in a live kernelcontext. kmdb provides features that allow for the control
of kernel execution and for the inspection and modificationof live kernel state. kmdb can be loaded at the beginning of
a boot session or after the system is booted. This man page describes the features and functionality thatare unique to kmdb or different in kmdb as compared to
mdb(1). For more information on mdb(1) or further details onthe features and functionality implemented by kmdb, see the
mdb(1) man page and the Oracle Solaris Modular Debugger Guide. Loading and UnloadingBoot-time Loading
When requested, the kernel runtime linker (krtld) loadskmdb prior to the transfer of control to the kernel. If
the -d flag is used, the debugger gains control of the
system prior to the execution of the initial function inthe unix object. If -d is not used, kmdb is loaded but
does not gain control until such time as it is expli-
citly entered. See the Debugger Entry section below. Fora list of the boot commands which cause kmdb to be
loaded at boot, see the SYNOPSIS section above. See
eeprom(1M) for an example of the use of that command onSunOS 5.11 Last change: 28 Oct 2009 1
User Commands kmdb(1)
a SPARC machine to specify that kmbd is always loaded upon boot.Boot-loaded kmdb can be unloaded only by means of a sys-
tem reboot.Some features of kmdb rely on the presence of kernel
services and are not immediately available to boot-
loaded kmdb. In particular, the loading and unloading of
dmods is not available until the module subsystem isinitialized. Requests are queued until they can be pro-
cessed. Similarly, translation of virtual addresses tophysical addresses is not be available until the VM sys-
tem has been initialized. Attempted translations fail until translation facilities are available.Run-time Loading
kmdb can also be loaded after the system has booted,
using the -K flag to mdb(1). When loaded in this
fashion, it will immediately gain control of the system.Run-time-loaded kmdb can be unloaded using the -U flag
to mdb(1) or from within the debugger with the -u flag
to the ::quit dcmd. Terminal typesWhen loaded, kmdb attempts to determine the proper ter-
minal type in use on the system console. If the system being debugged has an attached keyboard and localdisplay that are both used for the system console, kmdb
uses the terminal type appropriate for the machine:'sun' for SPARC; 'sun-color' for x86. When a serial con-
sole is in use, boot-loaded kmdb defaults to a terminal
type 'vt100'. Run-time-loaded kmdb defaults to the ter-
minal type requested by mdb(1). mdb(1) requests the ter-
minal type specified by the value of the TERM environ-
ment variable unless overridden by the -T flag. ::term
can be used to view the current terminal type. Debugger Entry Debugger entry can be requested explicitly or implicitly.Implicit entry, encountered when breakpoints or other execu-
tion control features are used, is discussed in the Execu-
tion Control section. The primary means for explicit debugger entry is with the keyboard abort sequence for systems with local consoles andSunOS 5.11 Last change: 28 Oct 2009 2
User Commands kmdb(1)
the BREAK character for those with serial consoles. Theabort sequence is STOP-A or Shift-Pause for SPARC systems
with local consoles, and F1-A or Shift-Pause for x86 systems
with local consoles. See kbd(1) for a discussion of the abort sequence and for instructions on disabling it. A second way to request entry into the debugger is with themdb(1) command. Invocations of mdb(1) with the -K flag after
the debugger is loaded trigger debugger entry.If the kernel panics and kmdb is loaded, by default, the
panic routine enters kmdb for live debugging. If a dump dev-
ice is specified, and you enter ::cont, the debugger exits and a crash dump is performed. To prevent the kernel fromentering kmdb when panicking, you can set the nopanicdebug
variable to 1. Set the nopanicdebug variable to 1 using kmdb
or including the following a line in /etc/system: set nopanicdebug = 1This can be useful if you want to keep kmdb loaded, but
always want a panic to trigger a crash dump without entering the debugger. Execution Control For the most part, the execution control facilities providedby kmdb for the kernel mirror those provided by the mdb(1)
process target. Breakpoints (::bp), watchpoints (::wp), ::continue, and the various flavors of ::step can be used.In contrast to the unlimited user process watchpoints sup-
plied by the kernel, kmdb is restricted to a set of CPU
watchpoints that limit the number, size, and type of watch-
points allowed. The ::wp command does not allow a watchpoint to be created if it is incompatible with the watchpoints supported by the hardware. Debugger modules (dmods)As with mdb(1), kmdb is installed with a number of
subsystem-specific debugger modules, or dmods. The dmods are
loaded and unloaded automatically with the loading and unloading of the subsystems that they support. The dmods can also be explicitly loaded and unloaded using ::load and ::unload.SunOS 5.11 Last change: 28 Oct 2009 3
User Commands kmdb(1)
kmdb uses kernel facilities to load and unload dmods and
must resume system execution to perform each requested action. When a dmod load or unload is complete, the systemis stopped and the debugger is automatically re-entered. For
a dmod load, processing is completed when the load of arequested dmod succeeds or fails. Status messages are pro-
vided in either case.Processor-specific functionality
Some functionality is specific to an individual processor type. An example of such functionality is the branch tracing provided by various x86 processors. Access to theseprocessor-specific features is provided with processor-
specific dcmds that are present only on systems that supportthem. The availability of processor-specific support is
indicated in the output of the ::status dcmd. The debugger relies on the kernel to determine the processor type. Eventhough the debugger might provide support for a given pro-
cessor type, the support is not exposed until the kernel has progressed to the point at which processor identification has completed. Kernel Macros The debugger provides access to a set of macros that are precompiled into the debugger. Only the precompiled macrosare available . Unlike with mdb(1), the $< dcmd may not be
used to load macros from arbitrary locations. Use the $M
command to list the available macros.Built-in dcmds
This section lists dcmds that are unique to kmdb or those
with behavior that differs in kmdb as compared to mdb(1).
[address]::bp [+/-dDestT] [-c cmd] [-n count] sym ...
address :b [cmd ...] Set a breakpoint at the specified locations. The ::bpdcmd sets a breakpoint at each address or symbol speci-
fied, including an optional address specified by an explicit expression preceding the dcmd, and each string or immediate value following the dcmd. The arguments canbe symbol names or immediate values denoting a particu-
lar virtual address of interest. If a symbol name is specified, the name may refer to a symbol that cannot yet be evaluated. It might consist of an object name and function name in a load object that has not yet been opened. In such a case, the breakpoint is deferred and is not active in the target until an object matching the given name is loaded. The breakpoint is automatically enabled when the load object is opened.SunOS 5.11 Last change: 28 Oct 2009 4
User Commands kmdb(1)
The -d, -D, -e, -s, -t, -T, -c, and -n options have the
same meaning as they do for the ::evset dcmd. See mdb(1) for a description of ::evset. If the :b form of the dcmd is used, a breakpoint is set only at the virtual address specified by the expression preceding the dcmd. The arguments following the :b dcmd are concatenated together to form the callback string. If this stringcontains meta-characters, it must be quoted.
::branches [-v]
(x86 only) Display the last branches taken by the CPU. This dcmd is supported only on x86 systems, and is available onlywhen processor-specific support is detected and enabled.
The number and type of branches displayed is dependent on the capabilities of the branch tracing facilitiesprovided by the CPU. When the -v option is used, the
instructions prior to a given branch are displayed. [function] ::call [arg [arg ...]]Call the specified function using the specified argu-
ments. The called function must be listed as a functionin the symbol table for a loaded module. String argu-
ments are passed by reference. When the call completes, the return value of the function is displayed. This dcmd must be used with extreme caution. The kernel will not be resumed when the call is made. The function being called may not make any assumptions regarding theavailability of any kernel services, and must not per-
form operations or calls that may block. The user mustalso beware of any side-effects introduced by the called
function, as kernel stability might be affected.[addr] ::cpuregs [-c cpuid]
Display the current general purpose register set for the specified CPU, in the format used by ::regs.[addr] ::cpustack [-c cpuid]
Print a C stack backtrace for the specified CPU. Thebacktrace displayed is for the point at which the speci-
fied CPU entered or was stopped by the debugger.SunOS 5.11 Last change: 28 Oct 2009 5
User Commands kmdb(1)
addr[,len] ::in [-L len]
(x86 only)Read len bytes from the I/O port specified by addr. The
value of the -L option, if provided, takes precedence
over the value of the repeat count. The read length must be 1, 2, or 4 bytes, and the port address must have the same alignment as the length.addr[,len] ::out [-L len] value
(x86 only)Write value to the len-byte I/O port specified by addr.
The value of the -L option, if provided, takes pre-
cedence over the value of the repeat count. The write length must be 1, 2, or 4 bytes and the port address must have the same alignment as the length.::quit [-u]
$q
Causes the debugger to exit. When the -u option is used,
the system is resumed and the debugger is unloaded. The-u option may not be used if the debugger was loaded at
boot. When the -u option is not used, SPARC systems will
exit to the boot PROM ok prompt. The go command can beused to re-enter the debugger. On x86 systems, a prompt
is displayed that requests permission to reboot the machine. ::step [over|out|branch]Step the target one instruction. The optional over argu-
ment is used to step over subroutine calls. When the optional out argument is specified, the target programcontinues until control returns from the current func-
tion. The optional branch argument is available only on x86systems when processor-specific support is detected and
enabled. When ::step branch is specified, the target program continues until the next branching instruction is encountered. On SPARC systems, the ::step dcmd may not be used to step 'ta' instructions. Similarly, it may not be used on x86 systems to step 'int' instructions. If the step results in a trap that cannot be resolved by the debugger, a message to that effect is printed and theSunOS 5.11 Last change: 28 Oct 2009 6
User Commands kmdb(1)
step will fail. cpuid::switch cpuid:x Use the specified CPU as the representative. Stack traces, general purpose register dumps, and similar functionality use the new representative CPU as the datasource. Full execution control functionality is avail-
able on the new representative CPU. ::term Display the current terminal type.addr[,len]::wp [+/-dDestT] [-rwx] [-pi] [-n count] [-c cmd]
addr[,len]:a [cmd ...] addr[,len]:p [cmd ...] addr[,len]:w [cmd ...] Set a watchpoint at the specified address, interpretedby default as a virtual address. If the -p option is
used, the address is interpreted as a physical address.On x86 platforms, watchpoints can be set on I/O ports
using the -i option. When the -i option is used, the
address is interpreted as that of an I/O port. The length in bytes of the watched region can be set by specifying an optional repeat count preceding the dcmd. If no length is explicitly set, the default is one byte. The ::wp dcmd allows the watchpoint to be configured to
trigger on any combination of read (-r option), write
(-w option), or execute (-x option) access.
The -d, -D, -e, -s, -t, -T, -c, and -n options have the
same meaning as they do for the ::evset dcmd. See mdb(1) for a description of ::evset. The :a dcmd sets a read access watchpoint at the specified address. The :p dcmd sets an execute access watchpoint at the specified address. The :w dcmd sets a write access watchpoint at the specified address. The arguments following the :a, :p, and :w dcmds are concatenated together to form thecallback string. If the string contains meta-characters,
it must be quoted.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 28 Oct 2009 7
User Commands kmdb(1)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | system/kernel (debugger) ||_____________________________|_____________________________|
| | developer/debug/mdb (dmods) ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
mdb(1), boot(1M), dumpadm(1M), eeprom(1M), kernel(1M), sys-
tem(4), attributes(5) Oracle Solaris Modular Debugger Guide SPARC Only kbd(1) NOTES Limitations on Memory Available to the Debugger The memory region available to the debugger is allocated when the debugger is loaded, and is fixed at that point. If dcmds attempt to allocate more memory than is available, they will, if possible, be terminated. The debugger willattempt to recover gracefully from an out-of-memory situa-
tion, but may be unable to, and may be forced to terminatethe system. This constraint is especially acute on 32-bit
x86 systems. Performance ImpactSystem performance will be negatively impacted by the load-
ing of kmdb, as the debugger will consume kernel memory and
other limited system resources.Booting into kmdb to Capture panic() Stack
To troubleshoot a panic() on a SPARC machine, it can be use-
ful to use eeprom(1M) to specify that the system always loadkmdb upon booting. Following a panic, the system starts to
reboot, in so doing clearing the panic stack from the con-
sole. By booting into kmdb, one can capture and interpret
the panic stack. See eeprom(1M) for an example of specifyingthat kmdb load upon boot.
SunOS 5.11 Last change: 28 Oct 2009 8