USB: Check the peripheral frequency for a stable connection

Author: rnd-ash

boards/atsame54_xpro/src/devices.rs

@@ -372,5 +372,6 @@ pub fn usb_allocator(
     let usb_gclk = clocks.get_gclk(Genselect::Gclk2).unwrap();
     let usb_clock = &clocks.usb(&usb_gclk).unwrap();
     let (dm, dp) = (dm.into(), dp.into());
-    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb))
+    /// Safety - V1 clocking API forces a 48Mhz USB clock
+    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb).unwrap())
 }

boards/feather_m4/src/lib.rs

@@ -272,5 +272,6 @@ pub fn usb_allocator(
     let usb_gclk = clocks.get_gclk(Genselect::Gclk2).unwrap();
     let usb_clock = &clocks.usb(&usb_gclk).unwrap();
     let (dm, dp) = (dm.into(), dp.into());
-    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb))
+    /// Safety - V1 clocking API forces a 48Mhz USB clock
+    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb).unwrap())
 }

boards/metro_m0/src/lib.rs

@@ -336,5 +336,6 @@ pub fn usb_allocator(
     let gclk0 = clocks.gclk0();
     let clock = &clocks.usb(&gclk0).unwrap();
     let (dm, dp) = (dm.into(), dp.into());
-    UsbBusAllocator::new(UsbBus::new(clock, pm, dm, dp, usb))
+    /// Safety - V1 clocking API forces a 48Mhz USB clock
+    UsbBusAllocator::new(UsbBus::new(clock, pm, dm, dp, usb).unwrap())
 }

boards/metro_m4/src/lib.rs

@@ -365,5 +365,6 @@ pub fn usb_allocator(
     let usb_gclk = clocks.get_gclk(Genselect::Gclk2).unwrap();
     let usb_clock = &clocks.usb(&usb_gclk).unwrap();
     let (dm, dp) = (dm.into(), dp.into());
-    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb))
+    /// Safety - V1 clocking API forces a 48Mhz USB clock
+    UsbBusAllocator::new(UsbBus::new(usb_clock, mclk, dm, dp, usb).unwrap())
 }

hal/src/peripherals/usb/d11/bus.rs

@@ -482,9 +482,41 @@ impl Inner {
     }
 }
 
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum UsbBusErr {
+    /// USB clock freq is not valid for a stable connection
+    InvalidClockFreq,
+}
+
 impl UsbBus {
+    /// Create a new USB Bus, checking the clock frequency of the USB clock for
+    /// a stable USB link to most hosts. The `clock` freq must be 48Mhz, otherwise
+    /// [`UsbBusErr::InvalidClockFreq`] will be returned
     pub fn new(
-        _clock: &clock::UsbClock,
+        clock: &clock::UsbClock,
+        pm: &mut Pm,
+        dm_pad: impl AnyPin<Id = PA24>,
+        dp_pad: impl AnyPin<Id = PA25>,
+        usb: Usb,
+    ) -> Result<Self, UsbBusErr> {
+        if clock.freq().to_Hz() != 48_000_000 {
+            Err(UsbBusErr::InvalidClockFreq)
+        } else {
+            let res = unsafe { Self::new_unchecked(clock, pm, dm_pad, dp_pad, usb) };
+            Ok(res)
+        }
+    }
+
+    /// Creates a new USB Bus, but does NOT perform the USB clock frequency check.
+    ///
+    /// SAFETY: For a SAMx to PC connection, the USB clock must be 48Mhz for stability.
+    /// This function allows you to bypass this check however if you intend to connect multiple SAM chips
+    /// together with faster running USB clocks for a boost in transfer rate.
+    ///
+    /// Consult the datasheet for GCLK_USB absolute maximums
+    pub unsafe fn new_unchecked(
+        clock: &clock::UsbClock,
         pm: &mut Pm,
         dm_pad: impl AnyPin<Id = PA24>,
         dp_pad: impl AnyPin<Id = PA25>,

hal/src/peripherals/usb/d5x/bus.rs

@@ -524,13 +524,44 @@ impl Inner {
     }
 }
 
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum UsbBusErr {
+    /// USB clock freq is not valid for a stable connection
+    InvalidClockFreq,
+}
+
 impl UsbBus {
+    /// Create a new USB Bus, checking the clock frequency of the USB clock for
+    /// a stable USB link to most hosts. The `clock` freq must be 48Mhz, otherwise
+    /// [`UsbBusErr::InvalidClockFreq`] will be returned
     pub fn new(
-        _clock: &clock::UsbClock,
+        clock: &clock::UsbClock,
         mclk: &mut Mclk,
         dm_pad: impl AnyPin<Id = PA24>,
         dp_pad: impl AnyPin<Id = PA25>,
         _usb: Usb,
+    ) -> Result<Self, UsbBusErr> {
+        if clock.freq().to_Hz() != 48_000_000 {
+            Err(UsbBusErr::InvalidClockFreq)
+        } else {
+            let res = unsafe { Self::new_unchecked(clock, mclk, dm_pad, dp_pad) };
+            Ok(res)
+        }
+    }
+
+    /// Creates a new USB Bus, but does NOT perform the USB clock frequency check.
+    ///
+    /// SAFETY: For a SAMx to PC connection, the USB clock must be 48Mhz for stability.
+    /// This function allows you to bypass this check however if you intend to connect multiple SAM chips
+    /// together with faster running USB clocks for a boost in transfer rate.
+    ///
+    /// Consult the datasheet for GCLK_USB absolute maximums
+    pub unsafe fn new_unchecked(
+        _clock: &clock::UsbClock,
+        mclk: &mut Mclk,
+        dm_pad: impl AnyPin<Id = PA24>,
+        dp_pad: impl AnyPin<Id = PA25>,
     ) -> Self {
         mclk.ahbmask().modify(|_, w| w.usb_().set_bit());
         mclk.apbbmask().modify(|_, w| w.usb_().set_bit());