sdk/fidl/fuchsia.hardware.usb.device/usb-device.fidl

// 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 fuchsia.hardware.usb.device;

using zx;

/// sizeof(usb_device_descriptor_t)
const DEVICE_DESC_SIZE uint32 = 18;

/// UINT16_MAX
const MAX_CONFIG_DESC_SIZE uint32 = 65536;

/// See GetStringDescriptor description below
const MAX_STRING_DESC_SIZE uint32 = 384;

protocol Device {
    /// Returns the speed of the USB device as a usb_speed_t value.
    GetDeviceSpeed() -> (struct {
        speed uint32;
    });

    /// Returns the device's USB device descriptor.
    GetDeviceDescriptor() -> (struct {
        desc array<uint8, DEVICE_DESC_SIZE>;
    });

    /// Returns the total size of the USB configuration descriptor for the given configuration.
    GetConfigurationDescriptorSize(struct {
        config uint8;
    }) -> (struct {
        s zx.status;
        size uint16;
    });

    /// Returns the device's USB configuration descriptor for the given configuration.
    GetConfigurationDescriptor(struct {
        config uint8;
    }) -> (struct {
        s zx.status;
        desc vector<uint8>:MAX_CONFIG_DESC_SIZE;
    });

    /// Fetches a string descriptor from the USB device.
    ///
    /// desc_id          :   The ID of the string descriptor to fetch, or 0 to fetch
    ///                      the language table instead.
    ///
    /// lang_id          :   The language ID of the string descriptor to fetch.
    ///                      If no matching language ID is present in the device's language
    ///                      ID table, the first entry of the language ID table will
    ///                      be substituted.
    /// actual_lang_id   :   The actual language ID of the string fetched, or 0 for
    ///                      the language ID table.
    ///
    /// The worst case size for the payload of a language ID table should be 252
    /// bytes, meaning that a 256 byte buffer should always be enough to hold any
    /// language ID table.
    ///
    /// The worst case size for a UTF-8 encoded string descriptor payload should be
    /// 378 bytes (126 UTF-16 code units with a worst case expansion factor of 3)
    GetStringDescriptor(struct {
        desc_id uint8;
        lang_id uint16;
    }) -> (struct {
        s zx.status;
        desc string:MAX_STRING_DESC_SIZE;
        actual_lang_id uint16;
    });

    /// Selects an alternate setting for an interface on a USB device.
    SetInterface(struct {
        interface_number uint8;
        alt_setting uint8;
    }) -> (struct {
        s zx.status;
    });

    /// Returns an implementation specific device ID for a USB device.
    /// For informational purposes only.
    GetDeviceId() -> (struct {
        device_id uint32;
    });

    /// Returns the implementation specific device ID for the hub that a USB device is connected to.
    /// For informational purposes only.
    GetHubDeviceId() -> (struct {
        hub_device_id uint32;
    });

    /// Returns the device's current configuration.
    GetConfiguration() -> (struct {
        configuration uint8;
    });

    /// Sets the device's current configuration.
    SetConfiguration(struct {
        configuration uint8;
    }) -> (struct {
        s zx.status;
    });
};