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