Lines Matching +full:- +full:- +full:all +full:- +full:features
5 [](./LICENSE)
7 … and easy-to-integrate implementation of the [GDB Remote Serial Protocol](https://sourceware.org/g…
11 …-overhead-protocol-extensions) (IDETs) to expose fine-grained, zero-cost control over enabled GDB …
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)
22 - **Excellent Ergonomics**
23 …- Instead of simply exposing the underlying GDB protocol "warts and all", `gdbstub` tries to abs…
24 …- Instead of having to dig through [obscure XML files deep the GDB codebase](https://github.com/…
25 …- Organizes GDB's countless optional protocol extensions into a coherent, understandable, and ty…
26 …- Automatically handles client/server protocol feature negotiation, without needing to micro-man…
27 …- `gdbstub` makes _extensive_ use of Rust's powerful type system + generics to enforce protocol …
28 …- Using a novel technique called [**Inlineable Dyn Extension Traits**](#zero-overhead-protocol-e…
29 - **Easy to Integrate**
30 …- `gdbstub`'s API is designed to be a "drop in" solution when you want to add debugging support …
31 - **`#![no_std]` Ready & Size Optimized**
32 …- `gdbstub` is a **`no_std` first** library, whereby all protocol features are required to be `n…
33 …- `gdbstub` does not require _any_ dynamic memory allocation, and can be configured to use fixed…
34 …- `gdbstub` is entirely **panic free** in most minimal configurations\*, resulting in substantia…
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…
37 …- "You don't pay for what you don't use": All code related to parsing/handling protocol extensio…
38 …- `gdbstub`'s minimal configuration has an incredibly low binary size + RAM overhead, enabling i…
39 …- When compiled in release mode, using all the tricks outlined in [`min-sized-rust`](https://git…
40 …- \*Exact numbers vary by target platform, compiler version, and `gdbstub` revision. In mixed-lang…
46 …features has required making some breaking API changes. While these changes are typically quite mi…
48 …-world projects](#real-world-examples) since its initial `0.1` release, and empirical evidence sug…
50 …he [Future Plans + Roadmap to `1.0.0`](#future-plans--roadmap-to-100) for more information on what…
52 ## Debugging Features
54 …features such as remote file I/O, spawning new processes, "rewinding" program execution, and much,…
56 - Base GDB Protocol
57 - Read/Write memory
58 - Read/Write registers
59 - Enumerating threads
61 Yep, that's right! That's all it takes to get `gdb` connected!
63 Of course, most use-cases will want to support additional debugging features as well. At the moment…
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`)
92 _Note:_ GDB features are implemented on an as-needed basis by `gdbstub`'s contributors. If there's …
94 …full list of GDB remote features, check out the [GDB Remote Configuration Docs](https://sourceware…
96 ### Zero-overhead Protocol Extensions
98 …sses to ensure any unused features are dead-code-eliminated in release builds _without_ having to …
102 …-level technical details of how IDETs work, I've included a brief writeup in the documentation [he…
106 By default, the `std` and `alloc` features are enabled.
108 When using `gdbstub` in `#![no_std]` contexts, make sure to set `default-features = false`.
110 - `alloc`
111 - Implement `Connection` for `Box<dyn Connection>`.
112 - Log outgoing packets via `log::trace!` (uses a heap-allocated output buffer).
113 - Provide built-in implementations for certain protocol features:
114 …- Use a heap-allocated packet buffer in `GdbStub` (if none is provided via `GdbStubBuilder::with…
115 - (Monitor Command) Use a heap-allocated output buffer in `ConsoleOutput`.
116 - `std` (implies `alloc`)
117 …- Implement `Connection` for [`TcpStream`](https://doc.rust-lang.org/std/net/struct.TcpStream.ht…
118 …- Implement [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) for `gdb…
119 - Add a `TargetError::Io` variant to simplify `std::io::Error` handling from Target methods.
120 - `paranoid_unsafe`
121 …- Please refer to the [`unsafe` in `gdbstub`](#unsafe-in-gdbstub) section below for more details.
125 ### Real-World Examples
131 - Virtual Machine Monitors (VMMs)
132 …- [crosvm](https://google.github.io/crosvm/running_crosvm/advanced_usage.html#gdb-support) - The…
133 …- [cloud-hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) - A VMM for modern cl…
134 …- [Firecracker](https://firecracker-microvm.github.io/) - A lightweight VMM developed by AWS (fe…
135 …- [uhyve](https://github.com/hermitcore/uhyve) - A minimal hypervisor for [RustyHermit](https://…
136 - OS Kernels (using `gdbstub` on `no_std`)
137 …- [`vmware-labs/node-replicated-kernel`](https://github.com/vmware-labs/node-replicated-kernel/t…
138 …- [`betrusted-io/xous-core`](https://github.com/betrusted-io/xous-core/blob/7d3d710/kernel/src/d…
139 - Emulators
140 - [solana_rbpf](https://github.com/solana-labs/rbpf) - VM and JIT compiler for eBPF programs
141 …- [rustyboyadvance-ng](https://github.com/michelhe/rustboyadvance-ng/) - Nintendo Gameboy Advanc…
142 - [gamegirl](https://github.com/anellie/gamegirl) - A Gameboy (Color/Advance) emulator
143 - [bevy-atari](https://github.com/mrk-its/bevy-atari) - An Atari XL/XE Emulator (MOS 6502)
144 - [rmips](https://github.com/starfleetcadet75/rmips) - MIPS R3000 virtual machine simulator
145 …- [clicky](https://github.com/daniel5151/clicky/) - Emulator for classic clickwheel iPods (dual-…
146 - [ts7200](https://github.com/daniel5151/ts7200/) - Emulator for the TS-7200 SoC (ARMv4T)
147 …- [vaporstation](https://github.com/Colin-Suckow/vaporstation) - A Playstation One emulator (MIP…
148 …- [microcorruption-emu](https://github.com/sapir/microcorruption-emu) - Emulator for the microco…
149 - Other
150 - [probe-rs](https://probe.rs/) - A modern, embedded debugging toolkit
151 …- [udbserver](https://github.com/bet4it/udbserver) - Plug-in GDB debugging for the [Unicorn Engi…
152 …- [enarx](https://github.com/enarx/enarx) - An open source framework for running applications in…
154 ### In-tree "Toy" Examples
158 - `armv4t` - `./examples/armv4t/`
159 - An incredibly simple ARMv4T-based system emulator with `gdbstub` support.
160 …- **Implements (almost) all available `target::ext` features.** This makes it a great resource whe…
161 - `armv4t_multicore` - `./examples/armv4t_multicore/`
162 - A dual-core variation of the `armv4t` example.
163 - Implements the core of `gdbstub`'s multithread extensions API, but not much else.
164 - `example_no_std` - `./example_no_std`
165 …- An _extremely_ minimal example which shows off how `gdbstub` can be used in a `#![no_std]` proje…
166 …- Unlike the `armv4t/armv4t_multicore` examples, this project does _not_ include a working emulato…
167 …- Doubles as a test-bed for tracking `gdbstub`'s approximate binary footprint (via the `check_size…
171 `gdbstub` limits its use of `unsafe` to a bare minimum, with all uses of `unsafe` required to have …
173 …-party unsafe code, `gdbstub` comes with an opt-in `paranoid_unsafe` feature, which enables `# section for more details
209 - _Note:_ The arch implementations under `gdbstub_arch` are _not_ guaranteed to be panic free!
210 - If you do spot a panicking arch in `gdbstub_arch`, consider opening a PR to fix it
212 If you're using `gdbstub` in a no-panic project and have determined that `gdbstub` is at fault for …
216 …features (e.g: remote filesystem support, tracepoint packets, most query packets, etc...) should _…
220 - [ ] Allow fine-grained control over target features via the `Arch` trait ([\#12](https://github…
221 - [ ] Implement GDB's various high-level operating modes:
222 - [x] Single/Multi Thread debugging
223 - [ ] Multiprocess Debugging
224 - [ ] Requires adding a new `target::ext::base::multiprocess` API.
225 …- _Note:_ `gdbstub` already implements multiprocess extensions "under-the-hood", and just hard-c…
226 …- [x] [Extended Mode](https://sourceware.org/gdb/current/onlinedocs/gdb/Connecting.html) (`targe…
227 …- [ ] [Non-Stop Mode](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Non_002dStop.html#Remote-…
228 - [x] Have a working example of `gdbstub` running in a "bare-metal" `#![no_std]` environment.
230 Additionally, while not _strict_ blockers to `1.0.0`, it would be good to explore these features as…
232 - [ ] Should `gdbstub` commit to a MSRV?
233 - [ ] Remove lingering instances of `RawRegId` from `gdbstub_arch` ([\#29](https://github.com/dan…
234 - [x] Exposing `async/await` interfaces (particularly wrt. handling GDB client interrupts) ([\#36…
235 - [ ] How/if to support [LLDB extensions](https://raw.githubusercontent.com/llvm-mirror/lldb/mast…
236 - [ ] Supporting multi-arch debugging via a single target
237 - e.g: debugging x86 and ARM processes on macOS
238 - [ ] Proper handling of "nack" packets (for spotty connections)
239 - Responding with "nack" is easy - the client has to re-transmit the command
240 - Re-transmitting after receiving a "nack" might be a bit harder...
244 gdbstub is free and open source! All code in this repository is dual-licensed under either:
246 * MIT License ([LICENSE-MIT](docs/LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opens…
247 …sion 2.0 ([LICENSE-APACHE](docs/LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](ht…
249 …. This means you can select the license you prefer! This dual-licensing approach is the de-facto s…
251 …ionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be…