feat: add API to send text to GDB client

Only from the Running state, as the implementation is based on the
`O xx` stop reply packet.

Closes #51

Author: daniel5151

examples/armv4t/main.rs

@@ -113,6 +113,14 @@ impl run_blocking::BlockingEventLoop for EmuGdbEventLoop {
                 Ok(simple_stub.incoming_data(target, byte))
             }
             emu::RunEvent::Event(event) => {
+                // example of using the console writer to print a message to the GDB console
+                // when the target finishes running.
+                if matches!(event, emu::Event::Halted) {
+                    let mut out = simple_stub.console_writer(target);
+                    let ret = target.cpu.reg_get(armv4t_emu::Mode::User, 0);
+                    gdbstub::outputln!(out, "Program completed. Return value: {}", ret);
+                }
+
                 // translate emulator stop reason into GDB stop reason
                 Ok(simple_stub.report_stop(target, |report_stop| {
                     use gdbstub::target::ext::breakpoints::WatchKind;

examples/armv4t_multicore/main.rs

@@ -114,6 +114,14 @@ impl run_blocking::BlockingEventLoop for EmuGdbEventLoop {
                 Ok(simple_stub.incoming_data(target, byte))
             }
             emu::RunEvent::Event(event, cpuid) => {
+                // example of using the console writer to print a message to the GDB console
+                // when the target finishes running.
+                if matches!(event, emu::Event::Halted) {
+                    let mut out = simple_stub.console_writer(target);
+                    let ret = target.cpu.reg_get(armv4t_emu::Mode::User, 0);
+                    gdbstub::outputln!(out, "Program completed. Return value: {}", ret);
+                }
+
                 // translate emulator stop reason into GDB stop reason
                 Ok(simple_stub.report_stop(target, |report_stop| {
                     use gdbstub::target::ext::breakpoints::WatchKind;

src/stub/mod.rs

@@ -72,6 +72,15 @@ pub mod run_blocking {
             }
         }
 
+        /// Return a writer that can be used to write arbitrary text to the GDB
+        /// client console.
+        pub fn console_writer(
+            &mut self,
+            target: &mut T,
+        ) -> state_machine::GdbConsoleWriter<'_, 'a, T, C> {
+            self.gdb.console_writer(target)
+        }
+
         /// Pass a byte to the GDB stub.
         pub fn incoming_data(self, target: &mut T, byte: u8) -> Event<'a, T, C> {
             Event {

src/stub/state_machine.rs

@@ -812,6 +812,53 @@ where
     }
 }
 
+/// A helper struct which enables writing arbitrary text to the GDB client
+/// console (either via `write_raw`, or via the `core::fmt::Write`
+/// implementation + [`output!`](crate::output) macro).
+pub struct GdbConsoleWriter<'gdb, 'a, T, C>
+where
+    T: Target,
+    C: Connection,
+{
+    gdb: &'gdb mut GdbStubStateMachineInner<'a, state::Running, T, C>,
+    use_rle: bool,
+}
+
+impl<'gdb, 'a, T, C> GdbConsoleWriter<'gdb, 'a, T, C>
+where
+    T: Target,
+    C: Connection,
+{
+    /// Write raw data to the GDB client console.
+    ///
+    /// Unless you have a specific reason to use this method, you will likely be
+    /// better served by using the `core::fmt::Write` implementation +
+    /// [`output!`](crate::output) macros instead.
+    ///
+    /// The GDB RSP docs recommend that console output be ASCII, but in
+    /// practice, GDB seems to be fine with receiving arbitrary binary data here
+    /// (e.g: it's possible to write UTF-8 data just fine, and it renders
+    /// correctly in GDB's console).
+    pub fn write_raw(&mut self, data: &[u8]) -> Result<(), GdbStubError<T::Error, C::Error>> {
+        let mut res = ResponseWriter::new(self.gdb.borrow_conn(), self.use_rle);
+        res.write_str("O").map_err(InternalError::from)?;
+        res.write_hex_buf(data).map_err(InternalError::from)?;
+        res.flush().map_err(InternalError::from)?;
+        Ok(())
+    }
+}
+
+impl<'gdb, 'a, T, C> core::fmt::Write for GdbConsoleWriter<'gdb, 'a, T, C>
+where
+    T: Target,
+    C: Connection,
+{
+    fn write_str(&mut self, s: &str) -> core::fmt::Result {
+        self.write_raw(s.as_bytes())
+            .map_err(|_| core::fmt::Error {})
+    }
+}
+
 /// Methods which can only be called from the
 /// [`GdbStubStateMachine::Running`] state.
 impl<'a, T, C> GdbStubStateMachineInner<'a, state::Running, T, C>
@@ -831,6 +878,15 @@ where
         }
     }
 
+    /// Return a struct that can be used to write arbitrary text to the GDB
+    /// client console.
+    pub fn console_writer(&mut self, target: &mut T) -> GdbConsoleWriter<'_, 'a, T, C> {
+        GdbConsoleWriter {
+            gdb: self,
+            use_rle: target.use_rle(),
+        }
+    }
+
     /// Pass a byte to the GDB stub.
     pub fn incoming_data(
         mut self,