✎ soc:2008:stefanha:project_plan:start

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Stefan Hajnoczi: GDB Remote Debugging ======

===== Project Plan =====

==== Summary ====

This project will enable gPXE debugging using the GDB remote target feature.  Developers will be able to inspect gPXE from a remote machine and control its execution.

Due to the low-level nature of gPXE and the environment it executes in, there is little support for debugging and crash analysis. This can make understanding and fixing errors frustrating.

The GNU Debugger (GDB) can debug remotely using a simple protocol.  The code that implements this protocol on the target is called a GDB stub.

Using remote debugging, developers will be able to get much better access to gPXE while it is running or when it has crashed. It will be easier to diagnose crashes and to understand error conditions.

==== Outline ====

=== The GDB Remote Protocol ===
The GNU Debugger (GDB) has support for remote debugging.  This lets users debug applications running on other machines or in special environments, like under virtualization.  Remote debugging works by speaking a simple protocol that carries checksummed packets of commands and replies.

The protocol is extensible and most commands are optional.  A minimal GDB stub must implement the following commands:
  * Register read/write.  These commands allow the debugger to get and set the state of the CPU.
  * Memory read/write.  These commands allows the debugger to peek and poke memory, as well as set breakpoints.
  * Single-step and continue.  These commands control the execution of a program.

Additional GDB protocol commands provide more advanced features, like hardware breakpoints, or optimizations of existing commands, like binary memory dumps for faster transfer.

I will start by implementing the minimal set of commands.  If we find that additional commands are useful in practice, I will also implement them.

=== GDB Stub Execution Model ===
The GDB stub controls the execution of gPXE, but the GDB stub is part of gPXE.  This sounds recursive - and it is!  Therefore, care must be taken to isolate the GDB stub from gPXE.  If the GDB stub is not isolated, it can hang itself.  For example, if the GDB stub calls ''strcmp()'', then placing a breakpoint inside ''strcmp()'' may lead to recursion in the GDB stub.

Only 32-bit protected mode support is planned.  The bulk of gPXE runs in 32-bit protected mode and gdb/binutils support this mode well.

=== Transports ===
Several transports are supported by GDB including serial, UDP, and TCP.  Serial is simple and serves as a good starting point.  UDP and TCP are more flexible but also more complex.  After discussion with mcb30, it looks like UDP is in scope and should be implemented.  I believe TCP is not a big win if UDP support is already in place.

==== Milestones and Timeline ====

  * Set up IDT and write interrupt handler.
  * Decide on interface for GDB transports and refactor serial console code to support serving as a GDB transport.
  * Implement GDB protocol encoder and decoder.
  * Implement memory read/write, including GDB scripts as tests.
  * Implement register read/write, including GDB scripts as tests.
  * Implement continue and single-step, including GDB scripts as tests.
  * Ensure that breakpoints are working, including GDB scripts as tests.
  * Implement UDP transport.
  * Documentation (how to debug, how to run tests).
  * (Possibly) implement TCP transport and support TCP listen sockets.
  * (Possibly) support running as a gPXE process for memory peek/poke during execution.

==== Reference links ====

  * [[http://code.google.com/soc/2008/etherboot/appinfo.html?csaid=13D4DE0EB18B0081|Google Summer of Code Application Information]]
  * [[http://sourceware.org/gdb/current/onlinedocs/gdb_33.html|GDB Remote Serial Protocol]]
  * [[http://sourceware.org/gdb/current/onlinedocs/gdb_18.html#SEC174|Debugging with GDB: Implementing a Remote Stub]]
  * [[http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/i386-stub.c?rev=1.5&content-type=text/x-cvsweb-markup&cvsroot=src|GDB's i386-stub.c]]
Trace: • iscsibootprepfc5 • iscsiboot • under_construction • 2008 • qemupxe • week6 • 2011 • elf-ebi-initramfs-lnxi-howto • journal • debian_lenny_iscsi • win2k8_iscsi_install