在 DFv2 驅動程式中連結及提供 Banjo 通訊協定

本指南會逐步說明在 DFv2 驅動程式庫中提供 Banjo 通訊協定的工作 並透過 DFv1 子項驅動程式庫程式連線至 Banjo 伺服器

請在 FIDL 程式庫中定義主要用於 DFv1 驅動程式的 Banjo 通訊協定 含有 @transport("Banjo") 和 @banjo_layout("ddk-protocol") 註解 行，例如：

/// The protocol provides access to functions of the driver.
@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol Misc {
    /// Returns a unique identifier for this device.
    strict GetHardwareId() -> (struct {
        status zx.Status;
        response uint32;
    });

    /// Returns the current device firmware version
    strict GetFirmwareVersion() -> (struct {
        status zx.Status;
        major uint32;
        minor uint32;
    });
};

(資料來源：gizmo.test.fidl)

如要讓 DFv2 驅動程式庫使用 Banjo 通訊協定，請參閱下列工作：

透過 DFv2 驅動程式提供 Banjo 通訊協定

本節逐步說明在 DFv2 驅動程式中實作 Banjo 通訊協定 並向子項驅動程式提供通訊協定這份逐步操作說明是根據 的 Banjo Transport 範例，這個範例會導入 gizmo.test FIDL 程式庫中的 Misc Banjo 通訊協定。

步驟如下：

  1. 設定 Banjo 通訊協定。
  2. 實作 Banjo 通訊協定。
  3. 提供 Banjo 協定。

1. 設定 Banjo 通訊協定

如要在 DFv2 驅動程式中設定 Misc Banjo 通訊協定，請按照下列步驟操作：

  1. 在 BUILD.gn 檔案中，將 Banjo 程式庫新增為 fuchsia_driver 目標，例如：

    fuchsia_driver("parent_driver") {
  output_name = "banjo_transport_parent"
  sources = [ "parent-driver.cc" ]
  deps = [
    "//examples/drivers/bind_library:gizmo.example_cpp",
    "//examples/drivers/transport/banjo:fuchsia.examples.gizmo_banjo_cpp",
     ...
  ]
}

  2. 在驅動程式庫的 C++ 標頭檔案中，加入 Banjo 程式庫的 C++ 標頭， 範例：

    #include <fuchsia/examples/gizmo/cpp/banjo.h>
...

namespace banjo_transport {
...

    (資料來源：parent-driver.h)

  3. 如要繼承 Banjo 通訊協定繫結，請使用以下程式碼更新驅動程式庫類別： 格式如下：

    ddk::<PROTOCOL_NAME>Protocol<<YOUR_DRIVER_CLASS>>

    將 PROTOCOL_NAME 替換為 Banjo 通訊協定的名稱，然後 YOUR_DRIVER_CLASS 是駕駛人的類別，這兩者都是駝峰式大小寫 例如：

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

    (資料來源：parent-driver.h)

2. 實作 Banjo 通訊協定

在驅動程式庫類別中，定義與實作 Banjo 中的每個函式 因此效能相當卓越

例如，以下範例顯示名為 ProtocolName 的 Banjo 通訊協定：

@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol ProtocolName {
   /// Returns a unique identifier for this device.
   strict FunctionName() -> (struct {
       status zx.Status;
       response_1 response_1_type;
       response_2 response_2_type;
   });
};

針對這個 ProtocolName Banjo 通訊協定， FunctionName 函式如下所示：

zx_status_t ProtocolNameFunctionName(response_1_type* response_1, response_2_type* response_2);

您可以透過應用程式找出現有 Banjo 通訊協定的 C++ 繫結 使用下列 Fuchsia 來源結帳路徑：

<OUT_DIRECTORY>/fidling/gen/<PATH_TO_THE_FIDL_LIBRARY>/banjo

舉例來說，如果 out 目錄是 out/default 且 FIDL 程式庫位於 examples/drivers/transport 目錄 則 C++ 繫結位於以下目錄中：

out/default/fidling/gen/examples/drivers/transport/banjo

請參閱 Banjo Transport 範例中的實作方式：

  • Misc 通訊協定包含下列函式：

    /// Returns a unique identifier for this device.
strict GetHardwareId() -> (struct {
 status zx.Status;
 response uint32;
});

/// Returns the current device firmware version
strict GetFirmwareVersion() -> (struct {
 status zx.Status;
 major uint32;
 minor uint32;
});

  • ParentBanjoTransportDriver 類別會將這些函式定義為 如下：

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

 // MiscProtocol implementation.
 zx_status_t MiscGetHardwareId(uint32_t* out_response);
 zx_status_t MiscGetFirmwareVersion(uint32_t* out_major, uint32_t* out_minor);
...
};

    (資料來源：parent-driver.h)

  • 函式的實作方式如下：

    zx_status_t ParentBanjoTransportDriver::MiscGetHardwareId(uint32_t* out_response) {
 *out_response = 0x1234ABCD;
 return ZX_OK;
}

zx_status_t ParentBanjoTransportDriver::MiscGetFirmwareVersion(uint32_t* out_major,
                                                              uint32_t* out_minor) {
 *out_major = 0x0;
 *out_minor = 0x1;
 return ZX_OK;
}

    (資料來源：parent-driver.cc)

3. 提供 Banjo 通訊協定

在 DFv2 驅動程式中實作 Banjo 通訊協定後，您需要 使用相容裝置伺服器向 DFv1 子節點提供通訊協定 套用了 Banjo 設定

若要這樣做，請在 在 DFv2 驅動程式中設定 Compat 裝置伺服器 指南：

  1. 設定 Compat 裝置伺服器。
  2. 為子系 DFv1 驅動程式提供 Banjo 服務。

從 DFv2 驅動程式連線至 Banjo 伺服器

本節使用 Banjo 傳輸範例。 ，逐步說明如何將 DFv2 子項驅動程式庫連線至父項 是 Banjo 通訊協定的驅動程式庫

步驟如下：

  1. 將兒童驅動程式庫與家長驅動程式連線。
  2. 使用 Banjo 通訊協定。

1. 將兒童驅動程式庫接上家長驅動程式庫

要能將兒童驅動程式庫與父母連線，以便使用 Banjo 通訊協定，子項必須與父項位於同一驅動程式代管程序 兩個驅動程式都必須使用 Compat banjo_client 程式庫

如要將子項驅動程式庫與家長驅動程式庫連接，請按照下列步驟操作：

  1. 在子項驅動程式庫程式的元件資訊清單 (.cml) 中設定 colocate 欄位變更為 true，例如：

    {
    include: [ 'syslog/client.shard.cml' ],
    program: {
        runner: 'driver',
        binary: 'driver/banjo_transport_child.so',
        bind: 'meta/bind/child-driver.bindbc',

        // Run in the same driver host as the parent driver
        colocate: 'true',
    },
    use: [
        { service: 'fuchsia.driver.compat.Service' },
    ],
}

    (資料來源：child-driver.cml)

  2. 在子項驅動程式庫 BUILD.gn 檔案中，將 Banjo 程式庫新增為 某個依附元件是位於 fuchsia_driver 目標中的依附元件，例如：

    fuchsia_driver("child_driver") {
  output_name = "banjo_transport_child"
  sources = [ "child-driver.cc" ]
  deps = [
    "//examples/drivers/transport/banjo:fuchsia.examples.gizmo_banjo_cpp",
    "//sdk/lib/driver/component/cpp:cpp",
    "//src/devices/lib/driver:driver_runtime",
  ]
}

    (資料來源：BUILD.gn)

  3. 在子項驅動程式庫的 C++ 標頭檔案中，加入 Banjo 程式庫的 C++ 標頭，例如：

    #include <fuchsia/examples/gizmo/cpp/banjo.h>
...

namespace banjo_transport {
...

    (資料來源：child-driver.h)

  4. 在子項驅動程式的 BUILD.gn 檔案中，新增相容性 banjo_client 將程式庫做為 fuchsia_driver 目標中的依附元件，例如：

    fuchsia_driver("child_driver") {
  output_name = "banjo_transport_child"
  sources = [ "child-driver.cc" ]
  deps = [
    "//examples/drivers/transport/banjo:fuchsia.examples.gizmo_banjo_cpp",
    "//sdk/lib/driver/compat/cpp",
    "//sdk/lib/driver/component/cpp:cpp",
    "//src/devices/lib/driver:driver_runtime",
  ]
}

    (資料來源：BUILD.gn)

  5. 在子項驅動程式庫的 C++ 來源檔案中，加入 Compat banjo_client 程式庫的 C++ 標頭，例如：

    #include "examples/drivers/transport/banjo/v2/child-driver.h"

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

namespace banjo_transport {

zx::result<> ChildBanjoTransportDriver::Start() {
...

    (資料來源：child-driver.cc)

  6. 在子項驅動程式庫程式的 C++ 來源檔案中，使用 compat::ConnectBanjo() 函式，例如：

    zx::result<Client> ConnectBanjo(const std::shared_ptr<fdf::Namespace>& incoming,
                                std::string_view parent_name = "default") {

    在 Banjo Transport 範例中， 驅動程式庫會執行下列作業來連線至 Misc 通訊協定：

    zx::result<ddk::MiscProtocolClient> client =
      compat::ConnectBanjo<ddk::MiscProtocolClient>(incoming());

if (client.is_error()) {
    FDF_SLOG(ERROR, "Failed to connect client", KV("status",
         client.status_string()));
    return client.take_error();
}

    (資料來源：child-driver.cc)

2. 使用 Banjo 通訊協定

在子項驅動程式庫中，使用通訊協定用戶端叫用 Banjo 函式。

例如，以下範例顯示一個名為 ProtocolName:

@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol ProtocolName {
   /// Returns a unique identifier for this device.
   strict FunctionName() -> (struct {
       status zx.Status;
       response_1 response_1_type;
       response_2 response_2_type;
   });
};

針對這個 ProtocolName Banjo 通訊協定， FunctionName 函式如下所示：

zx_status_t ProtocolNameFunctionName(response_1_type* response_1, response_2_type* response_2);

在 Banjo Transport 範例中， GetHardwareId() 函式的定義如下：

/// Returns a unique identifier for this device.
strict GetHardwareId() -> (struct {
 status zx.Status;
 response uint32;
});

(資料來源：gizmo.test.fidl)

使用儲存在 client_ 物件中的 Banjo 用戶端 而 hardware_id_ 變數定義為 是 uint32_t，您可以呼叫 GetHardwareId() 函式 包括：

zx_status_t status = client_.GetHardwareId(&hardware_id_);
if (status != ZX_OK) {
 return status;
}

(資料來源：child-driver.cc)