// 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;
};