From fb35cd083a3cb6103d58831e737689109c19322a Mon Sep 17 00:00:00 2001 From: Hidetoshi Shimokawa Date: Thu, 23 Sep 2004 06:44:30 +0000 Subject: [PATCH] Add dcons(4) related manpages. --- share/man/man4/Makefile | 5 +- share/man/man4/dcons.4 | 101 ++++++ share/man/man4/dcons_crom.4 | 62 ++++ share/man/man4/gdb.4 | 614 ++++++++++++++++++++++++++++++++++++ 4 files changed, 781 insertions(+), 1 deletion(-) create mode 100644 share/man/man4/dcons.4 create mode 100644 share/man/man4/dcons_crom.4 create mode 100644 share/man/man4/gdb.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 87ddf89942..733c113806 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,6 +1,6 @@ # @(#)Makefile 8.1 (Berkeley) 6/18/93 # $FreeBSD: src/share/man/man4/Makefile,v 1.83.2.66 2003/06/04 17:10:30 sam Exp $ -# $DragonFly: src/share/man/man4/Makefile,v 1.12 2004/09/20 20:38:17 eirikn Exp $ +# $DragonFly: src/share/man/man4/Makefile,v 1.13 2004/09/23 06:44:30 simokawa Exp $ MAN= aac.4 \ adv.4 \ @@ -35,6 +35,8 @@ MAN= aac.4 \ cue.4 \ da.4 \ dc.4 \ + dcons.4 \ + dcons_crom.4 \ ddb.4 \ de.4 \ disc.4 \ @@ -53,6 +55,7 @@ MAN= aac.4 \ fwe.4 \ fwohci.4 \ fxp.4 \ + gdb.4 \ gif.4 \ gre.4 \ gusc.4 \ diff --git a/share/man/man4/dcons.4 b/share/man/man4/dcons.4 new file mode 100644 index 0000000000..4ffc321cdd --- /dev/null +++ b/share/man/man4/dcons.4 @@ -0,0 +1,101 @@ +.\" Copyright (c) 2003 Hidetoshi Shimokawa +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man4/dcons.4,v 1.5 2004/06/17 19:51:17 ru Exp $ +.\" $DragonFly: src/share/man/man4/dcons.4,v 1.1 2004/09/23 06:44:30 simokawa Exp $ +.\" +.Dd February 11, 2003 +.Dt DCONS 4 +.Os +.Sh NAME +.Nm dcons +.Nd dumb console device driver +.Sh SYNOPSIS +.Cd device dcons +.Pp +.Cd options DDB +.Cd options ALT_BREAK_TO_DEBUGGER +.Pp +.Cd device firewire +.Sh DESCRIPTION +The +.Nm +device is a simple console device which just reads from and writes to +an allocated buffer for input and output respectively. +It is of no use by itself and it is supposed that the buffer is accessed +via a bus like +.Xr firewire 4 +or +.Xr kvm 3 +for interaction. +.Pp +The buffer consists of 4 channels. +There are 2 ports, one for the console TTY and another is GDB port, +then each port has an input channel and an output channel. +.Sh EXAMPLES +If you want to run +.Xr getty 8 +on +.Nm , +insert the following line into +.Xr /etc/ttys 5 +and send a +.Dv HUP +signal to +.Xr init 8 +using +.Xr kill 1 . +.Bd -literal -offset indent +dcons "/usr/libexec/getty std.9600" vt100 on secure +.Ed +.Pp +Once the +.Xr fwochi 4 +device is initialized to allow physical access, +the buffer can be accessed from another host via a +.Xr firewire 4 +bus using the +.Xr dconschat 8 +application. +See +.Xr dconschat 8 +for more details. +.Sh FILES +.Bl -tag -width indent -compact +.It Pa /dev/dcons +.It Pa /etc/ttys +.El +.Sh SEE ALSO +.Xr dcons_crom 4 , +.Xr ddb 4 , +.Xr firewire 4 , +.Xr fwohci 4 , +.Xr ttys 5 , +.Xr dconschat 8 , +.Xr fwcontrol 8 +.Sh AUTHORS +.An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org +.Sh BUGS +This driver is +.Ud . diff --git a/share/man/man4/dcons_crom.4 b/share/man/man4/dcons_crom.4 new file mode 100644 index 0000000000..b0adf714c9 --- /dev/null +++ b/share/man/man4/dcons_crom.4 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2003 Hidetoshi Shimokawa +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man4/dcons_crom.4,v 1.4 2004/06/17 19:51:17 ru Exp $ +.\" $DragonFly: src/share/man/man4/dcons_crom.4,v 1.1 2004/09/23 06:44:30 simokawa Exp $ +.\" +.Dd June 16, 2003 +.Dt DCONS_CROM 4 +.Os +.Sh NAME +.Nm dcons_crom +.Nd Configuration ROM stub for +.Xr dcons 4 +.Sh SYNOPSIS +.Cd device dcons_crom +.Cd device dcons +.Cd device firewire +.Sh DESCRIPTION +The +.Nm +exposes the buffer address of +.Xr dcons 4 +through the Configuration ROM of +.Xr firewire 4 . +This address is supposed to be used by +.Xr dconschat 8 . +.Sh SEE ALSO +.Xr dcons 4 , +.Xr firewire 4 , +.Xr fwohci 4 , +.Xr dconschat 8 , +.Xr fwcontrol 8 +.Sh AUTHORS +.An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org +.Sh BUGS +If you load +.Pa dcons_crom.ko +manually after the system is booted, you may +have to initiate a bus reset using +.Dq Nm fwcontrol Fl r +to update the Configuration ROM. diff --git a/share/man/man4/gdb.4 b/share/man/man4/gdb.4 new file mode 100644 index 0000000000..16563fe438 --- /dev/null +++ b/share/man/man4/gdb.4 @@ -0,0 +1,614 @@ +.\" Copyright (c) 2003 Greg Lehey +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man4/gdb.4,v 1.9 2004/01/28 00:02:10 grog Exp $ +.\" $DragonFly: src/share/man/man4/gdb.4,v 1.1 2004/09/23 06:44:30 simokawa Exp $ +.\" +.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" +.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: +.Bl -bullet +.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. +.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 +With a firewire link, it can be used to examine the memory of a remote system +without the participation of that system. +In this mode, the processor cannot be stopped and single stepped, but it can be +of use when the remote system has crashed and is no longer responding. +.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 +.Pq Cd "makeoptions DEBUG=-g" . +It is easiest to perform operations from the kernel build directory, by default +.Pa /usr/obj/usr/src/sys/GENERIC . +.Pp +First, ensure you have a copy of the debug macros in the directory: +.Pp +.Dl "make gdbinit" +.Pp +This command performs some transformations on the macros installed in +.Pa /usr/src/tools/debugscripts +to adapt them to the local environment. +.Ss "Inspecting the environment of the local machine" +To look at and change the contents of the memory of the system you are running +on, +.Pp +.Dl "gdb -k -wcore kernel.debug /dev/mem" +.Pp +In this mode, you need the +.Fl k +flag to indicate to +.Xr gdb 1 +that the +.Dq "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 cannot +.Dq continue +execution, so they will not 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: +.Pp +.Dl "gdb -k kernel.debug /var/crash/vmcore.29" +.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" +In the following discussion, the term +.Dq "local system" +refers to the system running the debugger, and +.Dq "remote system" +refers to the live system being debugged. +.Pp +To debug a live system with a remote link, the kernel must be compiled with the +option +.Cd "options DDB" . +The option +.Cd "options BREAK_TO_DEBUGGER" +enables the debugging machine stop the debugged machine once a connection has +been established by pressing +.Ql ^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 0x10 ) , +so the entry in +.Pa /boot/device.hints +should be: +.Pp +.Dl hint.sio.0.flags="0x90" +.Pp +To share a console and debug connection on a serial line, use the +.Cd "options GDB_REMOTE_CHAT" +option. +.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 option +.Cd "options DDB" . +The +.Cd "options GDB_REMOTE_CHAT" +is not necessary, since the firewire implementation uses separate ports for the +console and debug connection. +.Pp +A number of steps must be performed to set up a firewire link: +.Bl -bullet +.It +Ensure that both systems have +.Xr firewire 4 +support, and that the kernel of the remote system includes the +.Xr dcons 4 +and +.Xr dcons_crom 4 +drivers. +If they are not compiled into the kernel, load the KLDs: +.Pp +.Dl "kldload firewire" +.Pp +On the remote system only: +.Bd -literal -offset indent +kldload dcons +kldload dcons_crom +.Ed +.Pp +You should see something like this in the +.Xr dmesg 8 +output of the remote system: +.Bd -literal -offset indent +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: on firewire0 +dcons_crom0: bus_addr 0x22a000 +.Ed +.Pp +It is a good idea to load these modules at boot time with the following entry in +.Pa /boot/loader.conf : +.Pp +.Dl dcons_crom_enable="YES" +.Pp +This ensures that all three modules are loaded. +There is no harm in loading +.Xr dcons 4 +and +.Xr dcons_crom 4 +on the local system, but if you only want to load the +.Xr firewire 4 +module, include the following in +.Pa /boot/loader.conf : +.Pp +.Dl firewire_enable="YES" +.It +Next, use +.Xr fwcontrol 8 +to find the firewire node corresponding to the remote machine. +On the local machine you might see: +.Bd -literal -offset indent +# fwcontrol +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 remote machine, it looks like this: +.Bd -literal -offset indent +# fwcontrol +2 devices (info_len=2) +node EUI64 status + 0 0x000199000003622b 0 + 1 0x00c04f3226e88061 1 +.Ed +.It +Next, establish a firewire connection with +.Xr dconschat 8 : +.Pp +.Dl "dconschat -br -G 5556 -t 0x000199000003622b" +.Pp +.Li 0x000199000003622b +is the EUI64 address of the remote node, as determined from the output of +.Xr fwcontrol 8 +above. +When started in this manner, +.Xr dconschat 8 +establishes a local tunnel connection from port +.Li localhost:5556 +to the remote debugger. +You can also establish a console port connection with the +.Fl C +option to the same invocation +.Xr dconschat 8 . +See the +.Xr dconschat 8 +manpage for further details. +.Pp +The +.Xr dconschat 8 +utility +does not return control to the user. +It displays error messages and console output for the remote system, so it is a +good idea to start it in its own window. +.It +Finally, establish connection: +.Bd -literal -offset indent +# gdb kernel.debug +GNU gdb 5.2.1 (FreeBSD) +.Em "(political statements omitted)" +Ready to go. Enter 'tr' to connect to the remote target +with /dev/cuaa0, 'tr /dev/cuaa1' to connect to a different port +or 'trf portno' to connect to the remote target with the firewire +interface. portno defaults to 5556. + +Type 'getsyms' after connection to load kld symbols. + +If you're debugging a local system, you can use 'kldsyms' instead +to load the kld symbols. That's a less obnoxious interface. +(gdb) trf +0xc21bd378 in ?? () +.Ed +.Pp +The +.Ic trf +macro assumes a connection on port 5556. +If you want to use a different port (by changing the invocation of +.Xr dconschat 8 +above), use the +.Ic tr +macro instead. +For example, if you want to use port 4711, run +.Xr dconschat 8 +like this: +.Pp +.Dl "dconschat -br -G 4711 -t 0x000199000003622b" +.Pp +Then establish connection with: +.Bd -literal -offset indent +(gdb) tr localhost:4711 +0xc21bd378 in ?? () +.Ed +.El +.Ss "Non-cooperative debugging a live system with a remote firewire link" +In addition to the conventional debugging via firewire described in the previous +section, it is possible to debug a remote system without its cooperation, once +an initial connection has been established. +This corresponds to debugging a local machine using +.Pa /dev/mem . +It can be very useful if a system crashes and the debugger no longer responds. +To use this method, set the +.Xr sysctl 8 +variables +.Va hw.firewire.fwmem.eui64_hi +and +.Va hw.firewire.fwmem.eui64_lo +to the upper and lower halves of the EUI64 ID of the remote system, +respectively. +From the previous example, the remote machine shows: +.Bd -literal -offset indent +# fwcontrol +2 devices (info_len=2) +node EUI64 status + 0 0x000199000003622b 0 + 1 0x00c04f3226e88061 1 +.Ed +.Pp +Enter: +.Bd -literal -offset indent +# sysctl -w hw.firewire.fwmem.eui64_hi=0x00019900 +hw.firewire.fwmem.eui64_hi: 0 -> 104704 +# sysctl -w hw.firewire.fwmem.eui64_lo=0x0003622b +hw.firewire.fwmem.eui64_lo: 0 -> 221739 +.Ed +.Pp +Note that the variables must be explicitly stated in hexadecimal. +After this, you can examine the remote machine's state with the following input: +.Bd -literal -offset indent +# gdb -k kernel.debug /dev/fwmem0.0 +GNU gdb 5.2.1 (FreeBSD) +.Em "(messages omitted)" +Reading symbols from /boot/kernel/dcons.ko...done. +Loaded symbols for /boot/kernel/dcons.ko +Reading symbols from /boot/kernel/dcons_crom.ko...done. +Loaded symbols for /boot/kernel/dcons_crom.ko +#0 sched_switch (td=0xc0922fe0) at /usr/src/sys/kern/sched_4bsd.c:621 +0xc21bd378 in ?? () +.Ed +.Pp +In this case, it is not necessary to load the symbols explicitly. +The remote system continues to run. +.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 -tag -width indent +.It Ic ddb +Switch back to +.Xr ddb 4 . +This command is only meaningful when performing remote debugging. +.It Ic getsyms +Display +.Ic kldstat +information for the target machine and invite user to paste it back in. +This is required because +.Nm +does not allow data to be passed to shell scripts. +It is necessary for remote debugging and crash dumps; for local memory debugging +use +.Ic kldsyms +instead. +.It Ic kldsyms +Read in the symbol tables for the debugging machine. +This does not work for +remote debugging and crash dumps; use +.Ic getsyms +instead. +.It Ic tr Ar interface +Debug a remote system via the specified serial or firewire interface. +.It Ic tr0 +Debug a remote system via serial interface +.Pa /dev/cuaa0 . +.It Ic tr1 +Debug a remote system via serial interface +.Pa /dev/cuaa1 . +.It Ic trf +Debug a remote system via firewire interface at default port 5556. +.El +.Pp +The commands +.Ic tr0 , tr1 +and +.Ic trf +are convenience commands which invoke +.Ic tr . +.Ss "The current process environment" +The following macros are convenience functions intended to make things easier +than the standard +.Xr gdb 1 +commands. +.Bl -tag -width indent +.It Ic f0 +Select stack frame 0 and show assembler-level details. +.It Ic f1 +Select stack frame 1 and show assembler-level details. +.It Ic f2 +Select stack frame 2 and show assembler-level details. +.It Ic f3 +Select stack frame 3 and show assembler-level details. +.It Ic f4 +Select stack frame 4 and show assembler-level details. +.It Ic f5 +Select stack frame 5 and show assembler-level details. +.It Ic xb +Show 12 words in hex, starting at current +.Va ebp +value. +.It Ic xi +List the next 10 instructions from the current +.Va eip +value. +.It Ic xp +Show the register contents and the first four parameters of the current stack +frame. +.It Ic xp0 +Show the first parameter of current stack frame in various formats. +.It Ic xp1 +Show the second parameter of current stack frame in various formats. +.It Ic xp2 +Show the third parameter of current stack frame in various formats. +.It Ic xp3 +Show the fourth parameter of current stack frame in various formats. +.It Ic xp4 +Show the fifth parameter of current stack frame in various formats. +.It Ic xs +Show the last 12 words on stack in hexadecimal. +.It Ic xxp +Show the register contents and the first ten parameters. +.It Ic z +Single step 1 instruction (over calls) and show next instruction. +.It Ic zs +Single step 1 instruction (through calls) and show next instruction. +.El +.Ss "Examining other processes" +The following macros access other processes. +The +.Nm +debugger +does not understand the concept of multiple processes, so they effectively +bypass the entire +.Nm +environment. +.Bl -tag -width indent +.It Ic btp Ar pid +Show a backtrace for the process +.Ar pid . +.It Ic btpa +Show backtraces for all processes in the system. +.It Ic btpp +Show a backtrace for the process previously selected with +.Ic defproc . +.It Ic btr Ar ebp +Show a backtrace from the +.Ar ebp +address specified. +.It Ic defproc Ar pid +Specify the PID of the process for some other commands in this section. +.It Ic fr Ar frame +Show frame +.Ar frame +of the stack of the process previously selected with +.Ic defproc . +.It Ic pcb Ar proc +Show some PCB contents of the process +.Ar proc . +.El +.Ss "Examining data structures" +You can use standard +.Xr gdb 1 +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 -tag -width indent +.It Ic bp +Show information about the buffer header pointed to by the variable +.Va bp +in the current frame. +.It Ic bpd +Show the contents +.Pq Vt "char *" +of +.Va bp->data +in the current frame. +.It Ic bpl +Show detailed information about the buffer header +.Pq Vt "struct bp" +pointed at by the local variable +.Va bp . +.It Ic bpp Ar bp +Show summary information about the buffer header +.Pq Vt "struct bp" +pointed at by the parameter +.Ar bp . +.It Ic bx +Print a number of fields from the buffer header pointed at in by the pointer +.Ar bp +in the current environment. +.It Ic vdev +Show some information of the +.Vt vnode +pointed to by the local variable +.Va vp . +.El +.Ss "Miscellaneous macros" +.Bl -tag -width indent +.It Ic 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 Ic dmesg +Print the system message buffer. +This corresponds to the +.Xr dmesg 8 +utility. +This macro used to be called +.Ic msgbuf . +It can take a very long time over a serial line, +and it is even slower via firewire +or local memory due to inefficiencies in +.Nm . +When debugging a crash dump or over firewire, it is not necessary to start +.Nm +to access the message buffer: instead, use an appropriate variation of +.Bd -literal -offset indent +dmesg -M /var/crash/vmcore.0 -N kernel.debug +dmesg -M /dev/fwmem0.0 -N kernel.debug +.Ed +.It Ic kldstat +Equivalent of the +.Xr kldstat 8 +utility without options. +.It Ic pname +Print the command name of the current process. +.It Ic ps +Show process status. +This corresponds in concept, but not in appearance, to the +.Xr ps 1 +utility. +When debugging a crash dump or over firewire, it is not necessary to start +.Nm +to display the +.Xr ps 1 +output: instead, use an appropriate variation of +.Bd -literal -offset indent +ps -M /var/crash/vmcore.0 -N kernel.debug +ps -M /dev/fwmem0.0 -N kernel.debug +.Ed +.It Ic y +Kludge for writing macros. +When writing macros, it is convenient to paste them +back into the +.Nm +window. +Unfortunately, if the macro is already defined, +.Nm +insists on asking +.Pp +.Dl "Redefine foo?" +.Pp +It will not give up until you answer +.Ql 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 gdb 1 , +.Xr ps 1 , +.Xr ddb 4 , +.Xr firewire 4 , +.Xr vinumdebug 4 , +.Xr dconschat 8 , +.Xr dmesg 8 , +.Xr fwcontrol 8 , +.Xr kldload 8 +.Sh BUGS +The +.Xr gdb 1 +debugger +was never designed to debug kernels, and it is not a very good match. +Many problems exist. +.Pp +The +.Nm +implementation is very inefficient, and many operations are slow. +.Pp +Serial debugging is even slower, and race conditions can make it difficult to +run the link at more than 9600 bps. +Firewire connections do not have this problem. +.Pp +The debugging macros +.Dq "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. +.Pp +Many of these commands only work on the ia32 architecture. -- 2.41.0