system/banjo/ddk-protocol-usb-device/usb-device.banjo

// Copyright 2018 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 ddk.protocol.usb.device;

using zircon.hw.usb;
using zx;

[Layout="ddk-callback"]
interface UsbRequestComplete {
    Callback(UsbRequest2? req) -> ();
};

[Layout="ddk-callback"]
interface UsbRequestRelease {
    Callback(UsbRequest2? req) -> ();
};

/// Should be set by the requestor.
struct UsbHeader2 {
    /// Frame number for scheduling isochronous transfers.
    uint64 frame;
    uint32 device_id;
    /// bEndpointAddress from endpoint descriptor.
    uint8 ep_address;
    /// Number of bytes to transfer.
    zx.off length;
    /// Send zero length packet if length is multiple of max packet size.
    bool send_zlp;
};

/// Response data.
/// (Filled in by processor before |UsbRequestComplete()| is called)
struct UsbResponse2 {
    /// Status of transaction.
    zx.status status;
    /// Number of bytes actually transferred (on success).
    zx.off actual;
};

struct UsbRequest2 {
    UsbHeader2 header;

    /// For control transactions.
    zircon.hw.usb.UsbSetup setup;

    /// VMO handle for payload.
    handle<vmo> vmo_handle;
    handle<bti> bti_handle;
    usize size;
    /// Offset of the start of data from first page address of the vmo.
    zx.off offset;
    /// Mapped address of the first page of the vmo.
    /// Add offset to get actual data.
    vector<voidptr> virt;

    handle pmt;
    /// Phys addresses of the payload.
    vector<zx.paddr> phys_list;

    /// The |complete.callback()| callback is set by the requestor and is
    /// invoked by the 'complete' ops method when it is called by
    /// the processor upon completion of the usb request.
    /// The saved_complete_cb field can be used to temporarily save
    /// the original callback and overwrite it with the desired intermediate
    /// callback.
    UsbRequestComplete? complete;

    /// Set by the requestor for opting out of the complete_cb()
    /// callback for successfully completed requests. The callback
    /// will still be invoked if an error is encountered.
    /// This is useful for isochronous requests, where the requestor
    /// may not care about most callbacks. They will still have to request
    /// callbacks at a regular interval to queue more data, and free or
    /// reuse previously silently completed requests.
    bool cb_on_error_only;

    /// The current 'owner' of the usb request may save the original
    /// complete callback and cookie, allowing them to insert an
    /// intermediate callback.
    UsbRequestComplete? saved_complete;

    UsbResponse2 response;

    vector<voidptr> context;

    /// The release.callback() callback is set by the allocator and is
    /// invoked by the 'usb_request_release' method when it is called
    /// by the requestor.
    UsbRequestRelease? release;
};

[Layout="ddk-protocol"]
interface Usb {
    Control(uint8 request_type, uint8 @request, uint16 value, uint16 index,
                vector<voidptr> data, zx.time timeout) -> (zx.status s, usize length);
    /// queues a USB request
    RequestQueue(UsbRequest2? req) -> ();
    GetSpeed() -> (zircon.hw.usb.UsbSpeed s);
    SetInterface(int64 interface_number, uint8 alt_setting) -> (zx.status s);
    SetConfiguration(uint8 configuration) -> (zx.status s);
    GetConfiguration() -> (uint8 configuration);
    EnableEndpoint(zircon.hw.usb.UsbEndpointDescriptor ep_desc,
                   zircon.hw.usb.UsbSsEpCompDescriptor ss_com_desc,
                   bool enable) -> (zx.status s);
    /// Resets an endpoint that is in a halted or error state.
    /// Endpoints will be halted if the device returns a STALL in response to a USB transaction.
    /// When that occurs, the transaction will fail with ERR_IO_REFUSED.
    /// usb_reset_endpoint() the endpoint to normal running state.
    ResetEndpoint(uint8 ep_address) -> (zx.status s);
    /// returns the maximum amount of data that can be transferred on an endpoint in a single
    /// transaction.
    GetMaxTransferSize(uint8 ep_address) -> (usize s);
    GetDeviceId() -> (uint32 dev_id);
    GetDeviceDescriptor() -> (zircon.hw.usb.UsbDeviceDescriptor desc);
    GetConfigurationDescriptor(uint8 configuration)
           -> (vector<zircon.hw.usb.UsbConfigurationDescriptor>? desc);
    /// returns the USB descriptors for the USB device or interface
    /// the returned value is de-allocated with free()
    GetDescriptorList() -> (vector<voidptr> descriptors);
    /// Fetch the descriptor using the provided descriptor ID and language ID.  If
    /// the language ID requested is not available, the first entry of the language
    /// ID table will be used instead and be provided in the updated version of the
    /// parameter.
    ///
    /// The string will be encoded using UTF-8, and will be truncated to fit the
    /// space provided by the buflen parameter.  buflen will be updated to indicate
    /// the amount of space needed to hold the actual UTF-8 encoded string lenth, and
    /// may be larger than the original value passed.  Embedded nulls may be present
    /// in the string, and the result may not be null terminated if the string
    /// occupies the entire provided buffer.
    GetStringDescriptor(uint8 desc_id, uint16 lang_id) -> (zx.status s, uint16 lang_id,
                                                           vector<voidptr> buf);
    CancelAll(uint8 ep_address) -> (zx.status s);
    GetCurrentFrame() -> (uint64 frame);
};