Endpoints

The endpoints module contains implementations of various useful endpoint interfaces.

Isochronous

Endpoint interfaces for isochronous endpoints.

These interfaces provide interfaces for connecting memories or memory-like interfaces to hosts via isochronous pipes.

class sol_usb.gateware.usb.usb2.endpoints.isochronous.USBIsochronousInEndpoint(*args, src_loc_at: int = 0, **kwargs)

Isochronous endpoint that presents a memory-like interface.

Used for repeatedly streaming data to a host from a memory or memory-like interface. Intended to be useful as a transport for e.g. video or audio data.

Variables:

  • interface (EndpointInterface) – Communications link to our USB core.

  • bytes_in_frame (Signal(range(0, 3073)), input) –

    Specifies how many bytes will be transferred during this frame. If this is 0, a single ZLP will be emitted; for any other value one, two, or three packets will be generated, depending on the packet size. Latched in at the start of each frame.

    The maximum allowed value for this signal depends on the number of transfers per (micro)frame: - If this is a high-speed, high-throughput endpoint (descriptor indicates

    maxPacketSize > 512 and multiple transfers per microframe), then this value maxes out at (N * maxPacketSize), where N is the number of transfers per microframe.

    • For all other configurations, this must be <= the maximum packet size.

  • address (Signal(range(0,3072)), output) – Indicates the address / offset of the byte currently being transmitted. Can be used to drive the ``address` lines of an asynchronous memory

  • next_address (Signal(range(0,3072)), output) – Indicates the ‘address’ / offset of the byte that should be presented on :attr:value at the next usb-clock cycle. Can be used to drive the address lines of a synchronous memory.

  • value (Signal(8), input) – The value to be transmitted, this cycle. Can be directly tied to the read port of a memory.

Parameters:

  • endpoint_number (int) – The endpoint number (not address) this endpoint should respond to.

  • max_packet_size (int) – The maximum packet size for this endpoint. Should match the wMaxPacketSize provided in the USB endpoint descriptor.

Status

Endpoint interfaces for providing status updates to the host.

These are mainly meant for use with interrupt endpoints; and allow a host to e.g. repeatedly poll a device for status.

class sol_usb.gateware.usb.usb2.endpoints.status.USBSignalInEndpoint(*args, src_loc_at: int = 0, **kwargs)

Endpoint that transmits the value of a signal to a host whenever polled.

This is intended to be usable to implement a simple interrupt endpoint that polls for a status signal.

Variables:

  • signal (Signal(<variable width>), input) – The signal to be relayed to the host. This signal’s current value will be relayed each time the host polls our endpoint.

  • interface (EndpointInterface) – Communications link to our USB device.

  • status_read_complete (Signal(), output) – Strobe that pulses high for a single usb-domain cycle each time a status read is complete.

Parameters:

  • width (int) – The width of the signal we’ll relay up to the host, in bits.

  • endpoint_number (int) – The endpoint number (not address) this endpoint should respond to.

  • endianness (str, 'big' or 'little', optional) – The endianness with which to send the data. Defaults to little endian.

  • signal_domain (str, optional) – The name of the domain :attr:signal is clocked from. If this value is anything other than ‘usb’, the signal will automatically be synchronized to the USB clock domain.

Stream

Endpoint interfaces for working with streams.

The endpoint interfaces in this module provide endpoint interfaces suitable for connecting streams to USB endpoints.

class sol_usb.gateware.usb.usb2.endpoints.stream.USBStreamInEndpoint(*args, src_loc_at: int = 0, **kwargs)

Endpoint interface that transmits a simple data stream to a host.

This interface is suitable for a single bulk or interrupt endpoint.

This endpoint interface will automatically generate ZLPs when a stream packet would end without a short data packet. If the stream’s last signal is tied to zero, then a continuous stream of maximum-length-packets will be sent with no inserted ZLPs.

The flush input may be asserted to to cause all pending data to be transmitted as soon as possible. When flush is asserted, packets of varying length will be sent as needed, according to the data available.

This implementation is double buffered; and can store a single packets worth of data while transmitting a second packet.

Variables:

  • stream (StreamInterface, input stream) – Full-featured stream interface that carries the data we’ll transmit to the host.

  • flush (Signal(), input) – Assert to cause all pending data to be transmitted as soon as possible.

  • discard (Signal(), input) – Assert to cause all pending data to be discarded.

  • interface (EndpointInterface) – Communications link to our USB device.

Parameters:

  • endpoint_number (int) – The endpoint number (not address) this endpoint should respond to.

  • max_packet_size (int) – The maximum packet size for this endpoint. Should match the wMaxPacketSize provided in the USB endpoint descriptor.

class sol_usb.gateware.usb.usb2.endpoints.stream.USBMultibyteStreamInEndpoint(*args, src_loc_at: int = 0, **kwargs)

Endpoint interface that transmits a simple data stream to a host.

This interface is suitable for a single bulk or interrupt endpoint.

This variant accepts streams with payload sizes that are a multiple of one byte; data is always transmitted to the host in little-endian byte order.

This endpoint interface will automatically generate ZLPs when a stream packet would end without a short data packet. If the stream’s last signal is tied to zero, then a continuous stream of maximum-length-packets will be sent with no inserted ZLPs.

This implementation is double buffered; and can store a single packets worth of data while transmitting a second packet.

Variables:

  • stream (StreamInterface, input stream) – Full-featured stream interface that carries the data we’ll transmit to the host.

  • interface (EndpointInterface) – Communications link to our USB device.

Parameters:

  • byte_width (int) – The number of bytes to be accepted at once.

  • endpoint_number (int) – The endpoint number (not address) this endpoint should respond to.

  • max_packet_size (int) – The maximum packet size for this endpoint. Should match the wMaxPacketSize provided in the USB endpoint descriptor.

class sol_usb.gateware.usb.usb2.endpoints.stream.USBStreamOutEndpoint(*args, src_loc_at: int = 0, **kwargs)

Endpoint interface that receives data from the host, and produces a simple data stream.

This interface is suitable for a single bulk or interrupt endpoint.

Variables:

  • stream (StreamInterface, output stream) – Full-featured stream interface that carries the data we’ve received from the host.

  • interface (EndpointInterface) – Communications link to our USB device.

Parameters:

  • endpoint_number (int) – The endpoint number (not address) this endpoint should respond to.

  • max_packet_size (int) – The maximum packet size for this endpoint. If this there isn’t max_packet_size space in the endpoint buffer, this endpoint will NAK (or participate in the PING protocol.)

  • buffer_size (int, optional) – The total amount of data we’ll keep in the buffer; typically two max-packet-sizes or more. Defaults to twice the maximum packet size.