// 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.peripheral;

using zx;

const uint32 MAX_FUNCTION_DESCRIPTORS = 32;
const uint32 MAX_STRING_DESCRIPTORS = 255;

const uint32 MAX_STRING_LENGTH = 127;

struct FunctionDescriptor {
    uint8 interface_class;
    uint8 interface_subclass;
    uint8 interface_protocol;
};

/// The fields in DeviceDescriptor match those in usb_descriptor_t in the USB specification,
/// except for the string fields.
struct DeviceDescriptor {
    uint16 bcdUSB;
    uint8 bDeviceClass;
    uint8 bDeviceSubClass;
    uint8 bDeviceProtocol;
    uint8 bMaxPacketSize0;
    uint16 idVendor;
    uint16 idProduct;
    uint16 bcdDevice;
    string:MAX_STRING_LENGTH manufacturer;
    string:MAX_STRING_LENGTH product;
    string:MAX_STRING_LENGTH serial;
    uint8 bNumConfigurations;
};

/// Events protocol that is used as a callback to inform the client
/// of the completion of various server-side events.
/// This callback interface can be registered using the SetStateChangeListener
/// method on the Device protocol.
[Layout = "Simple"]
protocol Events {
    /// Invoked when a function registers
    FunctionRegistered() -> ();
    /// Invoked when all functions have been cleared.
    FunctionsCleared();
};

protocol Device {
    /// Sets the device's descriptors, adds the functions and creates the child devices for the
    /// configuration's interfaces.
    /// At least one function descriptor must be provided.
    SetConfiguration(DeviceDescriptor device_desc,
                     vector<FunctionDescriptor>:MAX_FUNCTION_DESCRIPTORS function_descriptors)
        -> () error zx.status;

    /// Tells the device to remove the child devices for the configuration's interfaces
    /// and reset the list of functions to empty.
    /// The caller should wait for the |FunctionsCleared| event.
    ClearFunctions() -> ();
    /// Adds a state change listener that is invoked when a state change completes.
    SetStateChangeListener(request<Events> listener);
};