1 //! Create custom target-specific debugging commands accessible via GDB's
2 //! `monitor` command!
3 
4 pub use crate::output;
5 pub use crate::outputln;
6 pub use crate::protocol::ConsoleOutput;
7 
8 use crate::target::Target;
9 
10 /// Target Extension - Handle custom GDB `monitor` commands.
11 pub trait MonitorCmd: Target {
12     /// Handle custom commands sent using the `monitor` command.
13     ///
14     /// The GDB remote serial protocol includes a built-in mechanism to send
15     /// arbitrary commands to the remote stub: the `monitor` command. For
16     /// example, running `monitor dbg` from the GDB client will invoke
17     /// `handle_monitor_cmd` with `cmd = b"dbg"`.
18     ///
19     /// Commands are _not_ guaranteed to be valid UTF-8, hence the use of
20     /// `&[u8]` as opposed to `&str`.
21     ///
22     /// Intermediate console output can be written back to the GDB client using
23     /// the provided `ConsoleOutput` object + the
24     /// [`gdbstub::output!`](macro.output.html) macro.
25     ///
26     /// _Note:_ The maximum length of incoming commands is limited by the size
27     /// of the packet buffer provided to the [`GdbStub`](struct.GdbStub.html).
28     /// Specifically, commands can only be up to `(buf.len() - 10) / 2` bytes.
handle_monitor_cmd(&mut self, cmd: &[u8], out: ConsoleOutput<'_>) -> Result<(), Self::Error>29     fn handle_monitor_cmd(&mut self, cmd: &[u8], out: ConsoleOutput<'_>)
30         -> Result<(), Self::Error>;
31 }
32 
33 define_ext!(MonitorCmdOps, MonitorCmd);
34