✎ 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.  In order to do this, you must either have two computers or run gPXE under virtualization (e.g. [[http://bellard.org/qemu/|QEMU]]).

When using two computers, one computer will run gPXE while the other will run GDB.  GDB communicates with gPXE over the serial port.  You will need a null modem serial cable to connect the two computers.

===== 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  GDBSTUB                 /* Remote GDB debugging */

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

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

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

You also need to build an ELF file that GDB can load symbols from:
<code>
$ make bin/gpxe.hd.tmp
</code>

Once ''bin/gpxe.hd.tmp'' exists, the ''make'' command will update it and you do not need to use ''make bin/gpxe.hd.tmp'' again.

===== Using GDB remote debugging =====
==== QEMU ====
Run gPXE in QEMU with the serial port redirected to a TCP port:
<code>
$ qemu -serial tcp::4444,server bin/gpxe.usb
</code>

Now you can connect with GDB from another terminal:
<code>
$ gdb
(gdb) file bin/gpxe.hd.tmp
(gdb) target remote localhost:4444
</code>

==== Two computers ====
**(Untested)** Connect the two computers using a null modem serial cable.  The gPXE serial port settings can be changed in ''src/config.h''.

Boot the gPXE machine and connect with GDB from the other machine:
<code>
$ gdb
(gdb) file bin/gpxe.hd.tmp
(gdb) target remote /dev/ttyS0
</code>

===== 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: • week6 • 2006 • ubuntu_iscsi2 • bootingmemdisk • wirelessboot • design • winpe_memdisk • aoebootprepdebianetch • usermanual • week12 • notes • week10 • notes • journal • 2009 • drivers • commandline • staging • 2011 • winxp_smb