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 ddk.protocol.usb.function;
6
7using ddk.protocol.usb.request;
8using zircon.hw.usb;
9using zx;
10
11[Layout = "ddk-protocol"]
12interface UsbFunction {
13    /// Registers callbacks to the USB function driver.
14    SetInterface(UsbFunctionInterface @interface) -> (zx.status s);
15
16    /// Allocates a unique interface descriptor number.
17    AllocInterface() -> (zx.status s, uint8 intf_num);
18
19    /// Allocates a unique endpoint descriptor number.
20    AllocEp(uint8 direction) -> (zx.status s, uint8 address);
21
22    /// Configures an endpoint based on provided descriptors.
23    ConfigEp(zircon.hw.usb.UsbEndpointDescriptor ep_desc,
24                zircon.hw.usb.UsbSsEpCompDescriptor ss_comp_desc) -> (zx.status s);
25
26    /// Disables the specified endpoint.
27    DisableEp(uint8 address) -> (zx.status s);
28
29    /// Adds a string descriptor to the device configuration.
30    AllocStringDesc(string @string) -> (zx.status s, uint8 index);
31
32    /// Queues a USB request with the lower level driver.
33    RequestQueue(ddk.protocol.usb.request.UsbRequest? usb_request,
34                 ddk.protocol.usb.request.UsbRequestComplete? complete_cb) -> ();
35
36    /// Stalls the specified endpoint.
37    EpSetStall(uint8 ep_address) -> (zx.status s);
38
39    /// Clears a stall condition for the specified endpoint.
40    EpClearStall(uint8 ep_address) -> (zx.status s);
41
42    /// Returns the size needed for a |usb_request_t|, including private storage needed by the
43    /// HCI driver.
44    GetRequestSize() -> (usize size);
45};
46
47/// Interface implemented by the USB function driver.
48[Layout = "ddk-interface"]
49interface UsbFunctionInterface {
50    /// Returns the size of the descriptor list for the function.
51    GetDescriptorsSize() -> (usize size);
52
53    /// Returns the descriptor list for the function.
54    /// TODO(voydanoff) - descriptors will likely vary (different max packet sizes, etc)
55    /// depending on whether we are in low/full, high or super speed mode.
56    /// We will need to add a usb_speed_t argument to this callback.
57    GetDescriptors() -> (vector<voidptr> descriptors);
58
59    /// Callback for handling ep0 control requests.
60    Control(zircon.hw.usb.UsbSetup setup, vector<voidptr> write) -> (zx.status status,
61                                                                     vector<voidptr> read);
62    /// Called to inform the function driver when the USB device configured state changes.
63    /// Called with configured == true in response to a SET_CONFIGURATION control request
64    /// that selects a configuration that contains this function. In this case, the function driver
65    /// should call usb_function_config_ep() to configure its endpoints.
66    /// Called with configured == false when configuration is disabled or USB is disconnected.
67    /// The function driver should then call usb_function_disable_ep() to disable its endpoints.
68    SetConfigured(bool configured, zircon.hw.usb.UsbSpeed speed) -> (zx.status s);
69
70    /// Called to set an alternate setting for an interface due to a SET_INTERFACE control request.
71    /// The function driver should call usb_function_config_ep() and/or usb_function_config_ep()
72    /// to configure or disable the interface's endpoints as appropriate.
73    SetInterface(uint8 interface, uint8 alt_setting) -> (zx.status s);
74};
75