[ot] hw/opentitan: ot_usbdev: Implementation data transfers

This commit implements the logic to support data transfers and
wire them in the server. The protocol is updated with commands
to support this. Isochronous transfers are not properly supported
at the moment.

Signed-off-by: Amaury Pouly <[email protected]>

Author: pamaury

docs/opentitan/usbdev.md

@@ -105,16 +105,19 @@ The following commands are defined.
 | **Command** | **Value** | **Direction** | **Description** | **Reference** |
 | ----------- | --------- | ------------- | --------------- | ------------- |
 | Invalid     |     0     | N/A           |  To avoid 0 meaning something | |
-| Hello       |     1     | Both          | First packet sent when connecting | [`Hello` command](#hello-command) |
+| Hello       |     1     | Both          | First packet sent when connecting | [Hello command](#hello-command) |
 | VBUS On     |     2     | Host to device | Turn VBUS on | [Bus commands](#bus-commands) |
 | VBUS Off    |     3     | Host to device | Turn VBUS off | [Bus commands](#bus-commands) |
 | Connect     |     4     | Device to host | Report device connection | [Bus commands](#bus-commands) |
 | Disconnect  |     5     | Device to host | Report device disconnection | [Bus commands](#bus-commands) |
 | Reset       |     6     | Host to device | Reset the device | [Bus commands](#bus-commands) |
 | Resume      |     7     | Host to device | Resume the device | [Bus commands](#bus-commands) |
 | Suspend     |     8     | Host to device | Suspend the device | [Bus commands](#bus-commands) |
+| Setup       |     9     | Host to device | Send a SETUP packet | [Setup command](#setup-command) |
+| Transfer    |    10     | Host to device | Start a transfer | [Transfer command](#transfer-command) |
+| Complete    |    11     | Device to host | Complete a transfer | [Complete command](#complete-command) |
+
 
-**TODO** Add transfer commands
 
 #### Hello command
 
@@ -132,5 +135,143 @@ The payload of this command is defined as follows.
 These commands (VBUS On/Off, (Dis)connection, Reset, Suspend/Resume) do not have any payload.
 See the [bus states](#bus-states) section for more detail.
 
-For the Connect/Disconnect commands, which are sent by the device, the ID should be the ID of the *last command*
-processed by the device.
+For the Connect/Disconnect commands, which are sent by the device, the ID should be the ID of the
+*last command* processed by the device.
+
+Sending a `Reset`, `VBUS Off` or `Suspend` command to the device automatically cancels any pending
+`Transfer` command.
+The device *may* send a `Complete` event with the `Cancelled` status for such transfers.
+
+#### Setup command
+
+This command is used to send a SETUP packet to the device.
+The payload of this command starts with a header defined as follows.
+See [Transfer handling](#transfer-handling) for more details.
+
+| **Field** | **Offset** | **Size** | **Value** |
+| --------- | ---------- | -------- | --------- |
+| Address   |     0      |    1     | Device address |
+| Endpoint  |     1      |    1     | Endpoint number |
+| Reserved  |     2      |    2     | Set to zero |
+| Setup     |     4      |    8     | SETUP packet |
+
+Sending a `Setup` command to an endpoint automatically cancels any pending transfer on this
+endpoint.
+The device *may* send a `Complete` event to the host with the `Cancelled` status.
+
+#### Transfer command
+
+This command is used to start a transfer to or from the device.
+See [Transfer handling](#transfer-handling) for more details.
+The payload of this command is defined below.
+
+| **Field** | **Offset** | **Size** | **Value** |
+| --------- | ---------- | -------- | --------- |
+| Address   |     0      |    1     | Device address |
+| Endpoint  |     1      |    1     | Endpoint (see below) |
+| Packet Size |   2      |    2     | Packet size (see [Transfer handling](#transfer-handling)) |
+| Flags     |     4      |    1     | Transfer flags (see below) |
+| Reserved  |     5      |    3     | Set to 0 |
+| Transfer Size |  8     |    4     | Size of the data |
+| Data      |     12     | variable | Transfer data (see below) |
+
+The `Endpoint` field is encoded as follows:
+| **Field** | **Bits** | **Value** |
+| --------- | -------- | -------- |
+| EP Number | 3:0      | The endpoint number |
+| Reserved  | 6:4      | Set to 0 |
+| Direction | 7        | Set to 1 for IN endpoint and 0 for OUT endpoint |
+
+Note that when submitting a control transfer, the `Direction` field must be set
+to indicate whether this is control OUT or IN transaction.
+
+The following flags are defined.
+
+| **Flag** | **Bit** | **Meaning** |
+| -------- | ------- | ----------- |
+| ZLP      |    0    | A zero-length packet must be sent after the data (only valid for OUT transfers) |
+
+For OUT transfers, the `Transfer Size` field indicates the size of the data in the payload after
+the header.
+For IN transfers, the `Transfer Size` field indicates the maximum size of the transfers to return
+to the host.
+
+Sending a `Transfer` command to an endpoint while one is already in progress is an error.
+The device must immediately reply with a `Complete` event with the `Error` status.
+
+#### Complete command
+
+The ID of this command must be the ID of the corresponding `Transfer` command.
+See [Transfer handling](#transfer-handling) for more details.
+The payload of this command is defined as follows.
+
+| **Field** | **Offset** | **Size** | **Value** |
+| --------- | ---------- | -------- | --------- |
+| Status    |     0      |     1    | Status of the transfer (see below) |
+| Reserved  |     1      |     3    | Set to 0 |
+| Transfer Size | 4      |     4    | Amount of data transferred |
+| Data      |     8      | variable | Transfer data (see below) |
+
+The `Transfer Size` field indicates the size of the data.
+The data must only be present when completing an IN transaction.
+
+The following status codes are defined:
+
+| **Status** | **Value** | **Meaning** |
+| -------- | ------- | ----------- |
+| Success  |    0    | The data was successfully transferred |
+| Stalled  |    1    | The device stalled the transfer |
+| Cancelled |    2   | Transfer was cancelled (see below) |
+| Error    |    3    | An unspecified error occurred |
+
+A transfer may be cancelled by any bus event such a turning VBUS off, the device disconnecting,
+the host resetting or suspending the device, or the host sending a `Setup` command.
+
+
+### Transfer handling
+
+In order to perform data transfers, the host must send a correct sequence
+of Setup and Data commands, in accordance to the USB specification. The
+protocol is designed to be very low-level and only provides minimal help.
+The host is allowed to send non-spec compliant sequences to fuzz the device.
+For properly sequenced transfers, the host should follow the guidelines below.
+
+Note that the `Transfer` command allows the host to send/receive more data than the
+indicated packet size.
+In this case, the transfer will automatically be split into multiple packets
+of size `Packet Size`.
+For OUT transfers, all packets except possibly the last one will be of the size
+indicated in the command. For IN transfers, the transfer stops as soon as a
+short packet is received (packet of size less than the one indicated in the
+command).
+If the `ZLP` flag is set for an OUT transfer, the device will additionally
+receive a zero-length packet.
+If at any point during this sequence, the device stalls the transfer,
+the transfer stops and the device must send a `Complete` event to the host with the
+`Stalled` status and the `Size` field indicating how much data was transferred successfully
+(and for IN transfers, the data must be present in the payload).
+If the transfer succeeds, the device must send a `Complete` event with the `Success` status,
+the `Size` field indicating how much data was transferred successfully
+(and for IN transfers, the data must be present in the payload).
+
+### Control transfers
+
+The host should first send a `Setup` command at the selected address and endpoint.
+The device does not reply to this command. Note that the USB specification specifies
+that sending a SETUP packet to an endpoint immediately cancels any transaction on this
+endpoint. The device *may* send a `Complete` events for such transfers with the `Cancelled`
+status.
+
+The rest of the sequence depends on the direction of the transfer:
+- OUT transfers: the host should send one or more `Transfer` commands to the endpoint
+  (with the OUT direction) with the control data.
+  Once all transfers are complete, the host should send a `Transfer` command to the endpoint
+  with the IN direction and `Size` set to 0.
+- IN transfers: the host should send one or more `Transfer` commands to the endpoint,
+  (with the IN direction) to receive the control data.
+  Once all transfers are complete, the host should send a `Transfer` command to the endpoint
+  with the OUT direction and `Size` set to 0.
+
+### Bulk and interrupt transfers
+
+TODO