bsp(metro_m4)!: Makes the usb_logging example safe and suppresses the static mut warnings.

Author: Dan Whitman

boards/metro_m4/Cargo.toml

@@ -14,6 +14,9 @@ version = "0.18.2"
 [package.metadata]
 chip = "ATSAMD51J19A"
 
+[dependencies]
+heapless = "0.9.1"
+
 [dependencies.cortex-m-rt]
 optional = true
 version = "0.7"

boards/metro_m4/examples/usb_logging.rs

@@ -1,12 +1,14 @@
 #![no_std]
 #![no_main]
+#![allow(static_mut_refs)]
 
 use metro_m4 as bsp;
 
 use bsp::ehal;
 use bsp::hal;
 use bsp::pac;
 
+use core::cell::OnceCell;
 use cortex_m::asm::delay as cycle_delay;
 use cortex_m::peripheral::NVIC;
 use ehal::digital::StatefulOutputPin;
@@ -40,20 +42,20 @@ fn main() -> ! {
     let mut red_led: bsp::RedLed = pins.d13.into();
 
     let bus_allocator = unsafe {
-        USB_ALLOCATOR = Some(bsp::usb_allocator(
+        let _ = USB_ALLOCATOR.set(bsp::usb_allocator(
             peripherals.usb,
             &mut clocks,
             &mut peripherals.mclk,
             pins.usb_dm,
             pins.usb_dp,
         ));
-        USB_ALLOCATOR.as_ref().unwrap()
+        USB_ALLOCATOR.get().unwrap()
     };
 
     unsafe {
-        USB_SERIAL = Some(SerialPort::new(bus_allocator));
-        USB_BUS = Some(
-            UsbDeviceBuilder::new(bus_allocator, UsbVidPid(0x2222, 0x3333))
+        let _ = USB_SERIAL.set(SerialPort::new(bus_allocator));
+        let _ = USB_BUS.set(
+            UsbDeviceBuilder::new(bus_allocator, UsbVidPid(0x16c0, 0x27dd))
                 .strings(&[StringDescriptors::new(LangID::EN)
                     .manufacturer("Fake company")
                     .product("Serial port")
@@ -65,44 +67,110 @@ fn main() -> ! {
     }
 
     unsafe {
+        core.NVIC.set_priority(interrupt::USB_OTHER, 1);
         core.NVIC.set_priority(interrupt::USB_TRCPT0, 1);
-        NVIC::unmask(interrupt::USB_TRCPT0);
         core.NVIC.set_priority(interrupt::USB_TRCPT1, 1);
-        NVIC::unmask(interrupt::USB_TRCPT1);
-        core.NVIC.set_priority(interrupt::USB_SOF_HSOF, 1);
-        NVIC::unmask(interrupt::USB_SOF_HSOF);
-        core.NVIC.set_priority(interrupt::USB_OTHER, 1);
         NVIC::unmask(interrupt::USB_OTHER);
+        NVIC::unmask(interrupt::USB_TRCPT0);
+        NVIC::unmask(interrupt::USB_TRCPT1);
     }
 
     // Flash the LED in a spin loop to demonstrate that USB is
     // entirely interrupt driven.
     loop {
         cycle_delay(5 * 1024 * 1024);
         red_led.toggle().unwrap();
-        // Turn off interrupts so we don't fight with the interrupt
-        cortex_m::interrupt::free(|_| unsafe {
-            if USB_BUS.as_mut().is_some() {
-                if let Some(serial) = USB_SERIAL.as_mut() {
-                    let _ = serial.write("Hello USB\n".as_bytes());
-                }
-            }
-        });
+
+        serial_writeln!("Hello USB");
     }
 }
 
-static mut USB_ALLOCATOR: Option<UsbBusAllocator<UsbBus>> = None;
-static mut USB_BUS: Option<UsbDevice<UsbBus>> = None;
-static mut USB_SERIAL: Option<SerialPort<UsbBus>> = None;
+static mut USB_ALLOCATOR: OnceCell<UsbBusAllocator<UsbBus>> = OnceCell::new();
+static mut USB_BUS: OnceCell<UsbDevice<UsbBus>> = OnceCell::new();
+static mut USB_SERIAL: OnceCell<SerialPort<UsbBus>> = OnceCell::new();
+
+/// Borrows the global singleton `UsbSerial` for a brief period with interrupts
+/// disabled
+///
+/// # Arguments
+/// `borrower`: The closure that gets run borrowing the global `UsbSerial`
+///
+/// # Safety
+/// the global singleton `UsbSerial` can be safely borrowed because we disable
+/// interrupts while it is being borrowed, guaranteeing that interrupt handlers
+/// like `USB` cannot mutate `UsbSerial` while we are as well.
+///
+/// # Panic
+/// If `init` has not been called and we haven't initialized our global
+/// singleton `UsbSerial`, we will panic.
+fn usbserial_get<T, R>(borrower: T) -> R
+where
+    T: Fn(&mut SerialPort<UsbBus>) -> R,
+{
+    usb_free(|_| unsafe {
+        let usb_serial = USB_SERIAL.get_mut().expect("UsbSerial not initialized");
+        borrower(usb_serial)
+    })
+}
+
+/// Execute closure `f` in an interrupt-free context.
+///
+/// This as also known as a "critical section".
+#[inline]
+fn usb_free<F, R>(f: F) -> R
+where
+    F: FnOnce(&cortex_m::interrupt::CriticalSection) -> R,
+{
+    NVIC::mask(interrupt::USB_OTHER);
+    NVIC::mask(interrupt::USB_TRCPT0);
+    NVIC::mask(interrupt::USB_TRCPT1);
+
+    let r = f(unsafe { &cortex_m::interrupt::CriticalSection::new() });
+
+    unsafe {
+        NVIC::unmask(interrupt::USB_OTHER);
+        NVIC::unmask(interrupt::USB_TRCPT0);
+        NVIC::unmask(interrupt::USB_TRCPT1);
+    };
+
+    r
+}
+
+/// Writes the given message out over USB serial.
+///
+/// # Arguments
+/// * println args: variable arguments passed along to `core::write!`
+///
+/// # Warning
+/// as this function deals with a static mut, and it is also accessed in the
+/// USB interrupt handler, we both have unsafe code for unwrapping a static mut
+/// as well as disabling of interrupts while we do so.
+///
+/// # Safety
+/// the only time the static mut is used, we have interrupts disabled so we know
+/// we have sole access
+#[macro_export]
+macro_rules! serial_writeln {
+    ($($tt:tt)+) => {{
+        use core::fmt::Write;
+
+        let mut s: heapless::String<256> = heapless::String::new();
+        core::write!(&mut s, $($tt)*).unwrap();
+        usbserial_get(|usbserial| {
+            usbserial.write(s.as_bytes()).ok();
+            usbserial.write("\r\n".as_bytes()).ok();
+        });
+    }};
+}
 
 fn poll_usb() {
     unsafe {
-        if let Some(usb_dev) = USB_BUS.as_mut() {
-            if let Some(serial) = USB_SERIAL.as_mut() {
+        if let Some(usb_dev) = USB_BUS.get_mut() {
+            if let Some(serial) = USB_SERIAL.get_mut() {
                 usb_dev.poll(&mut [serial]);
 
                 // Make the other side happy
-                let mut buf = [0u8; 16];
+                let mut buf = [0u8; 64];
                 let _ = serial.read(&mut buf);
             };
         }
@@ -119,11 +187,6 @@ fn USB_TRCPT1() {
     poll_usb();
 }
 
-#[interrupt]
-fn USB_SOF_HSOF() {
-    poll_usb();
-}
-
 #[interrupt]
 fn USB_OTHER() {
     poll_usb();