embassy-usb-driver

Crates

git

Versions

default

Flavors

Skip to main content

ControlPipe

Trait ControlPipe 

Source
pub trait ControlPipe {
    // Required methods
    fn max_packet_size(&self) -> usize;
    async fn setup(&mut self) -> [u8; 8];
    async fn data_out_transfer(
        &mut self,
        buf: &mut [u8],
    ) -> Result<usize, EndpointError>;
    async fn data_in_transfer(
        &mut self,
        data: &[u8],
        needs_zlp: bool,
    ) -> Result<(), EndpointDisabledError>;
    async fn accept(&mut self);
    async fn reject(&mut self);
    async fn accept_set_address(&mut self, addr: u8);
}
Expand description

USB control pipe trait.

The USB control pipe owns both OUT endpoint 0 and IN endpoint 0 in a single unit, and manages them together to implement the control pipe state machine.

The reason this is a separate trait instead of using EndpointOut/EndpointIn is that many USB peripherals treat the control pipe endpoints differently (different registers, different procedures), usually to accelerate processing in hardware somehow. A separate trait allows the driver to handle it specially.

The driver is responsible for handling the status stage. The stack DOES NOT do zero-length calls to data_in_transfer or data_out_transfer for the status zero-length packet. The status stage should be triggered by either accept(), or following data_in_transfer.

Note that the host can abandon a control request and send a new SETUP packet any time. If a SETUP packet arrives at any time during data_out_transfer, data_in_transfer, accept or reject, the driver must immediately return (with EndpointDisabledError from data_in_transfer and EndpointError::Disabled from data_out_transfer) to let the stack call setup() again to start handling the new control request. Not doing so will cause things to get stuck, because the host will never read/send the packet we’re waiting for.

Required Methods§

Source

fn max_packet_size(&self) -> usize

Maximum packet size for the control pipe

Source

async fn setup(&mut self) -> [u8; 8]

Read a single setup packet from the endpoint.

Source

async fn data_out_transfer( &mut self, buf: &mut [u8], ) -> Result<usize, EndpointError>

Read a DATA OUT transfer into buf in response to a control write request.

Must be called after setup() for requests with direction of Out and request length greater than zero.

buf must be at most as large as the request length.

§Errors
Source

async fn data_in_transfer( &mut self, data: &[u8], needs_zlp: bool, ) -> Result<(), EndpointDisabledError>

Send a DATA IN transfer with data in response to a control read request.

If needs_zlp is true and data.len() is an exact non-zero multiple of max_packet_size, a zero-length packet must be transmitted. The driver is responsible for handling the status stage following the transfer.

§Errors
Source

async fn accept(&mut self)

Accept a control request.

Causes the STATUS packet for the current request to be ACKed.

Source

async fn reject(&mut self)

Reject a control request.

Sets a STALL condition on the pipe to indicate an error.

Source

async fn accept_set_address(&mut self, addr: u8)

Accept SET_ADDRESS control and change bus address.

For most drivers this function should firstly call accept() and then change the bus address. However, there are peripherals (Synopsys USB OTG) that have reverse order.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§