// 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.device.manager;

using zx;

// This definition must be the same size as zx_device_prop_t and is checked by
// static assert.  Once the bindings better handle vectors of structs (FIDL-323)
// and we can move the binding struct definition into a more generate-able form,
// we can make this reflect the actual structure.
using DeviceProperty = uint64;

/// This definition must match ZX_DEVICE_NAME_MAX and is checked by a static assert.
const uint32 DEVICE_NAME_MAX = 31;

/// Maximum number of bytes in a path
const uint32 PATH_MAX = 1024;

/// Maximum number of bytes in a device arguments string.
const uint32 DEVICE_ARGS_MAX = 1024;

/// Maximum number of bytes in a metadata payload
const uint32 METADATA_MAX = 4096;

/// Maximum number of bytes in a command string
const uint32 COMMAND_MAX = 1024;

/// Maxmimum number of properties that can be attached to a device
const uint32 PROPERTIES_MAX = 256;

// All functions in these interfaces have the most-significant-byte set to 0x01 to allow
// multiplexing these interfaces and parts of the fuchsia.io interfaces.
// TODO(ZX-2922): I believe this shouldn't be necessary anymore.

/// Interface for controlling a device in a devhost process from the devcoordinator.
[Layout = "Simple"]
interface Controller {
    // TODO(ZX-2921): These should probably return a status?

    /// Create a device in the devhost that only implements the device protocol
    /// and claims to support the given |protocol_id|.  This device will communicate
    /// with the devcoordinator via |rpc|.
    0x10000001: CreateDeviceStub(handle<channel> rpc, uint32 protocol_id);

    /// Create a device in the devhost representing the shadowed half of device
    /// in another devhost.  This new device will communicate with the devcoordinator
    /// via |rpc|, and with its other half via |parent_proxy|.
    ///
    /// The new device will have the given driver responsible for running its half
    /// of the driver's cross-process protocol.  It's create() method will be invoked,
    /// giving it access to |parent_proxy| and |proxy_args|.
    ///
    /// parent_proxy, if present, will usually be a channel to the upper half of
    /// a shadowed device.  The one exception is when this method is used
    /// to create the Platform Bus, in which case it will be a VMO containing
    /// the ZBI.
    0x10000002: CreateDevice(handle<channel> rpc, string:PATH_MAX driver_path,
                             handle<vmo> driver, handle? parent_proxy,
                             string:DEVICE_ARGS_MAX? proxy_args);

    /// Bind the requested driver to this device.  |driver_path| is informational,
    /// but all calls to BindDriver/CreateDevice should use the same |driver_path|
    /// each time they use a |driver| VMO with the same contents.
    0x10000003: BindDriver(string:PATH_MAX driver_path, handle<vmo> driver)
                    -> (zx.status status);

    /// Give this device a channel to its shadow in another process.
    0x10000004: ConnectProxy(handle<channel> shadow);

    /// Ask this device to enter the suspend state indicated by |flags|.
    0x10000005: Suspend(uint32 flags) -> (zx.status status);

    /// Ask the devhost to remove this device.  On success, the remote end of
    /// this interface channel will close instead of returning a result.
    0x10000006: RemoveDevice();
};

/// Interface for the devices in devhosts to coordinate with the devcoordinator.
[Layout = "Simple"]
interface Coordinator {
    /// Record the addition of a new device that can be communicated with via |rpc|.
    /// For binding purposes, it is has properties |props|. |name| and |driver_path|
    /// are informational and used for debugging.  The device will have |protocol_id|
    /// as its primary protocol id.  |args| should only be used for shadowed devices,
    /// and will be forwarded to the shadow device.
    0x10000011: AddDevice(handle<channel> rpc,
                          vector<DeviceProperty>:PROPERTIES_MAX props,
                          string:DEVICE_NAME_MAX name, uint32 protocol_id,
                          string:PATH_MAX? driver_path, string:DEVICE_ARGS_MAX? args)
                    -> (zx.status status);

    /// Behaves as AddDevice, but marks the device as initially invisible.  This means
    /// that it will not be visible to other devices or the devfs until it is later marked
    /// visible (via MakeVisible).
    0x10000012: AddDeviceInvisible(handle<channel> rpc,
                                   vector<DeviceProperty>:PROPERTIES_MAX props,
                                   string:DEVICE_NAME_MAX name, uint32 protocol_id,
                                   string:PATH_MAX? driver_path,
                                   string:DEVICE_ARGS_MAX? args) -> (zx.status status);

    /// Record the removal of this device.
    0x10000013: RemoveDevice() -> (zx.status status);

    /// Mark this device as visible.
    0x10000014: MakeVisible() -> (zx.status status);

    /// Attempt to bind a driver against this device.  If |driver_path| is null,
    /// this will initiate the driver matching algorithm.
    /// TODO(teisenbe): Specify the behavior of invoking this multiple times.  I believe
    /// the current behavior is a bug.
    0x10000015: BindDevice(string:PATH_MAX? driver_path) -> (zx.status status);

    /// Returns the topological path of this device.
    0x10000016: GetTopologicalPath() -> (zx.status status, string:PATH_MAX? path);

    /// Requests that the firmware at the given path be loaded and returned.
    0x10000017: LoadFirmware(string:PATH_MAX fw_path)
                    -> (zx.status status, handle<vmo>? vmo, uint64 size);

    /// Retrieve the metadata blob associated with this device and the given key.
    0x10000018: GetMetadata(uint32 key)
                    -> (zx.status status, vector<uint8>:METADATA_MAX? data);

    /// Add metadata blob associated with this device and the given key.
    /// TODO(teisenbe): Document the behavior of calling this twice with the same
    /// key.  I believe the current behavior results in inaccessible data that is
    /// kept around for the lifetime of the device.
    0x10000019: AddMetadata(uint32 key, vector<uint8>:METADATA_MAX? data)
                    -> (zx.status status);

    /// Behaves like AddMetadata, but instead of associating it with the
    /// requesting device, associates it with the device at |device_path|.  If
    /// the device at |device_path| is not a child of the requesting device AND
    /// the requesting device is not running in the sys devhost, then this will
    /// fail.
    0x1000001a: PublishMetadata(string:PATH_MAX device_path, uint32 key,
                                vector<uint8>:METADATA_MAX? data) -> (zx.status status);

    /// Special commands for implementing the dmctl device.
    // TODO(teisenbe): We should revisit how these are carried over.

    /// Execute the given string command.  This is mostly used for accessing debug
    /// interfaces, but also as a backdoor for plumbing that has not been fully
    /// solved.
    0x10000020: DmCommand(handle<socket>? log_socket, string:COMMAND_MAX? command)
                    -> (zx.status status);

    /// Opens a new virtual console and transfers a handle to it over |vc_receiver|.
    0x10000021: DmOpenVirtcon(handle<channel> vc_receiver);

    /// Register a watcher with the system for device lifecycle changes.  There
    /// can only be one watcher.  Any subsequent calls will close the previous
    /// channel.
    0x10000022: DmWatch(handle<channel> watcher);

    /// Perform an mexec with the given kernel and bootdata.
    /// See ZX-2069 for the thoughts on deprecating mexec.
    0x10000023: DmMexec(handle<vmo> kernel, handle<vmo> bootdata);
};