Packet

Contains the gatware module necessary to interpret and generate low-level USB packets.

class sol_usb.gateware.usb.usb2.packet.HandshakeExchangeInterface(*, is_detector)

Record that carries handshakes detected -or- generated between modules.

Variables:

ack (Signal()) – When connected to a generator, pulsing this strobe will trigger generating of an ACK. When connected to a detector, this strobe will be pulsed when an ACK is detected from the host.
nak (Signal()) – When connected to a generator, pulsing this strobe will trigger generating of an NAK. When connected to a detector, this strobe will be pulsed when an NAK is detected from the host.
stall (Signal()) – When connected to a generator, pulsing this strobe will trigger generation of a STALL. Unused in a detector, currently.
nyet (Signal()) – When connected to a generator, pulsing this strobe will trigger generation of a NYET. Unused in a detector, currently.

Parameters:

is_detector (bool) – If true, this will be considered an interface to a detector that identifies handshakes. Otherwise, this will be considered an interface to a generator that accepts handshake requests.

class sol_usb.gateware.usb.usb2.packet.DataCRCInterface

Record providing an interface to a USB CRC-16 generator.

Variables:

start (Signal(), input to CRC generator) – Strobe that indicates that a new CRC computation should be started.
crc (Signal(), output from CRC generator) – The current CRC-16 value; updated with each sent or received byte.

class sol_usb.gateware.usb.usb2.packet.TokenDetectorInterface

Record providing an interface to a USB token detector.

Variables:

pid (Signal(4), detector output) – The Packet ID of the most recent token.
address (Signal(7), detector output) – The address associated with the relevant token.
endpoint (Signal(4), detector output) – The endpoint indicated by the most recent token.
new_token (Signal(), detector output) – Strobe asserted for a single cycle when a new token packet has been received.
ready_for_response (Signal(), detector output) – Strobe asserted for a single cycle one inter-packet delay after a token packet is complete. Indicates when the token packet can be responded to.
frame (Signal(11), detector output) – The current USB frame number.
new_frame (Signal(), detector output) – Strobe asserted for a single cycle when a new SOF has been received.
is_in (Signal(), detector output) – High iff the current token is an IN.
is_out (Signal(), detector output) – High iff the current token is an OUT.
is_setup (Signal(), detector output) – High iff the current token is a SETUP.
is_ping (Signal(), detector output) – High iff the current token is a PING.

class sol_usb.gateware.usb.usb2.packet.InterpacketTimerInterface

Record providing an interface to our interpacket timer.

See [USB2.0: 7.1.18] and the USBInterpacketTimer gateware for more information.

Variables:

start (Signal(), input to timer) – Strobe that indicates when the timer should be started. Usually started at the end of an Rx or Tx event.
tx_allowed (Signal(), output from timer) – Strobe that goes high when it’s safe to transmit after an Rx event.
tx_timeout (Signal(), output from timer) – Strobe that goes high when the transmit-after-receive window has passed.
rx_timeout (Signal(), output from timer) – Strobe that goes high when the receive-after-transmit window has passed.

attach(*subordinates)

Attaches subordinate interfaces to the given timer interface.

Parameters:: subordinates ([InterpacketTimerInterface, Signal]) – Each InterpacketTimerInterface is provided will be fully connected to a given timer interface. Each Signal provided will be interpreted as a timer reset, and added to the list of all resets.

class sol_usb.gateware.usb.usb2.packet.USBTokenDetector(*args, src_loc_at: int = 0, **kwargs)

Gateware that parses token packets and generates relevant events.

Variables:

interface (TokenDetectorInterface) – The interface that contains token detection events, and information about detected tokens.
speed (Signal(2), input) – Carries a USBSpeed constant identifying the device’s current operating speed.
address (Signal(7), input -or- output) – If :parameter:filter_by_address is true, this is an input that filters our event detector so it only reports tokens directed at a given address. If filter_by_address is false, this is an output that contains the address of the most recent token.

Parameters:

utmi (UTMIInterface) – The UTMI bus to observe.
filter_by_address (bool) – If true, this detector will only report events for the address supplied in the address[] field.

class sol_usb.gateware.usb.usb2.packet.USBHandshakeDetector(*args, src_loc_at: int = 0, **kwargs)

Gateware that detects handshake packets.

Variables:: detected (HandshakeExchangeInterface) – Strobes that indicate which handshakes we’re detecting.
Parameters:: utmi ([UTMIInterface, UTMITranslator]) – The UTMI interface to listen on.

class sol_usb.gateware.usb.usb2.packet.USBDataPacketCRC(*args, src_loc_at: int = 0, **kwargs)

Gateware that computes a running CRC-16.

By default, this module has no connections to the modules that use it.

These are added using add_interface; this module supports an arbitrary number of connection interfaces; see add_interface() for restrictions.

Variables:

rx_data (Signal(8), input) – Receive data input; can be carried directly from a UTMI interface.
rx_valid (Signal(), input) – Receive validity signal; can be carried directly from a UTMI interface.
tx_data (Signal(8), input) – Transmit data input; can be carried directly from a UTMI interface.
tx_valid (Signal(), input) – When high, the tx_data input is used to update the CRC.

Parameters:

initial_value ([int, Const]) – The initial value of the CRC shift register; the USB default is used if not provided.

add_interface(interface: DataCRCInterface)

Adds an interface to the CRC generator module.

Each interface can reset the CRC; and can read the current CRC value. No arbitration is performed; it’s assumed that no more than one interface will be computing a running CRC at at time.

Parameters:: interface (DataCRCInterface) – The interface to be added; accepts control signals from other modules, and brings CRC output to them. This method can be called multiple times to generate multiplpe CRCs.

class sol_usb.gateware.usb.usb2.packet.USBDataPacketReceiver(*args, src_loc_at: int = 0, **kwargs)

Gateware that converts received USB data packets into a data-stream packets.

It’s important to note that packet payloads are mostly directly carried over from UTMI. Since USB data is received -prior- to its CRC, one cannot know if a packet is valid until after it has been completely received. As a result, this interface will generate data of unknown validity, followed by a strobe on either packet_complete or crc_mismatch. The receiving interface must be prepared to handle crc_mismatch by discarding the received data.

Variables:

data_crc (DataCRCInterface) – Connection to the CRC generator.
timer (InterpacketTimerInterface) – Connection to our interpacket timer.
stream (USBOutDataStream, output) – Stream that carries captured packet data.
active_pid (Signal(4), output) – The PID of the data currently being received.
packet_id (Signal(4), output) – The packet ID of the most recently captured PID. Becomes valid simultaneous to a strobe on packet_complete or crc_mismatch.
packet_complete (Signal(), output) – Strobe that pulses high when a new packet is delivered with a valid CRC.
crc_mismatch (Signal(), output) – Strobe that pulses high when the given packet has a CRC mismatch; and thus the data received this far should be discarded.
ready_for_response (Signal(), output) – Strobe that indicates that an inter-packet delay has passed since packet_complete, and thus we’re now ready to respond with a handshake.

Parameters:

utmi (UTMIInterface, or equivalent) – The UTMI bus to observe.
max_packet_size (int) – The maximum packet (payload) size to be deserialized, in bytes.
standalone (bool) – Debug value. If True, a submodule CRC generator will be created.
speed (USBSpeed) – USBSpeed signal or constant that specifies our speed in standalone mode.

class sol_usb.gateware.usb.usb2.packet.USBDataPacketDeserializer(*args, src_loc_at: int = 0, **kwargs)

Gateware that captures USB data packet contents and parallelizes them.

Variables:

data_crc (DataCRCInterface) – Connection to the CRC generator.
new_packet (Signal(), output) – Strobe that pulses high for a single cycle when a new packet is delivered.
packet_id (Signal(4), output) – The packet ID of the captured PID.
packet (Signal(max_packet_size), output) – Packet data for a the most recently received packet.
length (Signal(range(0, max_packet_length +1)), output) – The length of the packet data presented on the packet[] output.

Parameters:

utmi (UTMIInterface, or equivalent) – The UTMI bus to observe.
max_packet_size (int) – The maximum packet (payload) size to be deserialized, in bytes.
create_crc_generator (bool) – If True, a submodule CRC generator will be created. Excellent for testing.

class sol_usb.gateware.usb.usb2.packet.USBDataPacketGenerator(*args, src_loc_at: int = 0, **kwargs)

Module that converts a FIFO-style stream into a USB data packet.

Handles steps such as PID generation and CRC-16 injection.

As a special case, if the stream pulses last (with valid = 1) without pulsing first, we’ll send a zero-length packet.

Variables:

data_pid (Signal(2), input) – The data packet number to use. The potential PIDS are: 0 = DATA0, 1 = DATA1, 2 = DATA2, 3 = MDATA; the interface is designed so that most endpoints can tie the MSb to zero and then perform PID toggling by toggling the LSb.
crc (DataCRCInterface) – Interface to our data CRC generator.
stream (USBInStreamInterface) – Stream input for the raw data to be transmitted.
tx (UTMITransmitInterface) – UTMI-subset transmit interface

Parameters:

standalone (bool) – If True, this unit will include its internal CRC generator. Perfect for unit testing or debugging.

class sol_usb.gateware.usb.usb2.packet.USBHandshakeGenerator(*args, src_loc_at: int = 0, **kwargs)

Module that generates handshake packets, on request.

Attributes:

issue_ack: Signal(), input: Pulsed to generate an ACK handshake packet.
issue_nak: Signal(), input: Pulsed to generate a NAK handshake packet.
issue_stall: Signal(), input: Pulsed to generate a STALL handshake.
tx: UTMITransmitInterface: Interface to the relevant UTMI interface.

class sol_usb.gateware.usb.usb2.packet.USBInterpacketTimer(*args, src_loc_at: int = 0, **kwargs)

Module that tracks inter-packet timings, enforcing spec-mandated packet gaps.

Ports other than speed are added dynamically via :method:add_interface`.

Variables:: speed (Signal(2), input) – The device’s current operating speed. Should be a USBSpeed enumeration value – 0 for high, 1 for full, 2 for low.

add_interface(interface: InterpacketTimerInterface)

Adds a connection to a user of this module.

This module performs no multiplexing; it’s assumed only one interface will be active at a time.

Parameters:: interface (InterpacketTimerInterface) – The InterPacketTimer interface to add to our module.