Remove imxrt-usbd dependency

mciantyre · mciantyre · commit 039dfea7411f · 2026-04-09T07:25:20.000-04:00
Users can select their own imxrt-usbd driver and usb-device ecosystem
for their system, and they can do this without waiting for an imxrt-hal
update / turning off default package features.

The imxrt-ral compatibility layer moves into imxrt-usbd. Right now,
we're still testing the driver here, since it's also helpful as a
logging backend.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -26,8 +26,9 @@ Users should program directly against the `Pit` type.
 
 **BREAKING** The ADC driver no longer supports unproven embedded-hal 0.2 traits.
 
-**BREAKING** Update `imxrt-usbd` to 0.3. Users are required to update to
-`usb-device` 0.3 and its compatible dependencies.
+**BREAKING** Remove the dependency on `imxrt-usbd` and the `usbd` module.
+Users should select their preferred versions of `imxrt-usbd`, `usb-device`,
+and other class packages.
 
 **BREAKING** Update imxrt-rs dependencies that affect the public API:
 
diff --git a/Cargo.toml b/Cargo.toml
@@ -72,10 +72,6 @@ workspace = true
 [dependencies.imxrt-ral]
 workspace = true
 
-[dependencies.imxrt-usbd]
-workspace = true
-optional = true
-
 [package.metadata.docs.rs]
 default-target = "thumbv7em-none-eabihf"
 features = ["imxrt-ral/imxrt1062", "imxrt1060"]
@@ -85,7 +81,6 @@ features = ["imxrt-ral/imxrt1062", "imxrt1060"]
 ###############
 
 [features]
-default = ["imxrt-usbd"]
 imxrt1010 = ["imxrt-iomuxc/imxrt1010"]
 imxrt1020 = ["imxrt-iomuxc/imxrt1020"]
 imxrt1060 = ["imxrt-iomuxc/imxrt1060"]
@@ -150,6 +145,7 @@ codegen-units = 256
 
 [dev-dependencies]
 imxrt-rt = { workspace = true }
+imxrt-usbd = { workspace = true }
 menu = "0.3.2"
 rtic = { version = "2.0", features = ["thumbv7-backend"] }
 log = "0.4"
@@ -222,3 +218,6 @@ git = "https://github.com/imxrt-rs/imxrt-ral"
 
 [patch.crates-io.imxrt-iomuxc]
 git = "https://github.com/imxrt-rs/imxrt-iomuxc"
+
+[patch.crates-io.imxrt-usbd]
+git = "https://github.com/imxrt-rs/imxrt-usbd"
diff --git a/board/src/lib.rs b/board/src/lib.rs
@@ -315,8 +315,9 @@ pub mod blocking {
 /// features. Then, simply define the default backend in your module.
 #[cfg(feature = "imxrt-log")]
 pub mod logging {
-    use crate::hal::{dma::channel::Channel, lpuart::Lpuart, usbd::Instances};
+    use crate::hal::{dma::channel::Channel, lpuart::Lpuart};
     pub use imxrt_log::Poller;
+    use imxrt_usbd::Instances;
     pub const BACKEND: Backend = crate::board_impl::DEFAULT_LOGGING_BACKEND;
 
     /// Select the logging front-end.
diff --git a/examples/hal_logging.rs b/examples/hal_logging.rs
@@ -59,7 +59,7 @@ fn main() -> ! {
     pit.set_interrupt_enable(PIT_CHANNEL, false);
     pit.enable(PIT_CHANNEL);
 
-    let usbd = hal::usbd::Instances {
+    let usbd = imxrt_usbd::Instances {
         usb: usb1,
         usbnc: usbnc1,
         usbphy: usbphy1,
diff --git a/examples/hal_srtc.rs b/examples/hal_srtc.rs
@@ -50,7 +50,7 @@ fn main() -> ! {
         board::Specifics { led, console, .. },
     ) = board::new();
 
-    let usbd = hal::usbd::Instances {
+    let usbd = imxrt_usbd::Instances {
         usb: usb1,
         usbnc: usbnc1,
         usbphy: usbphy1,
diff --git a/examples/hal_tempmon.rs b/examples/hal_tempmon.rs
@@ -68,7 +68,7 @@ fn main() -> ! {
     pit.set_interrupt_enable(PIT_CHANNEL, false);
     pit.enable(PIT_CHANNEL);
 
-    let usbd = hal::usbd::Instances {
+    let usbd = imxrt_usbd::Instances {
         usb: usb1,
         usbnc: usbnc1,
         usbphy: usbphy1,
diff --git a/examples/hal_trng.rs b/examples/hal_trng.rs
@@ -11,7 +11,6 @@ const MAKE_LOG_INTERVAL_MS: u32 = board::PIT_FREQUENCY / 1_000 * 250;
 
 use hal::pit::Channel;
 use imxrt_hal as hal;
-
 const FRONTEND: board::logging::Frontend = board::logging::Frontend::Log;
 const BACKEND: board::logging::Backend = board::logging::BACKEND;
 const PIT_CHANNEL: Channel = Channel::Chan2;
@@ -39,7 +38,7 @@ fn main() -> ! {
     pit.set_interrupt_enable(PIT_CHANNEL, false);
     pit.enable(PIT_CHANNEL);
 
-    let usbd = hal::usbd::Instances {
+    let usbd = imxrt_usbd::Instances {
         usb: usb1,
         usbnc: usbnc1,
         usbphy: usbphy1,
diff --git a/examples/rtic_logging.rs b/examples/rtic_logging.rs
@@ -95,7 +95,7 @@ mod app {
         pit.set_interrupt_enable(MAKE_LOG_CHANNEL, true);
         pit.enable(MAKE_LOG_CHANNEL);
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_sai_pcm5102.rs b/examples/rtic_sai_pcm5102.rs
@@ -135,7 +135,7 @@ mod app {
             pit.disable(POLL_LOG_CHANNEL);
         }
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_sai_sgtl5000.rs b/examples/rtic_sai_sgtl5000.rs
@@ -89,7 +89,7 @@ mod app {
             pit.disable(POLL_LOG_CHANNEL);
         }
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_usb_keypress.rs b/examples/rtic_usb_keypress.rs
@@ -8,9 +8,9 @@
 
 #[rtic::app(device = board, peripherals = false)]
 mod app {
-    use hal::usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
     use imxrt_hal as hal;
     use imxrt_hal::pit::Channel;
+    use imxrt_usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
 
     use usb_device::{
         bus::UsbBusAllocator,
@@ -88,7 +88,7 @@ mod app {
         let dma_a = dma[board::BOARD_DMA_A_INDEX].take().unwrap();
         let poller = board::logging::lpuart(FRONTEND, console, dma_a);
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_usb_mouse.rs b/examples/rtic_usb_mouse.rs
@@ -8,11 +8,11 @@
 
 #[rtic::app(device = board, peripherals = false)]
 mod app {
-    use hal::usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
     use imxrt_hal as hal;
     use imxrt_hal::pit::Channel;
 
     const PIT_CHANNEL: Channel = Channel::Chan0;
+    use imxrt_usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
 
     use usb_device::{
         bus::UsbBusAllocator,
@@ -83,7 +83,7 @@ mod app {
         let dma_a = dma[board::BOARD_DMA_A_INDEX].take().unwrap();
         let poller = board::logging::lpuart(FRONTEND, console, dma_a);
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_usb_serial.rs b/examples/rtic_usb_serial.rs
@@ -28,11 +28,11 @@
 
 #[rtic::app(device = board, peripherals = false)]
 mod app {
-    use hal::usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
     use imxrt_hal as hal;
     use imxrt_hal::pit::Channel;
 
     const PIT_CHANNEL: Channel = Channel::Chan0;
+    use imxrt_usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
 
     use usb_device::{
         bus::UsbBusAllocator,
@@ -96,7 +96,7 @@ mod app {
         let dma_a = dma[board::BOARD_DMA_A_INDEX].take().unwrap();
         let poller = board::logging::lpuart(FRONTEND, console, dma_a);
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/examples/rtic_usb_test_class.rs b/examples/rtic_usb_test_class.rs
@@ -21,11 +21,11 @@
 
 #[rtic::app(device = board, peripherals = false)]
 mod app {
-    use hal::usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
     use imxrt_hal as hal;
     use imxrt_hal::pit::Channel;
 
     const PIT_CHANNEL: Channel = Channel::Chan0;
+    use imxrt_usbd::{BusAdapter, EndpointMemory, EndpointState, Speed};
 
     use usb_device::{
         bus::UsbBusAllocator,
@@ -89,7 +89,7 @@ mod app {
         let dma_a = dma[board::BOARD_DMA_A_INDEX].take().unwrap();
         let poller = board::logging::lpuart(FRONTEND, console, dma_a);
 
-        let usbd = hal::usbd::Instances {
+        let usbd = imxrt_usbd::Instances {
             usb: usb1,
             usbnc: usbnc1,
             usbphy: usbphy1,
diff --git a/logging/CHANGELOG.md b/logging/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 **BREAKING** Integrate breaking dependencies for the USB back-end:
 
+- `imxrt-ral` 0.6
 - `imxrt-usbd` 0.3
 - `imxrt-hal` 0.6
 - `usb-device` 0.3
diff --git a/logging/src/defmt.rs b/logging/src/defmt.rs
@@ -178,11 +178,11 @@ unsafe impl defmt::Logger for Logger {
 ///
 /// See the crate-level documentation to understand how the USB device backend works.
 #[cfg(feature = "usbd")]
-pub fn usb_with_config<P: imxrt_usbd::Peripherals>(
-    peripherals: P,
+pub fn usb_with_config<const N: u8>(
+    peripherals: imxrt_usbd::Instances<N>,
     interrupts: super::Interrupts,
     backend_config: &crate::UsbdConfig,
-) -> Result<crate::Poller, crate::AlreadySetError<P>> {
+) -> Result<crate::Poller, crate::AlreadySetError<imxrt_usbd::Instances<N>>> {
     let (producer, consumer) = match crate::BUFFER.try_split() {
         Ok((prod, cons)) => (prod, cons),
         Err(_) => return Err(crate::AlreadySetError::new(peripherals)),
@@ -200,10 +200,10 @@ pub fn usb_with_config<P: imxrt_usbd::Peripherals>(
 /// This function uses default configurations for the backend.
 /// See the crate-level documentation to understand how the USB device backend works.
 #[cfg(feature = "usbd")]
-pub fn usbd<P: imxrt_usbd::Peripherals>(
-    peripherals: P,
+pub fn usbd<const N: u8>(
+    peripherals: imxrt_usbd::Instances<N>,
     interrupts: super::Interrupts,
-) -> Result<crate::Poller, crate::AlreadySetError<P>> {
+) -> Result<crate::Poller, crate::AlreadySetError<imxrt_usbd::Instances<N>>> {
     usb_with_config(
         peripherals,
         interrupts,
diff --git a/logging/src/lib.rs b/logging/src/lib.rs
@@ -161,7 +161,7 @@
 //! /// Returns `None` if any USB peripheral instance is taken,
 //! /// or if initialization fails.
 //! fn initialize_logger() -> Option<imxrt_log::Poller> {
-//!     let usb_instances = hal::usbd::Instances {
+//!     let usb_instances = imxrt_usbd::Instances {
 //!         usb: unsafe { ral::usb::USB1::instance() },
 //!         usbnc: unsafe { ral::usbnc::USBNC1::instance() },
 //!         usbphy: unsafe { ral::usbphy::USBPHY1::instance() },
diff --git a/logging/src/log.rs b/logging/src/log.rs
@@ -85,12 +85,12 @@ impl Default for LoggingConfig {
 ///
 /// See the crate-level documentation to understand how the USB device backend works.
 #[cfg(feature = "usbd")]
-pub fn usbd_with_config<P: imxrt_usbd::Peripherals>(
-    peripherals: P,
+pub fn usbd_with_config<const N: u8>(
+    peripherals: imxrt_usbd::Instances<N>,
     interrupts: super::Interrupts,
     frontend_config: &LoggingConfig,
     backend_config: &crate::UsbdConfig,
-) -> Result<Poller, crate::AlreadySetError<P>> {
+) -> Result<Poller, crate::AlreadySetError<imxrt_usbd::Instances<N>>> {
     let (producer, consumer) = match BUFFER.try_split() {
         Ok((prod, cons)) => (prod, cons),
         Err(_) => return Err(crate::AlreadySetError::new(peripherals)),
@@ -110,10 +110,10 @@ pub fn usbd_with_config<P: imxrt_usbd::Peripherals>(
 /// This function uses default configurations for the frontend and backend.
 /// See the crate-level documentation to understand how the USB device backend works.
 #[cfg(feature = "usbd")]
-pub fn usbd<P: imxrt_usbd::Peripherals>(
-    peripherals: P,
+pub fn usbd<const N: u8>(
+    peripherals: imxrt_usbd::Instances<N>,
     interrupts: super::Interrupts,
-) -> Result<Poller, crate::AlreadySetError<P>> {
+) -> Result<Poller, crate::AlreadySetError<imxrt_usbd::Instances<N>>> {
     usbd_with_config(
         peripherals,
         interrupts,
diff --git a/logging/src/usbd.rs b/logging/src/usbd.rs
@@ -124,8 +124,8 @@ impl Backend {
 /// # Panics
 ///
 /// Panics if called more than once.
-pub(crate) fn init<P: imxrt_usbd::Peripherals>(
-    peripherals: P,
+pub(crate) fn init<const N: u8>(
+    peripherals: imxrt_usbd::Instances<N>,
     interrupts: crate::Interrupts,
     consumer: super::Consumer,
     config: &UsbdConfig,
diff --git a/src/lib.rs b/src/lib.rs
@@ -205,78 +205,6 @@ pub mod dma {
     pub use crate::common::dma::*;
 }
 
-/// USB device.
-///
-/// This module re-exports types from the `imxrt-usbd` package. The driver is compatible
-///  with the [`usb-device`](https://docs.rs/usb-device/latest/usb_device/) ecosystem.
-///
-/// It also provides [`Instances`](crate::usbd::Instances), an implementation of `imxrt_usbd::Peripherals` over
-/// `imxrt-ral` USB instances.
-///
-/// # Example
-///
-/// Construct a [`BusAdapter`](crate::usbd::BusAdapter) with USB peripheral instances. See the
-/// [`BusAdapter`](crate::usbd::BusAdapter) documentation for more information on how to use the bus.
-///
-/// ```no_run
-/// use imxrt_hal as hal;
-/// use imxrt_ral as ral;
-///
-/// use hal::usbd;
-///
-/// # || -> Option<()> {
-/// let mut usb_analog = unsafe { ral::usb_analog::USB_ANALOG::instance() };
-/// let usb_instances = usbd::Instances {
-///     usb: unsafe { ral::usb::USB1::instance() },
-///     usbnc: unsafe { ral::usbnc::USBNC1::instance() },
-///     usbphy: unsafe { ral::usbphy::USBPHY1::instance() },
-/// };
-///
-/// // Prepare the USB clocks.
-/// let mut ccm_analog = unsafe { ral::ccm_analog::CCM_ANALOG::instance() };
-/// hal::ccm::analog::pll3::restart(&mut ccm_analog);
-///
-/// static ENDPOINT_MEMORY: usbd::EndpointMemory<2048> = usbd::EndpointMemory::new();
-/// static ENDPOINT_STATE: usbd::EndpointState = usbd::EndpointState::max_endpoints();
-///
-/// let usbd = usbd::BusAdapter::new(usb_instances, &ENDPOINT_MEMORY, &ENDPOINT_STATE);
-/// # Some(()) }().unwrap();
-/// ```
-#[cfg(feature = "imxrt-usbd")]
-pub mod usbd {
-    pub use imxrt_usbd::*;
-
-    use crate::ral;
-
-    /// Aggregate of `imxrt-ral` USB peripheral instances.
-    ///
-    /// This takes ownership of USB peripheral instances and implements
-    /// [`Peripherals`]. You can use this type to allocate a USB device
-    /// driver. See the [module-level documentation](crate::usbd) for an
-    /// example.
-    pub struct Instances<const N: u8> {
-        /// USB core registers.
-        pub usb: ral::usb::Instance<N>,
-        /// USB non-core registers.
-        pub usbnc: ral::usbnc::Instance<N>,
-        /// USBPHY registers.
-        pub usbphy: ral::usbphy::Instance<N>,
-    }
-
-    // Safety: pointers to USB peripheral blocks come from
-    // imxrt-ral, which provides correct addresses. We take
-    // ownership of the peripheral instances, preventing others
-    // from aliasing the peripherals.
-    unsafe impl<const N: u8> Peripherals for Instances<N> {
-        fn usb(&self) -> *const () {
-            (&*self.usb as *const ral::usb::RegisterBlock).cast()
-        }
-        fn usbphy(&self) -> *const () {
-            (&*self.usbphy as *const ral::usbphy::RegisterBlock).cast()
-        }
-    }
-}
-
 /// Pad muxing and configurations.
 ///
 /// This module re-exports select items from the `imxrt-iomuxc` crate. When a chip feature is enabled, the module also exports

Original file line number	Diff line number	Diff line change
`@@ -135,7 +135,7 @@ mod app {`
`135`	`135`	`pit.disable(POLL_LOG_CHANNEL);`
`136`	`136`	`}`
`137`	`137`
`138`		`- let usbd = hal::usbd::Instances {`
	`138`	`+ let usbd = imxrt_usbd::Instances {`
`139`	`139`	`usb: usb1,`
`140`	`140`	`usbnc: usbnc1,`
`141`	`141`	`usbphy: usbphy1,`
Original file line number	Diff line number	Diff line change
`@@ -89,7 +89,7 @@ mod app {`
`89`	`89`	`pit.disable(POLL_LOG_CHANNEL);`
`90`	`90`	`}`
`91`	`91`
`92`		`- let usbd = hal::usbd::Instances {`
	`92`	`+ let usbd = imxrt_usbd::Instances {`
`93`	`93`	`usb: usb1,`
`94`	`94`	`usbnc: usbnc1,`
`95`	`95`	`usbphy: usbphy1,`