DFv1 to DFv2 driver migration

This playbook offers guidelines, best practices, examples, and reference materials to help you migrate existing DFv1-based drivers, which are stored in the Fuchsia source tree (fuchsia.git), to Fuchsia's new driver framework (DFv2).

Before you start

DFv2 enables Fuchsia drivers to be fully user-space components. Like any other Fuchsia component, a DFv2 driver exposes and receives FIDL capabilities to and from other components and drivers in the system.

Notice the following key differences between DFv1 and DFv2:

  • DFv1: Drivers are not components. The Banjo protocol is used for driver-to-driver communication. Driver host interfaces or the DDK (Driver Development Kits) wrapper are used to manage the life cycle of drivers.

  • DFv2: Drivers are components. FIDL is used for all communication, including communication between drivers and non-drivers. The driver framework manages the life cycle of drivers. (For more information, see Comparison between DFv1 and DFv2.)

Here is a list for the expected conditions of your driver after completing the migration to DFv2:

  • The driver can be registered with the driver manager.
  • The driver can bind to a device node in the system.
  • Fuchsia components and drivers can use the driver's capabilities.
  • Fuchsia devices can be flashed with product images containing the driver.
  • All unit tests and integration tests for the driver are passed.

Before you begin working on driver migration, familiarize yourself with the driver's unit tests and integration tests.

Two phases in driver migration

When you're ready to migrate your DFv1 driver to DFv2, this playbook can assist you with migration tasks in a linear manner. However, keep in mind that, depending on your driver's features or settings, you may need to handle additional tasks that aren't covered in this playbook.

Driver migration from DFv1 to DFv2 can be divided into two phases:

  1. Migrate from Banjo to FIDL.
  2. Migrate from DFv1 to DFv2.