| // 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 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); |
| |
| /// 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); |
| |
| /// Watches a directory, receiving events of added messages on the |
| /// watcher request channel. |
| /// See fuchisa.io.Directory for more information. |
| 0x10000024: DirectoryWatch(uint32 mask, uint32 options, handle<channel> watcher) |
| -> (zx.status s); |
| }; |