1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
//! Base operations required to debug any target (read/write memory/registers, //! step/resume, etc...) //! //! It is recommended that single threaded targets implement the simplified //! `singlethread` API, as `gdbstub` includes optimized implementations of //! certain internal routines when operating in singlethreaded mode. pub mod multithread; pub mod singlethread; mod single_register_access; pub use single_register_access::{SingleRegisterAccess, SingleRegisterAccessOps}; /// Base operations for single/multi threaded targets. pub enum BaseOps<'a, A, E> { /// Single-threaded target SingleThread(&'a mut dyn singlethread::SingleThreadOps<Arch = A, Error = E>), /// Multi-threaded target MultiThread(&'a mut dyn multithread::MultiThreadOps<Arch = A, Error = E>), } /// Describes how the target should be resumed. /// /// Due to a quirk / bug in the mainline GDB client, targets are required to /// handle the `WithSignal` variants of `Step` and `Continue` regardless of /// whether or not they have a concept of "signals". /// /// If your target does not support signals (e.g: the target is a bare-metal /// microcontroller / emulator), the recommended behavior is to either return a /// target-specific fatal error, or to handle `{Step,Continue}WithSignal` the /// same way as their non-`WithSignal` variants. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum ResumeAction { /// Continue execution, stopping once a /// [`StopReason`](singlethread::StopReason) occurs. Continue, /// Step execution. Step, /// Continue with signal. ContinueWithSignal(u8), /// Step with signal. StepWithSignal(u8), } /// Describes the point reached in a replay log for the corresponding stop /// reason. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum ReplayLogPosition { /// Reached the beginning of the replay log. Begin, /// Reached the end of the replay log. End, } /// A handle to check for incoming GDB interrupts. /// /// At the moment, checking for incoming interrupts requires periodically /// polling for pending interrupts. e.g: /// /// ```ignore /// let interrupts = gdb_interrupt.no_async(); /// loop { /// if interrupts.pending() { /// return Ok(StopReason::GdbInterrupt) /// } /// /// // execute some number of clock cycles /// for _ in 0..1024 { /// match self.system.step() { .. } /// } /// } /// ``` /// /// There is an outstanding issue to add a non-blocking interface to /// `GdbInterrupt` (see [daniel5151/gdbstub#36](https://github.com/daniel5151/gdbstub/issues/36)). /// Please comment on the issue if this is something you'd like to see /// implemented and/or would like to help out with! pub struct GdbInterrupt<'a> { inner: &'a mut dyn FnMut() -> bool, } impl<'a> GdbInterrupt<'a> { pub(crate) fn new(inner: &'a mut dyn FnMut() -> bool) -> GdbInterrupt<'a> { GdbInterrupt { inner } } /// Returns a [`GdbInterruptNoAsync`] struct which can be polled using a /// simple non-blocking [`pending(&mut self) -> /// bool`](GdbInterruptNoAsync::pending) method. pub fn no_async(self) -> GdbInterruptNoAsync<'a> { GdbInterruptNoAsync { inner: self.inner } } } /// A simplified interface to [`GdbInterrupt`] for projects without /// async/await infrastructure. pub struct GdbInterruptNoAsync<'a> { inner: &'a mut dyn FnMut() -> bool, } impl<'a> GdbInterruptNoAsync<'a> { /// Checks if there is a pending GDB interrupt. pub fn pending(&mut self) -> bool { (self.inner)() } }