max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add support for USB classes handling control requests.

Browse Source
This commit is contained in:
alexmoon
2022-03-25 16:46:14 -04:00
committed by Dario Nieuwenhuis
parent 5c0db627fe
commit bdc6e0481c
8 changed files with 703 additions and 291 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
embassy-usb/src/builder.rs
View File

@ -1,3 +1,4 @@
use super::class::UsbClass;
use super::descriptor::{BosWriter, DescriptorWriter};
use super::driver::{Driver, EndpointAllocError};
use super::types::*;
@ -174,7 +175,10 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
}
/// Creates the [`UsbDevice`] instance with the configuration in this builder.
pub fn build(mut self) -> UsbDevice<'d, D> {
///
/// If a device has mutliple [`UsbClass`]es, they can be provided as a tuple list:
/// `(class1, (class2, (class3, ()))`.
pub fn build<C: UsbClass<'d, D>>(mut self, classes: C) -> UsbDevice<'d, D, C> {
self.config_descriptor.end_configuration();
self.bos_descriptor.end_bos();
@ -184,6 +188,7 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
self.device_descriptor.into_buf(),
self.config_descriptor.into_buf(),
self.bos_descriptor.writer.into_buf(),
classes,
)
}
@ -268,9 +273,10 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
/// Panics if endpoint allocation fails, because running out of endpoints or memory is not
/// feasibly recoverable.
#[inline]
pub fn alloc_control_endpoint_out(&mut self, max_packet_size: u16) -> D::EndpointOut {
self.alloc_endpoint_out(None, EndpointType::Control, max_packet_size, 0)
.expect("alloc_ep failed")
pub fn alloc_control_pipe(&mut self, max_packet_size: u16) -> D::ControlPipe {
self.bus
.alloc_control_pipe(max_packet_size)
.expect("alloc_control_pipe failed")
}
/// Allocates a bulk in endpoint.

190
embassy-usb/src/class.rs Normal file
View File

@ -0,0 +1,190 @@
use core::future::Future;
use crate::control::Request;
use crate::driver::{ControlPipe, Driver};
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum RequestStatus {
Unhandled,
Accepted,
Rejected,
}
impl Default for RequestStatus {
fn default() -> Self {
RequestStatus::Unhandled
}
}
/// A trait for implementing USB classes.
///
/// All methods are optional callbacks that will be called by
/// [`UsbDevice::run()`](crate::UsbDevice::run)
pub trait UsbClass<'d, D: Driver<'d>> {
type ControlOutFuture<'a>: Future<Output = RequestStatus> + 'a
where
Self: 'a,
'd: 'a,
D: 'a;
type ControlInFuture<'a>: Future<Output = ControlInRequestStatus> + 'a
where
Self: 'a,
'd: 'a,
D: 'a;
/// Called after a USB reset after the bus reset sequence is complete.
fn reset(&mut self) {}
/// Called when a control request is received with direction HostToDevice.
///
/// All requests are passed to classes in turn, which can choose to accept, ignore or report an
/// error. Classes can even choose to override standard requests, but doing that is rarely
/// necessary.
///
/// When implementing your own class, you should ignore any requests that are not meant for your
/// class so that any other classes in the composite device can process them.
///
/// # Arguments
///
/// * `req` - The request from the SETUP packet.
/// * `data` - The data from the request.
fn control_out<'a>(&'a mut self, req: Request, data: &'a [u8]) -> Self::ControlOutFuture<'a>
where
'd: 'a,
D: 'a;
/// Called when a control request is received with direction DeviceToHost.
///
/// All requests are passed to classes in turn, which can choose to accept, ignore or report an
/// error. Classes can even choose to override standard requests, but doing that is rarely
/// necessary.
///
/// See [`ControlIn`] for how to respond to the transfer.
///
/// When implementing your own class, you should ignore any requests that are not meant for your
/// class so that any other classes in the composite device can process them.
///
/// # Arguments
///
/// * `req` - The request from the SETUP packet.
/// * `control` - The control pipe.
fn control_in<'a>(
&'a mut self,
req: Request,
control: ControlIn<'a, 'd, D>,
) -> Self::ControlInFuture<'a>
where
'd: 'a;
}
impl<'d, D: Driver<'d>> UsbClass<'d, D> for () {
type ControlOutFuture<'a> = impl Future<Output = RequestStatus> + 'a where Self: 'a, 'd: 'a, D: 'a;
type ControlInFuture<'a> = impl Future<Output = ControlInRequestStatus> + 'a where Self: 'a, 'd: 'a, D: 'a;
fn control_out<'a>(&'a mut self, _req: Request, _data: &'a [u8]) -> Self::ControlOutFuture<'a>
where
'd: 'a,
D: 'a,
{
async move { RequestStatus::default() }
}
fn control_in<'a>(
&'a mut self,
_req: Request,
control: ControlIn<'a, 'd, D>,
) -> Self::ControlInFuture<'a>
where
'd: 'a,
D: 'a,
{
async move { control.ignore() }
}
}
impl<'d, D: Driver<'d>, Head, Tail> UsbClass<'d, D> for (Head, Tail)
where
Head: UsbClass<'d, D>,
Tail: UsbClass<'d, D>,
{
type ControlOutFuture<'a> = impl Future<Output = RequestStatus> + 'a where Self: 'a, 'd: 'a, D: 'a;
type ControlInFuture<'a> = impl Future<Output = ControlInRequestStatus> + 'a where Self: 'a, 'd: 'a, D: 'a;
fn control_out<'a>(&'a mut self, req: Request, data: &'a [u8]) -> Self::ControlOutFuture<'a>
where
'd: 'a,
D: 'a,
{
async move {
match self.0.control_out(req, data).await {
RequestStatus::Unhandled => self.1.control_out(req, data).await,
status => status,
}
}
}
fn control_in<'a>(
&'a mut self,
req: Request,
control: ControlIn<'a, 'd, D>,
) -> Self::ControlInFuture<'a>
where
'd: 'a,
{
async move {
match self
.0
.control_in(req, ControlIn::new(control.control))
.await
{
ControlInRequestStatus(RequestStatus::Unhandled) => {
self.1.control_in(req, control).await
}
status => status,
}
}
}
}
/// Handle for a control IN transfer. When implementing a class, use the methods of this object to
/// response to the transfer with either data or an error (STALL condition). To ignore the request
/// and pass it on to the next class, call [`Self::ignore()`].
pub struct ControlIn<'a, 'd: 'a, D: Driver<'d>> {
control: &'a mut D::ControlPipe,
}
#[derive(Eq, PartialEq, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct ControlInRequestStatus(pub(crate) RequestStatus);
impl ControlInRequestStatus {
pub fn status(self) -> RequestStatus {
self.0
}
}
impl<'a, 'd: 'a, D: Driver<'d>> ControlIn<'a, 'd, D> {
pub(crate) fn new(control: &'a mut D::ControlPipe) -> Self {
ControlIn { control }
}
/// Ignores the request and leaves it unhandled.
pub fn ignore(self) -> ControlInRequestStatus {
ControlInRequestStatus(RequestStatus::Unhandled)
}
/// Accepts the transfer with the supplied buffer.
pub async fn accept(self, data: &[u8]) -> ControlInRequestStatus {
self.control.accept_in(data).await;
ControlInRequestStatus(RequestStatus::Accepted)
}
/// Rejects the transfer by stalling the pipe.
pub fn reject(self) -> ControlInRequestStatus {
self.control.reject();
ControlInRequestStatus(RequestStatus::Rejected)
}
}

17
embassy-usb/src/control.rs
View File

@ -2,12 +2,6 @@ use core::mem;
use super::types::*;
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum ParseError {
InvalidLength,
}
/// Control request type.
#[repr(u8)]
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
@ -104,15 +98,12 @@ impl Request {
/// Standard USB feature Device Remote Wakeup for Set/Clear Feature
pub const FEATURE_DEVICE_REMOTE_WAKEUP: u16 = 1;
pub(crate) fn parse(buf: &[u8]) -> Result<Request, ParseError> {
if buf.len() != 8 {
return Err(ParseError::InvalidLength);
}
/// Parses a USB control request from a byte array.
pub fn parse(buf: &[u8; 8]) -> Request {
let rt = buf[0];
let recipient = rt & 0b11111;
Ok(Request {
Request {
direction: rt.into(),
request_type: unsafe { mem::transmute((rt >> 5) & 0b11) },
recipient: if recipient <= 3 {
@ -124,7 +115,7 @@ impl Request {
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),
})
}
}
/// Gets the descriptor type and index from the value field of a GET_DESCRIPTOR request.

42
embassy-usb/src/driver.rs
View File

@ -1,5 +1,7 @@
use core::future::Future;
use crate::control::Request;
use super::types::*;
/// Driver for a specific USB peripheral. Implement this to add support for a new hardware
@ -7,6 +9,7 @@ use super::types::*;
pub trait Driver<'a> {
type EndpointOut: EndpointOut + 'a;
type EndpointIn: EndpointIn + 'a;
type ControlPipe: ControlPipe + 'a;
type Bus: Bus + 'a;
/// Allocates an endpoint and specified endpoint parameters. This method is called by the device
@ -36,6 +39,11 @@ pub trait Driver<'a> {
interval: u8,
) -> Result<Self::EndpointIn, EndpointAllocError>;
fn alloc_control_pipe(
&mut self,
max_packet_size: u16,
) -> Result<Self::ControlPipe, EndpointAllocError>;
/// Enables and initializes the USB peripheral. Soon after enabling the device will be reset, so
/// there is no need to perform a USB reset in this method.
fn enable(self) -> Self::Bus;
@ -122,6 +130,40 @@ pub trait EndpointOut: Endpoint {
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Self::ReadFuture<'a>;
}
pub trait ControlPipe {
type SetupFuture<'a>: Future<Output = Request> + 'a
where
Self: 'a;
type DataOutFuture<'a>: Future<Output = Result<usize, ReadError>> + 'a
where
Self: 'a;
type AcceptInFuture<'a>: Future<Output = ()> + 'a
where
Self: 'a;
/// Reads a single setup packet from the endpoint.
fn setup<'a>(&'a mut self) -> Self::SetupFuture<'a>;
/// Reads the data packet of a control write sequence.
///
/// Must be called after `setup()` for requests with `direction` of `Out`
/// and `length` greater than zero.
///
/// `buf.len()` must be greater than or equal to the request's `length`.
fn data_out<'a>(&'a mut self, buf: &'a mut [u8]) -> Self::DataOutFuture<'a>;
/// Accepts a control request.
fn accept(&mut self);
/// Accepts a control read request with `data`.
///
/// `data.len()` must be less than or equal to the request's `length`.
fn accept_in<'a>(&'a mut self, data: &'a [u8]) -> Self::AcceptInFuture<'a>;
/// Rejects a control request.
fn reject(&mut self);
}
pub trait EndpointIn: Endpoint {
type WriteFuture<'a>: Future<Output = Result<(), WriteError>> + 'a
where

169
embassy-usb/src/lib.rs
View File

@ -1,16 +1,19 @@
#![no_std]
#![feature(generic_associated_types)]
#![feature(type_alias_impl_trait)]
// This mod MUST go first, so that the others see its macros.
pub(crate) mod fmt;
mod builder;
mod control;
pub mod class;
pub mod control;
pub mod descriptor;
pub mod driver;
pub mod types;
mod util;
use self::class::{RequestStatus, UsbClass};
use self::control::*;
use self::descriptor::*;
use self::driver::*;
@ -48,10 +51,9 @@ pub const CONFIGURATION_VALUE: u8 = 1;
/// The default value for bAlternateSetting for all interfaces.
pub const DEFAULT_ALTERNATE_SETTING: u8 = 0;
pub struct UsbDevice<'d, D: Driver<'d>> {
pub struct UsbDevice<'d, D: Driver<'d>, C: UsbClass<'d, D>> {
bus: D::Bus,
control_in: D::EndpointIn,
control_out: D::EndpointOut,
control: D::ControlPipe,
config: Config<'d>,
device_descriptor: &'d [u8],
@ -62,32 +64,21 @@ pub struct UsbDevice<'d, D: Driver<'d>> {
remote_wakeup_enabled: bool,
self_powered: bool,
pending_address: u8,
classes: C,
}
impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
impl<'d, D: Driver<'d>, C: UsbClass<'d, D>> UsbDevice<'d, D, C> {
pub(crate) fn build(
mut driver: D,
config: Config<'d>,
device_descriptor: &'d [u8],
config_descriptor: &'d [u8],
bos_descriptor: &'d [u8],
classes: C,
) -> Self {
let control_out = driver
.alloc_endpoint_out(
Some(0x00.into()),
EndpointType::Control,
config.max_packet_size_0 as u16,
0,
)
.expect("failed to alloc control endpoint");
let control_in = driver
.alloc_endpoint_in(
Some(0x80.into()),
EndpointType::Control,
config.max_packet_size_0 as u16,
0,
)
let control = driver
.alloc_control_pipe(config.max_packet_size_0 as u16)
.expect("failed to alloc control endpoint");
// Enable the USB bus.
@ -97,8 +88,7 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
Self {
bus: driver,
config,
control_in,
control_out,
control,
device_descriptor,
config_descriptor,
bos_descriptor,
@ -106,14 +96,13 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
remote_wakeup_enabled: false,
self_powered: false,
pending_address: 0,
classes,
}
}
pub async fn run(&mut self) {
let mut buf = [0; 8];
loop {
let control_fut = self.control_out.read(&mut buf);
let control_fut = self.control.setup();
let bus_fut = self.bus.poll();
match select(bus_fut, control_fut).await {
Either::Left(evt) => match evt {
@ -124,11 +113,7 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
self.remote_wakeup_enabled = false;
self.pending_address = 0;
// TODO
//self.control.reset();
//for cls in classes {
// cls.reset();
//}
self.classes.reset();
}
Event::Resume => {}
Event::Suspend => {
@ -136,16 +121,9 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
self.device_state = UsbDeviceState::Suspend;
}
},
Either::Right(n) => {
let n = n.unwrap();
assert_eq!(n, 8);
let req = Request::parse(&buf).unwrap();
Either::Right(req) => {
info!("control request: {:x}", req);
// Now that we have properly parsed the setup packet, ensure the end-point is no longer in
// a stalled state.
self.control_out.set_stalled(false);
match req.direction {
UsbDirection::In => self.handle_control_in(req).await,
UsbDirection::Out => self.handle_control_out(req).await,
@ -155,36 +133,6 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
}
}
async fn write_chunked(&mut self, data: &[u8]) -> Result<(), driver::WriteError> {
for c in data.chunks(8) {
self.control_in.write(c).await?;
}
if data.len() % 8 == 0 {
self.control_in.write(&[]).await?;
}
Ok(())
}
async fn control_out_accept(&mut self, req: Request) {
info!("control out accept");
// status phase
// todo: cleanup
self.control_out.read(&mut []).await.unwrap();
}
async fn control_in_accept(&mut self, req: Request, data: &[u8]) {
info!("control accept {:x}", data);
let len = data.len().min(req.length as _);
if let Err(e) = self.write_chunked(&data[..len]).await {
info!("write_chunked failed: {:?}", e);
}
// status phase
// todo: cleanup
self.control_out.read(&mut []).await.unwrap();
}
async fn control_in_accept_writer(
&mut self,
req: Request,
@ -193,17 +141,26 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
let mut buf = [0; 256];
let mut w = DescriptorWriter::new(&mut buf);
f(&mut w);
let pos = w.position();
self.control_in_accept(req, &buf[..pos]).await;
}
fn control_reject(&mut self, req: Request) {
info!("control reject");
self.control_out.set_stalled(true);
let pos = w.position().min(usize::from(req.length));
self.control.accept_in(&buf[..pos]).await;
}
async fn handle_control_out(&mut self, req: Request) {
// TODO actually read the data if there's an OUT data phase.
{
let mut buf = [0; 128];
let data = if req.length > 0 {
let size = self.control.data_out(&mut buf).await.unwrap();
&buf[0..size]
} else {
&[]
};
match self.classes.control_out(req, data).await {
RequestStatus::Accepted => return self.control.accept(),
RequestStatus::Rejected => return self.control.reject(),
RequestStatus::Unhandled => (),
}
}
const CONFIGURATION_NONE_U16: u16 = CONFIGURATION_NONE as u16;
const CONFIGURATION_VALUE_U16: u16 = CONFIGURATION_VALUE as u16;
@ -217,12 +174,12 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
Request::FEATURE_DEVICE_REMOTE_WAKEUP,
) => {
self.remote_wakeup_enabled = false;
self.control_out_accept(req).await;
self.control.accept();
}
(Recipient::Endpoint, Request::CLEAR_FEATURE, Request::FEATURE_ENDPOINT_HALT) => {
//self.bus.set_stalled(((req.index as u8) & 0x8f).into(), false);
self.control_out_accept(req).await;
self.control.accept();
}
(
@ -231,51 +188,61 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
Request::FEATURE_DEVICE_REMOTE_WAKEUP,
) => {
self.remote_wakeup_enabled = true;
self.control_out_accept(req).await;
self.control.accept();
}
(Recipient::Endpoint, Request::SET_FEATURE, Request::FEATURE_ENDPOINT_HALT) => {
self.bus
.set_stalled(((req.index as u8) & 0x8f).into(), true);
self.control_out_accept(req).await;
self.control.accept();
}
(Recipient::Device, Request::SET_ADDRESS, 1..=127) => {
self.pending_address = req.value as u8;
// on NRF the hardware auto-handles SET_ADDRESS.
self.control_out_accept(req).await;
self.control.accept();
}
(Recipient::Device, Request::SET_CONFIGURATION, CONFIGURATION_VALUE_U16) => {
self.device_state = UsbDeviceState::Configured;
self.control_out_accept(req).await;
self.control.accept();
}
(Recipient::Device, Request::SET_CONFIGURATION, CONFIGURATION_NONE_U16) => {
match self.device_state {
UsbDeviceState::Default => {
self.control_out_accept(req).await;
self.control.accept();
}
_ => {
self.device_state = UsbDeviceState::Addressed;
self.control_out_accept(req).await;
self.control.accept();
}
}
}
(Recipient::Interface, Request::SET_INTERFACE, DEFAULT_ALTERNATE_SETTING_U16) => {
// TODO: do something when alternate settings are implemented
self.control_out_accept(req).await;
self.control.accept();
}
_ => self.control_reject(req),
_ => self.control.reject(),
},
_ => self.control_reject(req),
_ => self.control.reject(),
}
}
async fn handle_control_in(&mut self, req: Request) {
match self
.classes
.control_in(req, class::ControlIn::new(&mut self.control))
.await
.status()
{
RequestStatus::Accepted | RequestStatus::Rejected => return,
RequestStatus::Unhandled => (),
}
match req.request_type {
RequestType::Standard => match (req.recipient, req.request) {
(Recipient::Device, Request::GET_STATUS) => {
@ -286,12 +253,12 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
if self.remote_wakeup_enabled {
status |= 0x0002;
}
self.control_in_accept(req, &status.to_le_bytes()).await;
self.control.accept_in(&status.to_le_bytes()).await;
}
(Recipient::Interface, Request::GET_STATUS) => {
let status: u16 = 0x0000;
self.control_in_accept(req, &status.to_le_bytes()).await;
self.control.accept_in(&status.to_le_bytes()).await;
}
(Recipient::Endpoint, Request::GET_STATUS) => {
@ -300,7 +267,7 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
if self.bus.is_stalled(ep_addr) {
status |= 0x0001;
}
self.control_in_accept(req, &status.to_le_bytes()).await;
self.control.accept_in(&status.to_le_bytes()).await;
}
(Recipient::Device, Request::GET_DESCRIPTOR) => {
@ -312,17 +279,17 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
UsbDeviceState::Configured => CONFIGURATION_VALUE,
_ => CONFIGURATION_NONE,
};
self.control_in_accept(req, &status.to_le_bytes()).await;
self.control.accept_in(&status.to_le_bytes()).await;
}
(Recipient::Interface, Request::GET_INTERFACE) => {
// TODO: change when alternate settings are implemented
let status = DEFAULT_ALTERNATE_SETTING;
self.control_in_accept(req, &status.to_le_bytes()).await;
self.control.accept_in(&status.to_le_bytes()).await;
}
_ => self.control_reject(req),
_ => self.control.reject(),
},
_ => self.control_reject(req),
_ => self.control.reject(),
}
}
@ -331,11 +298,9 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
let config = self.config.clone();
match dtype {
descriptor_type::BOS => self.control_in_accept(req, self.bos_descriptor).await,
descriptor_type::DEVICE => self.control_in_accept(req, self.device_descriptor).await,
descriptor_type::CONFIGURATION => {
self.control_in_accept(req, self.config_descriptor).await
}
descriptor_type::BOS => self.control.accept_in(self.bos_descriptor).await,
descriptor_type::DEVICE => self.control.accept_in(self.device_descriptor).await,
descriptor_type::CONFIGURATION => self.control.accept_in(self.config_descriptor).await,
descriptor_type::STRING => {
if index == 0 {
self.control_in_accept_writer(req, |w| {
@ -363,11 +328,11 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
self.control_in_accept_writer(req, |w| w.string(s).unwrap())
.await;
} else {
self.control_reject(req)
self.control.reject()
}
}
}
_ => self.control_reject(req),
_ => self.control.reject(),
}
}
}