Add USB support to arduino-micro

Fixes #40.

The purpose of this PR is to add USB support for the `atmega32u4`. This
is done using rust-embedded-community/usb-device GitHub repo, since that
appears to be the most popular crate this sort of thing.

When using `usb-device`, there are three main components to be aware of:

* For `avr-hal`, the main thing we care about is `UsbBus`. This trait is
  a hardware abstraction layer for the actual USB hardware. We implement
  this trait in `mcu/atmega-hal/src/usb.rs`.

* The `UsbClass` trait is used to implement support for each different
  type of USB device (e.g. speaker, keyboard, or serial port). These
  implementations are portable, so we can just use existing
  implementations from other crates. For `micro-usb-serial.rs`, we
  create a serial port using `usbd-serial`'s implementation of
  `UsbClass`.

  `usbd-serial` was chosen simply because it is the only serial class
  implementation that is mentioned in `usb-device`'s readme file.

* `UsbDevice` is used by our users (and our example code) to actually
  configure the USB device. Basically, to create `UsbDevice` the user just
  needs to combine our `UsbBus` implementation with the list of
  `UsbClass`es that they want to use.

Author: Ivan-Johnson

arduino-hal/src/lib.rs

@@ -190,6 +190,22 @@ pub mod eeprom {
 #[cfg(feature = "board-selected")]
 pub use eeprom::Eeprom;
 
+#[doc(no_inline)]
+#[cfg(any(
+    feature = "arduino-micro",
+    feature = "arduino-leonardo",
+    feature = "sparkfun-promicro"
+))]
+pub use atmega_hal::default_usb_bus_with_pll;
+
+#[doc(no_inline)]
+#[cfg(any(
+    feature = "arduino-micro",
+    feature = "arduino-leonardo",
+    feature = "sparkfun-promicro"
+))]
+pub use atmega_hal::default_usb_bus_with_pll_macro;
+
 #[cfg(feature = "board-selected")]
 pub mod simple_pwm {
     #[cfg(feature = "mcu-atmega")]

examples/arduino-leonardo/Cargo.toml

@@ -10,6 +10,8 @@ panic-halt = "1.0.0"
 ufmt = "0.2.0"
 nb = "1.1.0"
 embedded-hal = "1.0"
+usb-device = "0.3.2"
+usbd-serial = "0.2.2"
 
 [dependencies.arduino-hal]
 path = "../../arduino-hal/"

examples/arduino-leonardo/src/bin/micro-usb-serial.rs

@@ -0,0 +1 @@
+../../../arduino-micro/src/bin/micro-usb-serial.rs

examples/arduino-micro/Cargo.toml

@@ -8,6 +8,8 @@ publish = false
 panic-halt = "1.0.0"
 ufmt = "0.2.0"
 nb = "1.1.0"
+usb-device = "0.3.2"
+usbd-serial = "0.2.2"
 
 [dependencies.arduino-hal]
 path = "../../arduino-hal/"

examples/arduino-micro/src/bin/micro-usb-serial.rs

@@ -0,0 +1,55 @@
+#![no_std]
+#![no_main]
+use arduino_hal::Peripherals;
+use panic_halt as _;
+use usb_device::bus::UsbBusAllocator;
+use usb_device::device::StringDescriptors;
+use usb_device::device::UsbDeviceBuilder;
+use usb_device::device::UsbVidPid;
+use usb_device::LangID;
+use usbd_serial::SerialPort;
+
+#[arduino_hal::entry]
+fn main() -> ! {
+    let dp: Peripherals = arduino_hal::Peripherals::take().unwrap();
+
+    let usb_bus = arduino_hal::default_usb_bus_with_pll_macro!(dp);
+    let usb_bus_allocator = UsbBusAllocator::new(usb_bus);
+    let mut serial = SerialPort::new(&usb_bus_allocator);
+
+    let string_descriptors = StringDescriptors::new(LangID::EN_US)
+        .manufacturer("test manufacturer")
+        .product("test product")
+        .serial_number("test serial number");
+
+    let rand_ids = UsbVidPid(0x1ea7, 0x4a09);
+
+    let mut usb_dev = UsbDeviceBuilder::new(&usb_bus_allocator, rand_ids)
+        .strings(&[string_descriptors])
+        .unwrap()
+        .max_packet_size_0(64)
+        .unwrap()
+        .device_class(usbd_serial::USB_CLASS_CDC)
+        .build();
+
+    loop {
+        // Wait until we have data
+        if !usb_dev.poll(&mut [&mut serial]) {
+            continue;
+        }
+
+        // Read the data into this buffer
+        let mut read_buf = [0u8; 10];
+        let Ok(read_count) = serial.read(&mut read_buf) else {
+            continue;
+        };
+        if read_count == 0 {
+            continue;
+        }
+
+        let len = serial
+            .write(&read_buf[0..read_count])
+            .expect("The host should be reading data faster than the arduino can write it");
+        assert_eq!(len, read_count);
+    }
+}

examples/sparkfun-promicro/Cargo.toml

@@ -10,6 +10,8 @@ panic-halt = "1.0.0"
 ufmt = "0.2.0"
 nb = "1.1.0"
 embedded-hal = "1.0"
+usb-device = "0.3.2"
+usbd-serial = "0.2.2"
 
 [dependencies.arduino-hal]
 path = "../../arduino-hal/"

examples/sparkfun-promicro/src/bin/micro-usb-serial.rs

@@ -0,0 +1 @@
+../../../arduino-micro/src/bin/micro-usb-serial.rs

mcu/atmega-hal/Cargo.toml

@@ -21,7 +21,7 @@ atmega168 = ["avr-device/atmega168", "device-selected"]
 atmega328p = ["avr-device/atmega328p", "device-selected"]
 atmega328pb = ["avr-device/atmega328pb", "device-selected"]
 atmega32a = ["avr-device/atmega32a", "device-selected"]
-atmega32u4 = ["avr-device/atmega32u4", "device-selected"]
+atmega32u4 = ["avr-device/atmega32u4", "device-selected", "usb-device"]
 atmega2560 = ["avr-device/atmega2560", "device-selected"]
 atmega128a = ["avr-device/atmega128a", "device-selected"]
 atmega1280 = ["avr-device/atmega1280", "device-selected"]
@@ -37,6 +37,7 @@ docsrs = ["atmega328p"]
 
 [dependencies]
 avr-hal-generic = { path = "../../avr-hal-generic/" }
+usb-device = { version = "0.3.2", optional = true }
 
 [dependencies.avr-device]
 version = "0.8"

mcu/atmega-hal/src/lib.rs

@@ -1,4 +1,5 @@
 #![no_std]
+#![feature(asm_experimental_arch)]
 
 //! `atmega-hal`
 //! =============
@@ -119,6 +120,93 @@ pub use avr_hal_generic::clock;
 pub use avr_hal_generic::delay;
 pub use avr_hal_generic::prelude;
 
+#[cfg(feature = "atmega32u4")]
+mod usb;
+
+// TODO: fix bad usb-device::UsbBus link
+/// This function provides a safe abstraction layer over the USB hardware, by way of the
+/// [UsbBus](usb-device::UsbBus) trait.
+///
+/// There are a few notable limitations, however:
+///
+/// * This implementation requires exclusive access to the PLL, even though on a hardware
+///   level it is possible for the PLL output to be used by both the USB controller and
+///   the high-speed timer (TC4) simultaneously. Refer to GitHub issue #TBD for details.
+///
+///   TODO if Rahix agrees that this limitation isn't something we need to worry about
+///   as part of PR, then create a GitHub issue so that someone else can fix it later:
+///
+///   > **Title**
+///   >
+///   > Allow the USB and TC4 hardware to both use the PLL output simultaneously
+///   >
+///   > **Description**
+///   >
+///   > Our current UsbBus implementation prevents TC4 from using PLL output, even though
+///   > the hardware supports it. There are two main
+///   > problems that we need to solve first:
+///   >
+///   > 1. The current UsbBus implementation sets the PLL output to 48MHz. This could
+///   >    cause problems if the user has already configured TC4 to expect a different
+///   >    clock speed from the PLL.
+///   >
+///   > 2. We need to make the USB suspend state configurable. Currently when the USB
+///   >    bus is idle for 3ms or longer, it will disable the PLL to reduce power usage.
+///   >    However, this may not be desirable if TC4 is also using the PLL.
+///   >
+///   > **Comment**
+///   >
+///   > I think we *might* be able to solve this by splitting the constructor's
+///   > argument into two separate parts. Instead of passing ownership of the entire PLL
+///   > configuration (`pll: avr_device::atmega32u4::PLL`), we'd have one argument for
+///   > the registers that config the PLL clock speed (e.g. `pll_config: &PLLFRQ`) and one
+///   > optional argument for the registers that we use to turn the PLL on and off
+///   > (e.g. `pll_suspend: Option<&mut pllcsr>`). A value of `None` would indicate that
+///   > the user wants us to keep the PLL running while USB is idle.
+///   >
+///   > A few disclaimers:
+///   >
+///   > * This is a simplification. Instead of `pll_suspend: Option<&mut pllcsr>` we'd
+///   >   probably want to define a new trait,
+///   >   similar to what is done [in the `agausmann/atmega-usbd` repo](https://github.com/agausmann/atmega-usbd/blob/5fc68ca813ce0a37dab65dd4d66efe1ec125f2a8/src/lib.rs#L590-L618).
+///   >
+///   > * This is just one possible solution; there are others.
+///   >
+///   > * I've not spent much time investigating this, so this proposed solution might not work.
+///
+/// * The current implementation does not attempt to minimize power usage. For details,
+///   see GitHub issue #TBD.
+///
+///   TODO if Rahix agrees that this limitation isn't something we need to worry about
+///   as part of PR, then create a GitHub issue so that someone else can fix it later:
+///
+///   * Add support for using interrupts, in addition to polling.
+///     Similar to `agausmann/atmega-usbd`.
+///
+///   * Shutdown the PLL when the USB module is suspended (TODO: do in this PR?)
+///
+///   * and more?
+///
+/// * The underlying struct that implements `UsbBus` is private. This is done intentionally
+///   in order to make it easier to address the other issues without breaking backwards
+///   compatibility.
+#[cfg(feature = "atmega32u4")]
+pub fn default_usb_bus_with_pll(
+    usb: avr_device::atmega32u4::USB_DEVICE,
+    pll: avr_device::atmega32u4::PLL,
+) -> impl usb_device::class_prelude::UsbBus {
+    return usb::UsbdBus::new(usb, pll);
+}
+
+/// This macro is exactly equivalent to [default_usb_bus_with_pll](default_usb_bus_with_pll).
+#[cfg(feature = "atmega32u4")]
+#[macro_export]
+macro_rules! default_usb_bus_with_pll_macro {
+    ($p:expr) => {
+        $crate::default_usb_bus_with_pll($p.USB_DEVICE, $p.PLL)
+    };
+}
+
 #[cfg(feature = "device-selected")]
 pub mod adc;
 #[cfg(feature = "device-selected")]

mcu/atmega-hal/src/usb.rs

@@ -0,0 +1,91 @@
+use core::cell::Cell;
+
+use avr_device::atmega32u4::PLL;
+use avr_device::atmega32u4::USB_DEVICE;
+use avr_device::interrupt::Mutex;
+use usb_device::bus::PollResult;
+use usb_device::bus::UsbBus;
+use usb_device::endpoint::EndpointAddress;
+use usb_device::endpoint::EndpointType;
+use usb_device::UsbDirection;
+use usb_device::UsbError;
+
+const MAX_ENDPOINTS: usize = 7;
+
+struct EndpointTableEntry {
+    _ep_type: EndpointType,
+    _direction: UsbDirection,
+    _max_packet_size: u16,
+}
+
+pub struct UsbdBus {
+    _usb: Mutex<USB_DEVICE>,
+    _pll: Mutex<PLL>,
+    _pending_ins: Mutex<Cell<u8>>,
+    _endpoints: [Option<EndpointTableEntry>; MAX_ENDPOINTS],
+}
+
+impl UsbdBus {
+    pub fn new(_usb: USB_DEVICE, _pll: PLL) -> Self {
+        todo!();
+    }
+}
+
+impl UsbBus for UsbdBus {
+    fn alloc_ep(
+        &mut self,
+        _direction: UsbDirection,
+        _ep_addr: Option<EndpointAddress>,
+        _ep_type: EndpointType,
+        _max_packet_size: u16,
+        _interval: u8,
+    ) -> Result<EndpointAddress, UsbError> {
+        todo!();
+    }
+
+    fn enable(&mut self) {
+        todo!();
+    }
+
+    fn reset(&self) {
+        todo!();
+    }
+
+    fn set_device_address(&self, _addr: u8) {
+        todo!();
+    }
+
+    fn write(&self, _ep_addr: EndpointAddress, _buf: &[u8]) -> Result<usize, UsbError> {
+        todo!();
+    }
+
+    fn read(&self, _ep_addr: EndpointAddress, _buf: &mut [u8]) -> Result<usize, UsbError> {
+        todo!();
+    }
+
+    fn set_stalled(&self, _ep_addr: EndpointAddress, _stalled: bool) {
+        todo!();
+    }
+
+    fn is_stalled(&self, _ep_addr: EndpointAddress) -> bool {
+        todo!();
+    }
+
+    fn suspend(&self) {
+        todo!();
+    }
+
+    fn resume(&self) {
+        todo!();
+    }
+
+    fn poll(&self) -> PollResult {
+        todo!();
+    }
+}
+
+impl Drop for UsbdBus {
+    fn drop(&mut self) {
+        todo!()
+    }
+}