Manual Pages  — GDB

• It can be used to examine the memory of the processor on which it runs.
• It can be used to analyse a processor dump after a panic.
• 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.
• 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.

When used for remote debugging, gdb requires the presence of the ddb(4) kernel debugger. Commands exist to switch between gdb and ddb(4).

In this mode, you need the -k flag to indicate to gdb(1) that the "dump file" /dev/mem is a kernel data file. You can look at live data, and if you include the -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 "continue" execution, so they will not work.

• Ensure that both systems have firewire(4) support, and that the kernel of the remote system includes the dcons(4) and dcons_crom(4) drivers. If they are not compiled into the kernel, load the KLDs:

      kldload firewire

  On the remote system only:

  kldload dcons
  kldload dcons_crom
  

  You should see something like this in the dmesg(8) output of the remote system:

  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
  

  It is a good idea to load these modules at boot time with the following entry in /boot/loader.conf:

      dcons_crom_enable="YES"

  This ensures that all three modules are loaded. There is no harm in loading dcons(4) and dcons_crom(4) on the local system, but if you only want to load the firewire(4) module, include the following in /boot/loader.conf:

      firewire_enable="YES"

• Next, use fwcontrol(8) to find the firewire node corresponding to the remote machine. On the local machine you might see:

  # fwcontrol
  2 devices (info_len=2)
  node        EUI64        status
     1  0x00c04f3226e88061      0
     0  0x000199000003622b      1
  

  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:

  # fwcontrol
  2 devices (info_len=2)
  node        EUI64        status
     0  0x000199000003622b      0
     1  0x00c04f3226e88061      1
  

• Next, establish a firewire connection with dconschat(8):

      dconschat -br -G 5556 -t 0x000199000003622b

  0x000199000003622b is the EUI64 address of the remote node, as determined from the output of fwcontrol(8) above. When started in this manner, dconschat(8) establishes a local tunnel connection from port localhost:5556 to the remote debugger. You can also establish a console port connection with the -C option to the same invocation dconschat(8). See the dconschat(8) manpage for further details.

  The 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.

• Finally, establish connection:

  # gdb kernel.debug
  GNU gdb 5.2.1 (FreeBSD)
   (political statements omitted)
  Ready to go.  Enter 'tr' to connect to the remote target
  with /dev/cuau0, 'tr /dev/cuau1' 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 are debugging a local system, you can use 'kldsyms' instead
  to load the kld symbols.  That is a less obnoxious interface.
  (gdb) trf
  0xc21bd378 in ?? ()
  

  The trf macro assumes a connection on port 5556. If you want to use a different port (by changing the invocation of dconschat(8) above), use the tr macro instead. For example, if you want to use port 4711, run dconschat(8) like this:

      dconschat -br -G 4711 -t 0x000199000003622b

  Then establish connection with:

  (gdb) tr localhost:4711
  0xc21bd378 in ?? ()
  

# fwcontrol
2 devices (info_len=2)
node        EUI64        status
   0  0x000199000003622b      0
   1  0x00c04f3226e88061      1

Enter:

# 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

Note that the variables must be explicitly stated in hexadecimal. After this, you can examine the remote machine's state with the following input:

# gdb -k kernel.debug /dev/fwmem0.0
GNU gdb 5.2.1 (FreeBSD)
 (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 ?? ()

In this case, it is not necessary to load the symbols explicitly. The remote system continues to run.

The gdb implementation is very inefficient, and many operations are slow.

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.

The debugging macros "just grew." 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.

Many of these commands only work on the ia32 architecture.