编写最小 DFv2 驱动程序

本指南介绍了创建最小 DFv2 驱动程序所涉及的步骤。

本指南中的说明基于 框架驱动程序，该驱动程序可提供最低限度的实现， 在 Fuchsia 系统中构建、加载和注册新的 DFv2 驱动程序所需要。

具体步骤如下：

  1. 创建驱动程序头文件。
  2. 创建驱动程序源文件。
  3. 添加驱动程序导出宏。
  4. 创建 build 文件。
  5. 编写绑定规则。
  6. 创建驱动程序组件。

如需更多与 DFv2 相关的功能，请参阅其他任务。

创建驱动程序头文件

如需为 DFv2 驱动程序创建头文件，请执行以下操作：

  1. 为驱动程序创建一个新的头文件 (.h)（例如， skeleton_driver.h）。

  2. 在头文件中添加以下接口：

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

  3. 为 DriverBase 类添加一个接口， 例如：

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

namespace skeleton {

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

  // Called by the driver framework to initialize the driver instance.
  zx::result<> SkeletonDriver::Start() override;
};

}  // namespace skeleton

    （来源：skeleton_driver.h）

创建驱动程序源文件

如需实现 DriverBase 类的基本方法，请执行以下操作： 执行以下操作：

  1. 为驱动程序创建新的源文件 (.cc)（例如， skeleton_driver.cc）。

  2. 包含为驱动程序创建的头文件，例如：

    #include "skeleton_driver.h"

  3. 实现该类的基本方法，例如：

    #include "skeleton_driver.h"

namespace skeleton {

SkeletonDriver::SkeletonDriver(fdf::DriverStartArgs start_args,
                           fdf::UnownedSynchronizedDispatcher driver_dispatcher)
    : DriverBase("skeleton_driver", std::move(start_args),
          std::move(driver_dispatcher)) {
}

zx::result<> SkeletonDriver::Start() {
  return zx::ok();
}

}  // namespace skeleton

    （来源：skeleton_driver.cc）

    此驱动程序构造函数需要传递驱动程序名称（例如， "skeleton_driver")、start_args 和 driver_dispatcher 发送到 DriverBase 类。

添加驱动程序导出宏

如需添加驱动程序导出宏，请执行以下操作：

  1. 在驱动程序源文件中，添加以下头文件：

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

  2. 将以下宏（用于导出驱动程序类）添加到 ：

    FUCHSIA_DRIVER_EXPORT(skeleton::SkeletonDriver);

    例如：

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

#include "skeleton_driver.h"

namespace skeleton {

SkeletonDriver::SkeletonDriver(fdf::DriverStartArgs start_args,
                           fdf::UnownedSynchronizedDispatcher driver_dispatcher)
    : DriverBase("skeleton_driver", std::move(start_args),
          std::move(driver_dispatcher)) {
}

zx::result<> SkeletonDriver::Start() {
  return zx::ok();
}

}  // namespace skeleton

FUCHSIA_DRIVER_EXPORT(skeleton::SkeletonDriver);

    （来源：skeleton_driver.cc）

创建 build 文件

如需为驱动程序创建 build 文件，请执行以下操作：

  1. 创建一个新的 BUILD.gn 文件。

  2. 添加以下行以导入驱动程序构建规则：

    import("//build/drivers.gni")

  3. 为驱动程序添加目标，例如：

    fuchsia_driver("driver") {
  output_name = "skeleton_driver"
  sources = [ "skeleton_driver.cc" ]
  deps = [
    "//sdk/lib/driver/component/cpp",
    "//src/devices/lib/driver:driver_runtime",
  ]
}

    （来源：BUILD.gn）

    所有驱动程序中的 output_name 字段必须是唯一的。

写入绑定规则

如需为驱动程序编写绑定规则，请执行以下操作：

  1. 为驱动程序创建新的绑定规则文件 (.bind) （例如 skeleton_driver.bind）。meta

  2. 添加基本绑定规则，例如：

    using gizmo.example;
gizmo.example.TEST_NODE_ID == "skeleton_driver";

    （来源：skeleton_driver.bind）

  3. 在 BUILD.gn 文件中，添加以下代码行以导入 绑定构建规则：

    import("//build/bind/bind.gni")

  4. 在 BUILD.gn 文件中，为驱动程序的绑定规则添加一个目标， 例如：

    driver_bind_rules("bind") {
  rules = "meta/skeleton.bind"
  bind_output = "skeleton_driver.bindbc"
  deps = [ "//examples/drivers/bind_library:gizmo.example" ]
}

    （来源：BUILD.gn）

    所有驱动程序中的 bind_output 字段必须是唯一的。

创建驱动程序组件

如需为驱动程序创建 Fuchsia 组件，请执行以下操作：

  1. 在 meta 中创建新的组件清单文件 (.cml) 目录（例如 skeleton_driver.cml）。

  2. 包含以下组件分片：

    {
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
}

  3. 使用以下格式添加驱动程序的 program 信息：

    {
    program: {
        runner: "driver",
        binary: "driver/<OUTPUT_NAME>.so",
        bind: "meta/bind/<BIND_OUTPUT>",
    },
}

    binary 字段必须与 output_name 字段 BUILD.gn 文件的 fuchsia_driver 目标，以及 bind 字段必须与 driver_bind_rules 目标中的 bind_output 匹配， 例如：

    {
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        binary: "driver/skeleton_driver.so",
        bind: "meta/bind/skeleton.bindbc",
    },
}

    （来源：skeleton_driver.cml）

  4. 创建新的 JSON 文件以提供组件信息 （例如 component-info.json）。meta

  5. 以 JSON 格式添加驱动程序组件信息，例如：

    {
    "short_description": "Driver Framework example for a skeleton DFv2 driver",
    "manufacturer": "",
    "families": [],
    "models": [],
    "areas": [
        "DriverFramework"
    ]
}

    （来源：component-info.json）

  6. 在 BUILD.gn 文件中，添加以下代码行以导入组件 构建规则：

    import("//build/components.gni")

  7. 在 BUILD.gn 文件中，为驱动程序组件添加一个目标，例如：

    fuchsia_driver_component("component") {
  component_name = "skeleton"
  manifest = "meta/skeleton.cml"
  deps = [
     ":bind",
     ":driver"
  ]
  info = "component-info.json"
}

    （来源：BUILD.gn）

    请参阅下面这些字段的规则：

    • 将 manifest 字段设置为驱动程序的 .cml 文件的位置。
    • 将 info 字段设置为驱动程序组件的位置 信息 JSON 文件。
    • 设置 deps 数组以包含 fuchsia_driver 和 BUILD.gn 文件中的 driver_bind_rules 目标。

您现在可以在 Fuchsia 系统中构建、加载和注册此 DFv2 驱动程序

其他任务

本部分提供了可添加到最小 DFv2 的其他功能 驱动程序：

添加日志

默认情况下，如需从 DFv2 驱动程序输出日志，请使用 FDF_LOG 宏， 示例：

FDF_LOG(INFO, "Starting SimpleDriver")

除了使用 FDF_LOG 宏之外，您还可以使用 Fuchsia 的结构化日志记录器库 (structured_logger.h)，它使用 FDF_SLOG 宏。

如需使用 DFv2 驱动程序中的结构化日志，请执行以下操作：

  1. 加入以下标头：

    #include <lib/driver/logging/cpp/structured_logger.h>

  2. 使用 FDF_SLOG 宏可以输出日志，例如：

    FDF_SLOG(ERROR, "Failed to add child", KV("status", result.status_string()));

添加子节点

DFv2 驱动程序可以使用以下 Node 协议在 fuchsia.driver.framework FIDL 库：

open protocol Node {
    flexible AddChild(resource struct {
        args NodeAddArgs;
        controller server_end:NodeController;
        node server_end:<Node, optional>;
    }) -> () error NodeError;
};

为便于执行此操作，在启动期间，驱动程序框架为 通过 DriverBase 将节点的 Node 协议绑定到 DFv2 驱动程序。 驱动程序可以随时访问其节点客户端，以在其上创建子节点。 不过，直接使用此 FIDL 库需要进行的设置包括 创建 FIDL 通道对并构建 NodeAddArgs 表。 因此，DriverBase 类提供了一组辅助函数， 更轻松地添加子节点（要查看这些帮助程序，请查看 driver_base.h file.)

DFv2 驱动程序可以添加两种类型的节点：“无主”节点和“自有”节点。 无主节点和自有节点之间的主要区别在于， 参与司机匹配流程。

驱动程序框架会尝试查找与 无主节点，以便它可以将驱动程序绑定到节点。一旦匹配到驱动程序， 绑定的驱动程序将成为该节点的所有者。 另一方面，自有节点不参与匹配， 已经是所有者。

DriverBase 辅助函数

您的驱动程序当前绑定到的节点的客户端存储在 DriverBase 对象。这样，驱动程序就可以使用 DriverBase 类的 用于向此节点添加子节点的 AddChild() 和 AddOwnedChild() 函数。

不过，若要使用这些 DriverBase 辅助函数，节点不得 已经从驾驶员身上移开如果该节点已移出，或者您的目标节点不是 驱动程序当前绑定到的节点（即，对于孙节点）； 您需要使用 add_child.h 文件。这些方法与 DriverBase 辅助函数，但不适用于向节点添加子函数 在 DriverBase 对象无法达到的范围内进行传递，方法是提供正确的父级 作为目标。

最后，这些辅助函数负责在发生错误时记录错误， 因此驱动程序不需要日志记录。

创建无主的节点

如需创建无主的节点，驱动程序可以使用 DriverBase::AddChild() 帮助程序 函数。这些函数有两种类型：一种允许提供 DevfsAddArgs，另一个则不然。这些函数允许您设置 无主节点上的属性，驱动程序框架可使用这些属性来查找匹配的 两者的返回结果都是 NodeController 协议的客户端。 可以由驾驶员保留，也可以安全地丢弃。

以下示例代码会在驱动程序的绑定节点下创建一个无主的节点：

// Add a child node.
auto properties = std::vector{fdf::MakeProperty(bind_fuchsia_test::TEST_CHILD, "simple")};
zx::result child_result = AddChild(child_name, properties, compat_server_.CreateOffers2());
if (child_result.is_error()) {
  return child_result.take_error();
}

child_controller_.Bind(std::move(child_result.value()));

（来源：simple_driver.cc）

创建自有节点

如需创建自有节点，驱动程序可以使用 DriverBase::AddOwnedChild() 帮助程序 函数。同样有两种类型：一种允许 DevfsAddArgs，另一种允许 则不能。这些函数不提供属性参数，因为 节点不参与驱动程序匹配。两者的返回结果都是 OwnedChildNode 对象，该对象包含 NodeController 的客户端（ （可安全舍弃）以及 Node 协议的客户端， 无法安全舍弃。驱动程序必须一直持有 Node 客户端 它希望保留的节点存在。丢弃此客户端将导致驱动程序 移除该节点

下面的示例代码会使用 devfs 参数创建一个自有节点：

fuchsia_driver_framework::DevfsAddArgs devfs_args{{.connector = std::move(connector.value())}};
zx::result owned_child = AddOwnedChild("retriever", devfs_args);
if (owned_child.is_error()) {
  return owned_child.error_value();
}

child_node_.emplace(std::move(owned_child.value()));

（来源：retriever.cc）

清理驱动程序

如果 DFv2 驱动程序需要在停止之前执行拆解（例如， 停止线程），则需要通过替换并实现额外的 DriverBase 方法：PrepareStop() 和 Stop()

系统会在驱动程序的 fdf 调度程序被调用之前调用 PrepareStop() 函数。 并释放该驱动程序。因此，驾驶员需要 实现 PrepareStop()if 之前，必须先执行某些操作， 关闭驱动程序的调度程序，例如：

void SimpleDriver::PrepareStop(fdf::PrepareStopCompleter completer) {
 // Teardown threads
  FDF_LOG(INFO, "Preparing to stop SimpleDriver");
  completer(zx::ok());
}

系统会在属于此驱动程序的所有调度程序之后调用 Stop() 函数 例如：

void SimpleDriver::Stop() {
  FDF_LOG(INFO, "Stopping SimpleDriver");
}

添加兼容型设备服务器

如果您的 DFv2 驱动程序包含尚未迁移到的后代 DFv1 驱动程序 DFv2，您需要使用兼容性填充码，以便 DFv2 驱动程序能够进行通信 至系统中的其他 DFv1 驱动程序。有关详情，请参阅 在 DFv2 驱动程序中设置兼容型设备服务器 指南。