From ce05053536b9513060a4484cca26b6d791055425 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 16 Apr 2023 01:43:09 +0800 Subject: [PATCH] improve serial support; add stubs to allow for console i/o --- services/usb-device-xous/Cargo.toml | 3 +- services/usb-device-xous/src/api.rs | 75 ++++++--- services/usb-device-xous/src/lib.rs | 40 ++++- services/usb-device-xous/src/main_hw.rs | 213 +++++++++++++++++++++--- 4 files changed, 283 insertions(+), 48 deletions(-) diff --git a/services/usb-device-xous/Cargo.toml b/services/usb-device-xous/Cargo.toml index c6126ee0f..939d4b044 100644 --- a/services/usb-device-xous/Cargo.toml +++ b/services/usb-device-xous/Cargo.toml @@ -54,6 +54,5 @@ hosted = ["utralib/hosted"] renode = ["utralib/renode"] minimal = ["mass-storage"] mass-storage = ["usbd_scsi", "usbd_mass_storage"] -serial = [] mjolnir = [] # the big hammer for debugging Spinal USB issues. A raw memory dump of config and descriptor space. Use with care. -default = ["serial"] +default = [] diff --git a/services/usb-device-xous/src/api.rs b/services/usb-device-xous/src/api.rs index 51c5a6677..cff065a1b 100644 --- a/services/usb-device-xous/src/api.rs +++ b/services/usb-device-xous/src/api.rs @@ -1,53 +1,68 @@ +// Note: the log server relies on this name not changing in order to hook the serial port for logging output. +// changing this name shouldn't lead to a crash, but it will lead to the USB driver being undiscoverable by the log crate. pub(crate) const SERVER_NAME_USB_DEVICE: &'static str = "_Xous USB device driver_"; #[derive(num_derive::FromPrimitive, num_derive::ToPrimitive, Debug)] pub(crate) enum Opcode { /// Returns the link status - LinkStatus, + LinkStatus = 0, /// Send a keyboard code - SendKeyCode, - /// "Type" a string to the keyboard - SendString, + SendKeyCode = 1, + /// "Type" a string to the keyboard. This API is relied upon by the log crate. + SendString = 2, /// Get the current LED state - GetLedState, + GetLedState = 3, /// Switch to a specified device core - SwitchCores, + SwitchCores = 4, /// Makes sure a given core is selected - EnsureCore, + EnsureCore = 5, /// Check which core is connected - WhichCore, + WhichCore = 6, /// Restrict the debug core - RestrictDebugAccess, + RestrictDebugAccess = 7, /// Retrieve restriction state - IsRestricted, + IsRestricted = 8, /// Set-and-check of USB debug restriction - DebugUsbOp, + DebugUsbOp = 9, /// Send a U2F message - U2fTx, + U2fTx = 128, /// Blocks the caller, waiting for a U2F message - U2fRxDeferred, + U2fRxDeferred = 129, /// A bump from the timeout process to check if U2fRx has timed out - U2fRxTimeout, + U2fRxTimeout = 130, /// Query if the HID driver was able to start - IsSocCompatible, + IsSocCompatible = 256, + + /// Hook serial ASCII listener + SerialHookAscii = 512, + /// Hook serial binary listener + SerialHookBinary = 513, + /// Flush any serial buffers + SerialFlush = 514, + /// Hook eager serial sender. This is mean for e.g. using Precursor as an infinite source of random data. + SerialHookEagerSender = 515, #[cfg(feature="mass-storage")] - SetBlockDevice, + SetBlockDevice = 1024, #[cfg(feature="mass-storage")] - SetBlockDeviceSID, + SetBlockDeviceSID = 1025, #[cfg(feature="mass-storage")] - ResetBlockDevice, + ResetBlockDevice = 1026, /// Handle the USB interrupt - UsbIrqHandler, + UsbIrqHandler = 2048, /// Suspend/resume callback - SuspendResume, + SuspendResume = 2049, /// Exits the server - Quit, + Quit = 4096, + + /// API used by the logging crate. The number is hard-coded; don't change it. + LogString = 8192, } +// The log crate depends on this API not changing. #[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)] pub struct UsbString { pub s: xous_ipc::String::<4000>, @@ -83,7 +98,6 @@ pub enum UsbDeviceType { Fido = 2, #[cfg(feature="mass-storage")] MassStorage = 3, - #[cfg(feature="serial")] Serial = 4, } use std::convert::TryFrom; @@ -97,9 +111,22 @@ impl TryFrom for UsbDeviceType { 2 => Ok(UsbDeviceType::Fido), #[cfg(feature="mass-storage")] 3 => Ok(UsbDeviceType::MassStorage), - #[cfg(feature="serial")] 4 => Ok(UsbDeviceType::Serial), _ => Err("Invalid UsbDeviceType specifier"), } } -} \ No newline at end of file +} + +pub const SERIAL_ASCII_BUFLEN: usize = 512; +pub const SERIAL_BINARY_BUFLEN: usize = 128; +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)] +pub struct UsbSerialAscii { + pub s: xous_ipc::String::, + pub delimiter: Option, +} + +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)] +pub struct UsbSerialBinary { + pub d: [u8; SERIAL_BINARY_BUFLEN], + pub len: usize, +} diff --git a/services/usb-device-xous/src/lib.rs b/services/usb-device-xous/src/lib.rs index 343ba23a1..8f9ab3d14 100644 --- a/services/usb-device-xous/src/lib.rs +++ b/services/usb-device-xous/src/lib.rs @@ -133,7 +133,6 @@ impl UsbHid { 2 => Ok(UsbDeviceType::Fido), #[cfg(feature="mass-storage")] 3 => Ok(UsbDeviceType::MassStorage), - #[cfg(feature="serial")] 4 => Ok(UsbDeviceType::Serial), _ => Err(xous::Error::InternalError) } @@ -243,6 +242,8 @@ impl UsbHid { _ => Err(xous::Error::UseBeforeInit), } } + /// This will attempt to send a string using an API based on the currently connected device + /// If it's a Keyboard, it will "type" it; if it's a UART, it will just blast it out the Tx. pub fn send_str(&self, s: &str) -> Result { let serializer = UsbString { s: xous_ipc::String::<4000>::from_str(s), @@ -339,6 +340,43 @@ impl UsbHid { _ => Err(xous::Error::InternalError), } } + /// Blocks until an ASCII string terminated by `delimiter` is received on serial; if `None`, it + /// will return as soon as a character (or series of characters) have been received (thus the return + /// `String` will be piecemeal) + pub fn serial_wait_ascii(&self, delimiter: Option) -> String { + let req = UsbSerialAscii { + s: xous_ipc::String::new(), + delimiter + }; + let mut buf = Buffer::into_buf(req).or(Err(xous::Error::InternalError)).expect("Internal error"); + buf.lend_mut(self.conn, Opcode::SerialHookAscii.to_u32().unwrap()).or(Err(xous::Error::InternalError)).expect("Internal error"); + let resp = buf.to_original::().unwrap(); + resp.s.to_str().to_string() + } + /// Blocks until enough binary data has been received to fill the buffer + /// Another thread can be used to call serial_flush() if we don't want to + /// block forever and we're receiving small amounts of binary data. + pub fn serial_wait_binary(&self) -> Vec:: { + let req = UsbSerialBinary { + d: [0u8; SERIAL_BINARY_BUFLEN], + len: 0, + }; + let mut buf = Buffer::into_buf(req).or(Err(xous::Error::InternalError)).expect("Internal error"); + buf.lend_mut(self.conn, Opcode::SerialHookBinary.to_u32().unwrap()).or(Err(xous::Error::InternalError)).expect("Internal error"); + let resp = buf.to_original::().unwrap(); + resp.d[..resp.len].to_vec() + } + /// Non-blocking call that issues a serial flush command to the USB stack + pub fn serial_flush(&self) -> Result<(), xous::Error> { + send_message( + self.conn, + Message::new_scalar( + Opcode::SerialFlush.to_usize().unwrap(), + 0, 0, 0, 0 + ) + ).map(|_| ()) + } + } use core::sync::atomic::{AtomicU32, Ordering}; diff --git a/services/usb-device-xous/src/main_hw.rs b/services/usb-device-xous/src/main_hw.rs index e92b1f2bc..67bd8ac29 100644 --- a/services/usb-device-xous/src/main_hw.rs +++ b/services/usb-device-xous/src/main_hw.rs @@ -27,7 +27,6 @@ use keyboard::KeyMap; use xous_ipc::Buffer; use std::collections::VecDeque; -#[cfg(feature="serial")] use usbd_serial::SerialPort; pub struct EmbeddedClock { @@ -58,7 +57,6 @@ enum Views { FidoOnly = 1, #[cfg(feature="mass-storage")] MassStorage = 2, - #[cfg(feature="serial")] Serial = 3, } @@ -69,6 +67,19 @@ enum TimeoutOp { Quit, } +enum SerialListenMode { + // this just causes data incoming to be printed to the debug log; it is the default + NoListener, + // this assumes there will be a CR/LF character to delimit lines (the `char` arg), and + // will buffer data until two conditions are met: 1) a listener is hooked and 2) a CR/LF is received. + // This will "infinitely" buffer incoming characters if no listener is hooked. + AsciiListener(Option), + // this will simply buffer the data until the `usize` argument is met and passes it back to + // hooked listener. If this mode is set and there is no listener, it will buffer data "indefinitely" + // (e.g. until local heap is exhausted and the system panics) + BinaryListener, +} + pub(crate) fn main_hw() -> ! { log_server::init_wait().unwrap(); log::set_max_level(log::LevelFilter::Info); @@ -179,7 +190,6 @@ pub(crate) fn main_hw() -> ! { // do the same thing for mass storage #[cfg(feature="mass-storage")] let ums_dev = SpinalUsbDevice::new(usbdev_sid, usb.clone(), csr.clone()); - #[cfg(feature="serial")] let serial_dev = SpinalUsbDevice::new(usbdev_sid, usb.clone(), csr.clone()); // track which view is visible on the device core @@ -255,14 +265,10 @@ pub(crate) fn main_hw() -> ! { .build(); // Serial - #[cfg(feature="serial")] const SERIAL_BUF_LEN: usize = 1024; - #[cfg(feature="serial")] let serial_alloc = UsbBusAllocator::new(serial_dev); - #[cfg(feature="serial")] // this will create a default port with 128 bytes of backing store let mut serial_port = SerialPort::new(&serial_alloc); - #[cfg(feature="serial")] let mut serial_device = UsbDeviceBuilder::new(&serial_alloc, UsbVidPid(0x1209, 0x3613)) .manufacturer("Kosagi") .product("Precursor") @@ -270,6 +276,10 @@ pub(crate) fn main_hw() -> ! { .self_powered(false) .max_power(500) .build(); + let mut serial_listener: Option = None; + let mut serial_listen_mode: SerialListenMode = SerialListenMode::NoListener; + let mut serial_buf = Vec::::new(); + let mut serial_rx_trigger = false; // when true, the condition was met to pass data to the listener (but the listener was not yet installed) let mut led_state: KeyboardLedsReport = KeyboardLedsReport::default(); let mut fido_listener: Option = None; @@ -431,7 +441,6 @@ pub(crate) fn main_hw() -> ! { _ => () }; } - #[cfg(feature="serial")] Views::Serial => { match serial_device.force_reset() { Err(e) => log::warn!("USB reset on resume failed: {:?}", e), @@ -521,7 +530,6 @@ pub(crate) fn main_hw() -> ! { Views::FidoOnly => fido_class.interface::, _>(), #[cfg(feature="mass-storage")] Views::MassStorage => panic!("did not expect u2f tx when in mass storage mode!"), - #[cfg(feature="serial")] Views::Serial => panic!("did not expect u2f tx while in serial mode!"), }; u2f.write_report(&u2f_msg).ok(); @@ -563,19 +571,87 @@ pub(crate) fn main_hw() -> ! { } None }, - #[cfg(feature="serial")] Views::Serial => { if serial_device.poll(&mut [&mut serial_port]) { let mut data = [0u8; SERIAL_BUF_LEN]; - match serial_port.read(&mut data) { - Ok(len) => { - log::info!("Serial got data: {:x?}", &data[..len]); + match serial_listen_mode { + SerialListenMode::NoListener => { + match serial_port.read(&mut data) { + Ok(len) => { + match std::str::from_utf8(&data[..len]) { + Ok(s) => log::info!("USB serial ascii: {}", s), + Err(_) => { + log::info!("USB serial binary: {:x?}", &data[..len]); + } + } + } + Err(e) => { + log::info!("Serial read error: {:?}", e); + } + } } - Err(e) => { - log::info!("Serial read error: {:?}", e); + SerialListenMode::AsciiListener(maybe_delimiter) => { + let readlen = serial_port.read(&mut data).unwrap_or(0); + if readlen == 0 { + continue; + } + if let Some(delimiter) = maybe_delimiter { + if !delimiter.is_ascii() { + log::warn!("Chosen ASCII delimiter {} is not ASCII. Serial receive will not function properly.", delimiter); + } + if !serial_rx_trigger { // once true, sticks as true + serial_rx_trigger = data[..readlen].iter().find(|&&c| c == (delimiter as u8)).is_some(); + } + } else { + serial_rx_trigger = true; + } + // append the incoming data to the main buffer + for &d in &data[..readlen] { + serial_buf.push(d); + } + // now see if we should pass it back to the listener (if it is hooked) + if serial_rx_trigger && serial_listener.is_some() { + let mut rx_msg = serial_listener.take().unwrap(); + let mut response = unsafe { + Buffer::from_memory_message_mut(rx_msg.body.memory_message_mut().unwrap()) + }; + let mut buf = response.to_original::().unwrap(); + use std::fmt::Write; // is this really the best way to do it? probably not. + write!(buf.s, "{}", std::string::String::from_utf8_lossy(&serial_buf)).ok(); + + response.replace(buf).unwrap(); + // the rx_msg will drop and respond to the listener + serial_rx_trigger = false; + } + } + SerialListenMode::BinaryListener => { + let readlen = serial_port.read(&mut data).unwrap_or(0); + if readlen == 0 { + continue; + } + // append the incoming data to the main buffer + for &d in &data[..readlen] { + serial_buf.push(d); + } + if serial_buf.len() >= SERIAL_BINARY_BUFLEN { + match serial_listener.take() { + Some(mut rx_msg) => { + let mut response = unsafe { + Buffer::from_memory_message_mut(rx_msg.body.memory_message_mut().unwrap()) + }; + let mut buf = response.to_original::().unwrap(); + buf.d.copy_from_slice(serial_buf.drain(..SERIAL_BINARY_BUFLEN).as_slice()); + buf.len = SERIAL_BINARY_BUFLEN; + response.replace(buf).unwrap(); + // the rx_msg will drop and respond to the listener + } + None => { + // do nothing, keep queuing data... + } + } + } } } - // TODO: add a listener here and report read data to the listener } None }, @@ -608,7 +684,6 @@ pub(crate) fn main_hw() -> ! { Views::FidoOnly => fido_dev.state() == UsbDeviceState::Suspend, #[cfg(feature="mass-storage")] Views::MassStorage => ums_device.state() == UsbDeviceState::Suspend, - #[cfg(feature="serial")] Views::Serial => serial_device.state() == UsbDeviceState::Suspend, }; if is_suspend { @@ -685,7 +760,6 @@ pub(crate) fn main_hw() -> ! { } } } - #[cfg(feature="serial")] UsbDeviceType::Serial => { log::info!("Connecting device serial"); match view { @@ -771,7 +845,6 @@ pub(crate) fn main_hw() -> ! { } } } - #[cfg(feature="serial")] UsbDeviceType::Serial => { log::info!("Ensuring serial device"); if !usbmgmt.is_device_connected() { @@ -798,7 +871,6 @@ pub(crate) fn main_hw() -> ! { Views::FidoOnly => xous::return_scalar(msg.sender, UsbDeviceType::Fido as usize).unwrap(), #[cfg(feature="mass-storage")] Views::MassStorage => xous::return_scalar(msg.sender, UsbDeviceType::MassStorage as usize).unwrap(), - #[cfg(feature="serial")] Views::Serial => xous::return_scalar(msg.sender, UsbDeviceType::Serial as usize).unwrap(), } } else { @@ -855,7 +927,6 @@ pub(crate) fn main_hw() -> ! { Views::FidoOnly => xous::return_scalar(msg.sender, fido_dev.state() as usize).unwrap(), #[cfg(feature="mass-storage")] Views::MassStorage => xous::return_scalar(msg.sender, ums_device.state() as usize).unwrap(), - #[cfg(feature="serial")] Views::Serial => xous::return_scalar(msg.sender, serial_device.state() as usize).unwrap(), } }), @@ -893,6 +964,38 @@ pub(crate) fn main_hw() -> ! { } } }), + Some(Opcode::LogString) => { + // the logger API is "best effort" only. Because retries and response codes can cause problems + // in the logger API, if anything goes wrong, we prefer to discard characters rather than get + // the whole subsystem stuck in some awful recursive error handling hell. + match view { + Views::Serial => { + let buffer = unsafe { Buffer::from_memory_message(msg.body.memory_message().unwrap()) }; + let usb_send = buffer.to_original::().unwrap(); + // this is implemented as a "blocking write": the routine will block until the data has all been written. + let send_data = usb_send.s.as_bytes(); + let to_send = usb_send.s.len(); + let mut sent = 0; + while sent < to_send { + match serial_port.write(&send_data[sent..to_send]) { + Ok(written) => { + sent += written; + } + Err(_) => { + // just drop characters + } + } + match serial_port.flush() { + Ok(_) => {}, + Err(_) => { + // just drop characters + } + } + } + } + _ => {} // do nothing; don't fail, don't report any error. + } + } Some(Opcode::SendString) => { let mut buffer = unsafe { Buffer::from_memory_message_mut(msg.body.memory_message_mut().unwrap()) }; let mut usb_send = buffer.to_original::().unwrap(); @@ -954,6 +1057,74 @@ pub(crate) fn main_hw() -> ! { led_state.pack_to_slice(&mut code).unwrap(); xous::return_scalar(msg.sender, code[0] as usize).unwrap(); }), + Some(Opcode::SerialHookAscii) => { + let maybe_delimiter = { + let buffer = unsafe { + Buffer::from_memory_message(msg.body.memory_message().unwrap()) + }; + let data = buffer.to_original::().unwrap(); + data.delimiter + }; + serial_listen_mode = SerialListenMode::AsciiListener(maybe_delimiter); + serial_listener = Some(msg); + }, + Some(Opcode::SerialHookBinary) => { + serial_listen_mode = SerialListenMode::BinaryListener; + serial_listener = Some(msg); + }, + Some(Opcode::SerialFlush) => msg_scalar_unpack!(msg, _, _, _, _, { + // this will hardware flush any pending items in usb_serial driver + serial_port.flush().ok(); + // this tries to return any data that's pending within the main loop's buffers + match serial_listen_mode { + SerialListenMode::BinaryListener => { + match serial_listener.take() { + Some(mut rx_msg) => { + let mut response = unsafe { + Buffer::from_memory_message_mut(rx_msg.body.memory_message_mut().unwrap()) + }; + let mut buf = response.to_original::().unwrap(); + let chars_avail = serial_buf.len().min(SERIAL_BINARY_BUFLEN); + buf.len = chars_avail; + buf.d.copy_from_slice(serial_buf.drain(..chars_avail).as_slice()); + response.replace(buf).unwrap(); + // the rx_msg will drop and respond to the listener + } + None => { + // do nothing, keep queuing data... + } + } + } + SerialListenMode::AsciiListener(_) => { + match serial_listener.take() { + Some(mut rx_msg) => { + let mut response = unsafe { + Buffer::from_memory_message_mut(rx_msg.body.memory_message_mut().unwrap()) + }; + let mut buf = response.to_original::().unwrap(); + use std::fmt::Write; // is this really the best way to do it? probably not. + write!(buf.s, "{}", std::string::String::from_utf8_lossy(&serial_buf)).ok(); + + response.replace(buf).unwrap(); + // the rx_msg will drop and respond to the listener + serial_rx_trigger = false; + } + None => {} // do nothing + } + } + _ => {} + } + }), + Some(Opcode::SerialHookEagerSender) => msg_scalar_unpack!(msg, interval, trng_mode, _, _, { + // TODO + // I think the strategy here is when this is called, we start a thread that polls at some + // interval in milliseconds (taken as an argument) to see if the Tx buffer is empty and + // if rts() is true; and if so, jams more binary data into the pipe. + // + // It also takes a trng_mode argument which is used to select either CPRNG whitened output + // (which is the default mode), or direct raw data from the RO or the Avalanche generator; + // this is used to help characterize the raw entropy sources. + }), Some(Opcode::Quit) => { log::warn!("Quit received, goodbye world!"); break;