This is an old revision of the document!
====== 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. ===== 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]].
