README.md
1# gdbstub
2
3[](https://crates.io/crates/gdbstub)
4[](https://docs.rs/gdbstub)
5
6An ergonomic and easy-to-integrate implementation of the [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol) in Rust, with full `#![no_std]` support.
7
8 `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`](https://docs.rs/gdbstub/latest/gdbstub/target/ext/base/singlethread/trait.SingleThreadOps.html) trait, you can have a rich GDB debugging session up and running in no time!
9
10**If you're looking for a quick snippet of example code to see what a typical `gdbstub` integration might look like, check out [examples/armv4t/gdb/mod.rs](https://github.com/daniel5151/gdbstub/blob/dev/0.5/examples/armv4t/gdb/mod.rs)**
11
12- [Documentation (gdbstub)](https://docs.rs/gdbstub)
13- [Documentation (gdbstub_arch)](https://docs.rs/gdbstub_arch)
14- [Changelog](CHANGELOG.md)
15- [0.4 to 0.5 Transition Guide](docs/transition_guide.md)
16
17Why use `gdbstub`?
18
19- **Excellent Ergonomics**
20 - 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. For example:
21 - Instead of having to dig through [obscure XML files deep the GDB codebase](https://github.com/bminor/binutils-gdb/tree/master/gdb/features) just to read/write from CPU/architecture registers, `gdbstub` comes with a community-curated collection of [built-in architecture definitions](https://docs.rs/gdbstub_arch) for most popular platforms!
22 - Organizes GDB's countless optional protocol extensions into a coherent, understandable, and type-safe hierarchy of traits.
23 - Automatically handles client/server protocol feature negotiation, without needing to micro-manage the specific [`qSupported` packet](https://sourceware.org/gdb/onlinedocs/gdb/General-Query-Packets.html#qSupported) response.
24 - `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.
25 - Using a novel technique called [**Inlineable Dyn Extension Traits**](#zero-overhead-protocol-extensions) (IDETs), `gdbstub` enables fine-grained control over active protocol extensions _without_ relying on clunky `cargo` features.
26- **Easy to Integrate**
27 - `gdbstub`'s API is designed to be as unobtrusive as possible, and shouldn't require any large refactoring effort to integrate into an existing project. It doesn't require taking direct ownership of any key data structures, and aims to be a "drop in" solution when you need to add debugging to a project.
28- **`#![no_std]` Ready & Size Optimized**
29 - `gdbstub` is a **`no_std` first** library, whereby all protocol features are required to be `no_std` compatible.
30 - `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`](https://doc.rust-lang.org/alloc/) platforms.
31 - `gdbstub` is transport-layer agnostic, and uses a basic [`Connection`](https://docs.rs/gdbstub/latest/gdbstub/trait.Connection.html) 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.
32 - "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 unimplmeneted! See the [Zero-overhead Protocol Extensions](#zero-overhead-protocol-extensions) section below for more details.
33 - `gdbstub` tries to keep the binary and RAM footprint of its minimal configuration to a bare minimum, enabling it to be used on even the most resource-constrained microcontrollers.
34 - When compiled in release mode, using all the tricks outlined in [`min-sized-rust`](https://github.com/johnthagen/min-sized-rust), a baseline `gdbstub` implementation weighs in at **_roughly 10kb of `.text` and negligible `.rodata`!_** \*
35 - \* Exact numbers vary by target platform, compiler version, and `gdbstub` revision. Data was collected using the included `example_no_std` project compiled on x86_64.
36
37### Can I Use `gdbstub` in Production?
38
39**Yes, as long as you don't mind some API churn until `1.0.0` is released.**
40
41Due 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 Trait/Type 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](docs/transition_guide.md) document.
42
43That being said, `gdbstub` has already been integrated into [many real-world projects](#real-world-examples) since its initial `0.1` release, and empirical evidence suggests that it seems to be doing its job quite well! Thusfar, there haven't been any reported issues related to core GDB debugging functionality, with most issues being caused by faulty `Target` and/or `Arch` implementations.
44
45See the [Future Plans + Roadmap to `1.0.0`](#future-plans--roadmap-to-100) for more information on what features `gdbstub` still needs to implement before committing to API stability with version `1.0.0`.
46
47## Debugging Features
48
49The 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:
50
51- Base GDB Protocol
52 - Step + Continue
53 - Read/Write memory
54 - Read/Write registers
55 - Enumerating threads
56 - Only required in multithreaded targets
57
58Of course, most use-cases will want to support additional debugging features as well. At the moment, `gdbstub` implements the following GDB protocol extensions:
59
60- Automatic target architecture + feature reporting
61- Breakpoints
62 - Software Breakpoints
63 - Hardware Breakpoints
64 - Read/Write/Access Watchpoints (i.e: value breakpoints)
65- Advanced step/continue
66 - Reverse execution (reverse-step, reverse-continue)
67 - Range-stepping
68- Extended Mode
69 - Run/Attach/Kill Processes
70 - Pass environment variables / args to spawned processes
71 - Change working directory
72- Section offsets
73 - Get section/segment relocation offsets from the target
74- Custom `monitor` Commands
75 - Extend the GDB protocol with custom debug commands using GDB's `monitor` command
76
77_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!
78
79For a full list of GDB remote features, check out the [GDB Remote Configuration Docs](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html) for a table of GDB commands + their corresponding Remote Serial Protocol packets.
80
81### Zero-overhead Protocol Extensions
82
83Using 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!
84
85For 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!
86
87If you're interested in the low-level technical details of how IDETs work, I've included a brief writeup in the documentation [here](https://docs.rs/gdbstub/latest/gdbstub/target/ext/index.html#how-protocol-extensions-work---inlineable-dyn-extension-traits-idets).
88
89## Feature flags
90
91By default, the `std` and `alloc` features are enabled.
92
93When using `gdbstub` in `#![no_std]` contexts, make sure to set `default-features = false`.
94
95- `alloc`
96 - Implement `Connection` for `Box<dyn Connection>`.
97 - Log outgoing packets via `log::trace!` (uses a heap-allocated output buffer).
98 - Provide built-in implementations for certain protocol features:
99 - Use a heap-allocated packet buffer in `GdbStub` (if none is provided via `GdbStubBuilder::with_packet_buffer`).
100 - (Monitor Command) Use a heap-allocated output buffer in `ConsoleOutput`.
101- `std` (implies `alloc`)
102 - Implement `Connection` for [`TcpStream`](https://doc.rust-lang.org/std/net/struct.TcpStream.html) and [`UnixStream`](https://doc.rust-lang.org/std/os/unix/net/struct.UnixStream.html).
103 - Implement [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) for `gdbstub::Error`.
104 - Add a `TargetError::Io` variant to simplify `std::io::Error` handling from Target methods.
105
106## Examples
107
108### Real-World Examples
109
110- Virtual Machine Monitors (VMMs)
111 - [crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/main#gdb-support) - The Chrome OS Virtual Machine Monitor (x64)
112 - [Firecracker](https://firecracker-microvm.github.io/) - A lightweight VMM developed by AWS - feature is in [PR](https://github.com/firecracker-microvm/firecracker/pull/2168)
113- Emulators (x64)
114 - [clicky](https://github.com/daniel5151/clicky/) - An emulator for classic clickwheel iPods (dual-core ARMv4T SoC)
115 - [rustyboyadvance-ng](https://github.com/michelhe/rustboyadvance-ng/) - Nintendo GameBoy Advance emulator and debugger (ARMv4T)
116 - [vaporstation](https://github.com/Colin-Suckow/vaporstation) - A Playstation One emulator (MIPS)
117 - [ts7200](https://github.com/daniel5151/ts7200/) - An emulator for the TS-7200, a somewhat bespoke embedded ARMv4t platform
118 - [microcorruption-emu](https://github.com/sapir/microcorruption-emu) - msp430 emulator for the microcorruption.com ctf
119- Other
120 - [memflow](https://github.com/memflow/memflow-cli) - A physical memory introspection framework (part of `memflow-cli`) (64)
121
122While 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.
123
124If you end up using `gdbstub` in your project, consider opening a PR and adding it to this list!
125
126### In-tree "Toy" Examples
127
128These examples are built as part of the CI, and are guaranteed to be kept up to date with the latest version of `gdbstub`'s API.
129
130- `armv4t` - `./examples/armv4t/`
131 - An incredibly simple ARMv4T-based system emulator with `gdbstub` support.
132 - **Implements (almost) all available `target::ext` features.** This makes it a great resource when first implementing a new protocol extension!
133- `armv4t_multicore` - `./examples/armv4t_multicore/`
134 - A dual-core variation of the `armv4t` example.
135 - Implements the core of `gdbstub`'s multithread extensions API, but not much else.
136- `example_no_std` - `./example_no_std`
137 - An _extremely_ minimal example which shows off how `gdbstub` can be used in a `#![no_std]` project.
138 - Unlike the `armv4t/armv4t_multicore` examples, this project does _not_ include a working emulator, and simply stubs all `gdbstub` functions.
139 - Doubles as a test-bed for tracking `gdbstub`'s approximate binary footprint (via the `check_size.sh` script), and validating certain dead-code-elimination optimizations.
140
141## Using `gdbstub` on bare-metal hardware
142
143Quite a bit of work has gone into making `gdbstub` optimized for `#![no_std]`, which means it should be entirely possible to implement a `Target` which uses low-level trap instructions + context switching to debug bare-metal code.
144
145If you happen to stumble across this crate and end up using it to debug some bare-metal code, please let me know! I'd love to link to your project, and/or create a simplified example based off your code!
146
147## `unsafe` in `gdbstub`
148
149`gdbstub` limits its use of `unsafe` to a bare minimum, with all uses of `unsafe` required to have a corresponding `// SAFETY` comment as justification. The following list exhaustively documents all uses of `unsafe` in `gdbstub`.
150
151- When no cargo features are enabled:
152 - A few trivially safe calls to `NonZeroUsize::new_unchecked()` when defining internal constants.
153- When the `std` feature is enabled:
154 - An implementation of `UnixStream::peek` which uses `libc::recv`. This manual implementation will be removed once [rust-lang/rust#76923](https://github.com/rust-lang/rust/issues/76923) is stabilized.
155
156## Future Plans + Roadmap to `1.0.0`
157
158While the vast majority of GDB protocol features (e.g: remote filesystem support, tracepoint packets, most query packets, etc...) should _not_ require breaking API changes, there are still several key protocol features that'll need breaking API changes to be implemented.
159
160The following features are most likely to require breaking API changes, and should therefore be implemented prior to `1.0.0`. Not that this is _not_ an exhaustive list, and is subject to change.
161
162- [ ] Stabilize the `Arch` trait
163 - [ ] Allow fine-grained control over target features ([\#12](https://github.com/daniel5151/gdbstub/issues/12))
164 - [ ] Remove `RawRegId` ([\#29](https://github.com/daniel5151/gdbstub/issues/29))
165- [ ] Implement GDB's various high-level operating modes:
166 - [x] Single/Multi Thread debugging
167 - [ ] Multiprocess Debugging
168 - [ ] Will require adding a third `target::ext::base::multiprocess` API.
169 - _Note:_ `gdbstub` already implements multiprocess extensions "under-the-hood", and just hard-codes a fake PID, so this is mostly a matter of "putting in the work".
170 - [x] [Extended Mode](https://sourceware.org/gdb/current/onlinedocs/gdb/Connecting.html) (`target extended-remote`)
171 - [ ] [Non-Stop Mode](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Non_002dStop.html#Remote-Non_002dStop)
172 - This may require some breaking API changes and/or some internals rework -- more research is needed.
173- [ ] Have a working example of `gdbstub` running in a "bare-metal" `#![no_std]` environment (e.g: debugging a hobby OS via serial).
174 - While there's no reason it _shouldn't_ work, it would be good to validate that the API + implementation supports this use-case.
175
176Additionally, while not strict "blockers" to `1.0.0`, it would be good to explore these features as well:
177
178- [ ] Should `gdbstub` commit to a MSRV?
179- [ ] Exposing `async/await` interfaces (particularly wrt. handling GDB client interrupts) ([\#36](https://github.com/daniel5151/gdbstub/issues/36))
180- [ ] Supporting various [LLDB extensions](https://raw.githubusercontent.com/llvm-mirror/lldb/master/docs/lldb-gdb-remote.txt) to the GDB RSP
181 - Skimming through the list, it doesn't seem like these extensions would require breaking API changes -- more research is needed.
182- [ ] Supporting multi-arch debugging via a single target
183 - e.g: debugging both x86 and x64 processes when running in extended mode
184- Proper handling of client "nack" packets for spotty connections.
185
){kind=link}