1 .TH KDB 8 "September 17, 2004"
4 Built-in Kernel Debugger for Linux - v4.4
6 This document describes the built-in kernel debugger available
7 for linux. This debugger allows the programmer to interactively
8 examine kernel memory, disassemble kernel functions, set breakpoints
9 in the kernel code and display and modify register contents.
11 A symbol table is included in the kernel image and in modules which
12 enables all non-stack symbols (including static symbols) to be used as
13 arguments to the kernel debugger commands.
15 To include the kernel debugger in a linux kernel, use a
16 configuration mechanism (e.g. xconfig, menuconfig, et. al.)
17 to enable the \fBCONFIG_KDB\fP option. Additionally, for accurate
18 stack tracebacks, it is recommended that the \fBCONFIG_FRAME_POINTER\fP
19 option be enabled (if present). \fBCONFIG_FRAME_POINTER\fP changes the compiler
20 flags so that the frame pointer register will be used as a frame
21 pointer rather than a general purpose register.
23 After linux has been configured to include the kernel debugger,
24 make a new kernel with the new configuration file (a make clean
25 is recommended before making the kernel), and install the kernel
28 You can compile a kernel with kdb support but have kdb off by default,
29 select \fBCONFIG_KDB_OFF\fR. Then the user has to explicitly activate
30 kdb by booting with the 'kdb=on' flag or, after /proc is mounted, by
32 echo "1" > /proc/sys/kernel/kdb
34 You can also do the reverse, compile a kernel with kdb on and
35 deactivate kdb with the boot flag 'kdb=off' or, after /proc is mounted,
38 echo "0" > /proc/sys/kernel/kdb
41 When booting the new kernel, the 'kdb=early' flag
42 may be added after the image name on the boot line to
43 force the kernel to stop in the kernel debugger early in the
44 kernel initialization process. 'kdb=early' implies 'kdb=on'.
45 If the 'kdb=early' flag isn't provided, then kdb will automatically be
46 invoked upon system panic or when the \fBPAUSE\fP key is used from the
47 keyboard, assuming that kdb is on. Older versions of kdb used just a
48 boot flag of 'kdb' to activate kdb early, this is no longer supported.
50 KDB can also be used via the serial port. Set up the system to
51 have a serial console (see \fIDocumentation/serial-console.txt\fP), you
52 must also have a user space program such as agetty set up to read from
54 The control sequence \fB<esc>KDB\fP on the serial port will cause the
55 kernel debugger to be entered, assuming that kdb is on, that some
56 program is reading from the serial console, at least one cpu is
57 accepting interrupts and the serial console driver is still usable.
59 \fBNote:\fR\ When the serial console sequence consists of multiple
60 characters such as <esc>KDB then all but the last character are passed
61 through to the application that is reading from the serial console.
62 After exiting from kdb, you should use backspace to delete the rest of
65 If the console is sitting on the login prompt when you enter kdb, then
66 the login command may switch into upper case mode.
67 This is not a kdb bug, it is a "feature" of login - if the userid is
68 all upper case then login assumes that you using a TeleType (circa
69 1960) which does not have lower case characters.
70 Wait 60 seconds for login to timeout and it will switch back to lower
73 \fBNote:\fR\ Your distributor may have chosen a different kdb
74 activation sequence for the serial console.
75 Consult your distribution documentation.
77 If you have both a keyboard+video and a serial console, you can use
79 Define both video and serial consoles with boot parameters
82 console=tty0 console=ttyS0,38400
85 Any kdb data entered on the keyboard or the serial console will be echoed
88 If you are using a USB keyboard then kdb commands cannot be entered
89 until the kernel has initialised the USB subsystem and recognised the
91 Using kdb=early with a USB keyboard will not work, the USB subsystem is
94 While kdb is active, the keyboard (not serial console) indicators may strobe.
95 The caps lock and scroll lock lights will turn on and off, num lock is not used
96 because it can confuse laptop keyboards where the numeric keypad is mapped over
98 On exit from kdb the keyboard indicators will probably be wrong, they will not match the kernel state.
99 Pressing caps lock twice should get the indicators back in sync with
102 There are several categories of commands available to the
103 kernel debugger user including commands providing memory
104 display and modification, register display and modification,
105 instruction disassemble, breakpoints and stack tracebacks.
106 Any command can be prefixed with '-' which will cause kdb to ignore any
107 errors on that command, this is useful when packaging commands using
109 A line whose first non-space character is '#' is printed and ignored.
111 The following table shows the currently implemented standard commands,
112 these are always available. Other commands can be added by extra
113 debugging modules, type '?' at the kdb prompt to get a list of all
123 bd Disable Breakpoint
125 bl Display breakpoints
126 bp Set or Display breakpoint
127 bph Set or Display hardware breakpoint
128 bpa Set or Display breakpoint globally
129 bpha Set or Display hardware breakpoint globally
130 bt Stack backtrace for current process
131 btp Stack backtrace for specific process
132 bta Stack backtrace for all processes
133 btc Cycle over all live cpus and backtrace each one
134 cpu Display or switch cpus
135 dmesg Display system messages
136 defcmd Define a command as a set of other commands
137 ef Print exception frame
140 help Display help message
141 id Disassemble Instructions
142 kill Send a signal to a process
143 ll Follow Linked Lists
144 lsmod List loaded modules
145 md Display memory contents
146 mdWcN Display memory contents with width W and count N.
147 mdp Display memory based on a physical address
148 mdr Display raw memory contents
149 mds Display memory contents symbolically
150 mm Modify memory contents, words
151 mmW Modify memory contents, bytes
152 per_cpu Display per_cpu variables
153 pid Change the default process context
154 ps Display process status
155 reboot Reboot the machine
156 rd Display register contents
157 rm Modify register contents
158 set Add/change environment variable
159 sr Invoke SysReq commands
161 ssb Single step a cpu until a branch instruction
162 stackdepth Print the stack depth for selected processes
163 summary Summarize the system
167 Some commands can be abbreviated, such commands are indicated by a
168 non-zero \fIminlen\fP parameter to \fBkdb_register\fP; the value of
169 \fIminlen\fP being the minimum length to which the command can be
170 abbreviated (for example, the \fBgo\fP command can be abbreviated
173 If an input string does not match a command in the command table,
174 it is treated as an address expression and the corresponding address
175 value and nearest symbol are shown.
177 Some of the commands are described here.
178 Information on the more complicated commands can be found in the
179 appropriate manual pages.
182 With no parameters, it lists the available cpus.
183 \&'*' after a cpu number indicates a cpu that did not respond to the kdb
185 \&'+' after a cpu number indicates a cpu for which kdb has some data, but
186 that cpu is no longer responding to kdb, so you cannot switch to it.
187 This could be a cpu that has failed after entering kdb, or the cpu may
188 have saved its state for debugging then entered the prom, this is
189 normal for an IA64 MCA event.
190 \&'I' after a cpu number means that the cpu was idle before it entered
191 kdb, it is unlikely to contain any useful data.
192 \&'F' after a cpu number means that the cpu is offline.
193 There is currenly no way to distinguish between cpus that used to be
194 online but are now offline and cpus that were never online, the kernel
195 does not maintain the information required to separate those two cases.
197 followed by a number will switch to that cpu, you cannot switch to
198 a cpu marked '*', '+' or 'F'.
199 This command is only available if the kernel was configured for SMP.
201 dmesg [lines] [adjust]
202 Displays the system messages from the kernel buffer.
203 If kdb logging is on, it is disabled by dmesg and is left as disabled.
204 With no parameters or a zero value for 'lines', dmesg dumps the entire
206 If lines is specified and is positive, dmesg dumps the last 'lines'
208 If lines is specified and is negative, dmesg dumps the first 'lines'
210 If adjust is specified, adjust the starting point for the lines that
212 When 'lines' is positive, move the starting point back by 'adjust'
213 lines, when 'lines' is negative, move the starting point forward by
216 will dump 100 lines, from the start of the buffer.
218 will dump 100 lines, starting 100 lines from the end of the buffer,
220 will dump 100 lines, starting 200 lines from the end of the buffer.
222 will dump 100 lines, starting 100 lines from the start of the buffer.
225 Defines a new command as a set of other commands, all input until
227 is saved and executed as a package.
229 takes three parameters, the command name to be defined and used to
230 invoke the package, a quoted string containing the usage text and a
231 quoted string containing the help text for the command.
232 When using defcmd, it is a good idea to prefix commands that might fail
233 with '-', this ignores errors so the following commands are still
238 defcmd diag "" "Standard diagnostics"
250 When used with no parameters, defcmd prints all the defined commands.
253 Continue normal execution.
254 Active breakpoints are reestablished and the processor(s) allowed to
256 To continue at a specific address, use
258 to change the instruction pointer then go.
261 Disassemble instructions starting at an address.
262 Environment variable IDCOUNT controls how many lines of disassembly
263 output the command produces.
266 Internal command to send a signal (like kill(1)) to a process.
270 Internal command to list modules.
271 This does not use any kernel nor user space services so can be used at any time.
273 per_cpu <variable_name> [<length>] [<cpu>]
274 Display the values of a per_cpu variable, the variable_name is
275 specified without the \fIper_cpu__\fR prefix.
276 Length is the length of the variable, 1-8, if omitted or 0 it defaults
277 to the size of the machine's register.
278 To display the variable on a specific cpu, the third parameter is the
280 When the third parameter is omitted, the variable's value is printed
281 from all cpus, except that zero values are suppressed.
282 For each cpu, per_cpu prints the cpu number, the address of the
283 variable and its value.
286 Change the current process context, with no parameters it displays the
288 The current process is used to display registers, both kernel and user
290 It is also used when dumping user pages.
293 Reboot the system, with no attempt to do a clean close down.
295 stackdepth <percentage>
296 Print the stack usage for processes using more than the specified
297 percentage of their stack.
298 If percentage is not supplied, it defaults to 60.
299 This command is only implemented on i386 and ia64 architectures,
300 patches for other architectures will be gratefully accepted.
303 Print a summary of the system, including the time (no timezone is
304 applied), uname information and various critical system counters.
305 .SH INITIAL KDB COMMANDS
306 kdb/kdb_cmds is a plain text file where you can define kdb commands
307 which are to be issued during kdb_init(). One command per line, blank
308 lines are ignored, lines starting with '#' are ignored. kdb_cmds is
309 intended for per user customization of kdb, you can use it to set
310 environment variables to suit your hardware or to set standard
311 breakpoints for the problem you are debugging. This file is converted
312 to a small C object, compiled and linked into the kernel. You must
313 rebuild and reinstall the kernel after changing kdb_cmds. This file
314 will never be shipped with any useful data so you can always override
315 it with your local copy. Sample kdb_cmds:
318 # Initial commands for kdb, alter to suit your needs.
319 # These commands are executed in kdb_init() context, no SMP, no
320 # processes. Commands that require process data (including stack or
321 # registers) are not reliable this early. set and bp commands should
322 # be safe. Global breakpoint commands affect each cpu as it is booted.
329 .SH INTERRUPTS AND KDB
330 When a kdb event occurs, one cpu (the initial cpu) enters kdb state.
331 It uses a cross system interrupt to interrupt the
332 other cpus and bring them all into kdb state. All cpus run with
333 interrupts disabled while they are inside kdb, this prevents most
334 external events from disturbing the kernel while kdb is running.
336 Disabled interrupts means that any I/O that relies on interrupts cannot
337 proceed while kdb is in control, devices can time out. The clock tick
338 is also disabled, machines will lose track of time while they are
341 Even with interrupts disabled, some non-maskable interrupt events will
342 still occur, these can disturb the kernel while you are debugging it.
343 The initial cpu will still accept NMI events, assuming that kdb was not
344 entered for an NMI event. Any cpu where you use the SS or SSB commands
345 will accept NMI events, even after the instruction has finished and the
346 cpu is back in kdb. This is an unavoidable side effect of the fact that
347 doing SS[B] requires the cpu to drop all the way out of kdb, including
348 exiting from the event that brought the cpu into kdb. Under normal
349 circumstances the only NMI event is for the NMI oopser and that is kdb
350 aware so it does not disturb the kernel while kdb is running.
352 Sometimes doing SS or SSB on ix86 will allow one interrupt to proceed,
353 even though the cpu is disabled for interrupts. I have not been able
354 to track this one down but I suspect that the interrupt was pending
355 when kdb was entered and it runs when kdb exits through IRET even
356 though the popped flags are marked as cli(). If any ix86 hardware
357 expert can shed some light on this problem, please notify the kdb
359 .SH RECOVERING FROM KDB ERRORS
360 If a kdb command breaks and kdb has enough of a recovery environment
361 then kdb will abort the command and drop back into mainline kdb code.
362 This means that user written kdb commands can follow bad pointers
363 without killing kdb. Ideally all code should verify that data areas
364 are valid (using kdb_getarea) before accessing it but lots of calls to
365 kdb_getarea can be clumsy.
367 The sparc64 port does not currently provide this error recovery.
368 If someone would volunteer to write the necessary longjmp/setjmp
369 code, their efforts would be greatly appreciated. In the
370 meantime, it is possible for kdb to trigger a panic by accessing
372 .SH DEBUGGING THE DEBUGGER
373 kdb has limited support for debugging problems within kdb. If you
374 suspect that kdb is failing, you can set environment variable KDBDEBUG
375 to a bit pattern which will activate kdb_printf statements within kdb.
376 See include/linux/kdb.h, KDB_DEBUG_FLAG_xxx defines. For example
380 activates the event callbacks into kdb plus state tracing in sections
385 gives lots of tracing as kdb tries to decode the process stack.
387 You can also perform one level of recursion in kdb. If environment
388 variable RECURSE is not set or is 0 then kdb will either recover from
389 an error (if the recovery environment is satisfactory) or kdb will
390 allow the error to percolate, usually resulting in a dead system. When
391 RECURSE is 1 then kdb will recover from an error or, if there is no
392 satisfactory recovery environment, it will drop into kdb state to let
393 you diagnose the problem. When RECURSE is 2 then all errors drop into
394 kdb state, kdb does not attempt recovery first. Errors while in
395 recursive state all drop through, kdb does not even attempt to recover
396 from recursive errors.
398 kdb supports a command history, which can be accessed via keyboard
400 It supports the special keys on PC keyboards, control characters and
401 vt100 sequences on a serial console or a PC keyboard.
408 PC Special keys Control VT100 key Codes Action
410 Backspace ctrl-H Backspace 0x7f Delete character to the left of the cursor
411 Delete ctrl-D Delete \\e[3~ Delete character to the right of the cursor
412 Home ctrl-A Home \\e[1~ Go to start of line
413 End ctrl-E End \\e[4~ Go to end of line
414 Up arrow ctrl-P Up arrow \\e[A Up one command in history
415 Down arrow ctrl-N Down arrow \\e[B Down one command in history
416 Left arrow ctrl-B Left arrow \\e[D Left one character in current command
417 Right arrow ctrl-F Right arrow \\e[C Right one character in current command
421 There is no toggle for insert/replace mode, kdb editing is always in
423 Use delete and backspace to delete characters.
425 kdb also supports tab completion for kernel symbols
426 Type the start of a kernel symbol and press tab (ctrl-I) to complete
428 If there is more than one possible match, kdb will append any common
429 characters and wait for more input, pressing tab a second time will
430 display the possible matches
431 The number of matches is limited by environment variable DTABCOUNT,
432 with a default of 30 if that variable is not set.
434 Scott Lurndal, Richard Bass, Scott Foehner, Srinivasa Thirumalachar,
435 Masahiro Adegawa, Marc Esipovich, Ted Kline, Steve Lord, Andi Kleen,
438 Keith Owens <kaos@sgi.com> - kdb maintainer.
441 linux/Documentation/kdb/kdb_{bp,bt,env,ll,md,ps,rd,sr,ss}.man