✎ dev:gdbstub - Etherboot/gPXE Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== GDB remote debugging ======

===== Overview =====
You can use the [[http://www.gnu.org/software/gdb/|GNU Project Debugger (GDB)]] to debug gPXE.  You either need two computers or virtualization software (e.g. [[http://bellard.org/qemu/|QEMU]]).  One host runs gPXE while the other runs GDB.

gPXE supports debugging via serial port or over the network.  For serial, you need a null modem serial cable.  For network, you need the machine to be connected to a network with UDP port 43770 traffic allowed.

===== Building with GDB enabled =====
Create the following file in ''src/config-local.h'':
<code>
/* @BEGIN general.h
 *
 * Local config.h changes that do not get committed to git.
 *
 */

#define  GDBSERIAL               /* Remote GDB debugging over serial */
#define  GDBUDP                  /* Remote GDB debugging over UDP
                                  * (both may be set) */

/* @END general.h */
</code>

This file overrides ''src/config.h'' but is not under version control.  Therefore you will never accidentally commit a patch that enables GDB debugging.

Now build gPXE:
<code>
$ cd src
$ make
</code>

Notice that the ''bin'' directory contains not only the gPXE image you built, but also a file with the same name but ending with ''.tmp''.  This file is an ELF with debugging symbols that we can load in GDB.

===== Using GDB remote debugging =====
==== Breaking into the debugger ====
You can break into the debugger from the gPXE shell with the ''gdbstub'' command:
<code>
Usage:
  gdbstub <transport> [<options>...]

Start remote debugging using one of the following transports:
  serial           use serial port (if compiled in)
  udp <interface>  use UDP over network interface (if compiled in)
</code>

For example:
<code>
gdbstub serial     # debug via serial port
gdbstub udp net0   # debug over network interface 'net0'
</code>

gPXE will be waiting for a connection from a remote GDB.

==== Connecting with GDB ====
First we load debugging symbols:
<code>
$ cd gpxe/src
$ gdb
(gdb) file bin/gpxe.hd.tmp   # or equivalent for your gPXE image filename
</code>

Next you should set up the serial port in GDB if you are debugging via serial.  The ''set remotebaud N'' command is used to set the serial port baud rate to ''N''.  See [[http://sourceware.org/gdb/current/onlinedocs/gdb_18.html#SEC173|Remote Configuration]] in the GDB Manual.

Now connect to gPXE, which is already waiting since we entered the ''gdbstub'' command in the gPXE shell:
<code>
target remote /dev/ttyS0            # for serial debugging
target remote udp:192.168.1.2:43770 # for network debugging on gPXE
                                    # host 192.168.1.2
target remote 192.168.1.2:43770     # if you are forwarding over TCP
                                    # using QEMU -serial
</code>

You should soon see the normal GDB prompt and be able to start debugging.  If you have trouble, try the ''set debug remote 1'' GDB command to see the traffic between GDB and gPXE.

==== QEMU ====
To run gPXE in QEMU with the serial port redirected to a TCP port:
<code>
$ qemu -serial tcp::43770,server bin/gpxe.usb
</code>

==== Breaking into the debugger programmatically ====
You can break into the debugger without using the gPXE shell.  The following break into the debugger for serial debugging:
<code>
#include <gpxe/gdbserial.h>
#include <gpxe/gdbstub.h>
[...]
gdbstub_start ( gdbserial_configure() );
</code>

Here is the same thing for network debugging:
<code>
#include <gpxe/gdbudp.h>
#include <gpxe/gdbstub.h>
[...]
struct sockaddr_in sa = {
    /* FILL IN OR SET TO
       ZERO FOR DEFAULTS */
};
gdbstub_start ( gdbudp_configure ( "net0", &sa ) );
</code>

===== Limitations =====
Interrupt (''CTRL + C'') in GDB does not work.  Implementing this is not possible since gPXE does not use interrupts.  This means that you cannot hit ''CTRL + C'' if gPXE is in an infinite loop.

Debugging works for 32-bit protected mode.  There is no support for 16-bit real-mode.

Debugging can safely be used after ''initialise()'' and ''startup()'' have been called in ''main()''.  If you need to use it during ''initialise()'' or ''startup()'', take special care and modify the code if necessary (e.g. by hardcoding calls to initialize it beforehand).

When debugging over the network, gPXE will drop network packets while you are in the debugger.  This means you should use serial debugging if you need to minimize side-effects on gPXE.  You may also try using a dedicated NIC for debugging so that traffic to the primary NIC is not dropped while you are in the debugger.  Note that traffic may still be dropped if you stay in the debugger so long that the receive buffers fill up (i.e. gPXE is not running while you are in the debugger).

===== GDB documentation =====
  * [[http://sourceware.org/gdb/current/onlinedocs/gdb_toc.html|Debugging with GDB (official manual)]]
  * [[http://darkdust.net/files/GDB%20Cheat%20Sheet.pdf|A cheatsheet]], note that there are several others [[http://google.com/search?q=gdb+cheat+sheet|available]].

===== Getting help =====
You can email the [[https://lists.sourceforge.net/lists/listinfo/etherboot-developers|Etherboot-Developers]] list or ask on the [[http://www.etherboot.org/wiki/contact|IRC channel]].
Trace: • 2010 • isolinux • usermanual • 2011 • bootingmemdisk • gdbstub • journal • usbwithstorage • week6 • project_plan • journal • doc • gpxeonvmware • ubuntu_iscsi2 • 2009 • commandline