Application¶

Important

This module has been deprecated and moved to torii-usb, please see the migration guide.

USB3 application-layer gateware.

Descriptor¶

Utilities for building USB3 descriptors into gateware.

class sol_usb.gateware.usb.usb3.application.descriptor.GetDescriptorHandler(*args: Any, src_loc_at: int = 0, **kwargs: Any)¶

Gateware that handles responding to GetDescriptor requests.

Currently does not support descriptors in multiple languages.

Attributes:

value (Signal(16), input) – The value field associated with the Get Descriptor request. Contains the descriptor type and index.
length (Signal(16), input) – The length field associated with the Get Descriptor request. Determines the maximum amount allowed in a response.
start (Signal(), input) – Strobe that indicates when a descriptor should be transmitted.
tx (stream_type(), output stream) – Stream that carries our output descriptor data.
tx_length (Signal(16), output) – The actual length of the descriptor to be sent. At SuperSpeed, used for header generation.
stall (Signal(), output) – Strobe; pulsed if a STALL handshake should be generated, instead of a response.

Parameters:

domain (string) – The clock domain this generator should belong to. Defaults to ‘’.
stream_type (StreamInterface, or subclass) – The type of stream we’ll be multiplexing.

Request¶

Control-request interfacing and gateware for USB3.

class sol_usb.gateware.usb.usb3.application.request.SuperSpeedRequestHandlerInterface¶

Interface representing a connection between a control endpoint and a request handler.

Attributes:

setup (SetupPacket(), input to handler) – The setup packet relevant to the current request.
data_requested (Signal(), input to handler) – Strobe; pulsed when an IN token is received, and thus data is expected. If the relevant handler handles this request, it will want to respond with data on .tx*.
status_requested (Signal(), input to handler) – Strobe; pulsed when a STATUS token is received. The device should respond with a handshake; typically either an ACK or a STALL.
rx (SuperSpeedStreamInterface(), input stream to handler) – A stream containing any data received as part af an OUT request. Its ready is ignored.
rx_complete (Signal(), input to handler) – Strobes after successful data receipt. Like most USB data, the packet data cannot be considered to be known-good during receipt; but becomes good once :attr:rx_complete is strobed.
rx_invalid (Signal(), input to handler) – Strobes after an invalid data receipt. Indicates that the most recently received packet was corrupted; and should be discarded as invalid.
tx (SuperSpeedStreamInterface(), output stream from handler) – Should be driven to provide data in response to :attr:data_requested. On the same cycle as this stream becomes valid, :attr:tx_length and :attr:tx_sequence_number must be valid.
tx_length (Signal(range(1024 + 1)), output) – The length of the packet to be transmitted on :attr:tx. Mandatory for transmission.
tx_sequence_number (Signal(5)) – The signal number of the packet to be transmitted on :attr:tx. Should start with 0, and advance by one on each subsequent packet.
handshakes_out (HandshakeGeneratorInterface(), output from handler) – Carries any handshakes generated by this endpoint. endpoint_number does not typically need to be set; it is driven by the control endpoint.
handshakes_in (HandshakeGeneratorInterface(), input to handler) – Carries any handshakes received; can be monitored for e.g. ACKs to sent packets.
address_changed (Signal(), output from handler) – Strobe; should be pulsed when the device’s address is to be changed. Should be accompanied by a new address on :attr:new_address.
new_address (Signal(7), output from handler) – The new address to be applied to the device when :attr:address_changed is strobed.
config_changed (Signal(), output from handler) – Strobe; should be pulsed when the device’s configuration is to be changed. Should be accompanied by a new address on :attr:new_config.
new_config (Signal(8), output from handler) – The new configuration to be applied to the device when :attr:config_changed is strobed.
current_configuration (Signal(8), input to handler) – The index of the device’s current configuration.

class sol_usb.gateware.usb.usb3.application.request.SuperSpeedSetupDecoder(*args: Any, src_loc_at: int = 0, **kwargs: Any)¶

Gateware that decodes any received Setup packets.

Attributes:

sink (SuperSpeedStreamInterface(), input stream [read-only]) – Packet interface that carries in new data packets. Results should be considered questionable until :attr:packet_good or :attr:packet_bad are strobed.
rx_good (Signal(), input) – Strobe; indicates that the packet received passed validations and can be considered good.
rx_bad (Signal(), input) – Strobe; indicates that the packet failed CRC checks, or did not end properly.
header_in (DataHeaderPacket(), input) – Header associated with the active packet.
packet (SetupPacket(), output) – The parsed contents of our setup packet.

class sol_usb.gateware.usb.usb3.application.request.SuperSpeedRequestHandlerMultiplexer(*args: Any, src_loc_at: int = 0, **kwargs: Any)¶

Multiplexes multiple RequestHandlers down to a single interface.

Interfaces are added using .add_interface().

Attributes:: shared (SuperSpeedRequestHandlerInterface()) – The post-multiplexer RequestHandler interface.

add_interface(interface: SuperSpeedRequestHandlerInterface)¶

Adds a RequestHandlerInterface to the multiplexer.

Arbitration is not performed; it’s expected only one handler will be driving requests at a time.

class sol_usb.gateware.usb.usb3.application.request.StallOnlyRequestHandler(*args: Any, src_loc_at: int = 0, **kwargs: Any)¶

Simple gateware request handler that only conditionally stalls requests.

I/O port:

*: interface – The RequestHandlerInterface used to handle requests.: See its record definition for signal definitions.

class sol_usb.gateware.usb.usb3.application.request.SuperSpeedRequestHandler(*args: Any, src_loc_at: int = 0, **kwargs: Any)¶: Simple base class for request handlers.