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

// TODO(teisenbe): Move these interfaces to be internal to the devmgr codebase

using fuchsia.io;
using zx;

/// This has the same structure as zx_device_prop_t.
type DeviceProperty = struct {
    id uint16;
    reserved uint16;
    value uint32;
};

type PropertyValue = strict union {
    1: int_value uint32;
    2: str_value string:STR_LENGTH_MAX;
    3: bool_value bool;
};

type DeviceStrProperty = struct {
    key string:STR_LENGTH_MAX;
    value PropertyValue;
};

type DevicePropertyList = struct {
    props vector<DeviceProperty>:PROPERTIES_MAX;
    str_props vector<DeviceStrProperty>:STR_PROPERTIES_MAX;
};

// TODO(bwb): Make this descriptive of binding, not zx_bind_inst_t
// currently a magic bitfield defined in binding.h
type BindInstruction = struct {
    /// bitfield that encodes the operation and execution conditions
    op uint32;
    /// bitfield that encodes the arguments
    arg uint32;
    /// bitfield that encodes debugging information
    debug uint32;
};

// Identifier used to let the devcoordinator describe specific devices during
// composite construction
alias LocalDeviceId = uint64;

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

/// Maximum number of bytes in a path
// The simple name PATH_MAX collides with a musl #define on c++ bindings.
const DEVICE_PATH_MAX uint32 = 1024;

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

/// Maximum number of bytes in a metadata payload
const METADATA_BYTES_MAX uint32 = 8192;

/// Maximum number of metadata that can be added to a device
const METADATA_MAX uint32 = 32;

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

/// Maximum number of string properties that can be attached to a device
const STR_PROPERTIES_MAX uint32 = 256;

/// Maximum length of a string property key and value.
const STR_LENGTH_MAX uint32 = 255;

/// Maximum number of fragments that a composite device can have
const FRAGMENTS_MAX uint32 = 16;

/// Maximum number of parts that a composite device fragment can have
const DEVICE_FRAGMENT_PARTS_MAX uint32 = 16;

/// Maximum number of instructions in the match program of a device fragment part
const DEVICE_FRAGMENT_PART_INSTRUCTIONS_MAX uint32 = 32;

// Maximum number of instructions in a driver bind program
const BIND_RULES_INSTRUCTIONS_MAX uint32 = 256;

/// Bit flags for device add configuration
type AddDeviceConfig = strict bits : uint32 {
    /// Device can be a fragment in multiple composite devices
    ALLOW_MULTI_COMPOSITE = 0x00000001;
    /// Device should not trigger the auto-bind mechanism
    SKIP_AUTOBIND = 0x00000004;
};

/// A part of a description of a DeviceFragment
type DeviceFragmentPart = struct {
    match_program vector<BindInstruction>:DEVICE_FRAGMENT_PART_INSTRUCTIONS_MAX;
};

/// A piece of a composite device
type DeviceFragment = struct {
    name string:32;
    parts vector<DeviceFragmentPart>:DEVICE_FRAGMENT_PARTS_MAX;
};

/// Metadata that can be added to a device
type DeviceMetadata = struct {
    key uint32;
    data vector<uint8>:METADATA_BYTES_MAX;
};

/// Composite device parts and properties
type CompositeDeviceDescriptor = struct {
    props vector<DeviceProperty>:PROPERTIES_MAX;
    str_props vector<DeviceStrProperty>:STR_PROPERTIES_MAX;
    fragments vector<DeviceFragment>:FRAGMENTS_MAX;
    primary_fragment_index uint32;
    spawn_colocated bool;
    metadata vector<DeviceMetadata>:<METADATA_MAX, optional>;
};

/// A enum of CompatibilityTestStatus
type CompatibilityTestStatus = strict enum : uint32 {
    OK = 1;
    ERR_BIND_NO_DDKADD = 2;
    ERR_BIND_TIMEOUT = 3;
    ERR_UNBIND_NO_DDKREMOVE = 4;
    ERR_UNBIND_TIMEOUT = 5;
    ERR_SUSPEND_DDKREMOVE = 6;
    ERR_INTERNAL = 7;
};

/// Protocol for controlling devices in a devhost process from the devcoordinator
protocol DeviceController {
    /// 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. Returns a `status`
    /// and optionally a channel to the driver's test output. `test_output` will be
    /// not present unless the driver is configured to run its run_unit_tests hook, in
    /// which case the other end of the channel will have been passed to the driver.
    BindDriver(resource struct {
        driver_path string:DEVICE_PATH_MAX;
        driver zx.handle:VMO;
    }) -> (resource struct {
        status zx.status;
        test_output zx.handle:<CHANNEL, optional>;
    });

    /// Give this device a channel to its shadow in another process.
    ConnectProxy(resource struct {
        shadow zx.handle:CHANNEL;
    });

    /// Ask devhost to call the device init hook.
    Init() -> (struct {
        status zx.status;
    });

    /// Ask devhost to unbind this device. On success, the remote end of this
    /// interface channel will close instead of returning a result.
    Unbind() -> (struct {}) error zx.status;

    /// Ask the devhost to complete the removal of this device, which previously had
    /// invoked `ScheduleRemove`. This is a special case that can be removed
    /// once `device_remove` invokes `unbind`.
    CompleteRemoval() -> (struct {}) error zx.status;

    /// Ask devhost to suspend this device, using the target state indicated by `flags`.
    Suspend(struct {
        flags uint32;
    }) -> (struct {
        status zx.status;
    });

    /// Ask devhost to resume this device, using the target system state indicated by
    /// 'target_system_state'.
    Resume(struct {
        target_system_state uint32;
    }) -> (struct {
        status zx.status;
    });

    /// See fuchsia.io.Directory/Open for information.
    Open(resource struct {
        flags uint32;
        mode uint32;
        path string:fuchsia.io.MAX_PATH;
        object server_end:fuchsia.io.Node;
    });
};

const FRAGMENT_NAME_MAX uint32 = 32;

type Fragment = struct {
    name string:FRAGMENT_NAME_MAX;
    id LocalDeviceId;
};

/// Protocol for controlling a driver host process from the driver manager
protocol DriverHostController {
    /// 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 `coordinator`. Implements DeviceController on device_controller_rpc
    CreateDeviceStub(resource struct {
        coordinator_rpc client_end:Coordinator;
        device_controller_rpc server_end:DeviceController;
        protocol_id uint32;
        local_device_id LocalDeviceId;
    });

    /// 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 channel to a
    /// fuchsia.boot.Items protocol.
    ///
    /// `local_device_id` will be a unique value within the device's devhost
    CreateDevice(resource struct {
        coordinator_rpc client_end:Coordinator;
        device_controller_rpc server_end:DeviceController;
        driver_path string:DEVICE_PATH_MAX;
        driver zx.handle:VMO;
        parent_proxy zx.handle:optional;
        proxy_args string:<DEVICE_ARGS_MAX, optional>;
        local_device_id LocalDeviceId;
    });

    /// Introduce a composite device that has the given name and properties.
    /// `fragments` will be a list of all of the composite's fragments,
    /// described using devhost local device ids.  The order of the fragments
    /// will match the original composite creation request.  The new device will
    /// communicate with devcoordinator via `rpc`.
    ///
    /// `local_device_id` will be a unique value within the device's devhost, identifying
    /// the resulting composite device.
    CreateCompositeDevice(resource struct {
        coordinator_rpc client_end:Coordinator;
        device_controller_rpc server_end:DeviceController;
        fragments vector<Fragment>:FRAGMENTS_MAX;
        name string:DEVICE_NAME_MAX;
        local_device_id LocalDeviceId;
    }) -> (struct {
        status zx.status;
    });

    // TODO(fxbug.dev/68309): Currently unimplemented.
    /// Request to restart the driver host. Also restarts all children devices and drivers and
    /// rebinds them once the Driver Host has restarted.
    Restart() -> (struct {
        status zx.status;
    });
};

/// Interface for drivers in driver host to coordinate with the driver
/// manager.
protocol 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. `client_remote`, if present,
    /// will be passed to the device as an open connection for the client.
    /// On success, the returned `local_device_id` is the identifier assigned by devmgr.
    // TODO(fxb/74654): String properties are unimplemented.
    AddDevice(resource struct {
        coordinator server_end:Coordinator;
        device_controller client_end:DeviceController;
        property_list DevicePropertyList;
        name string:DEVICE_NAME_MAX;
        protocol_id uint32;
        driver_path string:<DEVICE_PATH_MAX, optional>;
        args string:<DEVICE_ARGS_MAX, optional>;
        device_add_config AddDeviceConfig;
        has_init bool;
        inspect zx.handle:<VMO, optional>;
        client_remote zx.handle:<CHANNEL, optional>;
    }) -> (struct {
        local_device_id LocalDeviceId;
    }) error zx.status;

    /// Requests the devcoordinator schedule the removal of this device,
    /// and the unbinding of its children.
    /// If `unbind_self` is true, the unbind hook for this device will also be called.
    ScheduleRemove(struct {
        unbind_self bool;
    });

    /// Requests the devcoordinator schedule the unbinding of this device's children.
    ScheduleUnbindChildren();

    /// 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.
    BindDevice(struct {
        driver_path string:<DEVICE_PATH_MAX, optional>;
    }) -> (struct {}) error zx.status;

    /// Returns the topological path of this device.
    GetTopologicalPath() -> (struct {
        path string:DEVICE_PATH_MAX;
    }) error zx.status;

    /// Requests that the firmware at the given path be loaded and returned.
    LoadFirmware(struct {
        driver_path string:DEVICE_PATH_MAX;
        fw_path string:DEVICE_PATH_MAX;
    }) -> (resource struct {
        vmo zx.handle:VMO;
        size uint64;
    }) error zx.status;

    /// Retrieve the metadata blob associated with this device and the given key.
    GetMetadata(struct {
        key uint32;
    }) -> (struct {
        data vector<uint8>:METADATA_BYTES_MAX;
    }) error zx.status;

    /// Retrieve the metadata size associated with this device and the given key.
    GetMetadataSize(struct {
        key uint32;
    }) -> (struct {
        size uint64;
    }) error zx.status;

    /// 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.
    AddMetadata(struct {
        key uint32;
        data vector<uint8>:<METADATA_BYTES_MAX, optional>;
    }) -> (struct {}) error zx.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.
    PublishMetadata(struct {
        device_path string:DEVICE_PATH_MAX;
        key uint32;
        data vector<uint8>:<METADATA_BYTES_MAX, optional>;
    }) -> (struct {}) error zx.status;

    /// Adds the given composite device.  This causes the devcoordinator to try to match the
    /// fragments against the existing device tree, and to monitor all new device additions
    /// in order to find the fragments as they are created.
    AddCompositeDevice(struct {
        name string:DEVICE_NAME_MAX;
        comp_desc CompositeDeviceDescriptor;
    }) -> (struct {}) error zx.status;

    /// Run Compatibility tests for the driver that binds to this device.
    /// The hook_wait_time is the time that the driver expects to take for
    /// each device hook in nanoseconds.
    /// Returns whether the compatibility tests started, and does not convey
    /// anything about the status of the test.
    RunCompatibilityTests(struct {
        hook_wait_time int64;
    }) -> (struct {
        status CompatibilityTestStatus;
    }) error zx.status;
};