Redesign transfer / endpoint API

Author: kevinmehall

Cargo.toml

@@ -22,7 +22,7 @@ env_logger = "0.10.0"
 futures-lite = "1.13.0"
 
 [target.'cfg(any(target_os="linux", target_os="android"))'.dependencies]
-rustix = { version = "0.38.17", features = ["fs", "event", "net"] }
+rustix = { version = "0.38.17", features = ["fs", "event", "net", "time"] }
 libc = "0.2.155"
 
 [target.'cfg(target_os="windows")'.dependencies]

examples/blocking.rs

@@ -1,5 +1,8 @@
 use futures_lite::future::block_on;
-use nusb::{transfer::RequestBuffer, MaybeFuture};
+use nusb::{
+    transfer::{Bulk, In, Out},
+    MaybeFuture,
+};
 
 fn main() {
     env_logger::init();
@@ -13,20 +16,22 @@ fn main() {
 
     let device = di.open().wait().unwrap();
     let interface = device.claim_interface(0).wait().unwrap();
+    let mut ep_out = interface.endpoint::<Bulk, Out>(0x02).unwrap();
+    let mut ep_in = interface.endpoint::<Bulk, In>(0x81).unwrap();
 
-    block_on(interface.bulk_out(0x02, Vec::from([1, 2, 3, 4, 5])))
-        .into_result()
-        .unwrap();
-
-    let mut queue = interface.bulk_in_queue(0x81);
+    let mut transfer = ep_out.allocate(64);
+    transfer.extend_from_slice(&[1, 2, 3, 4, 5]);
+    ep_out.submit(transfer);
+    block_on(ep_out.next_complete()).status().unwrap();
 
     loop {
-        while queue.pending() < 8 {
-            queue.submit(RequestBuffer::new(256));
+        while ep_in.pending() < 8 {
+            let transfer = ep_in.allocate(256);
+            ep_in.submit(transfer);
         }
-        let result = block_on(queue.next_complete());
+        let result = block_on(ep_in.next_complete());
         println!("{result:?}");
-        if result.status.is_err() {
+        if result.status().is_err() {
             break;
         }
     }

examples/bulk.rs

@@ -1,4 +1,5 @@
-use futures_lite::future::block_on;
+use std::time::Duration;
+
 use nusb::{
     transfer::{ControlIn, ControlOut, ControlType, Recipient},
     MaybeFuture,
@@ -19,47 +20,67 @@ fn main() {
     // Linux can make control transfers without claiming an interface
     #[cfg(any(target_os = "linux", target_os = "macos"))]
     {
-        let result = block_on(device.control_out(ControlOut {
-            control_type: ControlType::Vendor,
-            recipient: Recipient::Device,
-            request: 0x81,
-            value: 0x9999,
-            index: 0x9999,
-            data: &[1, 2, 3, 4],
-        }));
+        let result = device
+            .control_out(
+                ControlOut {
+                    control_type: ControlType::Vendor,
+                    recipient: Recipient::Device,
+                    request: 0x81,
+                    value: 0x9999,
+                    index: 0x9999,
+                    data: &[1, 2, 3, 4],
+                },
+                Duration::from_millis(100),
+            )
+            .wait();
         println!("{result:?}");
 
-        let result = block_on(device.control_in(ControlIn {
-            control_type: ControlType::Vendor,
-            recipient: Recipient::Device,
-            request: 0x81,
-            value: 0x9999,
-            index: 0x9999,
-            length: 256,
-        }));
+        let result = device
+            .control_in(
+                ControlIn {
+                    control_type: ControlType::Vendor,
+                    recipient: Recipient::Device,
+                    request: 0x81,
+                    value: 0x9999,
+                    index: 0x9999,
+                    length: 256,
+                },
+                Duration::from_millis(100),
+            )
+            .wait();
         println!("{result:?}");
     }
 
     // but we also provide an API on the `Interface` to support Windows
     let interface = device.claim_interface(0).wait().unwrap();
 
-    let result = block_on(interface.control_out(ControlOut {
-        control_type: ControlType::Vendor,
-        recipient: Recipient::Device,
-        request: 0x81,
-        value: 0x9999,
-        index: 0x9999,
-        data: &[1, 2, 3, 4],
-    }));
+    let result = interface
+        .control_out(
+            ControlOut {
+                control_type: ControlType::Vendor,
+                recipient: Recipient::Device,
+                request: 0x81,
+                value: 0x9999,
+                index: 0x9999,
+                data: &[1, 2, 3, 4],
+            },
+            Duration::from_millis(100),
+        )
+        .wait();
     println!("{result:?}");
 
-    let result = block_on(interface.control_in(ControlIn {
-        control_type: ControlType::Vendor,
-        recipient: Recipient::Device,
-        request: 0x81,
-        value: 0x9999,
-        index: 0x9999,
-        length: 256,
-    }));
+    let result = interface
+        .control_in(
+            ControlIn {
+                control_type: ControlType::Vendor,
+                recipient: Recipient::Device,
+                request: 0x81,
+                value: 0x9999,
+                index: 0x9999,
+                length: 256,
+            },
+            Duration::from_millis(100),
+        )
+        .wait();
     println!("{result:?}");
 }

examples/control.rs

@@ -33,24 +33,31 @@ fn inspect_device(dev: DeviceInfo) {
 
     let languages: Vec<u16> = dev
         .get_string_descriptor_supported_languages(timeout)
+        .wait()
         .map(|i| i.collect())
         .unwrap_or_default();
     println!("  Languages: {languages:02x?}");
 
     let language = languages.first().copied().unwrap_or(US_ENGLISH);
 
     if let Some(i_manufacturer) = dev_descriptor.manufacturer_string_index() {
-        let s = dev.get_string_descriptor(i_manufacturer, language, timeout);
+        let s = dev
+            .get_string_descriptor(i_manufacturer, language, timeout)
+            .wait();
         println!("  Manufacturer({i_manufacturer}): {s:?}");
     }
 
     if let Some(i_product) = dev_descriptor.product_string_index() {
-        let s = dev.get_string_descriptor(i_product, language, timeout);
+        let s = dev
+            .get_string_descriptor(i_product, language, timeout)
+            .wait();
         println!("  Product({i_product}): {s:?}");
     }
 
     if let Some(i_serial) = dev_descriptor.serial_number_string_index() {
-        let s = dev.get_string_descriptor(i_serial, language, timeout);
+        let s = dev
+            .get_string_descriptor(i_serial, language, timeout)
+            .wait();
         println!("  Serial({i_serial}): {s:?}");
     }
 

examples/string_descriptors.rs

@@ -0,0 +1,26 @@
+/// Bitset capable of storing 0x00..=0x0f and 0x80..=0x8f
+#[derive(Default, Clone, Copy)]
+pub struct EndpointBitSet(u32);
+
+impl EndpointBitSet {
+    pub fn mask(ep: u8) -> u32 {
+        let bit = ((ep & 0x0f) << 1) | (ep >> 7);
+        1 << bit
+    }
+
+    pub fn is_set(&self, bit: u8) -> bool {
+        self.0 & Self::mask(bit) != 0
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0 == 0
+    }
+
+    pub fn set(&mut self, bit: u8) {
+        self.0 |= Self::mask(bit)
+    }
+
+    pub fn clear(&mut self, bit: u8) {
+        self.0 &= !Self::mask(bit)
+    }
+}

src/bitset.rs

@@ -13,10 +13,7 @@ use std::{
 
 use log::warn;
 
-use crate::{
-    transfer::{Direction, TransferType},
-    Error,
-};
+use crate::{transfer::Direction, Error};
 
 pub(crate) const DESCRIPTOR_TYPE_DEVICE: u8 = 0x01;
 pub(crate) const DESCRIPTOR_LEN_DEVICE: u8 = 18;
@@ -696,6 +693,23 @@ impl<'a> Debug for EndpointDescriptor<'a> {
     }
 }
 
+/// Endpoint type.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[allow(dead_code)]
+pub enum TransferType {
+    /// Control endpoint.
+    Control = 0,
+
+    /// Isochronous endpoint.
+    Isochronous = 1,
+
+    /// Bulk endpoint.
+    Bulk = 2,
+
+    /// Interrupt endpoint.
+    Interrupt = 3,
+}
+
 /// Error from [`crate::Device::active_configuration`]
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct ActiveConfigurationError {