本页面提供了将驱动程序接口从 DFv1 迁移到 DFv2 的最佳实践和示例。
DFv1 驱动程序使用 DDK（驱动程序开发套件）库 (//src/lib/ddk)。在 DFv2 中，此库替换为驱动程序组件库，其中包含 DFv2 驱动程序的大部分基本实用程序。
将依赖项从 DDK 更新为 DFv2
移除 DFv1 驱动程序中 DDK 库下的所有软件包依赖项，并将其替换为新的 DFv2 库，
来源标题
替换源头文件中的 DDK 依赖项：
DFv1
//sdk/lib/driver/component/cpp:cpp
DFv2
#include <lib/driver/component/cpp/driver_base2.h>
构建依赖项
替换 BUILD.gn 文件中的 DDK 依赖项：
DFv1
"//src/lib/ddk",
"//src/lib/ddktl",
DFv2
"//sdk/lib/driver/component/cpp:cpp",
将接口从 DDK 更新为 DFv2
ddk：设备 mixin
ddk::Device<> 是在 ddktl/device.h 中定义的 mixin，可简化在 C++ 中编写 DDK 驱动程序的过程。
DFv1
以下 DFv1 驱动程序示例使用了 ddk::Device<> mixin：
#include <ddktl/device.h>
class SimpleDriver;
using DeviceType = ddk::Device<SimpleDriver, ddk::Initializable>;
class SimpleDriver : public DeviceType {
public:
explicit SimpleDriver(zx_device_t* parent);
~SimpleDriver();
static zx_status_t Bind(void* ctx, zx_device_t* dev);
void DdkInit(ddk::InitTxn txn);
void DdkRelease();
};
} // namespace simple
DFv2
在 DFv2 中，DriverBase2 类用于编写驱动程序。DFv2 驱动程序需要从 DriverBase2 类（而非 ddk::Device 混合类）继承，例如：
#include <lib/driver/component/cpp/driver_base2.h>
class SimpleDriver : public fdf::DriverBase2 {
public:
SimpleDriver();
zx::result<> Start(fdf::DriverContext context) override;
};
构造函数、init 钩子和绑定钩子
在 DFv1 中，驱动程序通过构造函数、init 钩子和绑定钩子进行初始化。
初始化钩子通常实现为 DdkInit()，例如：
void SimpleDriver::DdkInit(ddk::InitTxn txn) {}
绑定钩子是传递给 zx_driver_ops_t 结构的静态函数，例如：
zx_status_t SimpleDriver::Bind(void* ctx, zx_device_t* dev) {}
static zx_driver_ops_t simple_driver_ops = [][5] -> zx_driver_ops_t {
zx_driver_ops_t ops = {};
ops.version = DRIVER_OPS_VERSION;
ops.bind = SimpleDriver::Bind;
return ops;
}();
在 DFv2 中，所有 DFv1 逻辑都需要按以下顺序放入 DriverBase2 类的 Start() 函数中：构造函数、Init hook 和 Bind hook。
DFv1
#include <ddktl/device.h>
class SimpleDriver;
using DeviceType = ddk::Device<SimpleDriver, ddk::Initializable>;
class SimpleDriver : public DeviceType {
public:
explicit SimpleDriver(zx_device_t* parent) {
zxlogf(INFO, "SimpleDriver constructor logic");
}
~SimpleDriver() { delete this; }
static zx_status_t Bind(void* ctx, zx_device_t* dev) {
zxlogf(INFO, "SimpleDriver bind logic");
}
void DdkInit(ddk::InitTxn txn) {
zxlogf(INFO, "SimpleDriver initialized");
}
};
} // namespace simple
static zx_driver_ops_t simple_driver_ops = [][5] -> zx_driver_ops_t {
zx_driver_ops_t ops = {};
ops.version = DRIVER_OPS_VERSION;
ops.bind = SimpleDriver::Bind;
return ops;
}();
DFv2
class SimpleDriver : public fdf::DriverBase2 {
public:
SimpleDriver() : fdf::DriverBase2("simple_driver") {}
zx::result<> Start(fdf::DriverContext context) override {
fdf::info("SimpleDriver constructor logic");
fdf::info("SimpleDriver initialized");
fdf::info("SimpleDriver bind logic");
return zx::ok();
}
};
析构函数、DdkSuspend()、DdkUnbind() 和 DdkRelease()
在 DFv1 中，析构函数 DdkSuspend()、DdkUnbind() 和 DdkRelease() 用于拆解对象和线程（如需详细了解这些钩子，请参阅此 DFv1 简单驱动程序示例）。
在 DFv2 中，需要在 DriverBase2 类的 Stop() 方法（用于异步清理）或析构函数（用于同步清理）中实现拆解逻辑，例如：
class SimpleDriver : public fdf::DriverBase2 {
public:
SimpleDriver() : fdf::DriverBase2("simple_driver") {}
~SimpleDriver() override {
// Perform synchronous teardowns here
}
void Stop(fdf::StopCompleter completer) override {
// Called before the driver dispatchers are shutdown. Only implement this function
// if you need to manually clean up objects asynchronously before dispatchers shutdown.
completer(zx::ok());
}
};
此外，在迁移到 DFv2 时，请排除 DdkRelease() 方法中的自删除语句，例如：
void DdkRelease() {
delete this; // Do not migrate this statement to DFv2
}
ZIRCON_DRIVER() 宏
在 DFv1 中，驱动程序通过 ZIRCON_DRIVER() 宏进行声明。在 DFv2 中，driver_export 库取代了 ZIRCON_DRIVER() 宏。需要在驱动程序实现中声明驱动程序导出，通常是在 .cc 文件中。
DFv1
ZIRCON_DRIVER() 宏的示例：
static zx_driver_ops_t simple_driver_ops = [][5] -> zx_driver_ops_t {
zx_driver_ops_t ops = {};
ops.version = DRIVER_OPS_VERSION;
ops.bind = SimpleDriver::Bind;
return ops;
}();
ZIRCON_DRIVER(SimpleDriver, simple_driver_ops, "zircon", "0.1");
DFv2
以下 driver_export 示例迁移了 DFv1 ZIRCON_DRIVER() 宏示例：
#include <lib/driver/component/cpp/driver_export2.h>
...
FUCHSIA_DRIVER_EXPORT2(simple::SimpleDriver);
ddk::Messageable 混入
在 DFv1 中，ddk::Messageable<> 混入用于实现 FIDL 服务器。在 DFv2 中，可以通过直接从 FIDL 服务器继承来替换 ddk:Messageable<> mixin。
DFv1
using I2cDeviceType = ddk::Device<I2cChild, ddk::Messageable<fuchsia_hardware_i2c::Device>::Mixin>;
class I2cDriver : public I2cDeviceType {
...
// Functions from the fuchsia.hardware.i2c Device protocol
void Transfer(TransferRequestView request, TransferCompleter::Sync& completer) override;
void GetName(GetNameCompleter::Sync& completer) override;
}
DFv2
class I2cDriver : public DriverBase2, public fidl::WireServer<fuchsia_hardware_i2c::Device> {
...
// Functions from the fuchsia.hardware.i2c Device protocol
void Transfer(TransferRequestView request, TransferCompleter::Sync& completer) override;
void GetName(GetNameCompleter::Sync& completer) override;
}
实现 FIDL 服务器后，您需要将该服务添加到传出目录：
向驱动程序类添加
ServerBindingGroup。使用
fidl::ServerBindingGroup表示 Zircon 传输，使用fdf::ServerBindingGroup表示驱动程序传输，例如：class I2cDriver: public DriverBase2 { ... private: fidl::ServerBindingGroup<fidl_i2c::Device> bindings_; }将绑定添加到出站目录，例如：
auto serve_result = outgoing()->AddService<fuchsia_hardware_i2c::Service>( fuchsia_hardware_i2c::Service::InstanceHandler({ .device = bindings_.CreateHandler(this, dispatcher()->async_dispatcher(), fidl::kIgnoreBindingClosure), })); if (serve_result.is_error()) { fdf::error("Failed to add Device service: {}", serve_result); return serve_result.take_error(); }
DdkAdd() 和 device_add()
DdkAdd() 和 device_add() 方法用于添加子节点，例如：
zx_status_t status = device->DdkAdd(ddk::DeviceAddArgs("i2c");
如需在 DFv2 中添加子节点，请参阅编写最小 DFv2 驱动程序指南中的添加子节点部分。
DdkAddCompositeNodeSpec()
DdkAddCompositeNodeSpec() 方法会向系统添加复合节点规范，例如：
auto status = DdkAddCompositeNodeSpec("ft3x27_touch", spec);
如需了解如何在 DFv2 中添加复合节点规范，请参阅创建复合节点指南。
device_get_protocol()
device_get_protocol() 方法用于检索和连接到 Banjo 服务器。在 DFv2 中，我们将该调用替换为 compat/cpp/banjo_client 库。
DFv1
misc_protocol_t misc;
zx_status_t status = device_get_protocol(parent, ZX_PROTOCOL_MISC, &misc);
if (status != ZX_OK) {
return status;
}
DFv2
zx::result<ddk::MiscProtocolClient> client =
compat::ConnectBanjo<ddk::MiscProtocolClient>(incoming);
FIDL 连接函数
在 DFv1 中，DDK 提供了以下用于连接到 FIDL 协议的函数：
DdkConnectFidlProtocol()DdkConnectFragmentFidlProtocol()DdkConnectRuntimeProtocol()DdkConnectFragmentRuntimeProtocol()
在 DFv2 中，您可以使用驱动程序命名空间库连接到 FIDL 协议。
DdkConnectFidlProtocol()
DFv1
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> client_end =
DdkConnectFidlProtocol<fuchsia_examples_gizmo::Service::Device>();
if (client_end.is_error()) {
zxlogf(ERROR, "Failed to connect fidl protocol");
return client_end.status_value();
}
（来源：DFv1 驱动程序传输示例）
DFv2
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> connect_result =
context.incoming().Connect<fuchsia_examples_gizmo::Service::Device>();
if (connect_result.is_error()) {
fdf::error("Failed to connect gizmo device protocol: {}", connect_result);
return connect_result.take_error();
}
（来源：DFv2 驱动程序传输示例）
DdkConnectFragmentFidlProtocol()
DFv1
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> client_end =
DdkConnectFragmentFidlProtocol<fuchsia_examples_gizmo::Service::Device>(parent, "gizmo");
if (codec_client_end.is_error()) {
zxlogf(ERROR, "Failed to connect to fidl protocol: %s",
zx_status_get_string(codec_client_end.status_value()));
return codec_client_end.status_value();
}
DFv2
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> connect_result =
context.incoming().Connect<fuchsia_examples_gizmo::Service::Device>("gizmo");
if (connect_result.is_error()) {
fdf::error("Failed to connect gizmo device protocol: {}", connect_result);
return connect_result.take_error();
}
DdkConnectRuntimeProtocol()
DFv1
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> client_end =
DdkConnectRuntimeProtocol<fuchsia_examples_gizmo::Service::Device>();
if (client_end.is_error()) {
zxlogf(ERROR, "Failed to connect fidl protocol");
return client_end.status_value();
}
（来源：DFv1 驱动程序传输示例）
DFv2
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> connect_result =
context.incoming().Connect<fuchsia_examples_gizmo::Service::Device>();
if (connect_result.is_error()) {
fdf::error("Failed to connect gizmo device protocol: {}", connect_result);
return connect_result.take_error();
}
（来源：DFv2 驱动程序传输示例）
DdkConnectFragmentRuntimeProtocol()
DFv1
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> client_end =
DdkConnectFragmentRuntimeProtocol<fuchsia_examples_gizmo::Service::Device>("gizmo_parent");
if (client_end.is_error()) {
zxlogf(ERROR, "Failed to connect fidl protocol");
return client_end.status_value();
}
DFv2
zx::result<fidl::ClientEnd<fuchsia_examples_gizmo::Device>> connect_result =
context.incoming().Connect<fuchsia_examples_gizmo::Service::Device>("gizmo_parent");
if (connect_result.is_error()) {
fdf::error("Failed to connect gizmo device protocol: {}", connect_result);
return connect_result.take_error();
}
元数据
在 DFv1 中，驱动程序可以使用 DdkAddMetadata() 和 ddk::GetEncodedMetadata<>() 等函数添加和检索元数据。请参阅下方的代码示例。
如需将这些元数据函数迁移到 DFv2，请执行以下操作：
完成设置兼容设备服务器指南中的操作。
按照转发、添加和解析 DFv1 元数据部分中的说明操作。
DdkAddMetadata()
DFv1
zx_status_t status = dev->DdkAddMetadata(DEVICE_METADATA_PRIVATE,
metadata.value().data(), sizeof(metadata.value());
if (status != ZX_OK) {
zxlogf(ERROR, "DdkAddMetadata failed: %s", zx_status_get_string(status));
}
DFv2
compat_server->inner().AddMetadata(DEVICE_METADATA_PRIVATE,
metadata.value().data(), sizeof(metadata.value()));
ddk::GetEncodedMetadata<>()
DFv1
auto decoded =
ddk::GetEncodedMetadata<fuchsia_hardware_i2c_businfo::wire::I2CBusMetadata>(
parent, DEVICE_METADATA_I2C_CHANNELS);
DFv2
fidl::Arena arena;
zx::result i2c_bus_metadata =
compat::GetMetadata<fuchsia_hardware_i2c_businfo::wire::I2CBusMetadata>(
incoming, arena, DEVICE_METADATA_I2C_CHANNELS);
迁移其他接口
TRACE_DURATION
TRACE_DURATION() 方法适用于 DFv1 和 DFv2。
DFv1
在 DFv1 中，TRACE_DURATION 宏是从以下 DDK 库导入的：
#include <lib/ddk/trace/event.h>
DFv2
如需在 DFv2 中使用 TRACE_DURATION 宏，请将 include 行更改为以下标头：
#include <lib/trace/event.h>
并将以下代码行添加到 build 依赖项中：
fuchsia_cc_driver("i2c-driver") {
...
deps = [
...
"//zircon/system/ulib/trace",
]
}
zxlogf()
zxlogf() 方法在 DFv2 中不可用，需要迁移到 fdf::info()、fdf::error() 等。
如需查看相关说明，请参阅编写最简单的 DFv2 驱动程序指南中的添加日志部分。