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

using zx;
using fuchsia.hardware.usb.hub;
using fuchsia.hardware.usb.hubdescriptor;
using fuchsia.hardware.usb.request;

alias UsbSpeed = uint32;

// Note: the "uint64 foo_device" parameters should be interpreted as zx_device_t*.
// TODO(https://fxbug.dev/42148112): restore types.
@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol UsbBus {
    /// Configures a new hub based on its USB hub descriptor.
    strict ConfigureHub(struct {
        @in_out
        hub_device uint64;
        speed UsbSpeed;
        desc fuchsia.hardware.usb.hubdescriptor.UsbHubDescriptor;
        multi_tt bool;
    }) -> (struct {
        s zx.Status;
    });
    /// Informs the USB bus that a new device has been added.
    strict DeviceAdded(struct {
        @in_out
        hub_device uint64;
        port uint32;
        speed UsbSpeed;
    }) -> (struct {
        s zx.Status;
    });
    /// Informs the USB bus that a device has been removed.
    strict DeviceRemoved(struct {
        @in_out
        hub_device uint64;
        port uint32;
    }) -> (struct {
        s zx.Status;
    });
    /// Used by USB hub driver to register its USB hub protocol with the USB bus driver.
    strict SetHubInterface(resource struct {
        @in_out
        usb_device uint64;
        hub client_end:fuchsia.hardware.usb.hub.UsbHubInterface;
    }) -> (struct {
        s zx.Status;
    });
    /// Queues a USB request with the host stack.
    strict RequestQueue(resource struct {
        @in_out
        usb_request fuchsia.hardware.usb.request.UsbRequest;
        @in_out
        complete_cb client_end:fuchsia.hardware.usb.request.UsbRequestCompleteCallback;
    }) -> ();
};

/// Interface for use by the HCI controller to use to notify when devices are added and removed.
@transport("Banjo")
@banjo_layout("ddk-interface")
closed protocol UsbBusInterface {
    /// Notifies the USB bus driver that a new device has been added.
    strict AddDevice(struct {
        device_id uint32;
        hub_id uint32;
        speed UsbSpeed;
    }) -> (struct {
        s zx.Status;
    });
    /// Notifies the USB bus driver that a device has been removed.
    strict RemoveDevice(struct {
        device_id uint32;
    }) -> (struct {
        s zx.Status;
    });
    /// Used by the HCI controller to reset a port on a USB hub.
    strict ResetPort(struct {
        hub_id uint32;
        port uint32;
        enumerating bool;
    }) -> (struct {
        s zx.Status;
    });
    /// Used by the HCI controller to reinitialize a device after it has been reset.
    strict ReinitializeDevice(struct {
        device_id uint32;
    }) -> (struct {
        s zx.Status;
    });
};