blob: 68187ee0a474f558fecd93bf0cd7845e235b5bbb [file] [log] [blame]
// 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 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 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);
/// 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);