Application

USB3 application-layer gateware.

Descriptor

Utilities for building USB3 descriptors into gateware.

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

Gateware that handles responding to GetDescriptor requests.

Currently does not support descriptors in multiple languages.

Variables:

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

Variables:

  • 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, src_loc_at: int = 0, **kwargs)

Gateware that decodes any received Setup packets.

Variables:

  • 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, src_loc_at: int = 0, **kwargs)

Multiplexes multiple RequestHandlers down to a single interface.

Interfaces are added using .add_interface().

Variables:

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, src_loc_at: int = 0, **kwargs)

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, src_loc_at: int = 0, **kwargs)

Simple base class for request handlers.