教程：在驱动程序之间传递元数据

本指南介绍了如何使用 metadata 库将元数据从一个驱动程序传递到另一个驱动程序。元数据是驱动程序创建的任意数据，应可供绑定到其子节点的驱动程序访问。通常，驱动程序可以创建自己的 FIDL 协议来传递元数据，不过，元数据库提供了在驱动程序之间传递元数据的功能，且所需的代码更少。

您可以点击此处查看驱动程序发送、检索和转发元数据的示例。

元数据定义

首先，必须将元数据的类型定义为 FIDL 类型，并使用 @serializable 进行注释：

library fuchsia.examples.metadata;

// Type of the metadata to be passed.
// Make sure to annotate it with `@serializable`.
@serializable
type Metadata = table {
    1: test_property string:MAX;
};

此元数据将使用 fuchsia.driver.metadata/Service FIDL 服务在驱动程序的传出命名空间中提供。驱动程序传出命名空间中的 FIDL 服务名称将不是 fuchsia.driver.metadata.Service。而是 FIDL 类型的可序列化名称。仅当 FIDL 类型附有 @serializable 注释时，才会创建可序列化名称。

FIDL 库的 build 目标将定义如下：

fidl("fuchsia.examples.metadata") {
  sources = [ "fuchsia.examples.metadata.fidl" ]
}

发送元数据

初始设置

假设我们有一个驱动程序想要向其子级发送元数据：

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

class Sender : public fdf::DriverBase {
 public:
  Sender(fdf::DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher)
      : DriverBase("sender", std::move(start_args), std::move(driver_dispatcher)) {}
};

FUCHSIA_DRIVER_EXPORT(Sender);

其组件清单如下所示：

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

其 build 目标定义如下：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "sender"
  sources = [
    "sender.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",
  ]
}

fuchsia_driver_component("component") {
  testonly = true
  component_name = "sender"
  manifest = "meta/sender.cml"
  deps = [
    ":driver",
    ":bind", # Bind rules not specified in this tutorial.
  ]
  info = "sender.json" # Info not specified in this tutorial.
}

发送流程

为了让此驱动程序向其子驱动程序发送元数据，它需要创建 fdf_metadata::MetadataServer 类的实例，调用 fdf_metadata::MetadataServer::Serve() 以提供元数据，并将由 fdf_metadata::MetadataServer::CreateOffer() 创建的元数据服务器的 offer 传递给子节点：


// Defines the fuchsia.examples.metadata types in C++.
#include <fidl/fuchsia.examples.metadata/cpp/fidl.h>

// Defines fdf::MetadataServer.
#include <lib/driver/metadata/cpp/metadata_server.h>

class Sender : public fdf::DriverBase {
 public:
  zx::result<> Start() override {
    // Serve the metadata to the driver's outgoing directory.
    fuchsia_examples_metadata::Metadata metadata({.test_property = "test value"});
    ZX_ASSERT(metadata_server_.Serve(*outgoing(), dispatcher(), metadata).is_ok());

    std::vector<fuchsia_driver_framework::Offer> offers;

    std::optional<fuchsia_driver_framework::Offer> metadata_offer =
      metadata_server.CreateOffer();

    // The metadata server should create an offer because it is serving
    // metadata.
    ZX_ASSERT(metadata_offer.has_value());

    // The metadata server's offer must be provided to the child node.
    offers.push_back(metadata_offer);

    zx::result child = AddChild("child", {}, offers);
    if (child.is_error()) {
      return child.take_error();
    }

    return zx::ok();
  }

 private:
  // Responsible for serving metadata.
  fdf_metadata::MetadataServer<fuchsia_examples_metadata::Metadata> metadata_server_;
};

fdf_metadata::MetadataServer::Serve() 可以多次调用，元数据服务器将提供最新的元数据实例。

需要更新 driver build 目标，以包含元数据库和定义元数据类型的 FIDL 库：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "sender"
  sources = [
    "sender.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",

    # This should be the fuchsia.examples.metadata FIDL library's C++ target.
    ":fuchsia.examples.metadata_cpp",

    # This library contains `fdf::MetadataServer`.
    "//sdk/lib/driver/metadata/cpp",
  ]
}

公开元数据服务

最后，驱动程序需要在其组件清单中声明并公开 fuchsia.examples.metadata.Metadata FIDL 服务：

{
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        binary: "driver/sender.so",
        bind: "meta/bind/sender.bindbc",
    },
    capabilities: [
        { service: "fuchsia.examples.metadata.Metadata" },
    ],
    expose: [
        {
            service: "fuchsia.examples.metadata.Metadata",
            from: "self",
        },
    ],
}

从技术上讲，没有 fuchsia.examples.metadata.Metadata FIDL 服务。 在底层，fdf_metadata::MetadataServer 会提供 fuchsia.driver.metadata/Service FIDL 服务，以便发送元数据。不过，fdf_metadata::MetadataServer 不会像普通的 FIDL 服务那样，以 fuchsia.driver.metadata.Service 为名称提供此服务。而是以元数据类型的可序列化名称提供服务。在本例中，该值为 fuchsia.examples.metadata.Metadata。此名称可在 C++ 字段 fuchsia_examples_metadata::Metadata::kSerializableName 中找到。这样，接收驱动程序就能识别正在传递的元数据类型。这意味着，即使 fuchsia.examples.metadata.Metadata FIDL 服务不存在，驱动程序也需要声明并公开该服务。

检索元数据

初始设置

假设我们有一个驱动程序想要从其父驱动程序中检索元数据：

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

class Retriever : public fdf::DriverBase {
 public:
  Retriever(fdf::DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher)
      : DriverBase("retriever", std::move(start_args), std::move(driver_dispatcher)) {}
};

FUCHSIA_DRIVER_EXPORT(Retriever);

其组件清单如下所示：

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

其 build 目标定义如下：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "retriever"
  sources = [
    "retriever.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",
  ]
}

fuchsia_driver_component("component") {
  testonly = true
  component_name = "retriever"
  manifest = "meta/retriever.cml"
  deps = [
    ":driver",
    ":bind", # Bind rules not specified in this tutorial.
  ]
  info = "retriever.json" # Info not specified in this tutorial.
}

检索流程

为了让驱动程序从其父驱动程序检索元数据，该驱动程序需要调用 fdf_metadata::GetMetadata()：

// Defines the fuchsia.examples.metadata types in C++.
#include <fidl/fuchsia.examples.metadata/cpp/fidl.h>

// Defines fdf::GetMetadata().
#include <lib/driver/metadata/cpp/metadata.h>

class Retriever : public fdf::DriverBase {
 public:
  zx::result<> Start() override {
    zx::result<fuchsia_examples_metadata::Metadata> metadata =
      fdf_metadata::GetMetadata<fuchsia_examples_metadata::Metadata>(incoming());
    ZX_ASSERT(!metadata.is_error());

    return zx::ok();
  }
};

需要更新 driver build 目标，使其依赖于元数据库和定义元数据类型的 FIDL 库：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "retriever"
  sources = [
    "retriever.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",

    # This should be the fuchsia.examples.metadata FIDL library's C++ target.
    ":fuchsia.examples.metadata_cpp",

    # This library contains `fdf::GetMetadata()`.
    "//sdk/lib/driver/metadata/cpp",
  ]
}

使用元数据服务

最后，驱动程序需要在其组件清单中声明对 fuchsia.examples.metadata.Metadata FIDL 服务的使用情况：

{
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        binary: "driver/retriever.so",
        bind: "meta/bind/retriever.bindbc",
    },
    use: [
        { service: "fuchsia.examples.metadata.Metadata" },
    ],
}

转发元数据

初始设置

假设我们有一个驱动程序想要从其父驱动程序检索元数据，并将该元数据转发给其子驱动程序：

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

class Forwarder : public fdf::DriverBase {
 public:
  Forwarder(fdf::DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher)
      : DriverBase("forwarder", std::move(start_args), std::move(driver_dispatcher)) {}
};

FUCHSIA_DRIVER_EXPORT(Forwarder);

其组件清单如下所示：

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

其 build 目标定义如下：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "forwarder"
  sources = [
    "forwarder.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",
  ]
}

fuchsia_driver_component("component") {
  testonly = true
  component_name = "forward"
  manifest = "meta/forward.cml"
  deps = [
    ":driver",
    ":bind", # Bind rules not specified in this tutorial.
  ]
  info = "forward.json" # Info not specified in this tutorial.
}

前向过程

为了使驱动程序能够将其父驱动程序的元数据转发给其子驱动程序，它需要创建 fdf_metadata::MetadataServer 类的实例，调用 fdf_metadata::MetadataServer::ForwardAndServe() 以从其父驱动程序检索元数据并将其提供给驱动程序的传出目录，然后将由 fdf_metadata::MetadataServer::CreateOffer() 创建的元数据服务器的 offer 传递给子节点。

如果 fdf_metadata::MetadataServer::ForwardAndServe() 无法从其父级检索元数据，则不会返回错误。而是会返回 zx::ok(false)，并且不会投放任何内容。```cpp // 在 C++ 中定义 fuchsia.examples.metadata 类型。

包含

// 定义 fdf::MetadataServer。

包含

class Forwarder : public fdf::DriverBase { public: zx::result<> Start() override { // Retrieve the metadata from the driver's parent and serve it to the // driver's outgoing directory. zx::result is_serving = metadataserver.ForwardAndServe( *outgoing(), dispatcher(), incoming()).is_ok(); ZX_ASSERT(is_serving.is_ok());

std::vector<fuchsia_driver_framework::Offer> offers;
std::optional<fuchsia_driver_framework::Offer> metadata_offer =
  metadata_server_.CreateOffer();

// The metadata server may not be serving metadata if the driver failed to
// retrieve it from the driver's parent. In that case, the metadata server
// will not have an offer.
if (metadata_offer.has_value()) {
  // The metadata server's offer must be provided to the child node.
  offers.push_back(metadata_offer.value());
}

zx::result child = AddChild("child", {}, offers);
if (child.is_error()) {
  return child.take_error();
}

return zx::ok();

}

private: // Responsible for serving metadata. fdf_metadata::MetadataServer metadataserver; }; ```

需要注意的是，fdf_metadata::MetadataServer::ForwardAndServe() 不会检查父驱动程序在 fdf_metadata::MetadataServer::ForwardAndServe() 被调用后是否更改了其提供的元数据。司机将不得不再次致电 fdf_metadata::MetadataServer::ForwardAndServe() 以纳入更改。

需要更新 driver build 目标，使其依赖于定义元数据类型的元数据库和 FIDL 库：

fuchsia_cc_driver("driver") {
  testonly = true
  output_name = "forwarder"
  sources = [
    "forwarder.cc",
  ]
  deps = [
    "//src/devices/lib/driver:driver_runtime",

    # This should be the fuchsia.examples.metadata FIDL library's C++ target.
    ":fuchsia.examples.metadata_cpp",

    # This library contains `fdf::MetadataServer`.
    "//sdk/lib/driver/metadata/cpp",
  ]
}

公开和使用元数据服务

最后，驱动程序需要在其组件清单中声明、使用和公开 fuchsia.examples.metadata.Metadata FIDL 服务：

{
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
    program: {
        runner: "driver",
        binary: "driver/forwarder.so",
        bind: "meta/bind/forwarder.bindbc",
    },
    capabilities: [
        { service: "fuchsia.examples.metadata.Metadata" },
    ],
    expose: [
        {
            service: "fuchsia.examples.metadata.Metadata",
            from: "self",
        },
    ],
    use: [
        { service: "fuchsia.examples.metadata.Metadata" },
    ],
}