squishy.gateware.quirks#

This module contains implementations of various non-standard or broken implementations of mechanisms or protocols that Squishy uses.

Currently the only quirks are for USB in the squishy.quirks.usb module, which contains USB descriptors specific to Windows to allow for full DFU compatibility.

This module contains USB quirks for various platforms. The lame duck is currently only Windows which needs special USB descriptors, and are in the squishy.quirks.usb.windows module.

class squishy.gateware.quirks.usb.windows.WindowsRequestHandler(*args, src_loc_at: int = 0, **kwargs)#

The Windows-specific handler for Windows requests.

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 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 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 GetDescriptorSetHandler or the status phase concludes, we return to IDLE.

handler_condition(setup: SetupPacket) → Operator#

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 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:

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