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

Add DeviceStateHandler, DeviceCommand channel, and remote wakeup support

Browse Source
This commit is contained in:
alexmoon
2022-04-10 15:41:51 -04:00
parent 2217de24c0
commit f5656e3544
11 changed files with 472 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,9 +1,14 @@
use embassy::blocking_mutex::raw::{NoopRawMutex, RawMutex};
use embassy::channel::Channel;
use heapless::Vec;
use crate::DeviceCommand;
use super::control::ControlHandler;
use super::descriptor::{BosWriter, DescriptorWriter};
use super::driver::{Driver, EndpointAllocError};
use super::types::*;
use super::DeviceStateHandler;
use super::UsbDevice;
use super::MAX_INTERFACE_COUNT;
@ -93,6 +98,11 @@ pub struct Config<'a> {
/// Default: 100mA
/// Max: 500mA
pub max_power: u16,
/// Whether the USB bus should be enabled when built.
///
/// Default: true
pub start_enabled: bool,
}
impl<'a> Config<'a> {
@ -112,15 +122,18 @@ impl<'a> Config<'a> {
supports_remote_wakeup: false,
composite_with_iads: false,
max_power: 100,
start_enabled: true,
}
}
}
/// Used to build new [`UsbDevice`]s.
pub struct UsbDeviceBuilder<'d, D: Driver<'d>> {
pub struct UsbDeviceBuilder<'d, D: Driver<'d>, M: RawMutex> {
config: Config<'d>,
handler: Option<&'d dyn DeviceStateHandler>,
interfaces: Vec<(u8, &'d mut dyn ControlHandler), MAX_INTERFACE_COUNT>,
control_buf: &'d mut [u8],
commands: Option<&'d Channel<M, DeviceCommand, 1>>,
driver: D,
next_interface_number: u8,
@ -132,7 +145,7 @@ pub struct UsbDeviceBuilder<'d, D: Driver<'d>> {
pub bos_descriptor: BosWriter<'d>,
}
impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D, NoopRawMutex> {
/// Creates a builder for constructing a new [`UsbDevice`].
///
/// `control_buf` is a buffer used for USB control request data. It should be sized
@ -145,6 +158,58 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
config_descriptor_buf: &'d mut [u8],
bos_descriptor_buf: &'d mut [u8],
control_buf: &'d mut [u8],
handler: Option<&'d dyn DeviceStateHandler>,
) -> Self {
Self::new_inner(
driver,
config,
device_descriptor_buf,
config_descriptor_buf,
bos_descriptor_buf,
control_buf,
handler,
None,
)
}
}
impl<'d, D: Driver<'d>, M: RawMutex> UsbDeviceBuilder<'d, D, M> {
/// Creates a builder for constructing a new [`UsbDevice`].
///
/// `control_buf` is a buffer used for USB control request data. It should be sized
/// large enough for the length of the largest control request (in or out)
/// anticipated by any class added to the device.
pub fn new_with_channel(
driver: D,
config: Config<'d>,
device_descriptor_buf: &'d mut [u8],
config_descriptor_buf: &'d mut [u8],
bos_descriptor_buf: &'d mut [u8],
control_buf: &'d mut [u8],
handler: Option<&'d dyn DeviceStateHandler>,
channel: &'d Channel<M, DeviceCommand, 1>,
) -> Self {
Self::new_inner(
driver,
config,
device_descriptor_buf,
config_descriptor_buf,
bos_descriptor_buf,
control_buf,
handler,
Some(channel),
)
}
fn new_inner(
driver: D,
config: Config<'d>,
device_descriptor_buf: &'d mut [u8],
config_descriptor_buf: &'d mut [u8],
bos_descriptor_buf: &'d mut [u8],
control_buf: &'d mut [u8],
handler: Option<&'d dyn DeviceStateHandler>,
channel: Option<&'d Channel<M, DeviceCommand, 1>>,
) -> Self {
// Magic values specified in USB-IF ECN on IADs.
if config.composite_with_iads
@ -174,9 +239,12 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
UsbDeviceBuilder {
driver,
handler,
config,
interfaces: Vec::new(),
control_buf,
commands: channel,
next_interface_number: 0,
next_string_index: 4,
@ -187,20 +255,21 @@ impl<'d, D: Driver<'d>> UsbDeviceBuilder<'d, D> {
}
/// Creates the [`UsbDevice`] instance with the configuration in this builder.
pub async fn build(mut self) -> UsbDevice<'d, D> {
pub fn build(mut self) -> UsbDevice<'d, D, M> {
self.config_descriptor.end_configuration();
self.bos_descriptor.end_bos();
UsbDevice::build(
self.driver,
self.config,
self.handler,
self.commands,
self.device_descriptor.into_buf(),
self.config_descriptor.into_buf(),
self.bos_descriptor.writer.into_buf(),
self.interfaces,
self.control_buf,
)
.await
}
/// Allocates a new interface number.

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

@ -11,7 +11,6 @@ pub trait Driver<'a> {
type EndpointIn: EndpointIn + 'a;
type ControlPipe: ControlPipe + 'a;
type Bus: Bus + 'a;
type EnableFuture: Future<Output = Self::Bus> + 'a;
/// Allocates an endpoint and specified endpoint parameters. This method is called by the device
/// and class implementations to allocate endpoints, and can only be called before
@ -47,7 +46,7 @@ pub trait Driver<'a> {
/// 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::EnableFuture;
fn into_bus(self) -> Self::Bus;
/// Indicates that `set_device_address` must be called before accepting the corresponding
/// control transfer, not after.
@ -57,19 +56,25 @@ pub trait Driver<'a> {
}
pub trait Bus {
type EnableFuture<'a>: Future<Output = ()> + 'a
where
Self: 'a;
type PollFuture<'a>: Future<Output = Event> + 'a
where
Self: 'a;
type RemoteWakeupFuture<'a>: Future<Output = Result<(), Unsupported>> + 'a
where
Self: 'a;
/// Enables 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(&mut self) -> Self::EnableFuture<'_>;
/// Disables and powers down the USB peripheral.
fn disable(&mut self);
fn poll<'a>(&'a mut self) -> Self::PollFuture<'a>;
/// Called when the host resets the device. This will be soon called after
/// [`poll`](crate::device::UsbDevice::poll) returns [`PollResult::Reset`]. This method should
/// reset the state of all endpoints and peripheral flags back to a state suitable for
/// enumeration, as well as ensure that all endpoints previously allocated with alloc_ep are
/// initialized as specified.
fn reset(&mut self);
/// Sets the device USB address to `addr`.
fn set_device_address(&mut self, addr: u8);
@ -83,17 +88,6 @@ pub trait Bus {
/// Gets whether the STALL condition is set for an endpoint. Only used during control transfers.
fn is_stalled(&mut self, ep_addr: EndpointAddress) -> bool;
/// Causes the USB peripheral to enter USB suspend mode, lowering power consumption and
/// preparing to detect a USB wakeup event. This will be called after
/// [`poll`](crate::device::UsbDevice::poll) returns [`PollResult::Suspend`]. The device will
/// continue be polled, and it shall return a value other than `Suspend` from `poll` when it no
/// longer detects the suspend condition.
fn suspend(&mut self);
/// Resumes from suspend mode. This may only be called after the peripheral has been previously
/// suspended.
fn resume(&mut self);
/// Simulates a disconnect from the USB bus, causing the host to reset and re-enumerate the
/// device.
///
@ -106,6 +100,16 @@ pub trait Bus {
fn force_reset(&mut self) -> Result<(), Unsupported> {
Err(Unsupported)
}
/// Initiates a remote wakeup of the host by the device.
///
/// The default implementation just returns `Unsupported`.
///
/// # Errors
///
/// * [`Unsupported`](crate::UsbError::Unsupported) - This UsbBus implementation doesn't support
/// remote wakeup or it has not been enabled at creation time.
fn remote_wakeup(&mut self) -> Self::RemoteWakeupFuture<'_>;
}
pub trait Endpoint {

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

@ -12,6 +12,9 @@ pub mod driver;
pub mod types;
mod util;
use driver::Unsupported;
use embassy::blocking_mutex::raw::{NoopRawMutex, RawMutex};
use embassy::channel::Channel;
use heapless::Vec;
use self::control::*;
@ -28,8 +31,12 @@ pub use self::builder::UsbDeviceBuilder;
/// In general class traffic is only possible in the `Configured` state.
#[repr(u8)]
#[derive(PartialEq, Eq, Copy, Clone, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum UsbDeviceState {
/// The USB device has just been created or reset.
/// The USB device is disabled.
Disabled,
/// The USB device has just been enabled or reset.
Default,
/// The USB device has received an address from the host.
@ -37,9 +44,6 @@ pub enum UsbDeviceState {
/// The USB device has been configured and is fully functional.
Configured,
/// The USB device has been suspended by the host or it has been unplugged from the USB bus.
Suspend,
}
/// The bConfiguration value for the not configured state.
@ -53,8 +57,39 @@ pub const DEFAULT_ALTERNATE_SETTING: u8 = 0;
pub const MAX_INTERFACE_COUNT: usize = 4;
pub struct UsbDevice<'d, D: Driver<'d>> {
#[derive(PartialEq, Eq, Copy, Clone, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum DeviceCommand {
Enable,
Disable,
RemoteWakeup,
}
/// A handler trait for changes in the device state of the [UsbDevice].
pub trait DeviceStateHandler {
/// Called when the host resets the device.
fn reset(&self) {}
/// Called when the host has set the address of the device to `addr`.
fn addressed(&self, _addr: u8) {}
/// Called when the host has enabled or disabled the configuration of the device.
fn configured(&self, _configured: bool) {}
/// Called when the bus has entered or exited the suspend state.
fn suspended(&self, _suspended: bool) {}
/// Called when remote wakeup feature is enabled or disabled.
fn remote_wakeup_enabled(&self, _enabled: bool) {}
/// Called when the USB device has been disabled.
fn disabled(&self) {}
}
pub struct UsbDevice<'d, D: Driver<'d>, M: RawMutex = NoopRawMutex> {
bus: D::Bus,
handler: Option<&'d dyn DeviceStateHandler>,
commands: Option<&'d Channel<M, DeviceCommand, 1>>,
control: ControlPipe<D::ControlPipe>,
config: Config<'d>,
@ -64,6 +99,7 @@ pub struct UsbDevice<'d, D: Driver<'d>> {
control_buf: &'d mut [u8],
device_state: UsbDeviceState,
suspended: bool,
remote_wakeup_enabled: bool,
self_powered: bool,
pending_address: u8,
@ -71,33 +107,38 @@ pub struct UsbDevice<'d, D: Driver<'d>> {
interfaces: Vec<(u8, &'d mut dyn ControlHandler), MAX_INTERFACE_COUNT>,
}
impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
pub(crate) async fn build(
impl<'d, D: Driver<'d>, M: RawMutex> UsbDevice<'d, D, M> {
pub(crate) fn build(
mut driver: D,
config: Config<'d>,
handler: Option<&'d dyn DeviceStateHandler>,
commands: Option<&'d Channel<M, DeviceCommand, 1>>,
device_descriptor: &'d [u8],
config_descriptor: &'d [u8],
bos_descriptor: &'d [u8],
interfaces: Vec<(u8, &'d mut dyn ControlHandler), MAX_INTERFACE_COUNT>,
control_buf: &'d mut [u8],
) -> UsbDevice<'d, D> {
) -> UsbDevice<'d, D, M> {
let control = driver
.alloc_control_pipe(config.max_packet_size_0 as u16)
.expect("failed to alloc control endpoint");
// Enable the USB bus.
// This prevent further allocation by consuming the driver.
let bus = driver.enable().await;
let bus = driver.into_bus();
Self {
bus,
config,
handler,
commands,
control: ControlPipe::new(control),
device_descriptor,
config_descriptor,
bos_descriptor,
control_buf,
device_state: UsbDeviceState::Default,
suspended: false,
remote_wakeup_enabled: false,
self_powered: false,
pending_address: 0,
@ -105,41 +146,94 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
}
}
pub async fn run(&mut self) {
pub async fn run(&mut self) -> ! {
if self.config.start_enabled {
self.bus.enable().await;
} else {
self.wait_for_enable().await
}
loop {
let control_fut = self.control.setup();
let bus_fut = self.bus.poll();
match select(bus_fut, control_fut).await {
Either::Left(evt) => match evt {
let commands_fut = recv_or_wait(self.commands);
match select3(bus_fut, control_fut, commands_fut).await {
Either3::First(evt) => match evt {
Event::Reset => {
trace!("usb: reset");
self.bus.reset();
self.device_state = UsbDeviceState::Default;
self.suspended = false;
self.remote_wakeup_enabled = false;
self.pending_address = 0;
for (_, h) in self.interfaces.iter_mut() {
h.reset();
}
if let Some(h) = &mut self.handler {
h.reset();
}
}
Event::Resume => {
trace!("usb: resume");
self.suspended = false;
if let Some(h) = &mut self.handler {
h.suspended(false);
}
}
Event::Suspend => {
trace!("usb: suspend");
self.bus.suspend();
self.device_state = UsbDeviceState::Suspend;
self.suspended = true;
if let Some(h) = &mut self.handler {
h.suspended(true);
}
}
},
Either::Right(req) => match req {
Either3::Second(req) => match req {
Setup::DataIn(req, stage) => self.handle_control_in(req, stage).await,
Setup::DataOut(req, stage) => self.handle_control_out(req, stage).await,
},
Either3::Third(cmd) => match cmd {
DeviceCommand::Enable => warn!("usb: Enable command received while enabled."),
DeviceCommand::Disable => {
trace!("usb: disable");
self.bus.disable();
self.device_state = UsbDeviceState::Disabled;
if let Some(h) = &mut self.handler {
h.disabled();
}
self.wait_for_enable().await;
}
DeviceCommand::RemoteWakeup => {
if self.remote_wakeup_enabled {
match self.bus.remote_wakeup().await {
Ok(()) => (),
Err(Unsupported) => warn!("Remote wakeup is unsupported!"),
}
} else {
warn!("Remote wakeup not enabled.");
}
}
},
}
}
}
async fn wait_for_enable(&mut self) {
loop {
// When disabled just wait until we're told to re-enable
match recv_or_wait(self.commands).await {
DeviceCommand::Enable => break,
cmd => warn!("usb: {:?} received while disabled", cmd),
}
}
trace!("usb: enable");
self.bus.enable().await;
self.device_state = UsbDeviceState::Default;
}
async fn handle_control_out(&mut self, req: Request, stage: DataOutStage) {
const CONFIGURATION_NONE_U16: u16 = CONFIGURATION_NONE as u16;
const CONFIGURATION_VALUE_U16: u16 = CONFIGURATION_VALUE as u16;
@ -156,20 +250,33 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
(RequestType::Standard, Recipient::Device) => match (req.request, req.value) {
(Request::CLEAR_FEATURE, Request::FEATURE_DEVICE_REMOTE_WAKEUP) => {
self.remote_wakeup_enabled = false;
if let Some(h) = &mut self.handler {
h.remote_wakeup_enabled(false);
}
self.control.accept(stage)
}
(Request::SET_FEATURE, Request::FEATURE_DEVICE_REMOTE_WAKEUP) => {
self.remote_wakeup_enabled = true;
if let Some(h) = &mut self.handler {
h.remote_wakeup_enabled(true);
}
self.control.accept(stage)
}
(Request::SET_ADDRESS, addr @ 1..=127) => {
self.pending_address = addr as u8;
self.bus.set_device_address(self.pending_address);
self.device_state = UsbDeviceState::Addressed;
if let Some(h) = &mut self.handler {
h.addressed(self.pending_address);
}
self.control.accept(stage)
}
(Request::SET_CONFIGURATION, CONFIGURATION_VALUE_U16) => {
self.device_state = UsbDeviceState::Configured;
self.bus.set_configured(true);
if let Some(h) = &mut self.handler {
h.configured(true);
}
self.control.accept(stage)
}
(Request::SET_CONFIGURATION, CONFIGURATION_NONE_U16) => match self.device_state {
@ -177,6 +284,9 @@ impl<'d, D: Driver<'d>> UsbDevice<'d, D> {
_ => {
self.device_state = UsbDeviceState::Addressed;
self.bus.set_configured(false);
if let Some(h) = &mut self.handler {
h.configured(false);
}
self.control.accept(stage)
}
},

72
embassy-usb/src/util.rs
View File

@ -1,45 +1,85 @@
use core::future::Future;
use core::marker::PhantomData;
use core::pin::Pin;
use core::task::{Context, Poll};
use embassy::blocking_mutex::raw::RawMutex;
use embassy::channel::Channel;
#[derive(Debug, Clone)]
pub enum Either<A, B> {
Left(A),
Right(B),
pub enum Either3<A, B, C> {
First(A),
Second(B),
Third(C),
}
pub fn select<A, B>(a: A, b: B) -> Select<A, B>
/// Same as [`select`], but with more futures.
pub fn select3<A, B, C>(a: A, b: B, c: C) -> Select3<A, B, C>
where
A: Future,
B: Future,
C: Future,
{
Select { a, b }
Select3 { a, b, c }
}
pub struct Select<A, B> {
/// Future for the [`select3`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select3<A, B, C> {
a: A,
b: B,
c: C,
}
impl<A: Unpin, B: Unpin> Unpin for Select<A, B> {}
impl<A, B> Future for Select<A, B>
impl<A, B, C> Future for Select3<A, B, C>
where
A: Future,
B: Future,
C: Future,
{
type Output = Either<A::Output, B::Output>;
type Output = Either3<A::Output, B::Output, C::Output>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
match a.poll(cx) {
Poll::Ready(x) => Poll::Ready(Either::Left(x)),
Poll::Pending => match b.poll(cx) {
Poll::Ready(x) => Poll::Ready(Either::Right(x)),
Poll::Pending => Poll::Pending,
},
let c = unsafe { Pin::new_unchecked(&mut this.c) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either3::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either3::Second(x));
}
if let Poll::Ready(x) = c.poll(cx) {
return Poll::Ready(Either3::Third(x));
}
Poll::Pending
}
}
pub struct Pending<T> {
_phantom: PhantomData<T>,
}
impl<T> Pending<T> {
fn new() -> Self {
Pending {
_phantom: PhantomData,
}
}
}
impl<T> Future for Pending<T> {
type Output = T;
fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
Poll::Pending
}
}
pub async fn recv_or_wait<M: RawMutex, T, const N: usize>(ch: Option<&Channel<M, T, N>>) -> T {
match ch {
Some(ch) => ch.recv().await,
None => Pending::new().await,
}
}