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