// 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 MAX_FUNCTION_DESCRIPTORS uint32 = 32;
const MAX_CONFIG_DESCRIPTORS uint32 = 5;
const MAX_STRING_DESCRIPTORS uint32 = 255;

const MAX_STRING_LENGTH uint32 = 127;

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

alias ConfigurationDescriptor = vector<FunctionDescriptor>:MAX_FUNCTION_DESCRIPTORS;

/// The fields in DeviceDescriptor match those in usb_descriptor_t in the USB specification,
/// except for the string fields.
type DeviceDescriptor = struct {
    bcd_usb uint16;
    b_device_class uint8;
    b_device_sub_class uint8;
    b_device_protocol uint8;
    b_max_packet_size0 uint8;
    id_vendor uint16;
    id_product uint16;
    bcd_device uint16;
    manufacturer string:MAX_STRING_LENGTH;
    product string:MAX_STRING_LENGTH;
    serial string:MAX_STRING_LENGTH;
    b_num_configurations uint8;
};

/// 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.
closed protocol Events {
    /// Invoked when a function registers
    strict FunctionRegistered() -> ();
    /// Invoked when all functions have been cleared.
    strict FunctionsCleared();
};

closed 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.
    strict SetConfiguration(struct {
        device_desc DeviceDescriptor;
        config_descriptors vector<ConfigurationDescriptor>:MAX_CONFIG_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.
    strict ClearFunctions() -> ();
    /// Adds a state change listener that is invoked when a state change completes.
    strict SetStateChangeListener(resource struct {
        listener client_end:Events;
    });
};