1kmdb(1) User Commands kmdb(1)
2
6 kmdb - in situ kernel debugger
7
9 Boot-time Loading
10 SPARC
11 ok boot [device-specifier] -k [-d] [boot-flags]
13 ok boot [device-specifier] kmdb [-d] [boot-flags]
16 x86
20 kernel$ /platform/i86pc/kernel/$ISADIR/unix -k [-d] [boot-flags]
22 Runtime Loading
25 mdb -K
26
29 kmdb is an interactive kernel debugger which implements the user inter‐
30 face and functionality of mdb(1) in a live kernel context. kmdb pro‐
31 vides features that allow for the control of kernel execution and for
32 the inspection and modification of live kernel state. kmdb can be
33 loaded at the beginning of a boot session or after the system is
34 booted.
35 This man page describes the features and functionality that are unique
38 to kmdb or different in kmdb as compared to mdb(1). For more informa‐
39 tion on mdb(1) or further details on the features and functionality
40 implemented by kmdb, see the mdb(1) man page and the Solaris Modular
41 Debugger Guide.
42 Loading and Unloading
44 Boot-time Loading When requested, the kernel runtime linker (krtld)
45 loads kmdb prior to the transfer of control to the
46 kernel. If the -d flag is used, the debugger gains
47 control of the system prior to the execution of
48 the initial function in the 'unix' object. If -d
49 is not used, kmdb is loaded but does not gain con‐
50 trol until such time as it is explicitly entered.
51 See the Debugger Entry section below. For a list
52 of the boot commands which cause kmdb to be loaded
53 at boot, see the SYNOPSIS section above.
54 Boot-loaded kmdb can be unloaded only by means of
56 a system reboot.
57 Some features of kmdb rely on the presence of ker‐
59 nel services and are not immediately available to
60 boot-loaded kmdb. In particular, the loading and
61 unloading of dmods is not available until the mod‐
62 ule subsystem is initialized. Requests are queued
63 until they can be processed. Similarly, transla‐
64 tion of virtual addresses to physical addresses is
65 not be available until the VM system has been ini‐
66 tialized. Attempted translations fail until trans‐
67 lation facilities are available.
68 Run-time Loading kmdb can also be loaded after the system has
71 booted, using the -K flag to mdb(1). When loaded
72 in this fashion, it will immediately gain control
73 of the system. Run-time-loaded kmdb can be
74 unloaded using the -U flag to mdb(1) or from
75 within the debugger with the -u flag to the ::quit
76 dcmd.
77 Terminal types When loaded, kmdb attempts to determine the proper
80 terminal type in use on the system console. If the
81 system being debugged has an attached keyboard and
82 local display that are both used for the system
83 console, kmdb uses the terminal type appropriate
84 for the machine: 'sun' for SPARC; 'sun-color' for
85 x86. When a serial console is in use, boot-loaded
86 kmdb defaults to a terminal type 'vt100'. Run-
87 time-loaded kmdb defaults to the terminal type
88 requested by mdb(1). mdb(1) requests the terminal
89 type specified by the value of the TERM environ‐
90 ment variable unless overridden by the -T flag.
91 ::term can be used to view the current terminal
92 type.
93 Debugger Entry
96 Debugger entry can be requested explicitly or implicitly. Implicit
97 entry, encountered when breakpoints or other execution control features
98 are used, is discussed in the Execution Control section.
99 The primary means for explicit debugger entry is with the keyboard
102 abort sequence for systems with local consoles and the BREAK character
103 for those with serial consoles. The abort sequence is STOP-A or Shift-
104 Pause for SPARC systems with local consoles, and F1-A or Shift-Pause
105 for x86 systems with local consoles. See kbd(1) for a discussion of the
106 abort sequence and for instructions on disabling it.
107 A second way to request entry into the debugger is with the mdb(1) com‐
110 mand. Invocations of mdb(1) with the -K flag after the debugger is
111 loaded trigger debugger entry.
112 If the kernel panics and kmdb is loaded, by default, the panic routine
115 enters kmdb for live debugging. If a dump device is specified, and you
116 enter ::cont, the debugger exits and a crash dump is performed. To pre‐
117 vent the kernel from entering kmdb when panicking, you can set the
118 nopanicdebug variable to 1. Set the nopanicdebug variable to 1 using
119 kmdb or including the following a line in /etc/system:
120 set nopanicdebug = 1
122 This can be useful if you want to keep kmdb loaded, but always want a
127 panic to trigger a crash dump without entering the debugger.
128 Execution Control
130 For the most part, the execution control facilities provided by kmdb
131 for the kernel mirror those provided by the mdb(1) process target.
132 Breakpoints (::bp), watchpoints (::wp), ::continue, and the various
133 flavors of ::step can be used.
134 In contrast to the unlimited user process watchpoints supplied by the
137 kernel, kmdb is restricted to a set of CPU watchpoints that limit the
138 number, size, and type of watchpoints allowed. The ::wp command does
139 not allow a watchpoint to be created if it is incompatible with the
140 watchpoints supported by the hardware.
141 Debugger modules (dmods)
143 As with mdb(1), kmdb is installed with a number of subsystem-specific
144 debugger modules, or dmods. The dmods are loaded and unloaded automati‐
145 cally with the loading and unloading of the subsystems that they sup‐
146 port. The dmods can also be explicitly loaded and unloaded using ::load
147 and ::unload.
148 kmdb uses kernel facilities to load and unload dmods and must resume
151 system execution to perform each requested action. When a dmod load or
152 unload is complete, the system is stopped and the debugger is automati‐
153 cally re-entered. For a dmod load, processing is completed when the
154 load of a requested dmod succeeds or fails. Status messages are pro‐
155 vided in either case.
156 Processor-specific functionality
158 Some functionality is specific to an individual processor type. An
159 example of such functionality is the branch tracing provided by various
160 x86 processors. Access to these processor-specific features is provided
161 with processor-specific dcmds that are present only on systems that
162 support them. The availability of processor-specific support is indi‐
163 cated in the output of the ::status dcmd. The debugger relies on the
164 kernel to determine the processor type. Even though the debugger might
165 provide support for a given processor type, the support is not exposed
166 until the kernel has progressed to the point at which processor identi‐
167 fication has completed.
168 Kernel Macros
170 The debugger provides access to a set of macros that are precompiled
171 into the debugger. Only the precompiled macros are available . Unlike
172 with mdb(1), the $< dcmd may not be used to load macros from arbitrary
173 locations. Use the $M command to list the available macros.
174 Built-in dcmds
176 This section lists dcmds that are unique to kmdb or those with behavior
177 that differs in kmdb as compared to mdb(1).
178 [address]::bp [+/-dDestT] [-c cmd] [-n count] sym ...
180 address :b [cmd ...]
181 Set a breakpoint at the specified locations. The ::bp dcmd sets a
183 breakpoint at each address or symbol specified, including an
184 optional address specified by an explicit expression preceding the
185 dcmd, and each string or immediate value following the dcmd. The
186 arguments can be symbol names or immediate values denoting a par‐
187 ticular virtual address of interest.
188 If a symbol name is specified, the name may refer to a symbol that
190 cannot yet be evaluated. It might consist of an object name and
191 function name in a load object that has not yet been opened. In
192 such a case, the breakpoint is deferred and is not active in the
193 target until an object matching the given name is loaded. The
194 breakpoint is automatically enabled when the load object is opened.
195 The -d, -D, -e, -s, -t, -T, -c, and -n options have the same mean‐
197 ing as they do for the ::evset dcmd. See mdb(1) for a description
198 of ::evset. If the :b form of the dcmd is used, a breakpoint is set
199 only at the virtual address specified by the expression preceding
200 the dcmd. The arguments following the :b dcmd are concatenated
201 together to form the callback string. If this string contains meta-
202 characters, it must be quoted.
203 ::branches [-v]
206 (x86 only)
207 Display the last branches taken by the CPU. This dcmd is supported
209 only on x86 systems, and is available only when processor-specific
210 support is detected and enabled. The number and type of branches
211 displayed is dependent on the capabilities of the branch tracing
212 facilities provided by the CPU. When the -v option is used, the
213 instructions prior to a given branch are displayed.
214 [function] ::call [arg [arg ...]]
217 Call the specified function using the specified arguments. The
219 called function must be listed as a function in the symbol table
220 for a loaded module. String arguments are passed by reference. When
221 the call completes, the return value of the function is displayed.
222 This dcmd must be used with extreme caution. The kernel will not be
224 resumed when the call is made. The function being called may not
225 make any assumptions regarding the availability of any kernel ser‐
226 vices, and must not perform operations or calls that may block. The
227 user must also beware of any side-effects introduced by the called
228 function, as kernel stability might be affected.
229 [addr] ::cpuregs [-c cpuid]
232 Display the current general purpose register set for the specified
234 CPU, in the format used by ::regs.
235 [addr] ::cpustack [-c cpuid]
238 Print a C stack backtrace for the specified CPU. The backtrace dis‐
240 played is for the point at which the specified CPU entered or was
241 stopped by the debugger.
242 addr[,len] ::in [-L len]
245 (x86 only)
246 Read len bytes from the I/O port specified by addr. The value of
248 the -L option, if provided, takes precedence over the value of the
249 repeat count. The read length must be 1, 2, or 4 bytes, and the
250 port address must have the same alignment as the length.
251 addr[,len] ::out [-L len] value
254 (x86 only)
255 Write value to the len-byte I/O port specified by addr. The value
257 of the -L option, if provided, takes precedence over the value of
258 the repeat count. The write length must be 1, 2, or 4 bytes and the
259 port address must have the same alignment as the length.
260 ::quit [-u]
263 $q
264 Causes the debugger to exit. When the -u option is used, the system
266 is resumed and the debugger is unloaded. The -u option may not be
267 used if the debugger was loaded at boot. When the -u option is not
268 used, SPARC systems will exit to the boot PROM ok prompt. The go
269 command can be used to re-enter the debugger. On x86 systems, a
270 prompt is displayed that requests permission to reboot the machine.
271 ::step [over|out|branch]
274 Step the target one instruction. The optional over argument is used
276 to step over subroutine calls. When the optional out argument is
277 specified, the target program continues until control returns from
278 the current function.
279 The optional branch argument is available only on x86 systems when
281 processor-specific support is detected and enabled. When ::step
282 branch is specified, the target program continues until the next
283 branching instruction is encountered.
284 On SPARC systems, the ::step dcmd may not be used to step 'ta'
286 instructions. Similarly, it may not be used on x86 systems to step
287 'int' instructions. If the step results in a trap that cannot be
288 resolved by the debugger, a message to that effect is printed and
289 the step will fail.
290 cpuid::switch
293 cpuid:x
294 Use the specified CPU as the representative. Stack traces, general
296 purpose register dumps, and similar functionality use the new rep‐
297 resentative CPU as the data source. Full execution control func‐
298 tionality is available on the new representative CPU.
299 ::term
302 Display the current terminal type.
304 addr[,len]::wp [+/-dDestT] [-rwx] [-pi] [-n count] [-c cmd]
307 addr[,len]:a [cmd ...]
308 addr[,len]:p [cmd ...]
309 addr[,len]:w [cmd ...]
310 Set a watchpoint at the specified address, interpreted by default
312 as a virtual address. If the -p option is used, the address is
313 interpreted as a physical address. On x86 platforms, watchpoints
314 can be set on I/O ports using the -i option. When the -i option is
315 used, the address is interpreted as that of an I/O port.
316 The length in bytes of the watched region can be set by specifying
318 an optional repeat count preceding the dcmd. If no length is
319 explicitly set, the default is one byte. The ::wp dcmd allows the
320 watchpoint to be configured to trigger on any combination of read
321 (-r option), write (-w option), or execute (-x option) access.
322 The -d, -D, -e, -s, -t, -T, -c, and -n options have the same mean‐
324 ing as they do for the ::evset dcmd. See mdb(1) for a description
325 of ::evset. The :a dcmd sets a read access watchpoint at the speci‐
326 fied address. The :p dcmd sets an execute access watchpoint at the
327 specified address. The :w dcmd sets a write access watchpoint at
328 the specified address. The arguments following the :a, :p, and :w
329 dcmds are concatenated together to form the callback string. If the
330 string contains meta-characters, it must be quoted.
331
334 See attributes(5) for descriptions of the following attributes:
335 ┌─────────────────────────────┬─────────────────────────────┐
340 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
341 ├─────────────────────────────┼─────────────────────────────┤
342 │Availability │SUNWckr (debugger) │
343 ├─────────────────────────────┼─────────────────────────────┤
344 │ │SUNWmdbr (dmods) │
345 ├─────────────────────────────┼─────────────────────────────┤
346 │Interface Stability │Evolving │
347 └─────────────────────────────┴─────────────────────────────┘
348
350 mdb(1), boot(1M), dumpadm(1M), kernel(1M), system(4), attributes(5)
351 Solaris Modular Debugger Guide
354 SPARC Only
356 kbd(1)
357
359 Limitations on Memory Available to the Debugger
360 The memory region available to the debugger is allocated when the
361 debugger is loaded, and is fixed at that point. If dcmds attempt to
362 allocate more memory than is available, they will, if possible, be ter‐
363 minated. The debugger will attempt to recover gracefully from an out-
364 of-memory situation, but may be unable to, and may be forced to termi‐
365 nate the system. This constraint is especially acute on 32-bit x86 sys‐
366 tems.
367 Performance Impact
369 System performance will be negatively impacted by the loading of kmdb,
370 as the debugger will consume kernel memory and other limited system
371 resources.
372SunOS 5.11 3 May 2007 kmdb(1)