host_sp_comms: add low-level "debug" interface

When debugging recent IPCC problems, it would have been very useful to
have a low-level "debug" interface for sending traffic between host and
SP so that we could probe the issues in question on a bench machine.

I hacked something for this by overloading an IPCC transaction that
wasn't used on the machine I wanted to test on, which was enormously
impactful, as it exposed a quartz problem in the FPGA that Nathanael was
able to fix quickly.  But it was obviously a hack, and moreoever, since
it was tied to IPCC (and IPCC was considered suspect at the time), using
it felt like a bit of a gamble.

Having a dedicated debugging interface that is below the level of IPCC,
and not complected with COBS encoding, Hubpack, and so on, would be
generally useful.  This is the Hubris side of that: I've implemented a
parallel protocol for supporting three simple debug messages:

1. A discard message: this simply throws away what is sent to it, with
   the side effect of emitting a message into a ring buffer.
2. An echo message: this echos the data sent to it back to the distant
   end, and produces a ring buffer entry.
3. A "chargen" message: this causes $n$ bytes from a repeating pattern
   of printable ASCII characters to be back to the host, limited by the
   number requested and size of the output buffer.

Since the IPCC header and magic number are fixed, debug messages are
easily distinguishable from normal IPCC messages by looking for a prefix
string in a received "frame" from the host: the two can never collide.

Author: dancrossnyc

app/cosmo/base.toml

@@ -256,7 +256,7 @@ features = ["stm32h753", "usart6", "baud_rate_3M", "hardware_flow_control", "vla
 uses = ["usart6", "dbgmcu"]
 interrupts = {"usart6.irq" = "usart-irq"}
 priority = 9
-max-sizes = {flash = 69120, ram = 65536}
+max-sizes = {flash = 69792, ram = 65536}
 stacksize = 5400
 start = true
 task-slots = ["sys", { cpu_seq = "cosmo_seq" }, "hf", "control_plane_agent", "net", "packrat", "i2c_driver", { spi_driver = "spi2_driver" }, "sprot", "auxflash"]

app/gimlet/base.toml

@@ -242,7 +242,7 @@ features = ["stm32h753", "uart7", "baud_rate_3M", "hardware_flow_control", "vlan
 uses = ["uart7", "dbgmcu"]
 interrupts = {"uart7.irq" = "usart-irq"}
 priority = 8
-max-sizes = {flash = 67680, ram = 65536}
+max-sizes = {flash = 68608, ram = 65536}
 stacksize = 5376
 start = true
 task-slots = ["sys", { cpu_seq = "gimlet_seq" }, "hf", "control_plane_agent", "net", "packrat", "i2c_driver", { spi_driver = "spi2_driver" }, "sprot"]

task/host-sp-comms/src/main.rs

@@ -104,12 +104,25 @@ const MAX_HOST_FAIL_MESSAGE_LEN: usize = 4096;
 // of that for us.
 const NUM_HOST_MAC_ADDRESSES: u16 = 3;
 
+// The same IO path can be used for both IPCC, and a lower-level debugging
+// interface, for testing the IO path itself.  We differentiate between the two
+// by detecting specific header types, and parsing the corresponding messages
+// into a typed enum: debug message handling is then short-circuited.
+enum DebugCmd<'a> {
+    Discard,
+    Echo(&'a [u8]),
+    CharGen(u16),
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, counters::Count)]
 enum Trace {
     #[count(skip)]
     None,
     UartRxOverrun,
     ParseError(#[count(children)] DecodeFailureReason),
+    DebugDiscard,
+    DebugEcho(u64),
+    DebugCharGen(u16),
     SetState {
         now: u64,
         #[count(children)]
@@ -786,6 +799,56 @@ impl ServerImpl {
         }
     }
 
+    // Process a request message from the host.
+    fn process_message(
+        &mut self,
+        reset_tx_buf: bool,
+    ) -> Result<(), DecodeFailureReason> {
+        // Debug messages have a distinct header that separates them from normal
+        // IPCC messages.
+        if is_debug_message(self.rx_buf) {
+            self.process_debug_message(reset_tx_buf)
+        } else {
+            self.process_ipcc_message(reset_tx_buf)
+        }
+    }
+
+    // Process a framed debug packet
+    fn process_debug_message(
+        &mut self,
+        reset_tx_buf: bool,
+    ) -> Result<(), DecodeFailureReason> {
+        match parse_debug_message(self.rx_buf) {
+            Ok(cmd) => {
+                if reset_tx_buf {
+                    self.tx_buf.reset();
+                }
+                match cmd {
+                    DebugCmd::Discard => ringbuf_entry!(Trace::DebugDiscard),
+                    DebugCmd::Echo(data) => {
+                        ringbuf_entry!(Trace::DebugEcho(data.len() as u64));
+                        let _ = self.tx_buf.try_copy_raw_data(data);
+                    }
+                    DebugCmd::CharGen(count) => {
+                        ringbuf_entry!(Trace::DebugCharGen(count));
+                        // const CHARGEN: &'static [u8] =
+                        //     b"!\"#$%&'()*+,-./0123456789:;\
+                        //     <=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]\
+                        //     ^_abcdefghijklmnopqrstuvwxyz{|}~`";
+                        let mut it = (b'!'..=b'~').cycle().take(count.into());
+                        let _ = self.tx_buf.try_fill(&mut it);
+                    }
+                }
+                Ok(())
+            }
+            Err(err) => {
+                ringbuf_entry!(Trace::ParseError(err));
+                self.rx_buf.clear();
+                Err(err)
+            }
+        }
+    }
+
     // Process the framed packet sitting in `self.rx_buf`. If it warrants a
     // response, we configure `self.tx_buf` appropriate: either populating it
     // with a response if we can come up with that response immediately, or
@@ -800,10 +863,11 @@ impl ServerImpl {
     //
     // This method always (i.e., on success or failure) clears `rx_buf` before
     // returning to prepare for the next packet.
-    fn process_message(
+    fn process_ipcc_message(
         &mut self,
         reset_tx_buf: bool,
     ) -> Result<(), DecodeFailureReason> {
+        // If the message was Not a debug message, then parse it normally.
         let (header, request, data) = match parse_received_message(self.rx_buf)
         {
             Ok((header, request, data)) => (header, request, data),
@@ -1663,8 +1727,9 @@ impl NotificationHandler for ServerImpl {
     }
 }
 
-// This is conceptually a method on `ServerImpl`, but it takes a reference to
-// `rx_buf` instead of `self` to avoid borrow checker issues.
+// Parse a received message.  This is conceptually a method on `ServerImpl`,
+// but it takes a reference to `rx_buf` instead of `self` to avoid borrow
+// checker issues.
 fn parse_received_message(
     rx_buf: &mut [u8],
 ) -> Result<(Header, HostToSp, &[u8]), DecodeFailureReason> {
@@ -1690,6 +1755,48 @@ fn parse_received_message(
     Ok((header, request, data))
 }
 
+// Debug messages have a distinct header that separates them from IPCC
+// messages.  The first 5 bytes are the ASCII characters, "DEBUG".  The
+// 6th and 7th bytes encode the command number, as 0 padded ASCII hexadecimal
+// string (using upper case for the non-numeric hexadigits).  The commands
+// are:
+//
+//   "07" (0x07 ==  7 dec) Echo
+//   "09" (0x09 ==  9 dec) Discard
+//   "13" (0x13 == 19 dec) CharGen
+//
+// The command values correspond to the IANA-assigned port numbers for the
+// corresponding UDP and TCP/IP services.
+//
+// This is conceptually a method on `ServerImpl`, but it takes references to
+// several of its fields instead of `self` to avoid borrow checker issues.
+fn is_debug_message(msg: &[u8]) -> bool {
+    if msg.len() < 7 {
+        return false;
+    }
+    msg[0..5] == *b"DEBUG"
+}
+
+// This is conceptually a method on `ServerImpl`, but it takes references to
+// several of its fields instead of `self` to avoid borrow checker issues.
+fn parse_debug_message(
+    msg: &[u8],
+) -> Result<DebugCmd<'_>, DecodeFailureReason> {
+    assert!(is_debug_message(msg));
+    match &msg[5..7] {
+        b"07" => Ok(DebugCmd::Echo(&msg[7..])),
+        b"09" => Ok(DebugCmd::Discard),
+        b"13" if msg.len() == 11 => {
+            let nstr = str::from_utf8(&msg[7..11])
+                .map_err(|_| DecodeFailureReason::Deserialize)?;
+            let n = u16::from_str_radix(nstr, 16)
+                .map_err(|_| DecodeFailureReason::Deserialize)?;
+            Ok(DebugCmd::CharGen(n))
+        }
+        _ => Err(DecodeFailureReason::Deserialize),
+    }
+}
+
 // This is conceptually a method on `ServerImpl`, but it takes references to
 // several of its fields instead of `self` to avoid borrow checker issues.
 fn handle_reboot_waiting_in_a2_timer(

task/host-sp-comms/src/tx_buf.rs

@@ -293,6 +293,40 @@ impl TxBuf {
         let n = corncobs::encode_buf(&self.msg[..msg_len], &mut self.pkt[1..]);
         self.state = State::ToSend(0..n + 1);
     }
+
+    // Copies a "raw" slice of bytes into the output packet buffer.
+    pub(crate) fn try_copy_raw_data(&mut self, bs: &[u8]) -> Result<usize, ()> {
+        let n = usize::min(self.pkt.len() - 2, bs.len());
+        if bs[..n].contains(&0) {
+            return Err(());
+        }
+        let end = n + 1;
+        self.pkt[0] = 0;
+        self.pkt[1..end].copy_from_slice(&bs[..n]);
+        self.pkt[end] = 0;
+        self.state = State::ToSend(0..end + 1);
+        Ok(n)
+    }
+
+    pub(crate) fn try_fill(
+        &mut self,
+        it: &mut impl Iterator<Item = u8>,
+    ) -> Result<(), ()> {
+        let max = self.pkt.len() - 2;
+        let mut idx = 0;
+        self.pkt[idx] = 0;
+        idx += 1;
+        for b in it.take(max) {
+            if b == 0 {
+                return Err(());
+            }
+            self.pkt[idx] = b;
+            idx += 1;
+        }
+        self.pkt[idx] = 0;
+        self.state = State::ToSend(0..idx + 1);
+        Ok(())
+    }
 }
 
 enum State {