Trait usb_device::bus::UsbBus

source · [−]
pub trait UsbBus: Sync + Sized {
    const QUIRK_SET_ADDRESS_BEFORE_STATUS: bool = false;

    fn alloc_ep(
        &mut self,
        ep_dir: UsbDirection,
        ep_addr: Option<EndpointAddress>,
        ep_type: EndpointType,
        max_packet_size: u16,
        interval: u8
    ) -> Result<EndpointAddress>;
    fn enable(&mut self);
    fn reset(&self);
    fn set_device_address(&self, addr: u8);
    fn write(&self, ep_addr: EndpointAddress, buf: &[u8]) -> Result<usize>;
    fn read(&self, ep_addr: EndpointAddress, buf: &mut [u8]) -> Result<usize>;
    fn set_stalled(&self, ep_addr: EndpointAddress, stalled: bool);
    fn is_stalled(&self, ep_addr: EndpointAddress) -> bool;
    fn suspend(&self);
    fn resume(&self);
    fn poll(&self) -> PollResult;

    fn force_reset(&self) -> Result<()> { ... }
}
Expand description

A trait for device-specific USB peripherals. Implement this to add support for a new hardware platform.

The UsbBus is shared by reference between the global UsbDevice as well as UsbClasses, and therefore any required mutability must be implemented using interior mutability. Most operations that may mutate the bus object itself take place before enable is called. After the bus is enabled, in practice most access won’t mutate the object itself but only endpoint-specific registers and buffers, the access to which is mostly arbitrated by endpoint handles.

Provided Associated Constants

Indicates that set_device_address must be called before accepting the corresponding control transfer, not after.

The default value for this constant is false, which corresponds to the USB 2.0 spec, 9.4.6

Required Methods

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 enable is called.

Arguments
  • ep_dir - The endpoint direction.
  • ep_addr - A static endpoint address to allocate. If Some, the implementation should attempt to return an endpoint with the specified address. If None, the implementation should return the next available one.
  • max_packet_size - Maximum packet size in bytes.
  • interval - Polling interval parameter for interrupt endpoints.
Errors
  • EndpointOverflow - Available total number of endpoints, endpoints of the specified type, or endpoind packet memory has been exhausted. This is generally caused when a user tries to add too many classes to a composite device.
  • InvalidEndpoint - A specific ep_addr was specified but the endpoint in question has already been allocated.

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.

Called when the host resets the device. This will be soon called after 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.

Sets the device USB address to addr.

Writes a single packet of data to the specified endpoint and returns number of bytes actually written.

The only reason for a short write is if the caller passes a slice larger than the amount of memory allocated earlier, and this is generally an error in the class implementation.

Errors
  • InvalidEndpoint - The ep_addr does not point to a valid endpoint that was previously allocated with UsbBus::alloc_ep.
  • WouldBlock - A previously written packet is still pending to be sent.
  • BufferOverflow - The packet is too long to fit in the transmission buffer. This is generally an error in the class implementation, because the class shouldn’t provide more data than the max_packet_size it specified when allocating the endpoint.

Implementations may also return other errors if applicable.

Reads a single packet of data from the specified endpoint and returns the actual length of the packet.

This should also clear any NAK flags and prepare the endpoint to receive the next packet.

Errors
  • InvalidEndpoint - The ep_addr does not point to a valid endpoint that was previously allocated with UsbBus::alloc_ep.
  • WouldBlock - There is no packet to be read. Note that this is different from a received zero-length packet, which is valid in USB. A zero-length packet will return Ok(0).
  • BufferOverflow - The received packet is too long to fit in buf. This is generally an error in the class implementation, because the class should use a buffer that is large enough for the max_packet_size it specified when allocating the endpoint.

Implementations may also return other errors if applicable.

Sets or clears the STALL condition for an endpoint. If the endpoint is an OUT endpoint, it should be prepared to receive data again.

Gets whether the STALL condition is set for an endpoint.

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 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.

Resumes from suspend mode. This may only be called after the peripheral has been previously suspended.

Gets information about events and incoming data. Usually called in a loop or from an interrupt handler. See the PollResult struct for more information.

Provided Methods

Simulates 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.

Implementors