编写最小 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_argsdriver_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_driverBUILD.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 驱动程序中设置兼容型设备服务器 指南。