Merge remote-tracking branch 'origin/master' into feature/alternate-settings

Author: ryan-summers

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+on:
+  push:
+    branches: [ staging, trying, master ]
+  pull_request:
+
+name: CI
+
+jobs:
+  ci-linux:
+    name: CI
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        rust: [stable]
+
+        include:
+          # Test nightly but don't fail
+          - rust: nightly
+            experimental: true
+            TARGET: x86_64-unknown-linux-gnu
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ matrix.rust }}
+          target: ${{ matrix.TARGET }}
+          override: true
+
+      - name: Install libusb library
+        run: sudo apt-get install -y libusb-1.0.0-dev
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+          args: --all-targets
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+          args: --features control-buffer-256
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+          args: --features defmt

.github/workflows/rustfmt.yml

@@ -0,0 +1,23 @@
+on:
+  push:
+    branches: [ staging, trying, master ]
+  pull_request:
+
+name: Code formatting check
+
+jobs:
+  fmt:
+    name: Rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+          components: rustfmt
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all -- --check

.travis.yml

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### Added
+* New enums and allocators for Isochronous endpoints
+* Added support for alternate settings on interfaces
+
+### Changed
+* `EndpointType` enum now has fields for isochronous synchronization and usage.
+
+## [0.2.9] - 2022-08-02
+
+### Fixed
+* Fixed an issue where USB devices were not enumerating on Windows ([#32](https://github.com/rust-embedded-community/usb-device/issues/82))
+* Add optional support for defmt ([#76](https://github.com/rust-embedded-community/usb-device/pull/76))
+* Fixed Suspend state transition so it goes back to the previous state, not just Default ([#97](https://github.com/rust-embedded-community/usb-device/pull/97))
+
+## [0.2.8] - 2021-03-13
+
+## [0.2.7] - 2020-10-03
+
+## [0.2.6] - 2020-09-22
+
+## [0.2.5] - 2020-02-10
+
+## [0.2.4] - 2020-02-01
+
+## [0.2.3] - 2019-08-28
+
+## [0.2.2] - 2019-07-27
+
+## [0.2.1] - 2019-06-07
+
+## [0.2.0] - 2019-06-07
+
+## 0.1.0 - 2019-06-07
+
+This is the initial release to crates.io.
+
+[Unreleased]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.9...HEAD
+[0.2.9]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.8...v0.2.9
+[0.2.8]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.7...v0.2.8
+[0.2.7]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.6...v0.2.7
+[0.2.6]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/rust-embedded-community/usb-device/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/rust-embedded-community/usb-device/compare/v0.1.0...v0.2.0

CHANGELOG.md

@@ -9,9 +9,12 @@ license = "MIT"
 authors = ["Matti Virkkunen <[email protected]>"]
 repository = "https://github.com/mvirkkunen/usb-device"
 
+[dependencies]
+defmt = { version = "0.3", optional = true }
+
 [dev-dependencies]
-rusb = "0.8.0"
-rand = "0.6.1"
+rusb = "0.9.1"
+rand = "0.8.5"
 
 [features]
 # Use a 256 byte buffer for control transfers instead of 128.

Cargo.toml

@@ -20,17 +20,26 @@ each device's USB peripheral.
 Hardware driver crates
 ----------------------
 
-* [stm32-usbd](https://github.com/stm32-rs/stm32-usbd) - device-driver implementation for multiple STM32 microcontroller families.
-  Examples can be found in each individual HAL crate that implements the USB peripheral.
+* [atsam4](https://github.com/atsam-rs/atsam4-hal) - device-driver implementation for atsam4e & atsam4s microcontrollers (UDP). Examples can be found [here](https://github.com/atsam-rs/sam_xplained). While not expressly supported with this crate, atsam3s and atsam55g could also be supported with a similar code-base.
 
 * [atsamd](https://github.com/atsamd-rs/atsamd) - device-driver implementation for samd21 & samd51 microcontrollers. An example for the
   itsybitsy_m4 board from Adafruit can be found [here](https://github.com/atsamd-rs/atsamd/blob/master/boards/itsybitsy_m4/examples/usb_serial.rs).
 
 * [imxrt-usbd](https://github.com/imxrt-rs/imxrt-usbd) - device-driver implementation for NXP i.MX RT microcontrollers. Examples for
   i.MX RT boards, like the Teensy 4, are maintained with the driver.
 
+* [stm32-usbd](https://github.com/stm32-rs/stm32-usbd) - device-driver implementation for multiple STM32 microcontroller families.
+  Examples can be found in each individual HAL crate that implements the USB peripheral.
+
 Class crates
 ------------
 
-* [usbd-serial](https://github.com/mvirkkunen/usbd-serial) [![Crates.io](https://img.shields.io/crates/v/usbd-serial.svg)](https://crates.io/crates/usbd-serial) - CDC-ACM serial port class
 * [usbd-hid](https://github.com/twitchyliquid64/usbd-hid) [![Crates.io](https://img.shields.io/crates/v/usbd-hid.svg)](https://crates.io/crates/usbd-hid) - HID class
+* [usbd-serial](https://github.com/mvirkkunen/usbd-serial) [![Crates.io](https://img.shields.io/crates/v/usbd-serial.svg)](https://crates.io/crates/usbd-serial) - CDC-ACM serial port class
+
+
+Others
+------
+
+Other implementations for USB in Rust
+* The [Embassy](https://github.com/embassy-rs/embassy) project has an async USB stack, embassy-usb.

README.md

@@ -1,4 +1,7 @@
-use crate::endpoint::{Endpoint, EndpointAddress, EndpointDirection, EndpointType};
+use crate::endpoint::{
+    Endpoint, EndpointAddress, EndpointDirection, EndpointType, IsochronousSynchronizationType,
+    IsochronousUsageType,
+};
 use crate::{Result, UsbDirection, UsbError};
 use core::cell::RefCell;
 use core::mem;
@@ -211,7 +214,7 @@ impl<B: UsbBus> UsbBusAllocator<B> {
     ///
     /// This directly delegates to [`UsbBus::alloc_ep`], so see that method for details. In most
     /// cases classes should call the endpoint type specific methods instead.
-    pub fn alloc<'a, D: EndpointDirection>(
+    pub fn alloc<D: EndpointDirection>(
         &self,
         ep_addr: Option<EndpointAddress>,
         ep_type: EndpointType,
@@ -244,6 +247,41 @@ impl<B: UsbBus> UsbBusAllocator<B> {
             .expect("alloc_ep failed")
     }
 
+    /// Allocates an isochronous endpoint.
+    ///
+    /// # Arguments
+    ///
+    /// * `synchronization` - Type of synchronization used by the endpoint
+    /// * `usage` - Whether the endpoint is data, explicit feedback, or data+implicit feedback
+    /// * `payload_size` - Payload size in bytes.
+    /// * `interval` - Interval for polling, expressed in frames/microframes.
+    ///
+    /// See USB 2.0 section 9.6.6.
+    ///
+    /// # Panics
+    ///
+    /// Panics if endpoint allocation fails, because running out of endpoints or memory is not
+    /// feasibly recoverable.
+    #[inline]
+    pub fn isochronous<D: EndpointDirection>(
+        &self,
+        synchronization: IsochronousSynchronizationType,
+        usage: IsochronousUsageType,
+        payload_size: u16,
+        interval: u8,
+    ) -> Endpoint<'_, B, D> {
+        self.alloc(
+            None,
+            EndpointType::Isochronous {
+                synchronization,
+                usage,
+            },
+            payload_size,
+            interval,
+        )
+        .expect("alloc_ep failed")
+    }
+
     /// Allocates a bulk endpoint.
     ///
     /// # Arguments
@@ -263,6 +301,7 @@ impl<B: UsbBus> UsbBusAllocator<B> {
     /// Allocates an interrupt endpoint.
     ///
     /// * `max_packet_size` - Maximum packet size in bytes. Cannot exceed 64 bytes.
+    /// * `interval` - Polling interval.
     ///
     /// # Panics
     ///
@@ -281,6 +320,7 @@ impl<B: UsbBus> UsbBusAllocator<B> {
 
 /// A handle for a USB interface that contains its number.
 #[derive(Copy, Clone, Eq, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct InterfaceNumber(pub(crate) u8);
 
 impl From<InterfaceNumber> for u8 {
@@ -291,6 +331,7 @@ impl From<InterfaceNumber> for u8 {
 
 /// A handle for a USB string descriptor that contains its index.
 #[derive(Copy, Clone, Eq, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct StringIndex(u8);
 
 impl StringIndex {

src/bus.rs

@@ -4,6 +4,7 @@ use core::mem;
 /// Control request type.
 #[repr(u8)]
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum RequestType {
     /// Request is a USB standard request. Usually handled by
     /// [`UsbDevice`](crate::device::UsbDevice).
@@ -18,6 +19,7 @@ pub enum RequestType {
 
 /// Control request recipient.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Recipient {
     /// Request is intended for the entire device.
     Device = 0,
@@ -35,6 +37,7 @@ pub enum Recipient {
 
 /// A control request read from a SETUP packet.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Request {
     /// Direction of the request.
     pub direction: UsbDirection,

src/control.rs

@@ -5,6 +5,7 @@ use crate::{Result, UsbDirection, UsbError};
 use core::cmp::min;
 
 #[derive(Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[allow(unused)]
 enum ControlState {
     Idle,
@@ -51,10 +52,10 @@ impl<B: UsbBus> ControlPipe<'_, B> {
     }
 
     pub fn waiting_for_response(&self) -> bool {
-        match self.state {
-            ControlState::CompleteOut | ControlState::CompleteIn(_) => true,
-            _ => false,
-        }
+        matches!(
+            self.state,
+            ControlState::CompleteOut | ControlState::CompleteIn(_)
+        )
     }
 
     pub fn data(&self) -> &[u8] {
@@ -65,7 +66,7 @@ impl<B: UsbBus> ControlPipe<'_, B> {
         self.state = ControlState::Idle;
     }
 
-    pub fn handle_setup<'p>(&'p mut self) -> Option<Request> {
+    pub fn handle_setup(&mut self) -> Option<Request> {
         let count = match self.ep_out.read(&mut self.buf[..]) {
             Ok(count) => count,
             Err(UsbError::WouldBlock) => return None,
@@ -122,10 +123,10 @@ impl<B: UsbBus> ControlPipe<'_, B> {
             return Some(req);
         }
 
-        return None;
+        None
     }
 
-    pub fn handle_out<'p>(&'p mut self) -> Option<Request> {
+    pub fn handle_out(&mut self) -> Option<Request> {
         match self.state {
             ControlState::DataOut(req) => {
                 let i = self.i;
@@ -147,7 +148,12 @@ impl<B: UsbBus> ControlPipe<'_, B> {
                     return Some(req);
                 }
             }
-            ControlState::StatusOut => {
+            // The host may terminate a DATA stage early by sending a zero-length status packet
+            // acknowledging the data we sent it.
+            ControlState::DataIn
+            | ControlState::DataInLast
+            | ControlState::DataInZlp
+            | ControlState::StatusOut => {
                 self.ep_out.read(&mut []).ok();
                 self.state = ControlState::Idle;
             }
@@ -160,7 +166,7 @@ impl<B: UsbBus> ControlPipe<'_, B> {
             }
         }
 
-        return None;
+        None
     }
 
     pub fn handle_in_complete(&mut self) -> bool {
@@ -191,7 +197,7 @@ impl<B: UsbBus> ControlPipe<'_, B> {
             }
         };
 
-        return false;
+        false
     }
 
     fn write_in_chunk(&mut self) {