The driver runner is the runner responsible for launching components that run in the driver host environment.
Using the driver runner
To use the driver runner, the component's manifest must include a program
block similar to the following:
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
}
}
A driver component's program
block requires the following fields at a minimum:
runner
– This field must be set to the stringdriver
.binary
– The path to the driver's binary output in the component's package.bind
– The path to the compiled bind program in the component's package.
Optional fields
In additional to the required fields, the driver runner accepts a set of optional fields, which are used to specify metadata or configure the runtime environment of the driver component.
Colocation
If the colocate
field is set to the string true
, the driver will be put in
the same driver host as its parent driver if possible. However
this is advisory. The driver manager may still put the driver
in a separate driver host, for instance, if the parent device has MUST_ISOLATE
set. In DFv1, a driver is always colocated if the parent device is a composite –
isolation may still be enforced by setting MUST_ISOLATE
on the primary
fragment of the composite.
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
colocate: "true"
}
}
If the colocate
field is not specified, its value defaults to the string
false
.
colocate
is mutually exclusive to the host_restart_on_crash
field.
Only one of them can be true for a driver.
Default dispatcher options
The default_dispatcher_opts
field provides the options which are used when
creating the driver's default dispatcher, for example:
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
default_dispatcher_opts: [ "allow_sync_calls" ]
}
}
The options in this field correspond to the flags defined in this
types.h
file. Today, the supported options are:
allow_sync_calls
: This option indicates that the dispatcher may not share Zircon threads with other drivers. This setting allows the driver to make synchronous Banjo or FIDL calls on the dispatcher without deadlocking.
Fallback
If the fallback
field is set to the string true
, this fallback driver will
only attempt to bind once all the base driver packages are indexed. Furthermore,
if this driver matches to a node and a non-fallback driver matches to the same
node, the non-fallback driver will bind to the node instead.
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
fallback: "true"
}
}
If the fallback
field is not specified, its value defaults to the string
false
.
Device categories
The device_categories
field provides metadata indicating the device categories
that the driver controls, for example:
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
device_categories: [
{ category: "board", subcategory: "i2c" },
{ category: "sensor", subcategory: "temperature" },
]
}
}
This metadata is used to determine the tests that the driver will undergo during its certification process. See the full list of device categories and subcategories in the FHCP schema.
Host restart on crash
The host_restart_on_crash
field tells the driver framework that it should restart the
driver host for the node that the driver binds to should the driver go down unexpectedly.
This includes if:
- The driver host crashes.
- The driver closes its client end to the
fuchsia.driver.framework/Node
protocol while running.
Because this affects the driver host, it can only be set by the root driver of the host.
The root driver is the driver for which the host was created. This is the case if and only if
the colocate
field is set to false
.
Therefore host_restart_on_crash
and colocate
are mutually exclusive. Only
one of them can be true
for a driver.
{
program: {
runner: "driver",
binary: "driver/example.so",
bind: "meta/bind/example.bindbc",
host_restart_on_crash: "true"
}
}
If the host_restart_on_crash
field is not specified, its value defaults to the string
false
.
When host_restart_on_crash
is false
, the node is removed from the driver framework's
node topology if the driver goes down unexpectedly.
Further reading
For more detailed explanation of how drivers are bound, see Driver binding.