diff options
author | grog <grog@FreeBSD.org> | 2003-12-30 01:39:08 +0000 |
---|---|---|
committer | grog <grog@FreeBSD.org> | 2003-12-30 01:39:08 +0000 |
commit | 4a412278131cad9edfa931aea4f57fa986c915d5 (patch) | |
tree | 69f4a21bc510a7c92f280c06caa29164a95d52de /share | |
parent | 2f97cd97724122818c872cf2319d2f3295401de9 (diff) | |
download | FreeBSD-src-4a412278131cad9edfa931aea4f57fa986c915d5.zip FreeBSD-src-4a412278131cad9edfa931aea4f57fa986c915d5.tar.gz |
New man page for kernel debugging with gdb.
Reviewed by: jkoshy, des, gallatin, njl.
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man4/gdb.4 | 450 |
1 files changed, 450 insertions, 0 deletions
diff --git a/share/man/man4/gdb.4 b/share/man/man4/gdb.4 new file mode 100644 index 0000000..e36c461 --- /dev/null +++ b/share/man/man4/gdb.4 @@ -0,0 +1,450 @@ +.\" $FreeBSD$ +.Dd December 30, 2003 +.Dt GDB 4 +.Os +.Sh NAME +.Nm gdb +.Nd external kernel debugger +.Sh SYNOPSIS +.Cd makeoptions DEBUG=-g +.Cd options DDB +.Cd options GDB_REMOTE_CHAT +.Pp +To prevent activation of the debugger on kernel +.Xr panic 9 : +.Cd options DDB_UNATTENDED +.Sh DESCRIPTION +The +.Nm +kernel debugger is a variation of +.Xr gdb 1 +which understands some aspects of the +.Fx +kernel environment. It can be used in a number of ways: +.Pp +.Bl -bullet -offset indent -compact +.It +It can be used to debug another system interactively via a serial or firewire +link. In this mode, the processor can be stopped and single stepped. +.It +It can be used to examine the memory of the processor on which it runs. +.It +It can be used to analyse a processor dump after a panic. +.El +.Pp +When used for remote debugging, +.Nm +requires the presence of the +.Xr ddb 4 +kernel debugger. +Commands exist to switch between +.Nm +and +.Xr ddb 4 . +.Sh PREPARING FOR DEBUGGING +When debugging kernels, it is practically essential to have built a kernel with +debugging symbols +.Cd ( makeoptions DEBUG=-g ). +It's easiest to perform operations from the kernel build directory, by default +.Pa /usr/obj/sys/GENERIC . +.Pp +First, ensure you have a copy of the debug macros in the directory: +.Bd -literal -offset 5m +# \f(CBmake gdbinit\fP +.Ed +.Pp +This command performs some transformations on the macros installed in +.Pa /usr/src/tools/debugscripts +to adapt them to the local environment. +.Ss Debugging a local machine +To look at and change the contents of the memory of the system you're running +on, +.Bd -literal -offset 5m +# \f(CBgdb -k -wcore kernel.debug /dev/mem\fP +.Ed +.Pp +In this mode, you need the +.Fl k +flag to indicate to +.Nm gdb +that the ``dump file'' +.Pa /dev/mem +is a kernel data file. +You can look at live data, and if you include the +.Fl wcore +option, you can change it at your peril. +The system does not stop (obviously), so a number of things will not work. +You can set breakpoints, but you can't ``continue'' execution, so they won't +work. +.Ss Debugging a crash dump +By default, crash dumps are stored in the directory +.Pa /var/crash . +Investigate them from the kernel build directory with: +.Bd -literal -offset 5m +# \f(CBgdb -k kernel.debug /var/crash/vmcore.29\fP +.Ed +.Pp +In this mode, the system is obviously stopped, so you can only look at it. +.Ss Debugging a live system with a remote link +To debug a live system with a remote link, the kernel must be compiled with the +options +.Cd options DDB +and +.Cd options GDB_REMOTE_CHAT . +The option +.Cd options BREAK_TO_DEBUGGER +enables the debugging machine stop the debugged machine once a connection has +been established by pressing +.Li ^C. +.Ss Debugging a live system with a remote serial link +When using a serial port for the remote link on the i386 platform the serial +port must be identified by setting the flag bit +.Li 0x80 +for the specified interface. +Generally this port will also be used as a serial console (flag bit +.Li 0x10a), +so the entry in +.Pa /boot/device.hints +should be: +.Bd -literal -offset 5m +hint.sio.0.flags="0x90" +.Ed +.Ss Debugging a live system with a remote firewire link +As with serial debugging, to debug a live system with a firewire link, the +kernel must be compiled with the options +.Cd options DDB +and +.Cd options GDB_REMOTE_CHAT . +.Pp +A number of steps must be performed to set up a firewire link: +.Pp +.Bl -bullet -offset indent -compact +.It +First, ensure that the kernels of both systems include firewire support. +If it isn't compiled into the kernel, load the klds: +.Bd -literal -offset 5m +# \f(CBkldload dcons\fP +# \f(CBkldload dcons_crom\fP +.Ed +.Pp +You should see something like this in the +.Nm dmesg +output: +.Pp +.Bd -literal -offset 5m +fwohci0: BUS reset +fwohci0: node_id=0xc000ffc1, gen=3, CYCLEMASTER mode +firewire0: 2 nodes, maxhop <= 1, cable IRM = 1 (me) +firewire0: bus manager 1 (me) +firewire0: New S400 device ID:000199000003622b +dcons_crom0: <dcons configuration ROM> on firewire0 +dcons_crom0: bus_addr 0xf93000 +.Ed +.Pp +The corresponding output on the other machine looks like this: +.Pp +.Bd -literal -offset 5m +fwohci0: BUS reset +fwohci0: node_id=0x8800ffc0, gen=2, non CYCLEMASTER mode +firewire0: 2 nodes, maxhop <= 1, cable IRM = 1 +firewire0: bus manager 1 +firewire0: New S400 device ID:00c04f3226e88061 +dcons_crom0: <dcons configuration ROM> on firewire0 +dcons_crom0: bus_addr 0x22a000 +.Ed +.Pp +It's a good idea to load these modules at boot time with the following entry in +.Pa /boot/loader.conf : +.Pp +.Bd -literal -offset 5m +dcons_enable=YES +.Ed +.Pp +.It +Next, use +.Nm fwcontrol +to find the firewire node corresponding to the remote machine: +.Pp +.Bd -literal -offset 5m +# \f(CBfwcontrol\fP +2 devices (info_len=2) +node EUI64 status + 1 0x00c04f3226e88061 0 + 0 0x000199000003622b 1 +.Ed +.Pp +The first node is always the local system, so in this case, node 0 is the remote +system. +If there are more than two systems, check from the other end to find which node +corresponds to the remote system. +On the other machine, it looks like this: +.Pp +.Bd -literal -offset 5m +# \f(CBfwcontrol\fP +2 devices (info_len=2) +node EUI64 status + 0 0x000199000003622b 0 + 1 0x00c04f3226e88061 1 +.Ed +.Pp +.It +Next, establish a firewire connection with +.Nm fwchat : +.Pp +.Bd -literal -offset 5m +# \f(CBfwchat -b -t \f[CBI]target-address\fR +.Ed +.Pp +.Ar target-address +is the EUI64 address of the remote node, in this case +.Li 0x00c04f3226e88061 . +When started in this manner, +.Nm fwchat +establishes two local tunnel connections: +.Ar localhost:5555 +is a connection to a +.Nm getty +process, which is not of interest here, and +.Ar localhost:5556 +is a connection to the debugger. +The port numbers can be changed with the +.Fl p +flag to +.Nm fwcontrol . +.El +.Pp +.Sh COMMANDS +The user interface to +.Nm +is via +.Xr gdb 1 , +so +.Xr gdb 1 +commands also work. +This section discusses only the extensions for kernel debugging that get +installed in the kernel build directory. +.Ss "Debugging Environment" +The following macros manipulate the debugging environment: +.Bl -ohang -offset 3m +.It Cm ddb +Switch back to +.Nm ddb . +This command is only meaningful when performing remote debugging. +.It Cm getsyms +Display +.Nm kldstat +information for the target machine and invite user to paste it back in. +This is required because +.Nm gdb +does not allow data to be passed to shell scripts. +It's necessary for remote debugging and crash dumps; for local memory debugging +use +.Nm kldsyms +instead. +.It Cm kldsyms +Read in the symbol tables for the debugging machine. This doesn't work for +remote debugging and crash dumps; use +.Nm getsyms +instead. +.It Cm tr Ar interface +Debug a remote system via the specified serial or firewire interface. +.It Cm tr0 +Debug a remote system via serial interface +.Pa /dev/cuaa0 . +.It Cm tr1 +Debug a remote system via serial interface +.Pa /dev/cuaa1 . +.It Cm trf +Debug a remote system via firewire interface at default port 5556. +.El +.Pp +The commands +.Nm tr0 , +.Nm tr1 +and +.Nm trf +are convenience commands which invoke +.Nm tr . +.Ss "The current process environment" +The following macros are convenience functions intended to make things easier +than the standard +.Nm gdb +commands. +.Bl -ohang -offset 3m +.It Cm f0 +Select stack frame 0 and show assembler-level details. +.It Cm f1 +Select stack frame 1 and show assembler-level details. +.It Cm f2 +Select stack frame 2 and show assembler-level details. +.It Cm f3 +Select stack frame 3 and show assembler-level details. +.It Cm f4 +Select stack frame 4 and show assembler-level details. +.It Cm f5 +Select stack frame 5 and show assembler-level details. +.It Cm xb +Show 12 words in hex, starting at current +.Va ebp +value. +.It Cm xi +List the next 10 instructions from the current +.Va eip +value. +.It Cm xp +Show the register contents and the first four parameters of the current stack +frame. +.It Cm xp0 +Show the first parameter of current stack frame in various formats. +.It Cm xp1 +Show the second parameter of current stack frame in various formats. +.It Cm xp2 +Show the third parameter of current stack frame in various formats. +.It Cm xp3 +Show the fourth parameter of current stack frame in various formats. +.It Cm xp4 +Show the fifth parameter of current stack frame in various formats. +.It Cm xs +Show the last 12 words on stack in hexadecimal. +.It Cm xxp +Show the register contents and the first ten parameters. +.It Cm z +Single step 1 instruction (over calls) and show next instruction. +.It Cm zs +Single step 1 instruction (through calls) and show next instruction. +.El +.Ss "Examining other processes" +The following macros access other processes. +.Nm gdb +does not understand the concept of multiple processes, so they effectively +bypass the entire +.Nm gdb +environment. +.Bl -ohang -offset 3m +.It Cm btp Ar pid +Show a backtrace for the process +.Va pid . +.It Cm btpa +Show backtraces for all processes in the system. +.It Cm btpp +Show a backtrace for the process previously selected with +.Nm defproc . +.It Cm btr Ar ebp +Show a backtrace from the +.Va ebp +address specified +.It Cm defproc Ar pid +Specify the PID of the process for some other commands in this section. +.It Cm fr Ar frame +Show frame +.Va frame +of the stack of the process previously selected with +.Nm defproc . +.It Cm pcb Ar proc +Show some pcb contents of process +.Ar proc . +.El +.Ss "Examining data structures" +You can use standard +.Nm gdb +commands to look at most data structures. The macros in this section are +convenience functions which typically display the data in a more readable +format, or which omit less interesting parts of the structure. +.Bl -ohang -offset 3m +.It Cm bp +Show information about the buffer header pointed to by the variable +.Va bp +in the current frame. +.It Cm bpd +Show the contents +.Vt (char*) +of +.Va bp->data +in the current frame. +.It Cm bpl +Show detailed information about the buffer header +.Vt (struct bp) +pointed at by the local variable +.Va bp . +.It Cm bpp bp +Show summary information about the buffer header +.Vt (struct bp) +pointed at by the parameter +.Va bp . +.It Cm bx +Print a number of fields from the buffer header pointed at in by the pointer +.Va bp +in the current environment. +.It Cm vdev +Show some information of the vnode pointed to by the local variable +.Va vp . +.El +.Ss "Miscellaneous macros" +.Bl -ohang -offset 3m +.It Cm checkmem +Check unallocated memory for modifications. +This assumes that the kernel has been compiled with +.Cd options DIAGNOSTIC +This causes the contents of free memory to be set to +.Li 0xdeadc0de . +.It Cm dmesg +Print the system message buffer. This corresponds to the +.Nm dmesg +command. +It can take a very long time over a serial line, and it's even slow via firewire +or local memory due to inefficiencies in +.Nm gdb . +This macro used to be called +.Nm msgbuf . +.It Cm kldstat +Equivalent of the kldstat(8) command without options +.It Cm pname +Print the command name of the current process. +.It Cm ps +Show process status. +This corresponds in concept, but not in appearance, to the +.Nm ps +command. +.It Cm y +Kludge for writing macros. When writing macros, it's convenient to paste them +back into the +.Nm gdb +window. Unfortunately, if the macro is already defined, +.Nm gdb +insists on asking +.Bd -literal -offset 5m +Redefine foo? +.Ed +.Pp +It won't give up until you answer +.Li y . +This command is that answer. It does nothing else except to print a warning +message to remind you to remove it again. +.El +.Sh AUTHORS +This man page was written by +.An "Greg Lehey" Aq grog@FreeBSD.org +.Sh SEE ALSO +.Xr ddb 4 , +.Xr fwchat 8 , +.Xr fwcontrol 8 , +.Xr gdb 1 , +.Xr vinumdebug 4 . +.\" .Sh HISTORY +.Sh BUGS +.Bl -bullet -offset indent -compact +.It +.Nm +was never designed to debug kernels, and it's not a very good match. +Many problems exist. +.It +The debugging macros ``just growed''. +In general, the person who wrote them did so while looking for a specific +problem, so they may not be general enough, and they may behave badly when used +in ways for which they were not intended, even if those ways make sense. +.It +Serial debugging is very slow, and race conditions can make it difficult to run +the link at more than 9600 bps. Firewire connections do not have this problem. +.It +Many of these commands only work on the ia32 architecture. +.El |