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](https://fuchsia.dev/docs/concepts/drivers/driver_framework) (DFv2).

## Before you start

Before you begin working on driver migration, review some of the
[key concepts](https://fuchsia.dev/docs/concepts/drivers/README) 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](https://fuchsia.dev/docs/concepts/components/v2/README). Like any other Fuchsia component, a DFv2 driver
exposes and receives [FIDL](https://fuchsia.dev/docs/concepts/fidl/overview) 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 Kit) 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.

### 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](https://fuchsia.dev/docs/concepts/drivers/driver_framework#driver_manager).
- The driver can bind to a [device node](https://fuchsia.dev/docs/concepts/drivers/drivers_and_nodes) 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**](https://fuchsia.dev/docs/development/drivers/migration/migrate-from-dfv1-to-dfv2/overview): Update the driver's legacy DDK interfaces and other services to DFv2.
2. [**Migrate from Banjo to FIDL**](https://fuchsia.dev/docs/development/drivers/migration/migrate-from-banjo-to-fidl/overview): 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:

- [**Set up the compat device server in a DFv2 driver**](https://fuchsia.dev/docs/development/drivers/migration/set-up-compat-device-server): Set up the compat device server in a DFv2 driver and use it for communicating with DFv1 drivers.
- [**Connect and serve Banjo protocols in a DFv2 driver**](https://fuchsia.dev/docs/development/drivers/migration/serve-banjo-protocols): Serve Banjo protocols in a DFv2 driver and connect to its Banjo server from a DFv1 child driver.
- [**Set up services in a DFv2 driver**](https://fuchsia.dev/docs/concepts/drivers/driver_communication): Set up services in a DFv2 driver so that the driver's services can be discovered by other Fuchsia components in the system.

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/drivers/migration/README.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/drivers/migration/README.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/drivers/migration/README.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/drivers/migration/README.md "Edit the source code of this page")