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