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. Drivers should maintain their client connection to the node. Dropping the client connection while the driver is running will cause the driver framework to remove the driver and node from the topology. If the driver has set host_restart_on_crash to "true" in their component manifest, dropping the connection will initiate a restart of the driver host and driver.

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. Integer-based keys are no longer supported. The NodePropertyKey must be a string value.

 No default
value NodePropertyValue

Value for the property.

 No default

NodeProperty2

Defined in fuchsia.driver.framework/topology.fidl

Added: NEXT

FieldTypeDescriptionDefault
key NodePropertyKeyString

Property key.

 No default
value NodePropertyValue

Property value.

 No default

NodePropertyEntry

Defined in fuchsia.driver.framework/driver_start_args.fidl

Contains the node properties that belong to a node.

Deprecated: NEXT Added: 19

FieldTypeDescriptionDefault
name NodeName

Name of the node that has |node_properties|.

 No default
properties NodePropertyVector

Node properties that belong to the node whose name is |node_name|. If the node is a composite then |properties| is empty and does not contain its parents' properties.

 No default

NodePropertyEntry2

Defined in fuchsia.driver.framework/driver_start_args.fidl

Contains the node properties that belong to a node.

Added: NEXT

FieldTypeDescriptionDefault
name NodeName

Name of the node that has |node_properties|.

 No default
properties NodeProperties

Node properties that belong to the node whose name is |node_name|. If the node is a composite then |properties| is empty and does not contain its parents' properties.

 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

BusType flexible

Type: uint32

Defined in fuchsia.driver.framework/topology.fidl

Added: NEXT

NameValueDescription
1
2
3
4
5
6
7
8
9
10
11

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.
4

The spec failed to be added to the driver index.

Added: 20

Condition strict

Type: uint32

Defined in fuchsia.driver.framework/composite_node_spec.fidl

Represents a bind rule condition.

NameValueDescription
0
1
2

DeviceAddressStability flexible

Type: uint32

Defined in fuchsia.driver.framework/topology.fidl

Added: NEXT

NameValueDescription
0

When the driver is restarted, the device address may change.
1

When the system is restarted, the device address may change.
2

When the system is updated, the device address may change.
3

The device address on the bus is guaranteed stable for the lifetime of the system.

DriverPackageType flexible

Type: uint8

Defined in fuchsia.driver.framework/driver_info.fidl

The type of Fuchsia package that a driver component is inside of. More details about the various package categories are available at: https://fuchsia.dev/fuchsia-src/concepts/packages/package#types_of_packages

Added: 16

NameValueDescription
0

BOOT packages are inside the Zircon boot image.
1

BASE packages are included in the Fuchsia build as static local packages.
2

CACHED packages are BASE packages that can be updated during a resolve if a full package resolver is available.
3

UNIVERSE packages get onto the device only when resolved by the full package resolver.

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.
11

The node is in the process of unbinding all of its children.

Added: 20
12

The Node contains unsupported arguments, such as deprecated property keys or offers.

Added: NEXT

TABLES

BusInfo

Defined in fuchsia.driver.framework/topology.fidl

Added: NEXT

OrdinalFieldTypeDescription
bus BusType

The type of bus this node sits on.
address DeviceAddress

A unique identifier that describes the identity of this device on the given bus.
address_stability DeviceAddressStability

How stable the address.

CompositeDriverInfo

Defined in fuchsia.driver.framework/driver_info.fidl

Information for a composite driver.

Added: 16

OrdinalFieldTypeDescription
composite_name string

The name of the composite as specified in the driver's composite bind rules.
driver_info DriverInfo

General information for the driver.

CompositeDriverMatch

Defined in fuchsia.driver.framework/driver_info.fidl

Information for a composite driver that has matched with a composite.

Added: 16

OrdinalFieldTypeDescription
composite_driver CompositeDriverInfo

Information for the composite driver that has matched.
parent_names vector<string>

A list of all the parent names, ordered by index. These names come from the node definitions in the driver's composite bind rules.
primary_parent_index uint32

The primary node index. Identified by the primary node in the driver's composite bind rules.

CompositeInfo

Defined in fuchsia.driver.framework/driver_info.fidl

Information for a composite that is defined by a composite node spec.

Added: 16

OrdinalFieldTypeDescription
spec CompositeNodeSpec

The spec information that this composite node spec was created with.
matched_driver CompositeDriverMatch

Information for the node spec that is available only when a driver has matched to the properties in this spec's parents.

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.

CompositeParent

Defined in fuchsia.driver.framework/driver_info.fidl

A parent to a composite that is defined by a composite node spec.

Added: 16

OrdinalFieldTypeDescription
composite CompositeInfo

Information about the composite that this is a parent of.
index uint32

The index of this parent in the spec's parents.

DevfsAddArgs resource

Defined in fuchsia.driver.framework/topology.fidl

OrdinalFieldTypeDescription
connector client_end: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.
connector_supports fuchsia.device.fs/ConnectionType

The connection types that are supported by the |connector| given. The driver framework should handle connection types that are not supported by the connector. If not provided, only the device type is assumed as supported by the connector.

Added: 16
controller_connector client_end:fuchsia.device.fs/Connector

This is the controller connector to be installed in devfs. Connect() will be called when a client connects to the device_controller connection for this node in the filesystem. Optional: If this is not provided then the Node will handle the connection natively. This option should only be used by the compat shim or in tests

Added: HEAD

DeviceCategory

Defined in fuchsia.driver.framework/driver_info.fidl

Device categories as provided in the driver's component manifest.

Added: 16

OrdinalFieldTypeDescription
category string
subcategory string

DriverInfo

Defined in fuchsia.driver.framework/driver_info.fidl

General information for a driver, used with both composite and normal drivers.

Added: 16

OrdinalFieldTypeDescription
url string:4096

URL of the driver component.
name string

Name of the driver, taken from the first field of the ZIRCON_DRIVER macro in the driver.
colocate bool

If this is true then the driver should be colocated in its parent's DriverHost.
package_type DriverPackageType

The type of package this driver is in.
is_fallback bool

If this is true then the driver is a fallback driver. Fallback drivers have a lesser priority for binding, so they will only be chosen for binding if there is no non-fallback driver that has matched.
device_categories vector<DeviceCategory>

Device categories
bind_rules_bytecode vector<uint8>

Bind rules which declare set of constraints to evaluate in order to determine whether the driver indexer should bind this driver to a device.
driver_framework_version uint8

The version of the driver framework that this driver is using. Supported values are 1 (DFv1) and 2 (DFv2). If not provided, 1 is the assumed version.
is_disabled bool

Whether the driver is disabled. If true, this driver is not chosen to bind to nodes.

Added: 17

DriverStartArgs resource

Defined in fuchsia.driver.framework/driver_start_args.fidl

Arguments for starting a driver.

OrdinalFieldTypeDescription
node client_end: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.
node_properties NodePropertyDictionary

Node properties of the node the driver is bound to. If the node is non-composite then the "default" entry will contain the node's own properties. If the node is a composite then there is an entry for each of its parents and the "default" entry will reference the primary composite parent node's properties. The composite parent node's properties are those that were provided in the composite node specification and not the original properties of the parent.

Deprecated: NEXT Added: 19
node_offers NodeOffersVector

Node offers of the node the driver is bound to.

Added: 25
node_token handle<event>

Provides a token representing this node which can be exchanged with the driver framework to discern additional information about this node.

Added: NEXT
node_properties_2 NodePropertyDictionary2
Added: NEXT

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.

Removed: 19 Deprecated: 18
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.
offers2 NodeOffersVector

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.

Added: 18
bus_info BusInfo

Information that feeds into a structured bus topology for the device. It should only be specified by bus drivers, ideally those which are included by default.

Added: NEXT

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
framework_err internal

DeviceAddress flexible

Defined in fuchsia.driver.framework/topology.fidl

Added: NEXT
OrdinalVariantTypeDescription
int_value uint8

A fixed integer id, eg a spi bus address
array_int_value vector<uint8>:10

An array of integers, eg a PCI BDF.
char_int_value string:4

A uint32 value that can be interpretted as a 4 character sequence.
array_char_int_value vector<string:4>:10

An array of character sequences, eg a ACPI node path.
string_value string:32

A generic string, eg the device tree node path.

Driver_Start_Result strict

Defined in fuchsia.driver.framework/driver.fidl

OrdinalVariantTypeDescription
response Driver_Start_Response
err zx/Status
framework_err internal

NodeController_RequestBind_Result strict

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
response NodeController_RequestBind_Response
err zx/Status
framework_err internal

NodePropertyKey strict

Defined in fuchsia.driver.framework/topology.fidl

OrdinalVariantTypeDescription
int_value NodePropertyKeyUint

Integer-based keys are no longer supported. Use |string_value| instead.
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
framework_err internal

Offer flexible

Defined in fuchsia.driver.framework/topology.fidl

Added: 18
OrdinalVariantTypeDescription
zircon_transport fuchsia.component.decl/Offer
driver_transport fuchsia.component.decl/Offer

CONSTANTS

NameValueTypeDescription
MAX_DEVICE_ADDRESS_ARRAY_LEN 10 uint32
Added: NEXT
MAX_DEVICE_ADDRESS_STR_LEN 32 uint32
Added: NEXT
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_RESOURCE_NAME_LENGTH 128 uint8
Added: 18
MAX_SYMBOL_COUNT 64 uint8
MAX_SYMBOL_NAME_LENGTH 128 uint8

ALIASES

NameValueDescription
NodeName string[MAX_NODE_NAME_LENGTH]
NodeOffersVector vector[MAX_OFFER_COUNT]
Added: 18
NodeProperties vector[MAX_PROPERTY_COUNT]
Added: NEXT
NodePropertyDictionary vector[fidl/MAX]
Deprecated: NEXT Added: 19
NodePropertyDictionary2 vector[fidl/MAX]
Added: NEXT
NodePropertyKeyString string[256]
NodePropertyKeyUint uint32
NodePropertyValueBool bool
NodePropertyValueEnum string[256]
NodePropertyValueString string[256]
NodePropertyValueUint uint32
NodePropertyVector vector[MAX_PROPERTY_COUNT]