Constructing the control pipe from a user-provided buffer

Author: ryan-summers

CHANGELOG.md

@@ -16,6 +16,8 @@ interface.
 as this was not intended to be used in the public API.
     - If this is problematic, please open an issue in the main `usb-device` repository.
 * Changed handling of EP0 state to eliminate unexpected issues with device enumeration
+* [breaking] The control pipe is now provided in the `UsbDeviceBuilder` API to allow for user-provided control
+pipes. This makes it so that control pipes have configurable sizing.
 
 ## [0.3.1] - 2023-11-15
 

Cargo.toml

@@ -20,8 +20,6 @@ rusb = "0.9.1"
 rand = "0.8.5"
 
 [features]
-# Use a 256 byte buffer for control transfers instead of 128.
-control-buffer-256 = []
 
 # Enable logging and tracing via the `log` crate
 log = ["dep:log"]

src/control_pipe.rs

@@ -20,31 +20,28 @@ enum ControlState {
     Error,
 }
 
-// Maximum length of control transfer data stage in bytes. 128 bytes by default. You can define the
-// feature "control-buffer-256" to make it 256 bytes if you have larger control transfers.
-#[cfg(not(feature = "control-buffer-256"))]
-const CONTROL_BUF_LEN: usize = 128;
-#[cfg(feature = "control-buffer-256")]
-const CONTROL_BUF_LEN: usize = 256;
-
 /// Buffers and parses USB control transfers.
 pub struct ControlPipe<'a, B: UsbBus> {
     ep_out: EndpointOut<'a, B>,
     ep_in: EndpointIn<'a, B>,
     state: ControlState,
-    buf: [u8; CONTROL_BUF_LEN],
+    buf: &'a mut [u8],
     static_in_buf: Option<&'static [u8]>,
     i: usize,
     len: usize,
 }
 
 impl<B: UsbBus> ControlPipe<'_, B> {
-    pub fn new<'a>(ep_out: EndpointOut<'a, B>, ep_in: EndpointIn<'a, B>) -> ControlPipe<'a, B> {
+    pub fn new<'a>(
+        buf: &'a mut [u8],
+        ep_out: EndpointOut<'a, B>,
+        ep_in: EndpointIn<'a, B>,
+    ) -> ControlPipe<'a, B> {
         ControlPipe {
             ep_out,
             ep_in,
             state: ControlState::Idle,
-            buf: [0; CONTROL_BUF_LEN],
+            buf,
             static_in_buf: None,
             i: 0,
             len: 0,

src/device.rs

@@ -82,7 +82,11 @@ pub const DEFAULT_ALTERNATE_SETTING: u8 = 0;
 type ClassList<'a, B> = [&'a mut dyn UsbClass<B>];
 
 impl<B: UsbBus> UsbDevice<'_, B> {
-    pub(crate) fn build<'a>(alloc: &'a UsbBusAllocator<B>, config: Config<'a>) -> UsbDevice<'a, B> {
+    pub(crate) fn build<'a>(
+        alloc: &'a UsbBusAllocator<B>,
+        config: Config<'a>,
+        control_buffer: &'a mut [u8],
+    ) -> UsbDevice<'a, B> {
         let control_out = alloc
             .alloc(
                 Some(0x00.into()),
@@ -106,7 +110,7 @@ impl<B: UsbBus> UsbDevice<'_, B> {
         UsbDevice {
             bus,
             config,
-            control: ControlPipe::new(control_out, control_in),
+            control: ControlPipe::new(control_buffer, control_out, control_in),
             device_state: UsbDeviceState::Default,
             remote_wakeup_enabled: false,
             self_powered: false,

src/device_builder.rs

@@ -8,6 +8,7 @@ pub struct UsbVidPid(pub u16, pub u16);
 /// Used to build new [`UsbDevice`]s.
 pub struct UsbDeviceBuilder<'a, B: UsbBus> {
     alloc: &'a UsbBusAllocator<B>,
+    control_buffer: &'a mut [u8],
     config: Config<'a>,
 }
 
@@ -82,9 +83,14 @@ impl<'a> StringDescriptors<'a> {
 
 impl<'a, B: UsbBus> UsbDeviceBuilder<'a, B> {
     /// Creates a builder for constructing a new [`UsbDevice`].
-    pub fn new(alloc: &'a UsbBusAllocator<B>, vid_pid: UsbVidPid) -> UsbDeviceBuilder<'a, B> {
+    pub fn new(
+        alloc: &'a UsbBusAllocator<B>,
+        vid_pid: UsbVidPid,
+        control_buffer: &'a mut [u8],
+    ) -> UsbDeviceBuilder<'a, B> {
         UsbDeviceBuilder {
             alloc,
+            control_buffer,
             config: Config {
                 device_class: 0x00,
                 device_sub_class: 0x00,
@@ -105,7 +111,7 @@ impl<'a, B: UsbBus> UsbDeviceBuilder<'a, B> {
 
     /// Creates the [`UsbDevice`] instance with the configuration in this builder.
     pub fn build(self) -> UsbDevice<'a, B> {
-        UsbDevice::build(self.alloc, self.config)
+        UsbDevice::build(self.alloc, self.config, self.control_buffer)
     }
 
     builder_fields! {

src/lib.rs

@@ -137,6 +137,8 @@ pub mod endpoint;
 /// use usb_device::prelude::*;
 /// use usb_serial; // example class crate (not included)
 ///
+/// static mut CONTROL_BUFFER: [u8; 128] = [0; 128];
+///
 /// // Create the device-specific USB peripheral driver. The exact name and arguments are device
 /// // specific, so check the documentation for your device driver crate.
 /// let usb_bus = device_specific_usb::UsbBus::new(...);
@@ -151,7 +153,7 @@ pub mod endpoint;
 /// // pair. Additional builder arguments can specify parameters such as device class code or
 /// // product name. If using an existing class, remember to check the class crate documentation
 /// // for correct values.
-/// let mut usb_dev = UsbDeviceBuilder::new(&usb_bus, UsbVidPid(0x5824, 0x27dd))
+/// let mut usb_dev = UsbDeviceBuilder::new(&usb_bus, UsbVidPid(0x5824, 0x27dd), unsafe { &mut CONTROL_BUFFER })
 ///     .strings(&[StringDescriptors::new(LangID::EN)
 ///         .product("Serial port")])
 ///         .expect("Failed to set strings")

src/test_class.rs

@@ -22,6 +22,8 @@ mod sizes {
     pub const INTERRUPT_ENDPOINT: u16 = 31;
 }
 
+static mut CONTROL_BUFFER: [u8; 256] = [0; 256];
+
 /// Test USB class for testing USB driver implementations. Supports various endpoint types and
 /// requests for testing USB peripheral drivers on actual hardware.
 pub struct TestClass<'a, B: UsbBus> {
@@ -112,7 +114,7 @@ impl<B: UsbBus> TestClass<'_, B> {
         &self,
         usb_bus: &'a UsbBusAllocator<B>,
     ) -> UsbDeviceBuilder<'a, B> {
-        UsbDeviceBuilder::new(usb_bus, UsbVidPid(VID, PID))
+        UsbDeviceBuilder::new(usb_bus, UsbVidPid(VID, PID), unsafe { &mut CONTROL_BUFFER })
             .strings(&[StringDescriptors::default()
                 .manufacturer(MANUFACTURER)
                 .product(PRODUCT)