Request

Control

Full-gateware control request handlers.

class sol_usb.gateware.usb.request.control.ControlRequestHandler(*args, src_loc_at: int = 0, **kwargs)

Pure-gateware USB control request handler.

handle_register_write_request(m, new_value_signal, write_strobe, stall_condition=0)

Fills in the current state with a request handler meant to set a register.

Parameters:

  • new_value_signal – The signal to receive the new value to be applied to the relevant register.

  • write_strobe – The signal which will be pulsed when new_value_signal contains a update.

  • stall_condition – If provided, if this condition is true, the request will be STALL’d instead of acknowledged.

handle_simple_data_request(m, transmitter, data, length=1)

Fills in a given current state with a request that returns a given piece of data.

For e.g. GET_CONFIGURATION and GET_STATUS requests.

Parameters:

  • transmitter – The transmitter module we’re working with.

  • data – The data to be returned.

Interface

Request components shared between USB2 and USB3.

class sol_usb.gateware.usb.request.interface.SetupPacket

Record capturing the content of a setup packet.

Components (O = output from setup parser; read-only input to others):
O: received – Strobe; indicates that a new setup packet has been received,

and thus this data has been updated.

O: is_in_request – High if the current request is an ‘in’ request. O: type[2] – Request type for the current request. O: recipient[5] – Recipient of the relevant request.

O: request[8] – Request number. O: value[16] – Value argument for the setup request. O: index[16] – Index argument for the setup request. O: length[16] – Length of the relevant setup request.

Standard

Standard, full-gateware control request handlers.

class sol_usb.gateware.usb.request.standard.StandardRequestHandler(*args, src_loc_at: int = 0, **kwargs)

Pure-gateware USB setup request handler. Implements the standard requests required for enumeration.

Parameters:

  • descriptors (DeviceDescriptorCollection) – The DeviceDescriptorCollection that contains our descriptors.

  • max_packet_size (int, optional) – The maximum packet size for the endpoint associated with this handler.

  • blacklist (iterable of functions that accept a SetupPacket and return a boolean) – Collection of functions that determine if a given packet will be handled by this request handler.

  • avoid_blockram (int, optional) – If True, placing data into block RAM will be avoided.

Windows

class sol_usb.gateware.usb.request.windows.WindowsRequestHandler(*args, src_loc_at: int = 0, **kwargs)

The platform-specific handler for Windows requests.

Parameters:

  • descriptors – A collection of the platform-specific descriptors to respond to Windows with as requested.

  • maxPacketSize – The size of the largest allowable packet configured on endpoint 0.

Notes

The handler operates by reacting to incoming setup packets targeted directly to the device with the request type set to vendor-specific. It handles this and responds in accordance with the Microsoft OS 2.0 Descriptors Specification.

The main thing this handler has to deal with are the vendor requests to the device as the usb_construct.emitters.descriptors.microsoft.PlatformDescriptorCollection and descriptor system deals with the the rest of the spec.

To this end, when triggered, the handler works as follows:

  • The state machine does switches from IDLE into the CHECK_GET_DESCRIPTOR_SET state,

  • In the following cycle, we validate the request parameters and if they check out we enter the GET_DESCRIPTOR_SET state,

  • In the GET_DESCRIPTOR_SET state, when the data phase begins, we set our instance of the dragonBoot.windows.descriptorSet.GetDescriptorSetHandler running,

  • While the requested descriptor has not yet been delivered in full, we track data phase acks and:

    • When each complete packet is acked, update state in the dragonBoot.windows.descriptorSet.GetDescriptorSetHandler to keep the data flowing.

    • Keep the transmit DATA0/DATA1 packet ID value correct.

  • Once the data phase concludes and the status phase begins, we then respond to the host with an all-clear ACK

  • If either the dragonBoot.windows.descriptorSet.GetDescriptorSetHandler or the status phase concludes, we return to IDLE.

elaborate(platform) → Module

Describes the specific gateware needed to implement the platform-specific windows descriptor handling on USB EP0.

Parameters:

platform – The Torii platform for which the gateware will be synthesized.

Returns:

A complete description of the gateware behavior required.

Return type:

torii.hdl.dsl.Module

handlerCondition(setup: SetupPacket)

Defines the setup packet conditions under which the request handler will operate.

This is used to gate the handler’s operation and forms part of the condition under which the stall-only handler in dragonBoot.bootloader.DragonBoot will be triggered.

Parameters:

setup – A grouping of signals used to describe the most recent setup packet the control interface has seen.

Returns:

A combinatorial operation defining the sum conditions under which this handler will operate.

Return type:

torii.hdl.ast.Operator

Notes

The condition for the operation of this handler is defined as being:

  • A Vendor request directly to the device.

  • for either index value 0x07 or 0x08, respectively meaning:

    • GET_DESCRIPTOR_SET, and

    • SET_ALTERNATE_ENUM

The latter has not been given support as we don’t currently allow swapping out the device descriptors in this manner.

class sol_usb.gateware.usb.request.windows.descriptorSet.GetDescriptorSetHandler(*args, src_loc_at: int = 0, **kwargs)

Gateware that handles responding to Windows GET_DESCRIPTOR_SET requests.

Variables:

  • request (Signal(8), input) – The request field associated with the Get Descriptor Set request. Contains the descriptor set’s vendor code.

  • length (Signal(16), input) – The length field associated with the Get Descriptor Set request. Determines the maximum amount allowed in a response.

  • start (Signal(), input) – Strobe that indicates when a descriptor should be transmitted.

  • startPosition (Signal(11), input) – Specifies the starting position of the descriptor data to be transmitted.

  • tx (USBInStreamInterface(), inout) – The USBInStreamInterface that streams our descriptor data.

  • stall (Signal(), output) – Pulsed if a STALL handshake should be generated, instead of a response.

generateROM() → Tuple[Memory, int, int]

Generates a ROM used to hold descriptor sets.

Notes

All data is aligned to 4 byte boundaries.

This ROM is laid out as follows:

  • Index offsets and descriptor set lengths

    Each index of a descriptor set has an entry consistent of the length of the descriptor set (2 bytes) and the address of the first data byte (2 bytes).

    Address

    Data

    0000

    Length of the first descriptor set

    0002

    Address of the first descriptor set

    …

  • Data

    Descriptor data for each descriptor set. Padded by 0 to the next 4-byte address.

    Address

    Data

    …

    Descriptor data
Returns:

A List containing:

  • A Memory object defining the descriptor data and access information as defined above. The memory object uses 32-bit entries which the descriptor gateware accesses accordingly.

  • The length of the largest held descriptor.

  • The highest Vendor code number used by the descriptors for retrieval.

Return type:

Tuple [ torii.hdl.mem.Memory, int, int ]

elaborate(platform) → Module

Describes the specific gateware needed to implement Windows GET_DESCRIPTOR_SET requests.

Parameters:

platform – The Torii platform for which the gateware will be synthesized.

Returns:

A complete description of the gateware behavior required.

Return type:

torii.hdl.dsl.Module