.\" $FreeBSD$ .Dd January 16, 1996 .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 .Nm requires the presence of the .Xr ddb 4 kernel debugger. Commands exist to switch between .Nm and .Xr ddb 4 . .Ss 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 kernel.debug /dev/mem\fP .Ed .Pp In this mode, you can look at live data and 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 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 To use a firewire link, a number of steps must be performed: .Pp \fITo be completed\fP\/ .Pp 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 . .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 . .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 rq Show information about the request pointed to by the variable .Va rq in the current frame. .It Cm rqe Show information about the request element pointed to by the variable .Va rqe in the current frame. .It Cm rqq rq Show information about the request .Vt ( struct rq ) pointed at by .Va rq . .It Cm rqq0 Print information on some Vinum request structures. .It Cm rqq1 Print information on some Vinum request structures. .It Cm rrqe Ar rqe Show information about the request element .Vt ( struct rqe ) pointed at by the parameter .Va rqe . .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 finfo Show recently freed Vinum memory blocks. .It Cm kldstat Equivalent of the kldstat(8) command without options .It Cm meminfo Equivalent of .Nm vinum Ar info Fl v command. .It Cm msgbuf Print the system message buffer. This corresponds to the .Nm dmesg command. It can take a very long time over a serial line. .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 rqi Print out a simplified version of the same information as the .Nm vinum Ar info Fl V command. .It Cm rqinfo Show the Vinum request log buffer like the .Nm vinum Ar info Fl V 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 gdb 1 .\" .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