1 //! Community-created implementations of [`gdbstub::arch::Arch`] for various 2 //! architectures. 3 //! 4 //! _Note:_ If an architecture is missing from this crate, that does _not_ mean 5 //! that it can't be used with `gdbstub`! So-long as there's support for the 6 //! target architecture in GDB, it should be fairly straightforward to implement 7 //! `Arch` manually. 8 //! 9 //! Please consider upstreaming any missing `Arch` implementations you happen to 10 //! implement yourself! Aside from the altruistic motive of improving `gdbstub`, 11 //! upstreaming your `Arch` implementation will ensure that it's kept up-to-date 12 //! with any future breaking API changes. 13 //! 14 //! **Disclaimer:** These implementations are all community contributions, and 15 //! while they are tested (by the PR's author) and code-reviewed, it's not 16 //! particularly feasible to write detailed tests for each architecture! If you 17 //! spot a bug in any of the implementations, please file an issue / open a PR! 18 //! 19 //! # What's with `RegIdImpl`? 20 //! 21 //! Supporting the `Target::read/write_register` API required introducing a new 22 //! [`RegId`] trait + [`Arch::RegId`] associated type. `RegId` is used by 23 //! `gdbstub` to translate raw GDB register ids (a protocol level arch-dependent 24 //! `usize`) into human-readable enum variants. 25 //! 26 //! Unfortunately, this API was added after several contributors had already 27 //! upstreamed their `Arch` implementations, and as a result, there are several 28 //! built-in arch implementations which are missing proper `RegId` enums 29 //! (tracked under [issue #29](https://github.com/daniel5151/gdbstub/issues/29)). 30 //! 31 //! As a stop-gap measure, affected `Arch` implementations have been modified to 32 //! accept a `RegIdImpl` type parameter, which requires users to manually 33 //! specify a `RegId` implementation. 34 //! 35 //! If you're not interested in implementing the `Target::read/write_register` 36 //! methods and just want to get up-and-running with `gdbstub`, it's fine to 37 //! set `RegIdImpl` to `()` and use the built-in stubbed `impl RegId for ()`. 38 //! 39 //! A better approach would be to implement (and hopefully upstream!) a proper 40 //! `RegId` enum. While this will require doing a bit of digging through the GDB 41 //! docs + [architecture XML definitions](https://github.com/bminor/binutils-gdb/tree/master/gdb/features/), 42 //! it's not too tricky to get a working implementation up and running, and 43 //! makes it possible to safely and efficiently implement the 44 //! `Target::read/write_register` API. As an example, check out 45 //! [`ArmCoreRegId`](arm::reg::id::ArmCoreRegId#impl-RegId). 46 //! 47 //! Whenever a `RegId` enum is upstreamed, the associated `Arch`'s `RegIdImpl` 48 //! parameter will be defaulted to the newly added enum. This will simplify the 49 //! API without requiring an explicit breaking API change. Once all `RegIdImpl` 50 //! have a default implementation, only a single breaking API change will be 51 //! required to remove `RegIdImpl` entirely (along with this documentation). 52 53 #![cfg_attr(not(test), no_std)] 54 #![deny(missing_docs)] 55 56 pub mod aarch64; 57 pub mod arm; 58 pub mod mips; 59 pub mod msp430; 60 pub mod ppc; 61 pub mod riscv; 62 pub mod x86; 63 64 // used as part of intra-doc link 65 #[allow(unused_imports)] 66 use gdbstub::arch::*; 67