Update driver interfaces to DFv2

This page provides instructions, best practices, and examples related to updating a DFv1 driver to start using DFv2 interfaces.

Update dependencies from DDK to DFv2

DFv1 drivers use the DDK library (//src/lib/ddk). For DFv2 drivers, you can safely remove all package dependencies under this DDK library directory and replace them with the following new library, which includes most of the essential utilities for DFv2 drivers:

//sdk/lib/driver/component/cpp:cpp

In header files, include the following library for the new DFv2 driver interfaces:

#include <lib/driver/component/cpp/driver_base.h>

After updating dependencies from DDK to DFv2, your driver won't compile until you complete the next Update the driver interfaces from DFv1 to DFv2 section.

Update the driver interfaces from DFv1 to DFv2

DFv2 provides a virtual class called DriverBase that wraps regular routines for a driver. For DFv2 drivers, inheriting DriverBase in your new driver class is recommended, which makes the interfaces much simpler.

For example, let's say you have the following class in your DFv1 driver:

class MyExampleDriver;

using MyExampleDeviceType = ddk::Device<MyExampleDriver, ddk::Initializable,
   ddk::Unbindable>;

class MyExampleDriver : public MyExampleDeviceType {
 public:
  void DdkInit(ddk::InitTxn txn);
  void DdkUnbind(ddk::UnbindTxn txn);
  void DdkRelease();
}

If you update the interface to inherit from DriverBase, the new class may look like below:

class MyExampleDriver : public fdf::DriverBase {
  public:
    Driver(fdf::DriverStartArgs start_args,
        fdf::UnownedSynchronizedDispatcher driver_dispatcher);

    zx::result<> Start() override;
    void Stop() override;
}

In addition to starting and stopping the driver (as shown in the example above), the DriverBase class provides the objects that enable the driver to communicate with other components (and drivers). For instance, instead of declaring and creating your own outgoing directory in DFv1 (as in the Migrate from Banjo to FIDL phase), your driver can now call the outgoing() method of the DriverBase class to retrieve an outgoing directory, for example:

class DriverBase {
   ...
   // Used to access the outgoing directory that the driver is serving. Can be used to add both
   // zircon and driver transport outgoing services.
   std::shared_ptr<OutgoingDirectory>& outgoing() { return outgoing_; }

   ...
}

(Source: driver_base.h)

Another useful class available in DFv2 is the Node class. The example below shows a DFv2 driver's code that connects to the Node server and uses the AddChild() function to add a child node:

zx::result<> MyExampleDriver::Start() {
  fidl::WireSyncClient<fuchsia_driver_framework::Node> node(std::move(node()));
  auto args = fuchsia_driver_framework::wire::NodeAddArgs::Builder(arena)
                    .name(arena, “example_node”)
                    .Build();

  auto controller_endpoints = fidl::Endpoints<fuchsia_driver_framework::NodeController>::Create();

  auto result = node_->AddChild(args, std::move(controller_endpoints.server), {});
  if (!result.ok()) {
    FDF_LOG(ERROR, "Failed to add child: %s", result.status_string());
    return zx::error(result.status());
  }
  return zx::ok();
}

The NodeController endpoint (controller_endpoints in the example above) passed to the AddChild() function can be used to control the child node. For instance, this endpoint can be used to remove the child node from the node topology, request the driver framework to bind the node to a specific driver, or receive a callback when the child node is bound. The example below shows a DFv2 driver's code that removes the child node during shutdown:

void MyExampleDriver::Stop() {
  // controller_endpoints defined in the previous example.
  fidl::WireSyncClient<fuchsia_driver_framework::NodeController>
       node_controller(controller_endpoints.client);

  auto status = node_controller->Remove();
  if (!status.ok()) {
    FDF_LOG(ERROR, "Could not remove child: %s", status.status_string());
  }
}

Moreover, in DFv2, the OnBind() event is defined in the NodeController protocol, which is invoked by the child node from the server side. The DriverBase::PrepareStop() function provides a chance to perform de-initializations before DriverBase::Stop() is called.

The table below shows the mapping of the common driver and device interfaces between DFv1 and DFv2:

DFv1 DFv2
zx_driver_ops::bind() DriverBase::Start()
zx_driver_ops::init() DriverBase::Start()
zx_driver_ops::release() DriverBase::Stop()
device_add()

DdkAdd()		 Node::AddChild()
device_add_composite()

DdkAddComposite()		 None. Add composite nodes using specifications. See Composite Node.
device_add_composite_node_spec()

DdkAddCompositeNodeSpec()		 CompositeNodeManager::AddSpec()
zx_protocol_device::init()

DdkInit()		 None. In DFv2, a driver is in charge of the life cycle of the nodes (devices) it adds.
zx_protocol_device::unbind()

DdkUnbind()		 None. In DFv2, a driver is in charge of the life cycle of the nodes (devices) it adds.
zx_protocol_device::release()

DdkRelease()		 NodeController::Remove()
zx_protocol_device::get_protocol()

device_get_protocol()		 None. These methods are based on Banjo protocols In DFv2, all communications are in FIDL.
zx_protocol_device::service_connect()

device_service_connect()

DdkServiceConnect()		 None. This is an old-fashioned approach for drivers to establish FIDL connections with each other. For more information, see Use the DFv2 service discovery.
Device_connect_runtime_protocol()

DdkConnectRuntimeProtocol()		 None. These are newly added methods for service and protocol discovery in DFv1. For more information, see Use the DFv2 service discovery.

Use the DFv2 logger

Instead of using zxlogf() (which is deprecated in DFv2), the new logging mechanism in DFv2 depends on the fdf::Logger object, which is passed from the driver host through DriverStartArgs when starting the driver.

The fdf::DriverBase class wraps fdf::Logger and the driver can get its reference by calling the logger() method (see this wlantap-driver driver example). With this reference, you can print out logs using the logger.logf() function or using these macros, for example:

FDF_LOG(INFO, "Example log message here");

Update the macro

Aside from updating the interfaces, you need to change the macro that populates your driver interface functions:

  • From:

    ZIRCON_DRIVER()

  • To:

    FUCHSIA_DRIVER_EXPORT()

Set up the compat device server

If your DFv1 driver talks to other DFv1 drivers that haven't yet migrated to DFv2, you need to use the compatibility shim to enable your now-DFv2 driver to talk to other DFv1 drivers in the system. For more information on setting up and using this compatibility shim in a DFv2 driver, see the Set up the compat device server in a DFv2 driver guide.

Use the DFv2 service discovery

When working on driver migration, you will likely encounter one or more of the following three scenarios in which two drivers establish a FIDL connection (in child driver -> parent driver format):

  • Scenario 1: DFv2 driver -> DFv2 driver
  • Scenario 2: DFv1 driver -> DFv2 driver
  • Scenario 3: DFv2 driver -> DFv1 driver

Scenario 1 is the standard case for DFv2 drivers (this example shows the new DFv2 syntax). To update your driver under this scenario, see the DFv2 driver to DFv2 driver section below.

Scenario 2 and 3 are more complicated because the DFv1 driver is wrapped in the compatibility shim in the DFv2 world. However, the differences are:

  • In scenario 2, this Gerrit change shows a method that exposes a service from the DFv2 parent to the DFv1 child.

  • In scenario 3, the driver is connected to the fuchsia_driver_compat::Service::Device protocol provided by the compatibility shim of the parent driver, and the driver calls the ConnectFidl() method through this protocol to connect to the real protocol (for an example, see this Gerrit change).

To update your driver under scenario 2 or 3, see the DFv1 driver to DFv2 driver (with compatibility shim) section below.

DFv2 driver to DFv2 driver

To enable other DFv2 drivers to discover your driver's service, do the following:

  1. Update your driver's .fidl file.

    The protocol discovery in DFv2 requires adding service fields for the driver's protocols, for example:

    library fuchsia.example;

@discoverable
@transport("Driver")
protocol MyProtocol {
    MyMethod() -> (struct {
        ...
    });
};

service Service {
    my_protocol client_end:MyProtocol;
};

  2. Update the child driver.

    DFv2 drivers can connect to protocols in the same way as FIDL services, for example:

    incoming()->Connect<fuchsia_example::Service::MyProtocol>();

    You also need to update the component manifest (.cml) file to use your driver runtime service, for example:

    use: [
    { service: "fuchsia.example.Service" },
]

  3. Update the parent driver.

    Your parent driver needs to use the fdf::DriverBase's outgoing() function to get the fdf::OutgoingDirectory object. Note that you must use services rather than protocols. If your driver isn't using fdf::DriverBase you must create and serve an fdf::OutgoingDirectory on your own.

    Then you need to add the runtime service to your outgoing directory. The example below is a driver that inherits from the fdf::DriverBase class:

    zx::status<> Start() override {
  auto protocol = [this](
      fdf::ServerEnd<fuchsia_example::MyProtocol> server_end) mutable {
    // bindings_ is a class field with type fdf::ServerBindingGroup<fuchsia_example::MyProtocol>
    bindings_.AddBinding(
      dispatcher()->get(), std::move(server_end), this, fidl::kIgnoreBindingClosure);
  };

  fuchsia_example::Service::InstanceHandler handler(
       {.my_protocol = std::move(protocol)});

  auto status =
        outgoing()->AddService<fuchsia_wlan_phyimpl::Service>(std::move(handler));
  if (status.is_error()) {
    return status.take_error();
  }

  return zx::ok();
}

    Update the child node's NodeAddArgs to include an offer for your runtime service, for example:

    auto offers =
    std::vector{fdf::MakeOffer2<fuchsia_example::Service>(arena, name)};

fidl::WireSyncClient<fuchsia_driver_framework::Node> node(std::move(node()));
  auto args = fuchsia_driver_framework::wire::NodeAddArgs::Builder(arena)
                    .name(arena, “example_node”)
                    .offers2(offers)
                    .Build();

  zx::result controller_endpoints =
       fidl::CreateEndpoints<fuchsia_driver_framework::NodeController>();
  ZX_ASSERT(controller_endpoints.is_ok());

  auto result = node_->AddChild(
      args, std::move(controller_endpoints->server), {});

    Similarly, update the parent driver's component manifest (.cml) file to offer your runtime service, for example:

    capabilities: [
    { service: "fuchsia.example.Service" },
],

expose: [
    {
        service: "fuchsia.example.Service",
        from: "self",
    },
],

DFv1 driver to DFv2 driver (with compatibility shim)

To enable other DFv1 drivers to discover your DFv2 driver's service, do the following:

  1. Update the DFv1 drivers.

    You need to update the component manifest (.cml) files of the DFv1 drivers in the same way as mentioned in the DFv2 driver to DFv2 driver section above, for example:

    • Child driver:

      {
    include: [
        "//sdk/lib/driver_compat/compat.shard.cml",
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        compat: "driver/child-driver-name.so",
        bind: "meta/bind/child-driver-name.bindbc",
        colocate: "true",
    },
    use: [
        { service: "fuchsia.example.Service" },
    ],
}

    • Parent driver:

      {
    include: [
        "//sdk/lib/driver_compat/compat.shard.cml",
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        compat: "driver/parent-driver-name.so",
        bind: "meta/bind/parent-driver-name.bindbc",
    },
    capabilities: [
        { service: "fuchsia.example.Service" },
    ],
    expose: [
        {
            service: "fuchsia.example.Service",
            from: "self",
        },
    ],
}

  2. Update the DFv2 driver.

    The example below shows a method that exposes a service from the DFv2 parent to the DFv1 child:

      fit::result<fdf::NodeError> AddChild() {
    fidl::Arena arena;

    auto offer = fdf::MakeOffer2<ft::Service>(kChildName);

    // Set the properties of the node that a driver will bind to.
    auto property =
        fdf::MakeProperty(1 /*BIND_PROTOCOL */, bind_fuchsia_test::BIND_PROTOCOL_COMPAT_CHILD);

    auto args = fdf::NodeAddArgs{
      {
        .name = std::string(kChildName),
        .properties = std::vector{std::move(property)},
        .offers2 = std::vector{std::move(offer)},
      }
    };

    // Create endpoints of the `NodeController` for the node.
    auto endpoints = fidl::CreateEndpoints<fdf::NodeController>();
    if (endpoints.is_error()) {
      return fit::error(fdf::NodeError::kInternal);
    }

    auto add_result = node_.sync()->AddChild(fidl::ToWire(arena, std::move(args)),
                                             std::move(endpoints->server), {});

    (Source: root-driver.cc)

Update component manifests of other drivers

To complete the migration of a DFv1 driver to DFv2, you not only need to update the component manifest (.cml) file of your target driver, but you may also need to update the component manifest files of some other drivers that interact with your now-DFv2 driver.

Do the following:

  1. Update the component manifests of leaf drivers (that is, without child drivers) with the changes below:

    • Remove //sdk/lib/driver/compat/compat.shard.cml from the include field.
    • Replace the program.compat field with program.binary.

  2. Update the component manifests of other drivers that perform the following tasks:

    • Access kernel args.
    • Create composite devices.
    • Detect reboot, shutdown, or rebind calls.
    • Talk to other drivers using the Banjo protocol.
    • Access metadata from a parent driver or forward it.
    • Talk to a DFv1 driver that binds to a node added by your driver.

    For these drivers, update their component manifest with the changes below:

    • Copy some of the use capabilities from compat.shard.cml to the component manifest, for example:

      use: [
    {
        protocol: [
            "fuchsia.boot.Arguments",
            "fuchsia.boot.Items",
            "fuchsia.device.manager.SystemStateTransition",
            "fuchsia.driver.framework.CompositeNodeManager",
        ],
    },
    { service: "fuchsia.driver.compat.Service" },
],

    • Set the program.runner field to driver, for example:

      program: {
    runner: "driver",
    binary: "driver/compat.so",
},

Expose a devfs node from the DFv2 driver

To expose a devfs node from a DFv2 driver, you need to add the device_args member to the NodeAddArgs. In particular, it requires specifying the class name as well as implementing the connector, which can be simplified by making use of the Connector library, for example:

zx::result connector = devfs_connector_.Bind(dispatcher());
if (connector.is_error()) {
  return connector.take_error();
}

auto devfs =
    fuchsia_driver_framework::wire::DevfsAddArgs::Builder(arena).connector(
        std::move(connector.value()));

auto args = fuchsia_driver_framework::wire::NodeAddArgs::Builder(arena)
                    .name(arena, name)
                    .devfs_args(devfs.Build())
                    .Build();

(Source: parent-driver.cc)

For more information, see Expose the driver capabilities in the DFv2 driver codelab. Also, see this implementation of the ExportToDevfs method mentioned in the codelab.

Use dispatchers

Dispatchers fetch data from a channel between a FIDL client-and-server pair. By default, FIDL calls in this channel are asynchronous.

For introducing asynchronization to drivers in DFv2, see the following suggestions:

  • The fdf::Dispatcher::GetCurrent() method gives you the default dispatcher that the driver is running on (see this aml-ethernet driver example). If possible, it is recommended to use this default dispatcher alone.

  • Consider using multiple dispatchers for the following reasons (but not limited to):

    • The driver requires parallelism for performance.

    • The driver wants to perform blocking operations (because it is either a legacy driver or a non-Fuchsia driver being ported to Fuchsia) and it needs to handle more work while blocked.

  • If multiple dispatchers are needed, the fdf::Dispatcher::Create() method can create new dispatchers for your driver. However, you must call this method on the default dispatcher (for example, call it inside the Start() hook) so that the driver host is aware of the additional dispatchers that belong to your driver.

  • In DFv2, you don't need to shut down the dispatchers manually. They will be shut down between the PrepareStop() and Stop() calls.

For more details on migrating a driver to use multiple dispatchers, see the Update the DFv1 driver to use non-default dispatchers section (in the Migrate from Banjo to FIDL phrase).

Use the DFv2 inspect

To set up driver-maintained inspect metrics in DFv2, you need to create an inspect::ComponentInspector object, for example:

component_inspector_ =
    std::make_unique<inspect::ComponentInspector>(out, dispatcher, *inspector_);

(Source: driver-inspector.cc)

Creating an inspect::ComponentInspector object needs the following three input items:

  • The component::OutgoingDirectory object from the Context().outgoing()->component() call

  • A dispatcher

  • The original inspect::Inspector object

However, the DFv2 inspect does not require passing the VMO of inspect::Inspector to the driver framework.

(Optional) Implement your own load_firmware method

If your DFv1 driver calls the load_firmware() function in the DDK library, you need to implement your own version of this function because an equivalent function is not available in DFv2.

This function is expected to be simple to implement. You need to get the backing VMO from the path manually. For an example, see this Gerrit change.

(Optional) Use the node properties generated from FIDL service offers

DFv2 nodes contain the node properties generated from the FIDL service offers from their parents.

For instance, in the Parent Driver (The Server) example, the parent driver adds a node called "parent" with a service offer for fidl.examples.EchoService. In DFv2, a driver that binds to this node can have a bind rule for that FIDL service node property, for example:

using fidl.examples.echo;

fidl.examples.echo.Echo == fidl.examples.echo.Echo.ZirconTransport;

For more information, see the Generated bind libraries section of the FIDL tutorial page.

Update unit tests to DFv2

The mock_ddk library (which is used in unit tests for testing driver and device life cycle) is specific to DFv1. The new DFv2 test framework (see this Gerrit change) makes mocked FIDL servers available to DFv2 drivers through the TestEnvironment class.

The following libraries are available for unit testing DFv2 drivers:

  • //sdk/lib/driver/testing/cpp

    • TestNode – This class implements the fuchsia_driver_framework::Node protocol, which can be provided to a driver to create child nodes. This class is also used by tests to access the child nodes that the driver has created.

    • TestEnvironment – A wrapper over an OutgoingDirectory object that serves as the backing VFS (virtual file system) for the incoming namespace of the driver under test.

    • DriverUnderTest – This class is a RAII (Resource Acquisition Is Initialization) wrapper for the driver under test.

    • DriverRuntime – This class is a RAII wrapper over the managed driver runtime thread pool.

  • //sdk/lib/driver/testing/cpp/driver_runtime.h

    • TestSynchronizedDispatcher – This class is a RAII wrapper over the driver dispatcher.

The following library may be helpful for writing driver unit tests:

Lastly, the following example unit tests cover different configurations and test cases:

Additional resources

Some DFv2 drivers examples:

All the Gerrit changes mentioned in this section:

All the source code files mentioned in this section:

All the documentation pages mentioned in this section:

Previous
Frequently asked questions