| blob | bb4a7ffa8084a9be1e97081d8552fd39e688b13b |
1 .\" Copyright (c) 2003 Greg Lehey
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD: src/share/man/man4/gdb.4,v 1.9 2004/01/28 00:02:10 grog Exp $
26 .\" $DragonFly: src/share/man/man4/gdb.4,v 1.4 2006/10/14 23:06:42 swildner Exp $
27 .\"
28 .Dd December 30, 2003
29 .Dt GDB 4
30 .Os
31 .Sh NAME
32 .Nm gdb
33 .Nd external kernel debugger
34 .Sh SYNOPSIS
35 .Cd "makeoptions DEBUG=-g"
36 .Cd "options DDB"
37 .Cd "options GDB_REMOTE_CHAT"
38 .Sh DESCRIPTION
39 The
40 .Nm
41 kernel debugger is a variation of
42 .Xr gdb 1
43 which understands some aspects of the
44 .Fx
45 kernel environment.
46 It can be used in a number of ways:
47 .Bl -bullet
48 .It
49 It can be used to examine the memory of the processor on which it runs.
50 .It
51 It can be used to analyse a processor dump after a panic.
52 .It
53 It can be used to debug another system interactively via a serial or firewire
54 link.
55 In this mode, the processor can be stopped and single stepped.
56 .It
57 With a firewire link, it can be used to examine the memory of a remote system
58 without the participation of that system.
59 In this mode, the processor cannot be stopped and single stepped, but it can be
60 of use when the remote system has crashed and is no longer responding.
61 .El
62 .Pp
63 When used for remote debugging,
64 .Nm
65 requires the presence of the
66 .Xr ddb 4
67 kernel debugger.
68 Commands exist to switch between
69 .Nm
70 and
71 .Xr ddb 4 .
72 .Sh PREPARING FOR DEBUGGING
73 When debugging kernels, it is practically essential to have built a kernel with
74 debugging symbols
75 .Pq Cd "makeoptions DEBUG=-g" .
76 It is easiest to perform operations from the kernel build directory, by default
77 .Pa /usr/obj/usr/src/sys/GENERIC .
78 .Pp
79 First, ensure you have a copy of the debug macros in the directory:
80 .Pp
81 .Dl "make gdbinit"
82 .Pp
83 This command performs some transformations on the macros installed in
84 .Pa /usr/src/tools/debugscripts
85 to adapt them to the local environment.
86 .Ss "Inspecting the environment of the local machine"
87 To look at and change the contents of the memory of the system you are running
88 on,
89 .Pp
90 .Dl "gdb -k -wcore kernel.debug /dev/mem"
91 .Pp
92 In this mode, you need the
93 .Fl k
94 flag to indicate to
95 .Xr gdb 1
96 that the
97 .Dq "dump file"
98 .Pa /dev/mem
99 is a kernel data file.
100 You can look at live data, and if you include the
101 .Fl wcore
102 option, you can change it at your peril.
103 The system does not stop (obviously), so a number of things will not work.
104 You can set breakpoints, but you cannot
105 .Dq continue
106 execution, so they will not work.
107 .Ss "Debugging a crash dump"
108 By default, crash dumps are stored in the directory
109 .Pa /var/crash .
110 Investigate them from the kernel build directory with:
111 .Pp
112 .Dl "gdb -k kernel.debug /var/crash/vmcore.29"
113 .Pp
114 In this mode, the system is obviously stopped, so you can only look at it.
115 .Ss "Debugging a live system with a remote link"
116 In the following discussion, the term
117 .Dq "local system"
118 refers to the system running the debugger, and
119 .Dq "remote system"
120 refers to the live system being debugged.
121 .Pp
122 To debug a live system with a remote link, the kernel must be compiled with the
123 option
124 .Cd "options DDB" .
125 The option
126 .Cd "options BREAK_TO_DEBUGGER"
127 enables the debugging machine stop the debugged machine once a connection has
128 been established by pressing
129 .Ql ^C .
130 .Ss "Debugging a live system with a remote serial link"
131 When using a serial port for the remote link on the i386 platform, the serial
132 port must be identified by setting the flag bit
133 .Li 0x80
134 for the specified interface.
135 Generally, this port will also be used as a serial console (flag bit
136 .Li 0x10 ) ,
137 so the flags field for the interface in the kernel configuration file
138 should be:
139 .Pp
140 .Dl flags 0x90
141 .Pp
142 To share a console and debug connection on a serial line, use the
143 .Cd "options GDB_REMOTE_CHAT"
144 option.
145 .Ss "Debugging a live system with a remote firewire link"
146 As with serial debugging, to debug a live system with a firewire link, the
147 kernel must be compiled with the option
148 .Cd "options DDB" .
149 The
150 .Cd "options GDB_REMOTE_CHAT"
151 is not necessary, since the firewire implementation uses separate ports for the
152 console and debug connection.
153 .Pp
154 A number of steps must be performed to set up a firewire link:
155 .Bl -bullet
156 .It
157 Ensure that both systems have
158 .Xr firewire 4
159 support, and that the kernel of the remote system includes the
160 .Xr dcons 4
161 and
162 .Xr dcons_crom 4
163 drivers.
164 If they are not compiled into the kernel, load the KLDs:
165 .Pp
166 .Dl "kldload firewire"
167 .Pp
168 On the remote system only:
169 .Bd -literal -offset indent
170 kldload dcons
171 kldload dcons_crom
172 .Ed
173 .Pp
174 You should see something like this in the
175 .Xr dmesg 8
176 output of the remote system:
177 .Bd -literal -offset indent
178 fwohci0: BUS reset
179 fwohci0: node_id=0x8800ffc0, gen=2, non CYCLEMASTER mode
180 firewire0: 2 nodes, maxhop <= 1, cable IRM = 1
181 firewire0: bus manager 1
182 firewire0: New S400 device ID:00c04f3226e88061
183 dcons_crom0: <dcons configuration ROM> on firewire0
184 dcons_crom0: bus_addr 0x22a000
185 .Ed
186 .Pp
187 It is a good idea to load these modules at boot time with the following entry in
188 .Pa /boot/loader.conf :
189 .Pp
190 .Dl dcons_crom_enable="YES"
191 .Pp
192 This ensures that all three modules are loaded.
193 There is no harm in loading
194 .Xr dcons 4
195 and
196 .Xr dcons_crom 4
197 on the local system, but if you only want to load the
198 .Xr firewire 4
199 module, include the following in
200 .Pa /boot/loader.conf :
201 .Pp
202 .Dl firewire_enable="YES"
203 .It
204 Next, use
205 .Xr fwcontrol 8
206 to find the firewire node corresponding to the remote machine.
207 On the local machine you might see:
208 .Bd -literal -offset indent
209 # fwcontrol
210 2 devices (info_len=2)
211 node EUI64 status
212 1 0x00c04f3226e88061 0
213 0 0x000199000003622b 1
214 .Ed
215 .Pp
216 The first node is always the local system, so in this case, node 0 is the remote
217 system.
218 If there are more than two systems, check from the other end to find which node
219 corresponds to the remote system.
220 On the remote machine, it looks like this:
221 .Bd -literal -offset indent
222 # fwcontrol
223 2 devices (info_len=2)
224 node EUI64 status
225 0 0x000199000003622b 0
226 1 0x00c04f3226e88061 1
227 .Ed
228 .It
229 Next, establish a firewire connection with
230 .Xr dconschat 8 :
231 .Pp
232 .Dl "dconschat -br -G 5556 -t 0x000199000003622b"
233 .Pp
234 .Li 0x000199000003622b
235 is the EUI64 address of the remote node, as determined from the output of
236 .Xr fwcontrol 8
237 above.
238 When started in this manner,
239 .Xr dconschat 8
240 establishes a local tunnel connection from port
241 .Li localhost:5556
242 to the remote debugger.
243 You can also establish a console port connection with the
244 .Fl C
245 option to the same invocation
246 .Xr dconschat 8 .
247 See the
248 .Xr dconschat 8
249 manpage for further details.
250 .Pp
251 The
252 .Xr dconschat 8
253 utility
254 does not return control to the user.
255 It displays error messages and console output for the remote system, so it is a
256 good idea to start it in its own window.
257 .It
258 Finally, establish connection:
259 .Bd -literal -offset indent
260 # gdb kernel.debug
261 GNU gdb 5.2.1 (FreeBSD)
262 .Em "(political statements omitted)"
263 Ready to go. Enter 'tr' to connect to the remote target
264 with /dev/cuaa0, 'tr /dev/cuaa1' to connect to a different port
265 or 'trf portno' to connect to the remote target with the firewire
266 interface. portno defaults to 5556.
268 Type 'getsyms' after connection to load kld symbols.
270 If you're debugging a local system, you can use 'kldsyms' instead
271 to load the kld symbols. That's a less obnoxious interface.
272 (gdb) trf
273 0xc21bd378 in ?? ()
274 .Ed
275 .Pp
276 The
277 .Ic trf
278 macro assumes a connection on port 5556.
279 If you want to use a different port (by changing the invocation of
280 .Xr dconschat 8
281 above), use the
282 .Ic tr
283 macro instead.
284 For example, if you want to use port 4711, run
285 .Xr dconschat 8
286 like this:
287 .Pp
288 .Dl "dconschat -br -G 4711 -t 0x000199000003622b"
289 .Pp
290 Then establish connection with:
291 .Bd -literal -offset indent
292 (gdb) tr localhost:4711
293 0xc21bd378 in ?? ()
294 .Ed
295 .El
296 .Ss "Non-cooperative debugging a live system with a remote firewire link"
297 In addition to the conventional debugging via firewire described in the previous
298 section, it is possible to debug a remote system without its cooperation, once
299 an initial connection has been established.
300 This corresponds to debugging a local machine using
301 .Pa /dev/mem .
302 It can be very useful if a system crashes and the debugger no longer responds.
303 To use this method, set the
304 .Xr sysctl 8
305 variables
306 .Va hw.firewire.fwmem.eui64_hi
307 and
308 .Va hw.firewire.fwmem.eui64_lo
309 to the upper and lower halves of the EUI64 ID of the remote system,
310 respectively.
311 From the previous example, the remote machine shows:
312 .Bd -literal -offset indent
313 # fwcontrol
314 2 devices (info_len=2)
315 node EUI64 status
316 0 0x000199000003622b 0
317 1 0x00c04f3226e88061 1
318 .Ed
319 .Pp
320 Enter:
321 .Bd -literal -offset indent
322 # sysctl -w hw.firewire.fwmem.eui64_hi=0x00019900
323 hw.firewire.fwmem.eui64_hi: 0 -> 104704
324 # sysctl -w hw.firewire.fwmem.eui64_lo=0x0003622b
325 hw.firewire.fwmem.eui64_lo: 0 -> 221739
326 .Ed
327 .Pp
328 Note that the variables must be explicitly stated in hexadecimal.
329 After this, you can examine the remote machine's state with the following input:
330 .Bd -literal -offset indent
331 # gdb -k kernel.debug /dev/fwmem0.0
332 GNU gdb 5.2.1 (FreeBSD)
333 .Em "(messages omitted)"
334 Reading symbols from /modules/dcons.ko...done.
335 Loaded symbols for /modules/dcons.ko
336 Reading symbols from /modules/dcons_crom.ko...done.
337 Loaded symbols for /modules/dcons_crom.ko
338 #0 sched_switch (td=0xc0922fe0) at /usr/src/sys/kern/sched_4bsd.c:621
339 0xc21bd378 in ?? ()
340 .Ed
341 .Pp
342 In this case, it is not necessary to load the symbols explicitly.
343 The remote system continues to run.
344 .Sh COMMANDS
345 The user interface to
346 .Nm
347 is via
348 .Xr gdb 1 ,
349 so
350 .Xr gdb 1
351 commands also work.
352 This section discusses only the extensions for kernel debugging that get
353 installed in the kernel build directory.
354 .Ss "Debugging environment"
355 The following macros manipulate the debugging environment:
356 .Bl -tag -width indent
357 .It Ic ddb
358 Switch back to
359 .Xr ddb 4 .
360 This command is only meaningful when performing remote debugging.
361 .It Ic getsyms
362 Display
363 .Ic kldstat
364 information for the target machine and invite user to paste it back in.
365 This is required because
366 .Nm
367 does not allow data to be passed to shell scripts.
368 It is necessary for remote debugging and crash dumps; for local memory debugging
369 use
370 .Ic kldsyms
371 instead.
372 .It Ic kldsyms
373 Read in the symbol tables for the debugging machine.
374 This does not work for
375 remote debugging and crash dumps; use
376 .Ic getsyms
377 instead.
378 .It Ic tr Ar interface
379 Debug a remote system via the specified serial or firewire interface.
380 .It Ic tr0
381 Debug a remote system via serial interface
382 .Pa /dev/cuaa0 .
383 .It Ic tr1
384 Debug a remote system via serial interface
385 .Pa /dev/cuaa1 .
386 .It Ic trf
387 Debug a remote system via firewire interface at default port 5556.
388 .El
389 .Pp
390 The commands
391 .Ic tr0 , tr1
392 and
393 .Ic trf
394 are convenience commands which invoke
395 .Ic tr .
396 .Ss "The current process environment"
397 The following macros are convenience functions intended to make things easier
398 than the standard
399 .Xr gdb 1
400 commands.
401 .Bl -tag -width indent
402 .It Ic f0
403 Select stack frame 0 and show assembler-level details.
404 .It Ic f1
405 Select stack frame 1 and show assembler-level details.
406 .It Ic f2
407 Select stack frame 2 and show assembler-level details.
408 .It Ic f3
409 Select stack frame 3 and show assembler-level details.
410 .It Ic f4
411 Select stack frame 4 and show assembler-level details.
412 .It Ic f5
413 Select stack frame 5 and show assembler-level details.
414 .It Ic xb
415 Show 12 words in hex, starting at current
416 .Va ebp
417 value.
418 .It Ic xi
419 List the next 10 instructions from the current
420 .Va eip
421 value.
422 .It Ic xp
423 Show the register contents and the first four parameters of the current stack
424 frame.
425 .It Ic xp0
426 Show the first parameter of current stack frame in various formats.
427 .It Ic xp1
428 Show the second parameter of current stack frame in various formats.
429 .It Ic xp2
430 Show the third parameter of current stack frame in various formats.
431 .It Ic xp3
432 Show the fourth parameter of current stack frame in various formats.
433 .It Ic xp4
434 Show the fifth parameter of current stack frame in various formats.
435 .It Ic xs
436 Show the last 12 words on stack in hexadecimal.
437 .It Ic xxp
438 Show the register contents and the first ten parameters.
439 .It Ic z
440 Single step 1 instruction (over calls) and show next instruction.
441 .It Ic zs
442 Single step 1 instruction (through calls) and show next instruction.
443 .El
444 .Ss "Examining other processes"
445 The following macros access other processes.
446 The
447 .Nm
448 debugger
449 does not understand the concept of multiple processes, so they effectively
450 bypass the entire
451 .Nm
452 environment.
453 .Bl -tag -width indent
454 .It Ic btp Ar pid
455 Show a backtrace for the process
456 .Ar pid .
457 .It Ic btpa
458 Show backtraces for all processes in the system.
459 .It Ic btpp
460 Show a backtrace for the process previously selected with
461 .Ic defproc .
462 .It Ic btr Ar ebp
463 Show a backtrace from the
464 .Ar ebp
465 address specified.
466 .It Ic defproc Ar pid
467 Specify the PID of the process for some other commands in this section.
468 .It Ic fr Ar frame
469 Show frame
470 .Ar frame
471 of the stack of the process previously selected with
472 .Ic defproc .
473 .It Ic pcb Ar proc
474 Show some PCB contents of the process
475 .Ar proc .
476 .El
477 .Ss "Examining data structures"
478 You can use standard
479 .Xr gdb 1
480 commands to look at most data structures.
481 The macros in this section are
482 convenience functions which typically display the data in a more readable
483 format, or which omit less interesting parts of the structure.
484 .Bl -tag -width indent
485 .It Ic bp
486 Show information about the buffer header pointed to by the variable
487 .Va bp
488 in the current frame.
489 .It Ic bpd
490 Show the contents
491 .Pq Vt "char *"
492 of
493 .Va bp->data
494 in the current frame.
495 .It Ic bpl
496 Show detailed information about the buffer header
497 .Pq Vt "struct bp"
498 pointed at by the local variable
499 .Va bp .
500 .It Ic bpp Ar bp
501 Show summary information about the buffer header
502 .Pq Vt "struct bp"
503 pointed at by the parameter
504 .Ar bp .
505 .It Ic bx
506 Print a number of fields from the buffer header pointed at in by the pointer
507 .Ar bp
508 in the current environment.
509 .It Ic vdev
510 Show some information of the
511 .Vt vnode
512 pointed to by the local variable
513 .Va vp .
514 .El
515 .Ss "Miscellaneous macros"
516 .Bl -tag -width indent
517 .It Ic checkmem
518 Check unallocated memory for modifications.
519 This assumes that the kernel has been compiled with
520 .Cd "options DIAGNOSTIC"
521 This causes the contents of free memory to be set to
522 .Li 0xdeadc0de .
523 .It Ic dmesg
524 Print the system message buffer.
525 This corresponds to the
526 .Xr dmesg 8
527 utility.
528 This macro used to be called
529 .Ic msgbuf .
530 It can take a very long time over a serial line,
531 and it is even slower via firewire
532 or local memory due to inefficiencies in
533 .Nm .
534 When debugging a crash dump or over firewire, it is not necessary to start
535 .Nm
536 to access the message buffer: instead, use an appropriate variation of
537 .Bd -literal -offset indent
538 dmesg -M /var/crash/vmcore.0 -N kernel.debug
539 dmesg -M /dev/fwmem0.0 -N kernel.debug
540 .Ed
541 .It Ic kldstat
542 Equivalent of the
543 .Xr kldstat 8
544 utility without options.
545 .It Ic pname
546 Print the command name of the current process.
547 .It Ic ps
548 Show process status.
549 This corresponds in concept, but not in appearance, to the
550 .Xr ps 1
551 utility.
552 When debugging a crash dump or over firewire, it is not necessary to start
553 .Nm
554 to display the
555 .Xr ps 1
556 output: instead, use an appropriate variation of
557 .Bd -literal -offset indent
558 ps -M /var/crash/vmcore.0 -N kernel.debug
559 ps -M /dev/fwmem0.0 -N kernel.debug
560 .Ed
561 .It Ic y
562 Kludge for writing macros.
563 When writing macros, it is convenient to paste them
564 back into the
565 .Nm
566 window.
567 Unfortunately, if the macro is already defined,
568 .Nm
569 insists on asking
570 .Pp
571 .Dl "Redefine foo?"
572 .Pp
573 It will not give up until you answer
574 .Ql y .
575 This command is that answer.
576 It does nothing else except to print a warning
577 message to remind you to remove it again.
578 .El
579 .Sh SEE ALSO
580 .Xr gdb 1 ,
581 .Xr ps 1 ,
582 .Xr ddb 4 ,
583 .Xr firewire 4 ,
584 .Xr vinumdebug 4 ,
585 .Xr dconschat 8 ,
586 .Xr dmesg 8 ,
587 .Xr fwcontrol 8 ,
588 .Xr kldload 8
589 .Sh AUTHORS
590 This man page was written by
591 .An "Greg Lehey" Aq grog@FreeBSD.org .
592 .Sh BUGS
593 The
594 .Xr gdb 1
595 debugger
596 was never designed to debug kernels, and it is not a very good match.
597 Many problems exist.
598 .Pp
599 The
600 .Nm
601 implementation is very inefficient, and many operations are slow.
602 .Pp
603 Serial debugging is even slower, and race conditions can make it difficult to
604 run the link at more than 9600 bps.
605 Firewire connections do not have this problem.
606 .Pp
607 The debugging macros
608 .Dq "just growed" .
609 In general, the person who wrote them did so while looking for a specific
610 problem, so they may not be general enough, and they may behave badly when used
611 in ways for which they were not intended, even if those ways make sense.
612 .Pp
613 Many of these commands only work on the ia32 architecture.