| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.hardware.usb.request; |
| |
| using fuchsia.hardware.usb.descriptor; |
| |
| alias VmoId = uint64; |
| |
| /// Arbitrary limit on the max transfer size of Requests by embedding data (see Buffer::data). |
| const MAX_TRANSFER_SIZE uint32 = 300; |
| |
| /// Data buffer. There are two supported ways data may be conveyed, corresponding to the two |
| /// members of the Buffer union: |
| /// 1) vmo_id: Pre-registered VMO. A driver may preregister VMOs using the |
| /// fuchsia.hardware.usb.endpoint.Endpoint::RegisterVmos method. These VMOs are saved by |
| /// the underlying USB driver in correspondence to the given vmo_id. Future Requests may |
| /// refer to this by the unique vmo_id. |
| /// Because VMOs are reused across Requests and saved by the underlying driver, each VMO |
| /// only needs to be pinned/unpinned once. |
| /// 2) data: A data buffer for data that is not associated with a VMO. The underlying USB driver |
| /// should allocate its own VMO, copy the data from the buffer, and pin the VMO. This |
| /// should not be used often and not for large amounts of data. |
| type Buffer = flexible resource union { |
| /// The ID of a VMO that was previously registered. |
| 1: vmo_id VmoId; |
| /// Embedded data buffer to copy data to/from. |
| 2: data vector<uint8>:MAX_TRANSFER_SIZE; |
| }; |
| |
| /// Buffer region containing data. |
| type BufferRegion = resource table { |
| /// Buffer for data |
| 1: buffer Buffer; |
| /// Offset into the VMO to start reading or writing. This is relative to the offset passed to |
| /// RegisterVmos if using vmo_id. |
| 2: offset uint64; |
| /// Number of bytes to read/write from/to this buffer region. |
| 3: size uint64; |
| }; |
| |
| /// Control Request Information |
| type ControlRequestInfo = table { |
| /// Control Transfer required Setup packet |
| 1: setup fuchsia.hardware.usb.descriptor.UsbSetup; |
| }; |
| |
| /// Bulk Request Information |
| type BulkRequestInfo = table {}; |
| |
| /// Isochronous Request Information. |
| type IsochronousRequestInfo = table { |
| /// Frame ID |
| 1: frame_id uint64; |
| }; |
| |
| /// Interrupt Request Information |
| type InterruptRequestInfo = table {}; |
| |
| /// Extra information needed for different types of Requests. |
| type RequestInfo = flexible union { |
| /// Control Request Information |
| 1: control ControlRequestInfo; |
| /// Bulk Request Information |
| 2: bulk BulkRequestInfo; |
| /// Isochronous Request Information |
| 3: isochronous IsochronousRequestInfo; |
| /// Interrupt Request Information |
| 4: interrupt InterruptRequestInfo; |
| }; |
| |
| /// Requests passed over fuchsia.hardware.usb.endpoint.Endpoint. |
| /// See fuchsia.hardware.usb.endpoint.Endpoint::QueueRequests for more details. |
| type Request = resource table { |
| /// Data. This array is consumed in-order, and allows for scatter/gather semantics across |
| /// physically non-contiguous regions of a large buffer. |
| 1: data vector<BufferRegion>:MAX; |
| /// Indicates not to complete this Request when done unless it failed. |
| /// All Requests up to the next defer_completion == false are responded to as one unit. |
| 2: defer_completion bool; |
| /// Extra information needed for Request. |
| 3: information RequestInfo; |
| }; |