1kmdb(1)                          User Commands                         kmdb(1)
2
3
4

NAME

6       kmdb - in situ kernel debugger
7

SYNOPSIS

9   Boot-time Loading
10       SPARC
11
12       ok boot [device-specifier] -k [-d] [boot-flags]
13
14
15       ok boot [device-specifier] kmdb [-d] [boot-flags]
16
17
18
19       x86
20
21       kernel$ /platform/i86pc/kernel/$ISADIR/unix -k [-d] [boot-flags]
22
23
24   Runtime Loading
25       mdb -K
26
27

DESCRIPTION

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
36
37       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
43   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
55                            Boot-loaded  kmdb can be unloaded only by means of
56                            a system reboot.
57
58                            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
69
70       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
78
79       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
94
95   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
100
101       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
108
109       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
113
114       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
121         set nopanicdebug = 1
122
123
124
125
126       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
129   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
135
136       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
142   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
149
150       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
157   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
169   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
175   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
179       [address]::bp [+/-dDestT] [-c cmd] [-n count] sym ...
180       address :b [cmd ...]
181
182           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
189           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
196           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
204
205       ::branches [-v]
206       (x86 only)
207
208           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
215
216       [function] ::call [arg [arg ...]]
217
218           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
223           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
230
231       [addr] ::cpuregs [-c cpuid]
232
233           Display  the current general purpose register set for the specified
234           CPU, in the format used by ::regs.
235
236
237       [addr] ::cpustack [-c cpuid]
238
239           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
243
244       addr[,len] ::in [-L len]
245       (x86 only)
246
247           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
252
253       addr[,len] ::out [-L len] value
254       (x86 only)
255
256           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
261
262       ::quit [-u]
263       $q
264
265           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
272
273       ::step [over|out|branch]
274
275           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
280           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
285           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
291
292       cpuid::switch
293       cpuid:x
294
295           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
300
301       ::term
302
303           Display the current terminal type.
304
305
306       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
311           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
317           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
323           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
332

ATTRIBUTES

334       See attributes(5) for descriptions of the following attributes:
335
336
337
338
339       ┌─────────────────────────────┬─────────────────────────────┐
340       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
341       ├─────────────────────────────┼─────────────────────────────┤
342       │Availability                 │SUNWckr (debugger)           │
343       ├─────────────────────────────┼─────────────────────────────┤
344       │                             │SUNWmdbr (dmods)             │
345       ├─────────────────────────────┼─────────────────────────────┤
346       │Interface Stability          │Evolving                     │
347       └─────────────────────────────┴─────────────────────────────┘
348

SEE ALSO

350       mdb(1), boot(1M), dumpadm(1M), kernel(1M), system(4), attributes(5)
351
352
353       Solaris Modular Debugger Guide
354
355   SPARC Only
356       kbd(1)
357

NOTES

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
368   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.
372
373
374
375SunOS 5.11                        3 May 2007                           kmdb(1)
Impressum