README.md
1# gdbstub
2
3[](https://crates.io/crates/gdbstub)
4[](https://docs.rs/gdbstub)
5[](./LICENSE)
6
7An ergonomic, featureful, 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 _no-compromises_ `#![no_std]` support.
8
9`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.SingleThreadBase.html) trait, you can have a rich GDB debugging session up and running in no time!
10
11`gdbstub`'s API makes extensive use of a technique called [**Inlineable Dyn Extension Traits**](#zero-overhead-protocol-extensions) (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!
12
13**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](https://github.com/daniel5151/gdbstub/blob/master/examples/armv4t/gdb/mod.rs)**
14
15- [Documentation (gdbstub)](https://docs.rs/gdbstub)
16- [Documentation (gdbstub_arch)](https://docs.rs/gdbstub_arch)
17- [Changelog](CHANGELOG.md)
18- [0.5 to 0.6 Transition Guide](docs/transition_guide.md)
19
20Why use `gdbstub`?
21
22- **Excellent Ergonomics**
23 - 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.
24 - 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!
25 - Organizes GDB's countless optional protocol extensions into a coherent, understandable, and type-safe hierarchy of traits.
26 - 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.
27 - `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.
28 - 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 or the use of `unsafe` code!
29- **Easy to Integrate**
30 - `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.
31- **`#![no_std]` Ready & Size Optimized**
32 - `gdbstub` is a **`no_std` first** library, whereby all protocol features are required to be `no_std` compatible.
33 - `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.
34 - `gdbstub` is entirely **panic free** in most minimal configurations\*, resulting in substantially smaller and more robust code.
35 - \*See the [Writing panic-free code](#writing-panic-free-code) section below for more details.
36 - `gdbstub` is transport-layer agnostic, and uses a basic [`Connection`](https://docs.rs/gdbstub/latest/gdbstub/conn/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!
37 - "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](#zero-overhead-protocol-extensions) section below for more details.
38 - `gdbstub`'s minimal configuration has an incredibly low binary size + RAM overhead, enabling it to be used on even the most resource-constrained microcontrollers.
39 - 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 can weigh in at **_less than 10kb of `.text` + `.rodata`!_** \*
40 - \*Exact numbers vary by target platform, compiler version, and `gdbstub` revision. In mixed-language projects, cross-language LTO may be required ([\#101](https://github.com/daniel5151/gdbstub/issues/101#issuecomment-1264444815)). Data was collected using the included `example_no_std` project compiled on x86_64.
41
42### Can I Use `gdbstub` in Production?
43
44**Yes, as long as you don't mind some API churn until `1.0.0` is released.**
45
46Due 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](docs/transition_guide.md) document.
47
48That 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, 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.
49
50See 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`.
51
52## Debugging Features
53
54The 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:
55
56- Base GDB Protocol
57 - Read/Write memory
58 - Read/Write registers
59 - Enumerating threads
60
61Yep, that's right! That's all it takes to get `gdb` connected!
62
63Of course, most use-cases will want to support additional debugging features as well. At the moment, `gdbstub` implements the following GDB protocol extensions:
64
65- Automatic target architecture + feature configuration
66- Resume
67 - Continue
68 - Single Step
69 - Range Step
70 - _Reverse_ Step/Continue
71- Breakpoints
72 - Software Breakpoints
73 - Hardware Breakpoints
74 - Read/Write/Access Watchpoints (i.e: value breakpoints)
75- Extended Mode
76 - Launch new processes
77 - Attach to an existing process
78 - Kill an existing process
79 - Pass env vars + args to spawned processes
80 - Change working directory
81 - Enable/disable ASLR
82- Read Memory Map (`info mem`)
83- Read Section/Segment relocation offsets
84- Handle custom `monitor` Commands
85 - Extend the GDB protocol with custom debug commands using GDB's `monitor` command!
86- Host I/O
87 - Access the remote target's filesystem to read/write file
88 - Can be used to automatically read the remote executable on attach (using `ExecFile`)
89- Read auxiliary vector (`info auxv`)
90- Extra thread info (`info threads`)
91- Extra library information (`info sharedlibraries`)
92- Tracepoints
93 - Configure tracepoints and actions to perform when hit
94 - Select and interrogate collected trace frames
95 - _Note:_ Feature support is not exhaustive, and many feature haven't been implemented yet.
96
97_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!
98
99For 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.
100
101### Zero-overhead Protocol Extensions
102
103Using 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!
104
105For 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!
106
107If 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).
108
109## Feature flags
110
111By default, the `std` and `alloc` features are enabled.
112
113When using `gdbstub` in `#![no_std]` contexts, make sure to set `default-features = false`.
114
115- `alloc`
116 - Implement `Connection` for `Box<dyn Connection>`.
117 - Log outgoing packets via `log::trace!` (uses a heap-allocated output buffer).
118 - Provide built-in implementations for certain protocol features:
119 - Use a heap-allocated packet buffer in `GdbStub` (if none is provided via `GdbStubBuilder::with_packet_buffer`).
120 - (Monitor Command) Use a heap-allocated output buffer in `ConsoleOutput`.
121- `std` (implies `alloc`)
122 - 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).
123 - Implement [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) for `gdbstub::Error`.
124 - Add a `TargetError::Io` variant to simplify `std::io::Error` handling from Target methods.
125- `paranoid_unsafe`
126 - Please refer to the [`unsafe` in `gdbstub`](#unsafe-in-gdbstub) section below for more details.
127- `core_error`
128 - Make `GdbStubError` implement [`core::error::Error`](https://doc.rust-lang.org/core/error/trait.Error.html) instead of `std::error::Error`.
129
130## Examples
131
132### Real-World Examples
133
134While 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.
135
136If you end up using `gdbstub` in your project, consider opening a PR and adding it to this list!
137
138- Virtual Machine Monitors (VMMs)
139 - [OpenVMM/OpenHCL](https://openvmm.dev/reference/dev_feats/gdbstub.html) - (Microsoft) Modular, cross-platform, async-first VMM, with paravisor support
140 - [firecracker](https://github.com/firecracker-microvm/firecracker/blob/main/docs/gdb-debugging.md) - (Amazon) Secure and fast microVMs for serverless computing
141 - [crosvm](https://google.github.io/crosvm/running_crosvm/advanced_usage.html#gdb-support) - (Google) The Chrome OS VMM
142 - [cloud-hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) - A VMM for modern cloud workloads
143 - [uhyve](https://github.com/hermitcore/uhyve) - A minimal hypervisor for [RustyHermit](https://github.com/hermitcore/rusty-hermit)
144- OS Kernels (using `gdbstub` on `no_std`)
145 - [COCONUT-SVSM](https://github.com/coconut-svsm/svsm) - VM Service Module (SVSM), supporting Confidential VMs (CVMs)
146 - [`betrusted-io/xous-core`](https://github.com/betrusted-io/xous-core/blob/b471b604/kernel/src/debug/gdb.rs) - The Xous microkernel operating system
147 - [`vmware-labs/node-replicated-kernel`](https://github.com/vmware-labs/node-replicated-kernel/tree/57f953c2/kernel/src/arch/x86_64/gdb) - An (experimental) research OS kernel for x86-64 (amd64) machines
148- Emulators
149 - [obliteration](https://github.com/obhq/obliteration) - Kernel + VMM for running PS4 software on PCs
150 - [solana_rbpf](https://github.com/solana-labs/rbpf) - VM and JIT compiler for eBPF programs
151 - [rustyboyadvance-ng](https://github.com/michelhe/rustboyadvance-ng/) - Nintendo Gameboy Advance emulator and debugger (ARMv4T)
152 - [gamegirl](https://github.com/anellie/gamegirl) - A Gameboy (Color/Advance) emulator
153 - [bevy-atari](https://github.com/mrk-its/bevy-atari) - An Atari XL/XE Emulator (MOS 6502)
154 - [rmips](https://github.com/starfleetcadet75/rmips) - MIPS R3000 virtual machine simulator
155 - [clicky](https://github.com/daniel5151/clicky/) - Emulator for classic clickwheel iPods (dual-core ARMv4T)
156 - [ts7200](https://github.com/daniel5151/ts7200/) - Emulator for the TS-7200 SoC (ARMv4T)
157 - [vaporstation](https://github.com/Colin-Suckow/vaporstation) - A Playstation One emulator (MIPS)
158 - [microcorruption-emu](https://github.com/sapir/microcorruption-emu) - Emulator for the microcorruption.com ctf (MSP430)
159- Other
160 - [probe-rs](https://probe.rs/) - A modern, embedded debugging toolkit
161 - [udbserver](https://github.com/bet4it/udbserver) - Plug-in GDB debugging for the [Unicorn Engine](https://www.unicorn-engine.org/) (Multi Architecture)
162 - [enarx](https://github.com/enarx/enarx) - An open source framework for running applications in Trusted Execution Environments
163 - [icicle-emu](https://github.com/icicle-emu/icicle-emu) - An experimental fuzzing-specific, multi-architecture emulation framework
164
165### In-tree "Toy" Examples
166
167These 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.
168
169- `armv4t` - `./examples/armv4t/`
170 - An incredibly simple ARMv4T-based system emulator with `gdbstub` support.
171 - **Implements (almost) all available `target::ext` features.** This makes it a great resource when first implementing a new protocol extension!
172- `armv4t_multicore` - `./examples/armv4t_multicore/`
173 - A dual-core variation of the `armv4t` example.
174 - Implements the core of `gdbstub`'s multithread extensions API, but not much else.
175- `example_no_std` - `./example_no_std`
176 - An _extremely_ minimal example which shows off how `gdbstub` can be used in a `#![no_std]` project.
177 - Unlike the `armv4t/armv4t_multicore` examples, this project does _not_ include a working emulator, and simply stubs all `gdbstub` functions.
178 - Doubles as a test-bed for tracking `gdbstub`'s approximate binary footprint (via the `check_size.sh` script), as well as validating certain dead-code-elimination optimizations.
179
180## `unsafe` in `gdbstub`
181
182`gdbstub` limits its use of `unsafe` to a bare minimum, with all uses of `unsafe` required to have a corresponding `// SAFETY` comment as justification.
183
184For those paranoid about trusting third-party unsafe code, `gdbstub` comes with an opt-in `paranoid_unsafe` feature, which enables `#![forbid(unsafe_code)]` on the entire `gdbstub` crate, swapping out all instances of `unsafe` code with equivalent (albeit less-performant) alternatives.
185
186The following list exhaustively documents all uses of `unsafe` in `gdbstub`:
187
188- With `default` features
189 - Don't emit provably unreachable panics
190 - `src/protocol/packet.rs`: Method in `PacketBuf` that use index using stored sub-`Range<usize>` into the buffer
191 - `src/protocol/common/hex.rs`: `decode_hex_buf`
192
193- When the `std` feature is enabled:
194 - `src/connection/impls/unixstream.rs`: An implementation of `UnixStream::peek` which uses `libc::recv`. Will be removed once [rust-lang/rust#76923](https://github.com/rust-lang/rust/issues/76923) stabilizes this feature in the stdlib.
195
196
197## Writing panic-free code
198
199Ideally, the Rust compiler would have some way to opt-in to a strict "no-panic" mode. Unfortunately, at the time of writing (2022/04/24), no such mode exists. As such, the only way to avoid the Rust compiler + stdlib's implicit panics is by being _very careful_ when writing code, and _manually checking_ that those panicking paths get optimized out!
200
201And when I say "manually checking", I mean [checking generated asm output](example_no_std/dump_asm.sh).
202
203Why even go through this effort?
204
205- Panic infrastructure can be _expensive_, and when you're optimizing for embedded, `no_std` use-cases, panic infrastructure brings in hundreds of additional bytes into the final binary.
206- `gdbstub` can be used to implement low-level debuggers, and if the debugger itself panics, well... it's not like you can debug it all that easily!
207
208As such, **`gdbstub` promises to introduce zero additional panics** into an existing project, subject to the following conditions:
209
2101. The binary is compiled in release mode
211 - \*subject to the specific `rustc` version being used (codegen and optimization vary between versions)
212 - \*different hardware architectures may be subject to different compiler optimizations
213 - i.e: at this time, only `x86` is actively tested to be panic-free
2142. `gdbstub`'s `paranoid_unsafe` cargo feature is _disabled_
215 - LLVM is unable to omit certain `panic` checks without requiring a bit of `unsafe` code
216 - See the [`unsafe` in `gdbstub`](#unsafe-in-gdbstub) section for more details
2173. The `Arch` implementation being used doesn't include panicking code
218 - _Note:_ The arch implementations under `gdbstub_arch` are _not_ guaranteed to be panic free!
219 - If you do spot a panicking arch in `gdbstub_arch`, consider opening a PR to fix it
220
221If you're using `gdbstub` in a no-panic project and have determined that `gdbstub` is at fault for introducing a panicking code path, please file an issue!
222
223## Future Plans + Roadmap to `1.0.0`
224
225While the vast majority of GDB protocol features (e.g: remote filesystem support, tracepoint packets, most query packets, etc...) should _not_ require breaking API changes, the following features will most likely require at least some breaking API changes, and should therefore be implemented prior to `1.0.0`.
226
227Not that this is _not_ an exhaustive list, and is subject to change.
228
229- [ ] Allow fine-grained control over target features via the `Arch` trait ([\#12](https://github.com/daniel5151/gdbstub/issues/12))
230- [ ] Implement GDB's various high-level operating modes:
231 - [x] Single/Multi Thread debugging
232 - [ ] Multiprocess Debugging ([\#124](https://github.com/daniel5151/gdbstub/issues/124)
233 - [ ] Requires adding a new `target::ext::base::multiprocess` API.
234 - _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".
235 - [x] [Extended Mode](https://sourceware.org/gdb/current/onlinedocs/gdb/Connecting.html) (`target extended-remote`)
236 - [ ] [Non-Stop Mode](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Non_002dStop.html#Remote-Non_002dStop)
237- [x] Have a working example of `gdbstub` running in a "bare-metal" `#![no_std]` environment.
238
239Additionally, while not _strict_ blockers to `1.0.0`, it would be good to explore these features as well:
240
241- [ ] Should `gdbstub` commit to a MSRV?
242- [ ] Remove lingering instances of `RawRegId` from `gdbstub_arch` ([\#29](https://github.com/daniel5151/gdbstub/issues/29))
243- [x] Exposing `async/await` interfaces (particularly wrt. handling GDB client interrupts) ([\#36](https://github.com/daniel5151/gdbstub/issues/36))
244- [ ] How/if to support [LLDB extensions](https://raw.githubusercontent.com/llvm-mirror/lldb/master/docs/lldb-gdb-remote.txt) ([\#99](https://github.com/daniel5151/gdbstub/issues/99))
245- [ ] Supporting multi-arch debugging via a single target
246 - e.g: debugging x86 and ARM processes on macOS
247- [ ] Proper handling of "nack" packets (for spotty connections) ([\#137](https://github.com/daniel5151/gdbstub/issues/137))
248
249## License
250
251gdbstub is free and open source! All code in this repository is dual-licensed under either:
252
253* MIT License ([LICENSE-MIT](docs/LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
254* Apache License, Version 2.0 ([LICENSE-APACHE](docs/LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
255
256at your option. This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are [very good reasons](https://github.com/daniel5151/gdbstub/issues/68) to include both.
257
258Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
259
){kind=link}
){kind=link}
){kind=link}