✎ 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.  You will need a null modem serial cable to connect the two computers.

===== Status =====
This page documents the latest gPXE source code in git.  If you are not sure which version you are using, install [[http://git.or.cz/|git]] and grab the latest gPXE code:
<code>
$ git clone git://git.etherboot.org/scm/gpxe.git
</code>

===== 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''.  The GDB serial port settings can be changed using the [[http://sourceware.org/gdb/current/onlinedocs/gdb_18.html#SEC173|"set remotebaud" command]].

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>

===== Step-by-step screencast =====
[[http://video.google.com/videoplay?docid=-5951365569769661989&hl=en|Watch the screencast]] to see these steps performed.  A higher quality version is available [[http://etherboot.org/share/stefanha/gdbstub.mpeg|here]] (12 MB).

[[http://video.google.com/videoplay?docid=-5951365569769661989&hl=en|{{:dev:screencast.png|GDB Remote Debugging for gPXE Screencast}}]]

===== 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: • make_usb_drive • concepts • acknowledgements • howtos • week10 • winnt_iscsi • qemu • less1 • download • win2k3 • ideas • ubuntu_iscsi • 2011 • ubuntu910 • srp_install • dnsmasq