Initial commit

Author: mvirkkunen

.gitignore

@@ -0,0 +1,2 @@
+target/
+Cargo.lock

Cargo.toml

@@ -0,0 +1,4 @@
+[package]
+name = "usb-device"
+version = "0.1.0"
+authors = ["Matti Virkkunen <[email protected]>"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Matti Virkkunen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,49 @@
+usb-device
+==========
+
+Experimental device-side USB framework for microcontrollers in Rust.
+
+This crate is still under development and should not be considered production ready or even USB
+compliant.
+
+The UsbDevice object represents a composite USB device and is the most important object for
+end-users. Most of the other items are for implementing new USB classes or device-specific drivers.
+
+The UsbClass trait can be used to implemented USB classes such as HID devices or serial ports.
+Pre-made class implementations will be provided in separate crates.
+
+The UsbBus trait is intended to be implemented by device-specific crates to provide a driver for
+each device specific USB peripheral.
+
+Related crates
+--------------
+
+* [stm32f103xx-usb](https://github.com/mvirkkunen/stm32f103xx-usb) - device-driver implementation
+  for STM32F103 microcontrollers. Also contains runnable examples.
+
+TODO
+----
+
+Features planned but not implemented yet:
+
+- Documentation
+- Detecting bus state (connected/not connected)
+- Suspend and resume
+- Interface alternate settings
+- A safer DescriptorWriter
+- Extra string descriptors
+- Multilingual string descriptors
+- Isochronous endpoints
+- Standard requests
+  - GET_STATUS
+  - CLEAR_FEATURE
+  - SET_FEATURE
+  - GET_CONFIGURATION
+  - SYNCH_FRAME
+- Optimize interrupt driven operation (maybe UsbDevice::poll should return which device has data
+  available)
+
+Features not planning to support at the moment:
+
+- More than one configuration descriptor
+- Control transfers on other than endpoint 0

src/bus.rs

@@ -0,0 +1,137 @@
+use ::Result;
+
+pub trait UsbBus {
+    fn enable(&self);
+    fn reset(&self);
+    fn configure_ep(&self, ep_addr: u8, ep_type: EndpointType, max_packet_size: u16) -> Result<()>;
+    fn set_device_address(&self, addr: u8);
+    fn write(&self, ep_addr: u8, buf: &[u8]) -> Result<usize>;
+    fn read(&self, ep_addr: u8, buf: &mut [u8]) -> Result<usize>;
+    fn stall(&self, ep_addr: u8);
+    fn unstall(&self, ep_addr: u8);
+    fn poll(&self) -> PollResult;
+}
+
+#[repr(u8)]
+#[derive(Copy, Clone, Debug)]
+pub enum EndpointType {
+    Control = 0b00,
+    Isochronous = 0b01,
+    Bulk = 0b10,
+    Interrupt = 0b11,
+}
+
+// bEndpointAddress:
+// D7: Direction 0 = OUT, 1 = IN
+
+pub struct EndpointPair<'a, B: 'a + UsbBus> {
+    bus: &'a B,
+    address: u8,
+}
+
+impl<'a, B: UsbBus> EndpointPair<'a, B> {
+    pub fn new(bus: &'a B, address: u8) -> EndpointPair<'a, B> {
+        EndpointPair { bus, address }
+    }
+
+    pub fn split(self, ep_type: EndpointType, max_packet_size: u16) -> (EndpointOut<'a, B>, EndpointIn<'a, B>) {
+        let ep_out = EndpointOut {
+            bus: self.bus,
+            address: self.address,
+            ep_type: ep_type,
+            max_packet_size,
+            interval: 1,
+        };
+
+        let ep_in = EndpointIn {
+            bus: self.bus,
+            address: self.address | 0x80,
+            ep_type: ep_type,
+            max_packet_size,
+            interval: 1,
+        };
+
+        (ep_out, ep_in)
+    }
+}
+
+pub trait Endpoint {
+    fn address(&self) -> u8;
+    fn ep_type(&self) -> EndpointType;
+    fn max_packet_size(&self) -> u16;
+    fn interval(&self) -> u8;
+}
+
+pub struct EndpointOut<'a, B: 'a + UsbBus> {
+    bus: &'a B,
+    address: u8,
+    ep_type: EndpointType,
+    max_packet_size: u16,
+    interval: u8,
+}
+
+impl<'a, B: UsbBus> EndpointOut<'a, B> {
+    pub fn configure(&self) -> Result<()> {
+        self.bus.configure_ep(self.address, self.ep_type, self.max_packet_size)
+    }
+
+    pub fn read(&self, data: &mut [u8]) -> Result<usize> {
+        self.bus.read(self.address, data)
+    }
+
+    pub fn stall(&self) {
+        self.bus.stall(self.address);
+    }
+
+    pub fn unstall(&self) {
+        self.bus.unstall(self.address);
+    }
+}
+
+impl<'a, B: UsbBus> Endpoint for EndpointOut<'a, B> {
+    fn address(&self) -> u8 { self.address }
+    fn ep_type(&self) -> EndpointType { self.ep_type }
+    fn max_packet_size(&self) -> u16 { self.max_packet_size }
+    fn interval(&self) -> u8 { self.interval }
+}
+
+pub struct EndpointIn<'a, B: 'a + UsbBus> {
+    bus: &'a B,
+    address: u8,
+    ep_type: EndpointType,
+    max_packet_size: u16,
+    interval: u8,
+}
+
+impl<'a, B: UsbBus> EndpointIn<'a, B> {
+    pub fn configure(&self) -> Result<()> {
+        self.bus.configure_ep(self.address, self.ep_type, self.max_packet_size)
+    }
+
+    pub fn write(&self, data: &[u8]) -> Result<usize> {
+        self.bus.write(self.address, data)
+    }
+
+    pub fn stall(&self) {
+        self.bus.stall(self.address);
+    }
+
+    pub fn unstall(&self) {
+        self.bus.unstall(self.address);
+    }
+}
+
+impl<'a, B: UsbBus> Endpoint for EndpointIn<'a, B> {
+    fn address(&self) -> u8 { self.address }
+    fn ep_type(&self) -> EndpointType { self.ep_type }
+    fn max_packet_size(&self) -> u16 { self.max_packet_size }
+    fn interval(&self) -> u8 { self.interval }
+}
+
+#[derive(Default)]
+pub struct PollResult {
+    pub reset: bool,
+    pub setup: bool,
+    pub ep_in_complete: u16,
+    pub ep_out: u16,
+}

src/class.rs

@@ -0,0 +1,33 @@
+use ::Result;
+pub use device::{ControlOutResult, ControlInResult};
+pub use descriptor::DescriptorWriter;
+use control;
+
+pub trait UsbClass {
+    fn reset(&self) -> Result<()> {
+        Ok(())
+    }
+
+    fn get_configuration_descriptors(&self, writer: &mut DescriptorWriter) -> Result<()> {
+        let _ = writer;
+        Ok (())
+    }
+
+    fn control_out(&self, req: &control::Request, data: &[u8]) -> ControlOutResult {
+        let _ = (req, data);
+        ControlOutResult::Ignore
+    }
+
+    fn control_in(&self, req: &control::Request, data: &mut [u8]) -> ControlInResult {
+        let _ = (req, data);
+        ControlInResult::Ignore
+    }
+
+    fn endpoint_out(&self, addr: u8) {
+        let _ = addr;
+    }
+
+    fn endpoint_in_complete(&self, addr: u8) {
+        let _ = addr;
+    }
+}

src/control.rs

@@ -0,0 +1,81 @@
+use core::mem;
+use ::{Result, UsbError};
+
+#[repr(u8)]
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+pub enum Direction {
+    HostToDevice = 0,
+    DeviceToHost = 1,
+}
+
+#[repr(u8)]
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+pub enum RequestType {
+    Standard = 0,
+    Class = 1,
+    Vendor = 2,
+    Reserved = 3,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+pub enum Recipient {
+    Device = 0,
+    Interface = 1,
+    Endpoint = 2,
+    Other = 3,
+    Reserved = 4,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+pub struct Request {
+    pub direction: Direction,
+    pub request_type: RequestType,
+    pub recipient: Recipient,
+    pub request: u8,
+    pub value: u16,
+    pub index: u16,
+    pub length: u16,
+}
+
+impl Request {
+    pub(crate) fn parse(buf: &[u8]) -> Result<Request> {
+        if buf.len() != 8 {
+            return Err(UsbError::InvalidSetupPacket);
+        }
+
+        let rt = buf[0];
+        let recipient = rt & 0b11111;
+
+        Ok(Request {
+            direction: unsafe { mem::transmute(rt >> 7) },
+            request_type: unsafe { mem::transmute((rt >> 5) & 0b11) },
+            recipient:
+                if recipient <= 3 { unsafe { mem::transmute(recipient) } }
+                else { Recipient::Reserved },
+            request: buf[1],
+            value: (buf[2] as u16) | ((buf[3] as u16) << 8),
+            index: (buf[4] as u16) | ((buf[5] as u16) << 8),
+            length: (buf[6] as u16) | ((buf[7] as u16) << 8),
+        })
+    }
+
+    pub fn descriptor_type_index(&self) -> (u8, u8) {
+        ((self.value >> 8) as u8, self.value as u8)
+    }
+}
+
+// TODO: Maybe move parsing standard requests here altogether
+
+pub mod standard_request {
+    pub const GET_STATUS: u8 = 0;
+    pub const CLEAR_FEATURE: u8 = 1;
+    pub const SET_FEATURE: u8 = 3;
+    pub const SET_ADDRESS: u8 = 5;
+    pub const GET_DESCRIPTOR: u8 = 6;
+    pub const SET_DESCRIPTOR: u8 = 7;
+    pub const GET_CONFIGURATION: u8 = 8;
+    pub const SET_CONFIGURATION: u8 = 9;
+    pub const GET_INTERFACE: u8 = 10;
+    pub const SET_INTERFACE: u8 = 11;
+    pub const SYNCH_FRAME: u8 = 12;
+}