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§
Sourcefn max_packet_size(&self) -> usize
fn max_packet_size(&self) -> usize
Maximum packet size for the control pipe
Sourceasync fn data_out_transfer(
&mut self,
buf: &mut [u8],
) -> Result<usize, EndpointError>
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
EndpointError::Disabled- The control transfer was aborted by a bus reset or a new SETUP packet.EndpointError::BufferOverflow- A received packet is larger than the remaining space inbuf.
Sourceasync fn data_in_transfer(
&mut self,
data: &[u8],
needs_zlp: bool,
) -> Result<(), EndpointDisabledError>
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
EndpointDisabledError- The control transfer was aborted by a bus reset or a new SETUP packet.
Sourceasync fn accept(&mut self)
async fn accept(&mut self)
Accept a control request.
Causes the STATUS packet for the current request to be ACKed.
Sourceasync fn reject(&mut self)
async fn reject(&mut self)
Reject a control request.
Sets a STALL condition on the pipe to indicate an error.
Sourceasync fn accept_set_address(&mut self, addr: u8)
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".