1/// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5library fuchsia.hardware.usb.device;
6
7using zx;
8
9const uint32 DEVICE_DESC_SIZE = 18;         /// sizeof(usb_device_descriptor_t)
10const uint32 MAX_CONFIG_DESC_SIZE = 65536;  /// UINT16_MAX
11const uint32 MAX_STRING_DESC_SIZE = 384;    /// See GetStringDescriptor description below
12
13[Layout = "Simple"]
14interface Device {
15    /// Returns the speed of the USB device as a usb_speed_t value.
16    1: GetDeviceSpeed() -> (uint32 speed);
17
18    /// Returns the device's USB device descriptor.
19    2: GetDeviceDescriptor() -> (array<uint8>:DEVICE_DESC_SIZE desc);
20
21    /// Returns the total size of the USB configuration descriptor for the given configuration.
22    3: GetConfigurationDescriptorSize(uint8 config) -> (zx.status s, uint16 size);
23
24    /// Returns the device's USB configuration descriptor for the given configuration.
25    4: GetConfigurationDescriptor(uint8 config) -> (zx.status s,
26                                                    vector<uint8>:MAX_CONFIG_DESC_SIZE desc);
27
28    /// Fetches a string descriptor from the USB device.
29    //
30    /// desc_id          :   The ID of the string descriptor to fetch, or 0 to fetch
31    ///                      the language table instead.
32    //
33    /// lang_id          :   The language ID of the string descriptor to fetch.
34    ///                      If no matching language ID is present in the device's language
35    ///                      ID table, the first entry of the language ID table will
36    ///                      be substituted.
37    /// actual_lang_id   :   The actual language ID of the string fetched, or 0 for
38    ///                      the language ID table.
39    //
40    /// The worst case size for the payload of a language ID table should be 252
41    /// bytes, meaning that a 256 byte buffer should always be enough to hold any
42    /// language ID table.
43    //
44    /// The worst case size for a UTF-8 encoded string descriptor payload should be
45    /// 378 bytes (126 UTF-16 code units with a worst case expansion factor of 3)
46    5: GetStringDescriptor(uint8 desc_id, uint16 lang_id) -> (zx.status s,
47                                                              vector<uint8>:MAX_STRING_DESC_SIZE desc,
48                                                              uint16 actual_lang_id);
49
50    /// Selects an alternate setting for an interface on a USB device.
51    6: SetInterface(uint8 interface_number, uint8 alt_setting) -> (zx.status s);
52
53    /// Returns an implementation specific device ID for a USB device.
54    /// For informational purposes only.
55    7: GetDeviceId() -> (uint32 device_id);
56
57    /// Returns the implementation specific device ID for the hub that a USB device is connected to.
58    /// For informational purposes only.
59    8: GetHubDeviceId() -> (uint32 hub_device_id);
60
61    /// Returns the device's current configuration.
62    9: GetConfiguration() -> (uint8 configuration);
63
64    /// Sets the device's current configuration.
65    10: SetConfiguration(uint8 configuration) -> (zx.status s);
66};
67