share/man/man4/gdb.4

   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.
 267
 268 Type 'getsyms' after connection to load kld symbols.
 269
 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.