gdbstub

An ergonomic, featureful, and easy-to-integrate implementation of the GDB Remote Serial Protocol in Rust, with no-compromises #![no_std] support.

gdbstub makes it easy to integrate powerful guest debugging support to your emulator / hypervisor / debugger / embedded project. By implementing just a few basic methods of the gdbstub::Target trait, you can have a rich GDB debugging session up and running in no time!

gdbstub's API makes extensive use of a technique called Inlineable Dyn Extension Traits (IDETs) to expose fine-grained, zero-cost control over enabled GDB protocol features without relying on compile-time features flags. Aside from making it effortless to toggle enabled protocol features, IDETs also ensure that any unimplemented features are guaranteed to be dead-code-eliminated in release builds!

If you're looking for a quick snippet of example code to see what a featureful gdbstub integration might look like, check out examples/armv4t/gdb/mod.rs

• Documentation (gdbstub)
• Documentation (gdbstub_arch)
• Changelog
• 0.5 to 0.6 Transition Guide

Why use gdbstub?

• Excellent Ergonomics
  • Instead of simply exposing the underlying GDB protocol "warts and all", gdbstub tries to abstract as much of the raw GDB protocol details from the user.
    • Instead of having to dig through obscure XML files deep the GDB codebase just to read/write from CPU/architecture registers, gdbstub comes with a community-curated collection of built-in architecture definitions for most popular platforms!
    • Organizes GDB's countless optional protocol extensions into a coherent, understandable, and type-safe hierarchy of traits.
    • Automatically handles client/server protocol feature negotiation, without needing to micro-manage the specific qSupported packet response.
  • gdbstub makes extensive use of Rust's powerful type system + generics to enforce protocol invariants at compile time, minimizing the number of tricky protocol details end users have to worry about.
  • Using a novel technique called Inlineable Dyn Extension Traits (IDETs), gdbstub enables fine-grained control over active protocol extensions without relying on clunky cargo features or the use of unsafe code!
• Easy to Integrate
  • gdbstub's API is designed to be a "drop in" solution when you want to add debugging support into a project, and shouldn't require any large refactoring effort to integrate into an existing project.
• #![no_std] Ready & Size Optimized
  • gdbstub is a no_std first library, whereby all protocol features are required to be no_std compatible.
  • gdbstub does not require any dynamic memory allocation, and can be configured to use fixed-size, pre-allocated buffers. This enables gdbstub to be used on even the most resource constrained, no-alloc platforms.
  • gdbstub is entirely panic free in most minimal configurations*, resulting in substantially smaller and more robust code.
    • *See the Writing panic-free code section below for more details.
  • gdbstub is transport-layer agnostic, and uses a basic Connection interface to communicate with the GDB server. As long as target has some method of performing in-order, serial, byte-wise I/O (e.g: putchar/getchar over UART), it's possible to run gdbstub on it!
  • "You don't pay for what you don't use": All code related to parsing/handling protocol extensions is guaranteed to be dead-code-eliminated from an optimized binary if left unimplemented. See the Zero-overhead Protocol Extensions section below for more details.
  • gdbstub's minimal configuration has an incredibly low binary size + RAM overhead, enabling it to be used on even the most resource-constrained microcontrollers.
    • When compiled in release mode, using all the tricks outlined in min-sized-rust, a baseline gdbstub implementation can weigh in at less than 10kb of .text + .rodata! *
    • *Exact numbers vary by target platform, compiler version, and gdbstub revision. In mixed-language projects, cross-language LTO may be required (#101). Data was collected using the included example_no_std project compiled on x86_64.

Can I Use gdbstub in Production?

Yes, as long as you don't mind some API churn until 1.0.0 is released.

Due to gdbstub's heavy use of Rust's type system in enforcing GDB protocol invariants at compile time, it's often been the case that implementing new GDB protocol features has required making some breaking API changes. While these changes are typically quite minor, they are nonetheless semver-breaking, and may require a code-change when moving between versions. Any particularly involved changes will typically be documented in a dedicated transition guide document.

That being said, gdbstub has already been integrated into many real-world projects since its initial 0.1 release, and empirical evidence suggests that it seems to be doing its job quite well! Thusfar, most reported issues have been caused by improperly implemented Target and/or Arch implementations, while the core gdbstub library itself has proven to be reasonably bug-free.

See the Future Plans + Roadmap to 1.0.0 for more information on what features gdbstub still needs to implement before committing to API stability with version 1.0.0.

Debugging Features

The GDB Remote Serial Protocol is surprisingly complex, supporting advanced features such as remote file I/O, spawning new processes, "rewinding" program execution, and much, much more. Thankfully, most of these features are completely optional, and getting a basic debugging session up-and-running only requires implementing a few basic methods:

• Base GDB Protocol
  • Read/Write memory
  • Read/Write registers
  • Enumerating threads

Yep, that's right! That's all it takes to get gdb connected!

Of course, most use-cases will want to support additional debugging features as well. At the moment, gdbstub implements the following GDB protocol extensions:

• Automatic target architecture + feature configuration
• Resume
  • Continue
  • Single Step
  • Range Step
  • Reverse Step/Continue
• Breakpoints
  • Software Breakpoints
  • Hardware Breakpoints
  • Read/Write/Access Watchpoints (i.e: value breakpoints)
• Extended Mode
  • Launch new processes
  • Attach to an existing process
  • Kill an existing process
  • Pass env vars + args to spawned processes
  • Change working directory
  • Enable/disable ASLR
• Read Memory Map (info mem)
• Read Section/Segment relocation offsets
• Handle custom monitor Commands
  • Extend the GDB protocol with custom debug commands using GDB's monitor command!
• Host I/O
  • Access the remote target's filesystem to read/write file
  • Can be used to automatically read the remote executable on attach (using ExecFile)
• Read auxiliary vector (info auxv)
• Extra thread info (info threads)
• Extra library information (info sharedlibraries or info shared)
• Tracepoints
  • Configure tracepoints and actions to perform when hit
  • Select and interrogate collected trace frames
• Note: Feature support is not exhaustive, and many feature haven't been implemented yet.
• Flash operations (load)

Note: GDB features are implemented on an as-needed basis by gdbstub's contributors. If there's a missing GDB feature that you'd like gdbstub to implement, please file an issue and/or open a PR!

For a full list of GDB remote features, check out the GDB Remote Configuration Docs for a table of GDB commands + their corresponding Remote Serial Protocol packets.

Zero-overhead Protocol Extensions

Using a technique called Inlineable Dyn Extension Traits (IDETs), gdbstub is able to leverage the Rust compiler's powerful optimization passes to ensure any unused features are dead-code-eliminated in release builds without having to rely on compile-time features flags!

For example, if your target doesn't implement a custom GDB monitor command handler, the resulting binary won't include any code related to parsing / handling the underlying qRcmd packet!

If you're interested in the low-level technical details of how IDETs work, I've included a brief writeup in the documentation here.

Feature flags

By default, the std and alloc features are enabled.

When using gdbstub in #![no_std] contexts, make sure to set default-features = false.

• alloc
  • Implement Connection for Box<dyn Connection>.
  • Log outgoing packets via log::trace! (uses a heap-allocated output buffer).
  • Provide built-in implementations for certain protocol features:
    • Use a heap-allocated packet buffer in GdbStub (if none is provided via GdbStubBuilder::with_packet_buffer).
    • (Monitor Command) Use a heap-allocated output buffer in ConsoleOutput.
• std (implies alloc)
  • Implement Connection for TcpStream and UnixStream.
  • Implement std::error::Error for gdbstub::Error.
  • Add a TargetError::Io variant to simplify std::io::Error handling from Target methods.
• paranoid_unsafe
  • Please refer to the unsafe in gdbstub section below for more details.
• core_error
  • Make GdbStubError implement core::error::Error instead of std::error::Error.

Examples

Real-World Examples

While some of these projects may use older versions of gdbstub, they can nonetheless serve as useful examples of what a typical gdbstub integration might look like.

If you end up using gdbstub in your project, consider opening a PR and adding it to this list!

• Virtual Machine Monitors (VMMs)
  • OpenVMM/OpenHCL - (Microsoft) Modular, cross-platform, async-first VMM, with paravisor support
  • firecracker - (Amazon) Secure and fast microVMs for serverless computing
  • crosvm - (Google) The Chrome OS VMM
  • cloud-hypervisor - A VMM for modern cloud workloads
  • uhyve - A minimal hypervisor for RustyHermit
• OS Kernels (using gdbstub on no_std)
  • COCONUT-SVSM - VM Service Module (SVSM), supporting Confidential VMs (CVMs)
  • betrusted-io/xous-core - The Xous microkernel operating system
  • vmware-labs/node-replicated-kernel - An (experimental) research OS kernel for x86-64 (amd64) machines
  • patina - A UEFI compliant pure rust DXE core
• Emulators
  • obliteration - Kernel + VMM for running PS4 software on PCs
  • solana_rbpf - VM and JIT compiler for eBPF programs
  • rustyboyadvance-ng - Nintendo Gameboy Advance emulator and debugger (ARMv4T)
  • gamegirl - A Gameboy (Color/Advance) emulator
  • bevy-atari - An Atari XL/XE Emulator (MOS 6502)
  • rmips - MIPS R3000 virtual machine simulator
  • clicky - Emulator for classic clickwheel iPods (dual-core ARMv4T)
  • ts7200 - Emulator for the TS-7200 SoC (ARMv4T)
  • vaporstation - A Playstation One emulator (MIPS)
  • [microcorruption-emu](https://github.com/sapir/microcorrup