在 DFv2 驅動程式庫中設定 Compat 裝置伺服器

本指南說明如何在 DFv2 驅動程式庫中設定及使用 Compat 裝置伺服器，以便與 DFv1 驅動程式進行通訊。

Compat 裝置伺服器可協助 DFv2 驅動程式在遷移過程中維持與 DFv1 驅動程式的相容性。Compat 裝置伺服器提供 fuchsia_driver_compat::Device 介面 (請參閱 compat.fidl)。這個介面可讓 DFv2 驅動程式提供其資源給子系 DFv1 驅動程式。

Compat 裝置伺服器的主要特色如下：

• 資源共用：將 DFv2 驅動程式庫的資源順暢提供給子系 DFv1 驅動程式。

• Banjo 服務：將 DFv2 驅動程式庫中實作的 Banjo 通訊協定提供給 DFv1 驅動程式。

• 中繼資料處理：針對 DFv2 和 DFv1 驅動程式之間的通訊，轉送、新增及剖析 DFv1 中繼資料。

本指南提供逐步說明和範例，協助您完成下列工作：

• 設定 compat 裝置伺服器：在 DFv2 驅動程式庫中設定 compat 裝置伺服器，包括初始化 (同步或非同步)，並提供給子節點。

• 為子系 DFv1 驅動程式提供 Banjo 服務：與子系 DFv1 驅動程式設定及共用 Banjo 通訊協定。

• 轉送、新增及剖析 DFv1 中繼資料：新增、轉寄及擷取中繼資料，以確保 DFv2 和 DFv1 驅動程式之間能順暢交換資訊。

設定 compat 裝置伺服器

本節會根據 DFv2 Simple 驅動程式庫範例中提供相容性裝置伺服器設定操作說明。

步驟如下：

1. 將 compat 裝置伺服器指定為依附元件。
2. 同步或非同步初始化 Compat 裝置伺服器。
3. 將 compat 裝置伺服器提供給目標子節點。

1. 將 Compat 裝置伺服器指定為依附元件

如要將 Compat 裝置伺服器指定為 DFv2 驅動程式庫中的依附元件，請按照下列步驟操作：

1. 將以下依附元件新增至 BUILD.gn 的 fuchsia_driver 目標：

   "//sdk/lib/driver/compat/cpp",
   

2. 在驅動程式庫的來源檔案中加入 device_server.h 標頭：

   #include <lib/driver/compat/cpp/device_server.h>
   

3. 請在驅動程式庫的元件資訊清單 (.cml) 中加入 driver_component/driver.shard.cml 資料分割，例如：

    include: [
        "driver_component/driver.shard.cml",
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],
   

   (資料來源：simple_driver.cml)

   這個資料分割定義了 fuchsia.driver.compat.Service 的 use、capabilities 和 expose 欄位。

透過這項設定，DFv2 驅動程式庫現在可以為子系節點建立 DeviceServer 物件。每個 DeviceServer 物件只能有一個目標節點。

2. 以同步或非同步方式初始化 Compat 裝置伺服器

以同步或非同步方式初始化 DeviceServer 物件。根據預設，我們會建議您使用同步，而非非同步初始化。

不過，如果您符合下列其中一項條件，就可以考慮使用非同步初始化：

• 不允許目前調度工具上的同步或封鎖呼叫。

• 您的 DFv1 驅動程式庫已採用非同步程式碼的結構，且您需要非同步行為提升效能。

同步初始化

如要執行同步初始化，請執行下列操作：

1. 在類別中新增 SyncInitializedDeviceServer 物件，例如：

   class SimpleDriver : public fdf::DriverBase {
    ...
       compat::SyncInitializedDeviceServer compat_server_;
    ...
   }
   

2. 在驅動程式庫實作中，呼叫這個 DeviceServer 物件的 Initialize() 函式：

   zx::result<> Initialize(const std::shared_ptr<fdf::Namespace>& incoming,
                             const std::shared_ptr<fdf::OutgoingDirectory>& outgoing,
                             const std::optional<std::string>& node_name,
                             std::string_view child_node_name,
                             const ForwardMetadata& forward_metadata = ForwardMetadata::None(),
                             std::optional<DeviceServer::BanjoConfig> banjo_config = std::nullopt,
                             const std::optional<std::string>& child_additional_path = std::nullopt);
   

   這個函式的參數如下所示：

   • 叫用相同名稱的 DriverBase 存取子，即可傳遞 incoming、outgoing 和 node_name 的值 (請參閱下方範例)。

   • child_node_name 是此 DeviceServer 物件的指定子節點名稱。

     不過，如果 DFv2 驅動程式庫的節點和目標子項節點之間有任何中介節點，您必須將 child_additional_path 設為節點之間以 / 分隔的拓撲路徑。舉例來說，如果目標子項節點之前有 node-a 和 node-b，則 child_additional_path 的值必須為 node-a/node-b/。

   • forward_metadata 包含要從父項節點轉送的中繼資料相關資訊。(詳情請參閱轉送中繼資料)。

   • banjo_config 包含將 Banjo 通訊協定提供給目標子節點的資訊。不過，如果裝置伺服器未提供通訊協定，您可以將參數設為 std::nullopt。(詳情請參閱「為子系 DFv1 驅動程式提供 Banjo 服務」一文)。

   以下範例會初始化同步的相容性裝置伺服器物件：

   // Initialize our compat server.
     {
       zx::result<> result = compat_server_.Initialize(
          incoming(), outgoing(), node_name(), child_name);
       if (result.is_error()) {
         return result.take_error();
       }
     }
   

非同步初始化

如要進行非同步初始化，請執行下列操作：

1. 在類別中新增 AsyncInitializedDeviceServer 物件，例如：

   class SimpleDriver : public fdf::DriverBase {
    ...
       compat::AsyncInitializedDeviceServer compat_server_;
    ...
   }
   

2. 在驅動程式庫實作中，呼叫這個 DeviceServer 物件的 Begin() 函式：

   void Begin(const std::shared_ptr<fdf::Namespace>& incoming,
                const std::shared_ptr<fdf::OutgoingDirectory>& outgoing,
                const std::optional<std::string>& node_name, std::string_view child_node_name,
                fit::callback<void(zx::result<>)> callback,
                const ForwardMetadata& forward_metadata = ForwardMetadata::None(),
                std::optional<DeviceServer::BanjoConfig> banjo_config = std::nullopt,
                const std::optional<std::string>& child_additional_path = std::nullopt);
   

   參數與上述同步 Initialize() 函式幾乎相同 (callback 欄位除外)。

   當 DeviceServer 物件完成初始化並準備就緒時，系統會叫用回呼函式。建議您使用這個回呼函式來新增子節點。其他參數值的填入方式與同步初始化相同。

   以下範例會初始化非同步相容性裝置伺服器物件：

   void SimpleDriver::OnDeviceServerInitialized(zx::result<> device_server_init_result) {
      // Add the child nodes here
      async_completer_.value()(zx::ok());
      async_completer_.reset();
   }
   
   void SimpleDriver::Start(fdf::StartCompleter completer) {
      async_completer_.emplace(std::move(completer));
      device_server_.Begin(incoming(), outgoing(), node_name(), child_name,
      fit::bind_member<&MyDriver::OnDeviceServerInitialized>(this),
      compat::ForwardMetadata::Some({DEVICE_METADATA_MAC_ADDRESS}));
   }
   

3. 將 compat 裝置伺服器提供給目標子節點

compat 裝置伺服器初始化後，請將優惠傳送至目標子節點。

然而，如果目標節點不是直接子項，您必須將優惠傳送至子系鏈中下一個最接近的子項。舉例來說，節點拓撲顯示 A -> B -> C -> D，如果節點 A 是目前的節點，節點 D 是目標節點，那麼您必須將優惠傳送至節點 B，也就是鏈結中最接近子節點的節點。

使用 DeviceServer 物件的 CreateOffers2() 函式設定 NodeAddArgs 結構中的 offers2 欄位，例如：

fuchsia_driver_framework::NodeAddArgs args{
    {
        .name = std::string(child_name),
        .properties = {
            {
                fdf::MakeProperty(BIND_PROTOCOL, ZX_PROTOCOL_SERIAL_IMPL_ASYNC),
            }
        },
        .offers2 = compat_server_.CreateOffers2(),
    },
};

fidl::Arena arena;
node_client_
    ->AddChild(fidl::ToWire(arena, std::move(args)),
                std::move(node_controller->server));

如有任何其他優惠，請先將這些優惠新增至 DeviceServer 物件的優惠中，然後再在 NodeAddArgs 結構中設定 offers2 欄位，例如：

auto offers = device_server_.CreateOffers2();
offers.push_back(fdf::MakeOffer2<fuchsia_hardware_serialimpl::Service>(child_name));

fuchsia_driver_framework::NodeAddArgs args{
    {
        .name = std::string(child_name),
        .properties = {
            {
                fdf::MakeProperty(BIND_PROTOCOL, ZX_PROTOCOL_SERIAL_IMPL_ASYNC),
            }
        },
        .offers2 = std::move(offers),
    },
};

fidl::Arena arena;
node_client_
    ->AddChild(fidl::ToWire(arena, std::move(args)),
                std::move(node_controller->server));

如果相容性裝置伺服器是以同步方式初始化，則必須在呼叫 SyncInitializedDeviceServer::Initialize() 函式後執行這項作業。否則，您必須在傳遞至 AsyncInitializedDeviceServer::Begin() 呼叫的回呼函式中執行此操作。

為子系 DFv1 驅動程式提供 Banjo 服務

如果您的 DFv2 驅動程式庫會實作 Banjo 通訊協定，並想提供給目標子節點，您必須將通訊協定新增至相容裝置伺服器。

假設驅動程式實作 Misc Banjo 通訊協定，例如：

class ParentBanjoTransportDriver : public fdf::DriverBase,
                                   public ddk::MiscProtocol<ParentBanjoTransportDriver> {
...

(本節中的範例是以 Banjo 傳輸範例為基礎)。

如要將 Misc Banjo 通訊協定新增至相容裝置伺服器，請按照下列步驟操作：

1. 在驅動程式庫的來源檔案中加入下列標頭：

   #include <lib/driver/compat/cpp/banjo_server.h>
   

2. 為 Banjo 通訊協定建立 compat::BanjoServer 物件：

   compat::BanjoServer banjo_server_{ZX_PROTOCOL_<NAME>, this, &<name>_protocol_ops_};
   

   在上述範本中，請將 NAME 替換為大寫的通訊協定名稱，以及小寫的 name。因此，針對 Misc Banjo 通訊協定，物件會如下所示：

   class ParentBanjoTransportDriver : public fdf::DriverBase,
                                      public ddk::MiscProtocol<ParentBanjoTransportDriver> {
    ...
   
    private:
     compat::BanjoServer banjo_server_{ZX_PROTOCOL_MISC, this, &misc_protocol_ops_};
    ...
   }
   

3. 建立 BanjoConfig 物件，並將通訊協定回呼設為 Banjo 伺服器的回呼，例如：

   compat::DeviceServer::BanjoConfig banjo_config;
   banjo_config.callbacks[ZX_PROTOCOL_MISC] = banjo_server_.callback();
   

   這項設定會將 Banjo 設定資訊從 BanjoServer 物件傳遞至 Compat 裝置伺服器。

4. 初始化 compat 裝置伺服器時，請將 Initialize() 函式的 banjo_config 欄位設為 BanjoConfig 物件，例如：

   // Initialize our compat server.
   {
       zx::result<> result = compat_server_.Initialize(
          incoming(), outgoing(), node_name(), child_name, ForwardMetadata::None(),
           std::move(banjo_config));
       if (result.is_error()) {
         return result.take_error();
       }
   }
   

如需將這個 Banjo 通訊協定提供給子系 DFv1 驅動程式的其餘步驟，請參閱提供 DFv2 驅動程式中的 Banjo 通訊協定指南。

轉送、新增及剖析 DFv1 中繼資料

許多現有的 DFv1 驅動程式都會使用中繼資料，在父項及其子項之間轉發資訊。在 DFv2 驅動程式中，您可以使用 Compat 裝置伺服器執行下列作業：

• 新增及傳送中繼資料
• 轉送中繼資料
• 擷取中繼資料

新增並傳送中繼資料

系統會透過驅動程式庫的相容性裝置伺服器，將中繼資料傳遞至子節點。如要新增及傳送中繼資料，驅動程式庫需要建立相容性裝置伺服器，並呼叫其 AddMetadata() 函式：

zx_status_t AddMetadata(MetadataKey type, const void* data, size_t size);

(資料來源：device_server.h)

以下範例使用 AddMetadata() 函式新增中繼資料：

const uint64_t metadata = 0xAABBCCDDEEFF0011;
zx_status_t status = compat_device_server.AddMetadata(
    DEVICE_METADATA_PRIVATE, &metadata, sizeof(metadata));

然而，如果中繼資料是 FIDL 類型，則需要先使用 fidl::Persist() 呼叫將其保存，然後再將其新增至 AddMetadata() 函式，例如：

fuchsia_hardware_i2c_businfo::wire::I2CChannel local_channel(channel);
fit::result metadata = fidl::Persist(local_channel);
if (!metadata.is_ok()) {
  FDF_LOG(ERROR, "Failed to fidl-encode channel: %s",
          metadata.error_value().FormatDescription().data());
  return zx::error(metadata.error_value().status());
}
compat_server->AddMetadata(DEVICE_METADATA_I2C_DEVICE, metadata.value().data(),
                           metadata.value().size());

轉送中繼資料

如果 DFv2 驅動程式庫會從父項節點接收中繼資料，且需要將部分或所有中繼資料傳送至其子節點，您可以使用 Compat 裝置伺服器轉送中繼資料。

如要轉送中繼資料，請在初始化驅動程式庫 DeviceServer 物件時設定 forward_metadata 參數：

• 如要轉寄所有中繼資料，請將參數設為 ForwardMetadata::All()，例如：

  zx::result<> result = compat_server_.Initialize(
         incoming(), outgoing(), node_name(), child_name,
         compat::ForwardMetadata::All());
  

• 如果只想轉寄部分中繼資料，請使用 ForwardMetadata Some(std::unordered_set<MetadataKey> filter) 建立 ForwardMetadata 物件，並將這個物件傳遞至參數。

  以下範例只會使用 DEVICE_METADATA_ADC 鍵轉送中繼資料：

  zx::result<> result = compat_server_.Initialize(
         incoming(), outgoing(), node_name(), child_name,
         compat::ForwardMetadata::Some({DEVICE_METADATA_ADC}));
  

• 如果您不想轉寄中繼資料，請將參數設為 ForwardMetadata::None()，例如：

  zx::result<> result = compat_server_.Initialize(
         incoming(), outgoing(), node_name(), child_name,
                                compat::ForwardMetadata::None());
  

擷取中繼資料

Compat 裝置伺服器的中繼資料程式庫 (metadata.h) 提供從驅動程式擷取中繼資料的輔助函式。

如要使用這個中繼資料程式庫，請按照下列步驟操作：

1. 將以下依附元件新增至 BUILD.gn 中的 fuchsia_driver 目標：

   "//sdk/lib/driver/compat/cpp",
   

2. 在驅動程式庫的來源檔案中加入下列標頭：

   #include <lib/driver/compat/cpp/metadata.h>
   

3. 如要從驅動程式庫的相容性裝置伺服器擷取中繼資料，請使用 compat::GetMetadata<T>() 方法，並將 T 替換為中繼資料類型。

   以下範例使用 DEVICE_METADATA_VREG 鍵和 fuchsia_hardware_vreg::wire::Metadata 類型擷取中繼資料：

   fidl::Arena arena;
   zx::result<fuchsia_hardware_vreg::wire::Metadata> metadata = compat::GetMetadata<fuchsia_hardware_vreg::wire::Metadata>(
             incoming(), arena, DEVICE_METADATA_VREG);
   if (metadata.is_error()) {
     FDF_LOG(ERROR, "Failed to get metadata  %s", metadata.status_string());
     return completer(metadata.take_error());
   }
   

   如需中繼資料鍵和類型的完整清單，請參閱這個檔案。

4. (選用) 如果驅動程式庫為複合性質，則您需要傳送父項名稱，以指定中繼資料的來源父項節點，例如：

   zx::result<fuchsia_hardware_vreg::wire::Metadata> metadata = compat::GetMetadata<fuchsia_hardware_vreg::wire::Metadata>(
        incoming(), arena, DEVICE_METADATA_VREG, "pdev");
   

不過，如果中繼資料類型是動態大小的陣列，請使用 compat::GetMetadataArray<T>()，並以陣列的類型取代 T。

假設我們需要擷取 DEVICE_METADATA_GPIO_PINS 的中繼資料，因為其是 gpio_pin_t 結構體的陣列：

// type: array of gpio_pin_t
#define DEVICE_METADATA_GPIO_PINS 0x4F495047  // GPIO

接著，您必須將 T 替換為 gpio_pin_t，並擷取中繼資料，如下所示：

zx::result<std::vector<gpio_pin_t>>  gpio_pins =
     compat::GetMetadataArray<gpio_pin_t>(incoming(), DEVICE_METADATA_GPIO_PINS);
 if (gpio_pins.is_error()) {
   FDF_LOG(ERROR, "%s: Failed to get gpio pin metadata");
   return zx::error(gpio_pins.take_error());
 }

同理，如果驅動程式庫為複合型，則傳遞父項名稱以指定中繼資料的來源父項節點，例如：

zx::result<std::vector<gpio_pin_t>> gpio_pins =
     compat::GetMetadataArray<gpio_pin_t>(incoming(), DEVICE_METADATA_GPIO_PINS, "pdev");