pub trait Bus {
Show 15 methods
// Required methods
async fn enable(&mut self);
async fn disable(&mut self);
async fn poll(&mut self) -> Event;
fn control_max_packet_size(&self) -> usize;
async fn control_data_out(
&mut self,
buf: &mut [u8],
) -> Result<usize, EndpointError>;
async fn control_data_in(
&mut self,
data: &[u8],
needs_zlp: bool,
) -> Result<(), EndpointDisabledError>;
async fn control_accept(&mut self);
async fn control_reject(&mut self);
async fn control_accept_set_address(&mut self, addr: u8);
async fn endpoint_set_enabled(
&mut self,
ep_addr: EndpointAddress,
enabled: bool,
);
fn endpoint_is_enabled(&mut self, ep_addr: EndpointAddress) -> bool;
async fn endpoint_set_stalled(
&mut self,
ep_addr: EndpointAddress,
stalled: bool,
);
fn endpoint_is_stalled(&mut self, ep_addr: EndpointAddress) -> bool;
async fn remote_wakeup(&mut self) -> Result<(), Unsupported>;
// Provided method
async fn force_reset(&mut self) -> Result<(), Unsupported> { ... }
}Expand description
USB bus trait.
This trait provides methods that act on the whole bus, and on the control pipe. It is kept owned by the main USB task, and used to manage the bus.
§Control pipe
The 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. It is part of Bus instead of
Endpoint/EndpointIn/EndpointOut because many USB peripherals treat the control
endpoints differently (different registers, different procedures), usually to accelerate
processing in hardware somehow.
A control request starts with Event::Setup from poll. The stack then
calls control_data_out/control_data_in for the data stage, if any, and finishes the
request with control_accept or control_reject. The driver is responsible for handling the
status stage. The stack DOES NOT do zero-length calls to control_data_in or
control_data_out for the status zero-length packet. The status stage should be triggered by
either control_accept(), or following control_data_in.
§Aborting a control transfer
The stack does not call poll while it is in the middle of a control request,
so it cannot notice by itself that something happened to the bus. Therefore, if the transfer
can no longer complete, control_data_out, control_data_in, control_accept, control_reject and
control_accept_set_address must immediately return, with EndpointError::Disabled or
EndpointDisabledError where they have an error to return. This is the case when:
- the bus is reset (
Event::Reset), - the bus is suspended (
Event::Suspend), or power is removed (Event::PowerRemoved) in drivers that detect it, - the host abandoned the request and sent a new SETUP packet.
Returning early must not consume the event: the next call to poll must still
return it (for a new SETUP packet, Event::Setup). Not doing so will cause things to get
stuck, because the stack never gets to see the event, and the host will never read/send the
packet we’re waiting for.
Required Methods§
Sourceasync fn poll(&mut self) -> Event
async fn poll(&mut self) -> Event
Wait for a bus-related event.
This method should asynchronously wait for an event to happen, then
return it. See Event for the list of events this method should return.
If a bus event and a SETUP packet are both pending, the bus event must be returned first, because a reset or a suspend makes a SETUP packet received before it stale.
This future must be cancel-safe: dropping it must not lose an event.
Sourcefn control_max_packet_size(&self) -> usize
fn control_max_packet_size(&self) -> usize
Maximum packet size for the control pipe.
Sourceasync fn control_data_out(
&mut self,
buf: &mut [u8],
) -> Result<usize, EndpointError>
async fn control_data_out( &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 Event::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, see aborting a control transfer.EndpointError::BufferOverflow- A received packet is larger than the remaining space inbuf.
Sourceasync fn control_data_in(
&mut self,
data: &[u8],
needs_zlp: bool,
) -> Result<(), EndpointDisabledError>
async fn control_data_in( &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 the control
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, see aborting a control transfer.
Sourceasync fn control_accept(&mut self)
async fn control_accept(&mut self)
Accept a control request.
Causes the STATUS packet for the current request to be ACKed. Returns early if the transfer is aborted, see aborting a control transfer.
Sourceasync fn control_reject(&mut self)
async fn control_reject(&mut self)
Reject a control request.
Sets a STALL condition on the pipe to indicate an error.
Sourceasync fn control_accept_set_address(&mut self, addr: u8)
async fn control_accept_set_address(&mut self, addr: u8)
Accept SET_ADDRESS control and change bus address.
For most drivers this function should firstly call control_accept() and then change the bus address.
However, there are peripherals (Synopsys USB OTG) that have reverse order.
Sourceasync fn endpoint_set_enabled(
&mut self,
ep_addr: EndpointAddress,
enabled: bool,
)
async fn endpoint_set_enabled( &mut self, ep_addr: EndpointAddress, enabled: bool, )
Enable or disable an endpoint.
All non-control endpoints are initially disabled after Driver::start, and a USB bus
reset (Event::Reset) disables all non-control endpoints without the stack calling this
method. Enabling an endpoint clears any STALL condition on it, unblocks
Endpoint::wait_enabled, and sets Endpoint::is_enabled to true. Disabling an
endpoint must abort or prevent pending transfers with EndpointError::Disabled.
Sourcefn endpoint_is_enabled(&mut self, ep_addr: EndpointAddress) -> bool
fn endpoint_is_enabled(&mut self, ep_addr: EndpointAddress) -> bool
Get whether an endpoint is enabled.
Sourceasync fn endpoint_set_stalled(
&mut self,
ep_addr: EndpointAddress,
stalled: bool,
)
async fn endpoint_set_stalled( &mut self, ep_addr: EndpointAddress, stalled: bool, )
Set or clear the STALL condition for an endpoint.
If the endpoint is an OUT endpoint, it should be prepared to receive data again.
Sourcefn endpoint_is_stalled(&mut self, ep_addr: EndpointAddress) -> bool
fn endpoint_is_stalled(&mut self, ep_addr: EndpointAddress) -> bool
Get whether the STALL condition is set for an endpoint.
Sourceasync fn remote_wakeup(&mut self) -> Result<(), Unsupported>
async fn remote_wakeup(&mut self) -> Result<(), Unsupported>
Initiate a remote wakeup of the host by the device.
Whether this waits for the remote wakeup signaling to complete or only initiates it is implementation-defined.
§Errors
Unsupported- This UsbBus implementation doesn’t support remote wakeup or it has not been enabled at creation time.
Provided Methods§
Sourceasync fn force_reset(&mut self) -> Result<(), Unsupported>
async fn force_reset(&mut self) -> Result<(), Unsupported>
Simulate a disconnect from the USB bus, causing the host to reset and re-enumerate the device.
The default implementation just returns Unsupported.
§Errors
Unsupported- This UsbBus implementation doesn’t support simulating a disconnect or it has not been enabled at creation time.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".