DFv1 to DFv2 driver migration

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

Before you start

Before you begin working on driver migration, review some of the key concepts related to DFv2 and familiarize yourself with your DFv1 driver's unit tests and integration tests.

Key differences between DFv1 and DFv2

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.

Expected outcome

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

  • The driver can be registered with the DFv2 driver manager.
  • The driver can bind to a device node in the system.
  • Other Fuchsia components and drivers in the system can use the driver's capabilities.
  • Fuchsia devices can be flashed with product images containing the driver.
  • The driver passes all existing unit tests and integration tests.

Driver migration playbook

This playbook is designed to guide you through the migration tasks in a linear manner, which are divided into the following two phases:

  1. Migrate from DFv1 to DFv2: Update the driver's legacy DDK interfaces and other services to DFv2.
  2. Migrate from Banjo to FIDL: Update the Banjo protocols used by the driver to FIDL to finish the migration.

However, keep in mind that depending on your driver's features or settings, you may need to complete additional tasks that aren't covered in this playbook.

Extensions

The following guides are added to support tasks that were previously missing in the playbook: