fuchsia.driver.framework

Added: 13

PROTOCOLS

CompositeNodeManager

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Protocol through which board drivers can create composite node specs.

Composite node specs are created at runtime to dynamically bridge the static bind rules of a composite driver with the dynamic bind properties of nodes in the system so that the driver bind rules are more generic and reusable.

AddSpec

Adds the given composite node specification to the driver framework.

Request

NameType
payload CompositeNodeSpec

Response

NameType
payload CompositeNodeManager_AddSpec_Result

Driver

Defined in fuchsia.driver.framework/driver.fidl

This protocol is used by the Driver Framework's Driver Host to communicate various messages and lifecycle hooks to the driver. The connection for this protocol is established through the |DriverRegistration| defined in the driver_symbols library.

Once the driver has closed its server end, the Driver Framework will initiate the shutdown of all dispatchers belonging to this driver.

Added: 15

Start

Starts the driver with the given |start_args|.

Drivers should finish their initial setup and enumeration before returning from |Start|. In particular they should enumerate all currently available nodes by utilizing fuchsia.driver.framework/Node.AddChild and waiting for all calls to be completed.

The Framework will not consider the driver to be started until this call has returned successfully. Therefore a driver will not have |Stop| called on it until after it has replied to |Start| successfully.

If a driver returns an error, it will not have |Stop| called on it before the Driver Framework initiates shutdown of the driver's dispatchers. Therefore it should have performed all necessary cleanup before returning an error.

Request

NameType
start_args DriverStartArgs

Response

NameType
payload Driver_Start_Result

Stop

Stops the driver. To stop, the driver should teardown any resources it set up in or after |Start|. This is a one-way FIDL method. When the driver has completed stopping, it should close its server end. Asynchronous operations should fully complete before closing the server end.

Request

<EMPTY>

Node

Defined in fuchsia.driver.framework/topology.fidl

Protocol through which a driver manages a node that it is bound to.

AddChild

Adds a child node to this node.

If node is present, this driver takes responsibility for binding to the newly created child. Otherwise, the driver framework will locate an appropriate driver to bind the child to.

Request

NameType
args NodeAddArgs
controller server_end<NodeController>
node server_end<Node>?

Response

NameType
payload Node_AddChild_Result

NodeController

Defined in fuchsia.driver.framework/topology.fidl

Protocol through which a parent node controls one of its children.

OnBind

Event that is triggered when the associated Node is bound to a driver.

Response

<EMPTY>

Remove

Removes the node and all of its children.

Request

<EMPTY>

RequestBind

Request that the framework attempts to bind a driver to this node. This is an additional request for binding as the framework attempts to bind a node once when the node is created.

  • error ZX_ERR_ALREADY_BOUND if the node is already bound and force_rebind is false.
  • error ZX_ERR_ALREADY_EXISTS if the node has an outstanding |RequestBind| call which has not completed.

Request

NameType
payload NodeControllerRequestBindRequest

Response

NameType
payload NodeController_RequestBind_Result

STRUCTS

BindRule

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Represents a bind rule in a parent specification.

FieldTypeDescriptionDefault
key NodePropertyKey

Property key.

 No default
condition Condition

Condition for evaluating the property values in the matching process. The values must be ACCEPT or REJECT.

 No default
values vector<NodePropertyValue>[64]

A list of property values. Must not be empty. The property values must be the same type.

 No default

CompositeNodeManager_AddSpec_Response

Defined in fuchsia.driver.framework/composite_node_spec.fidl

<EMPTY>

Driver_Start_Response

Defined in fuchsia.driver.framework/driver.fidl

<EMPTY>

NodeController_RequestBind_Response

Defined in fuchsia.driver.framework/topology.fidl

<EMPTY>

NodeProperty

Defined in fuchsia.driver.framework/topology.fidl

Definition of a property for a node. A property is commonly used to match a node to a driver for driver binding.

FieldTypeDescriptionDefault
key NodePropertyKey

Key for the property.

 No default
value NodePropertyValue

Value for the property.

 No default

Node_AddChild_Response

Defined in fuchsia.driver.framework/topology.fidl

<EMPTY>

ParentSpec

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Specification for a node that parents the composite node created from the composite node specification.

FieldTypeDescriptionDefault
bind_rules vector<BindRule>[64]

Parent's bind rules. Property keys must be unique. Must not be empty.

 No default
properties vector<NodeProperty>[64]

Properties for matching against a composite driver's bind rules. Keys must be unique.

 No default

ENUMS

CompositeNodeSpecError flexible

Type: uint32

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Error codes for the CompositeNodeManager protocol.

NameValueDescription
1

An argument of the composite node spec was not provided.
2

The given composite node spec's nodes is empty.
3

The name in the given composite node spec is a duplicate of an already created composite node spec.

Condition strict

Type: uint32

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Represents a bind rule condition.

NameValueDescription
0
1
2

NodeError flexible

Type: uint32

Defined in fuchsia.driver.framework/topology.fidl

Error codes for the Node protocol.

NameValueDescription
1
2
3
4

The Node's name is invalid. Specifically, it must not contain a period in its name.
5

A sibling Node exists with the same name.
6

An offer for this Node is missing a source name.
7

An offer for this Node should not have a source or target.
8

A symbol for this Node is missing a name.
9

A symbol for this Node is missing an address.
10

There is another symbol for this Node with the same name.

TABLES

CompositeNodeSpec

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Struct that represents a composite node specification.

OrdinalFieldTypeDescription
name string

The composite node spec's name.
parents vector<ParentSpec>

The nodes in the composite node spec. Must not be empty. The first node is the primary node.

DevfsAddArgs resource

Defined in fuchsia.driver.framework/topology.fidl

OrdinalFieldTypeDescription
connector fuchsia.device.fs/Connector

This is the connector to be installed in devfs. Connect() will be called when a client connects to this node in the filesystem. Optional: If this is not provided then an empty node will appear in devfs.
class_name string[255]

This is the class name for installing this node in devfs. The node will be placed within /dev/class/{class_name}. If class_name does not exist under /dev/class/ it will be created. Optional: If this is not provided then the node will only be added via topological path.
inspect handle<vmo>

This is a vmo of inspect data that will be installed in devfs. Optional: If this is not provided then the devfs's inspect data will be empty.

DriverStartArgs resource

Defined in fuchsia.driver.framework/driver_start_args.fidl

Arguments for starting a driver.

OrdinalFieldTypeDescription
node Node

Node that the driver is bound to.
symbols vector<NodeSymbol>[64]

Symbols provided to the driver, for |node|. These come from the driver that added |node|, and are filtered to the symbols requested in the bind program.
url fuchsia.url/Url

URL of the package containing the driver. This is purely informational, used only to provide data for inspect.
program fuchsia.data/Dictionary

Information about the driver to start. Currently, we support the following entries:

  1. "binary": a string containing the package-relative path to the driver binary.
  2. "colocate" (optional): a string containing "true" or "false" specifying whether the driver should be colocated in the same driver host as the driver that added |node|. If not specified, the driver will be launched in a new driver host.
  3. "default_dispatcher_opts" (optional): an array of strings specifying the options for creating the default dispatcher. A string can be one of the following:
    • allow_sync_calls: allows synchronous calls to be done on the default dispatcher's thread.
  4. "default_dispatcher_scheduler_role" (optional): the scheduler role to set for the default dispatcher created for the driver.
incoming vector<fuchsia.component.runner/ComponentNamespaceEntry>[32]

Incoming namespace provided to the driver.
outgoing_dir server_end<fuchsia.io/Directory>

Outgoing directory served by the driver.
config handle<vmo>

Configuration passed to the driver.
node_name string

The name of the node the driver is bound to.

NodeAddArgs resource

Defined in fuchsia.driver.framework/topology.fidl

Arguments for adding a node.

OrdinalFieldTypeDescription
name NodeName

Name of the node.
offers vector<fuchsia.component.decl/Offer>[128]

Capabilities to offer to the driver that is bound to this node. The driver must ensure these capabilities are added to its outgoing directory before adding the child node.
symbols vector<NodeSymbol>[64]

Functions to provide to the driver that is bound to this node.
properties NodePropertyVector

Properties of the node.
devfs_args DevfsAddArgs

The arguments for how this node should be added to devfs.

NodeControllerRequestBindRequest

Defined in fuchsia.driver.framework/topology.fidl

OrdinalFieldTypeDescription
force_rebind bool

If this is true, then the node unbinds from its matched driver before it attempts to bind through the normal bind process.
driver_url_suffix string

If this is set, then only drivers matching this URL suffix will be considered in binding. E.g: "gpt.cm", "meta/gpt.cm", "fuchsia-boot:///#meta/gpt.cm".

NodeSymbol

Defined in fuchsia.driver.framework/topology.fidl

Definition of a symbol provided by a driver for a node. A symbol is local to a driver host.

OrdinalFieldTypeDescription
name string[128]

Name of the symbol.
address uint64

Virtual address of the symbol, within a driver host's process.

UNIONS

CompositeNodeManager_AddSpec_Result strict

Defined in fuchsia.driver.framework/composite_node_spec.fidl

OrdinalVariantTypeDescription
response CompositeNodeManager_AddSpec_Response
err CompositeNodeSpecError
transport_err internal

Driver_Start_Result strict

Defined in fuchsia.driver.framework/driver.fidl

OrdinalVariantTypeDescription
response Driver_Start_Response
err zx/Status
transport_err internal

NodeController_RequestBind_Result strict

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
response NodeController_RequestBind_Response
err zx/Status
transport_err internal

NodePropertyKey strict

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
int_value NodePropertyKeyUint
string_value NodePropertyKeyString

NodePropertyValue flexible

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
int_value NodePropertyValueUint
string_value NodePropertyValueString
bool_value NodePropertyValueBool
enum_value NodePropertyValueEnum

Node_AddChild_Result strict

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
response Node_AddChild_Response
err NodeError
transport_err internal

CONSTANTS

NameValueTypeDescription
MAX_NAMESPACE_COUNT fuchsia.component.runner/MAX_NAMESPACE_COUNT uint32
MAX_NODE_NAME_LENGTH 128 uint8
MAX_OFFER_COUNT fuchsia.component/MAX_DYNAMIC_OFFER_COUNT uint32
MAX_PROPERTY_COUNT 64 uint8
MAX_SYMBOL_COUNT 64 uint8
MAX_SYMBOL_NAME_LENGTH 128 uint8

ALIASES

NameValueDescription
NodeName string[MAX_NODE_NAME_LENGTH]
NodePropertyKeyString string[256]
NodePropertyKeyUint uint32
NodePropertyValueBool bool
NodePropertyValueEnum string[256]
NodePropertyValueString string[256]
NodePropertyValueUint uint32
NodePropertyVector vector[MAX_PROPERTY_COUNT]