本指南說明如何從驅動程式庫新增 FIDL 通訊協定，並用於其他驅動程式庫。本指南假設您熟悉下列概念：
FIDL 通訊協定定義
下列程式碼片段將使用這個 FIDL 通訊協定：
library fidl.examples.echo;
const MAX_STRING_LENGTH uint64 = 32;
// The discoverable annotation is required, otherwise the protocol bindings
// will not have a name string generated.
@discoverable
protocol Echo {
/// Returns the input.
EchoString(struct {
value string:<MAX_STRING_LENGTH, optional>;
}) -> (struct {
response string:<MAX_STRING_LENGTH, optional>;
});
};
service EchoService {
echo client_end:Echo;
};
父項驅動程式 (伺服器)
以下概略說明實作所呼叫通訊協定的父項驅動程式庫程式的編寫方式。雖然未顯示，但我們假設此類別使用的是 DDKTL。
// This class implement the fuchsia.examples.echo/Echo FIDL protocol using the
// new C++ FIDL bindings
class Device : public fidl::WireServer<fidl_examples_echo::Echo> {
// This is the main entry point for the driver.
static zx_status_t Bind(void* ctx, zx_device_t* parent) {
// When creating the device, we initialize it with a dispatcher provided by
// the driver framework. This dispatcher is allows us to schedule
// asynchronous work on the same thread as other drivers. You may opt to
// create your own dispatcher which is serviced on a thread you spawn if you
// desire instead.
auto* dispatcher = fdf::Dispatcher::GetCurrent()->async_dispatcher();
auto device = std::make_unique<Device>(parent, dispatcher);
// We add the FIDL protocol we wish to export to our child to our outgoing
// directory. When a connection is attempted we will bind the server end of
// the channel pair to our server implementation.
zx::result = device->outgoing_.AddService<fidl_examples_echo::EchoService>(
fidl_examples_echo::EchoService::InstanceHandler({
.echo = device->bindings_.CreateHandler(device.get(), dispatcher,
fidl::kIgnoreBindingClosure),
}));
// Utilizing the server end of the endpoint pair we created above, we bind
// it to our outgoing directory.
result = device->outgoing_.Serve(std::move(endpoints->server));
if (result.is_error()) {
zxlogf(ERROR, "Failed to service the outgoing directory");
return result.status_value();
}
// We declare our outgoing protocols here. These will be utilize to
// help the framework populate node properties which can be used for
// binding.
std::array offers = {
fidl_examples_echo::Service::Name,
};
status = device->DdkAdd(ddk::DeviceAddArgs("parent")
// The device must be spawned in a separate
// driver host.
.set_flags(DEVICE_ADD_MUST_ISOLATE)
.set_fidl_service_offers(offers)
// The client side of outgoing directory is
// provided to the framework. This will be
// forwarded to the new driver host that spawns to
// allow the child driver which binds the ability
// to connect to our outgoing FIDL protocols.
.set_outgoing_dir(endpoints->client.TakeChannel()));
if (status == ZX_OK) {
[[maybe_unused]] auto ptr = device.release();
} else {
zxlogf(ERROR, "Failed to add device");
}
return status;
}
private:
// This is the implementation of the only method our FIDL protocol requires.
void EchoString(EchoStringRequestView request, EchoStringCompleter::Sync& completer) override {
completer.Reply(request->value);
}
// This is a helper class which we use to serve the outgoing directory.
component::OutgoingDirectory outgoing_;
// This ensures that the fidl connections don't outlive the device object.
fidl::ServerBindingGroup<fidl_examples_echo::Echo> bindings_;
};
子項驅動程式 (用戶端)
裝訂
第一個要討論的重點是兒童驅動程式庫如何繫結。由於節點屬性的數量不限，因此可能會繫結，但如果您想單獨根據父項匯出的 FIDL 通訊協定進行繫結，就需要建構版本從 FIDL 程式庫自動產生的繫結程式庫 (詳情請參閱「產生的繫結程式庫」)。
您會在驅動程式庫的繫結規則中依賴並使用此繫結程式庫：
using fidl.examples.echo;
fidl.examples.echo.Echo == fidl.examples.echo.Echo.ZirconTransport;
ZirconTransport 是父項驅動程式庫用於向子項提供 Echo FIDL 通訊協定的傳輸方法。
您可以視需要新增其他繫結限制。請注意，只有父項驅動程式庫在新增裝置時宣告其 FIDL 通訊協定提供的屬性後，才會新增此處說明的屬性。
客戶代碼
下列程式碼片段位於子項驅動程式庫已成功繫結至上述父項驅動程式庫。
zx_status_t CallEcho() {
// The following method allows us to connect to the protocol we desire. This
// works by providing the server end of our endpoint pair to the framework. It
// will push this channel through the outgoing directory to our parent driver
// which will then bind it to its server implementation. We do not need to
// name the protocol because the method is templated on the channel type and
// it is able to automatically derive the name from the type.
zx::result client_end = DdkConnectFidlProtocol<fidl_examples_echo::EchoService::Echo>();
if (client_end.is_error()) {
zxlogf(ERROR, "Failed to connect fidl protocol: %s", client_end.status_string());
return client_end.status_value();
}
// We turn the client side of the endpoint pair into a synchronous client.
fidl::WireSyncClient client{std::move(client_end.value())};
// We can now utilize our client to make calls!
constexpr std::string_view kInput = "Test String";
auto result = client->EchoString(fidl::StringView::FromExternal(cpp17::string_view(kInput)));
if (!result.ok()) {
zxlogf(ERROR, "Failed to call EchoString");
return result.status();
}
if (result->response.get() != kInput) {
zxlogf(ERROR, "Unexpected response: Actual: \"%.*s\", Expected: \"%.*s\"",
static_cast<int>(result->response.size()), result->response.data(),
static_cast<int>(kInput.size()), kInput.data());
return ZX_ERR_INTERNAL;
}
return ZX_OK;
}
產生的繫結程式庫
所有 FIDL 程式庫都會收到系統根據這些程式庫建立自動產生的繫結程式庫。以便協助駕駛人根據父項提供的 FIDL 通訊協定和服務，以及父項用來提供每項規則的傳輸方法，建立繫結規則。
繫結程式庫
繫結程式庫中可能有三種可能的傳輸方法：Banjo、ZirconTransport 和 DriverTransport。目前，您可以放心假設值為 ZirconTransport (僅透過 Zircon 管道上的一般 FIDL) 或 DriverTransport (這是共置驅動程式的處理中通訊堆疊)。繫結程式庫包含通訊協定和這些傳輸方法的常數。
每項服務和 FIDL 程式庫中定義的可探索通訊協定都會在繫結程式庫中取得列舉，而列舉值是三種傳輸方法。
在以下範例中，FIDL 程式庫包含一個可探索的通訊協定：
protocol.fidl
library fuchsia.gizmo.protocol;
@discoverable
closed protocol TestingProtocol {
strict Get();
};
產生的 lib
// WARNING: This file is machine generated by bindc.
library fuchsia.gizmo.protocol;
enum TestingProtocol {
Banjo,
ZirconTransport,
DriverTransport,
};
建構目標
這些產生的繫結程式庫會使用 FIDL 程式庫的 library_name 和 target_name。繫結程式庫的目標名稱為 {fidl_target_name}_bindlib，其 library_name 也會與 FIDL 相同。
例如，如果 FIDL 程式庫目標為 //sdk/fidl/fidl.examples.echo:myecholibrary，則自動產生的繫結程式庫目標為 //sdk/fidl/fidl.examples.echo:myecholibrary_bindlib。
就實務上，大多數 FIDL 程式庫都與自身所在的資料夾具有相同的 target_name，通常也是程式庫名稱。例如，如果 FIDL 程式庫是 //sdk/fidl/fidl.examples.echo，則自動產生的繫結程式庫目標為 //sdk/fidl/fidl.examples.echo:fidl.examples.echo_bindlib。
產生的代碼目標
這些產生的繫結程式庫運作方式與使用者編寫的繫結程式庫完全相同。如要進一步瞭解如何為使用者編寫的繫結程式庫產生程式碼，請參閱「Bind 程式庫程式碼產生教學課程」。
範例
我們以上述所示的 FIDL 程式庫並用於範例。
FIDL (BUILD.gn)
fidl("my_fidl_target") { # The target_name
name = "fuchsia.gizmo.protocol" # The library_name (optional, defaults to
# target_name)
sources = [ "protocol.fidl" ]
}
這會提供產生的繫結程式庫，目標名稱為 :my_fidl_target_bindlib 和程式庫名稱 fuchsia.gizmo.protocol。為繫結程式庫產生的來源已顯示先前。我們可藉此為子項驅動程式庫建立繫結規則。
子項繫結規則 (BUILD.gn)
driver_bind_rules("bind") {
rules = "child_driver.bind"
bind_output = "child_driver.bindbc"
deps = [ ":my_fidl_target_bindlib" ]
}
sub-driver.bind
using fuchsia.gizmo.protocol;
fuchsia.gizmo.protocol.TestingProtocol == fuchsia.gizmo.protocol.TestingProtocol.ZirconTransport;
驅動程式庫建立子項節點時，系統會自動為 fuchsia_driver_framework::NodeAddArgs 資料表中的每個 offers 指派屬性。因此，父項驅動程式無需手動指定這個屬性。
例如，如果名為 fuchsia_hardware_gizmo::Service 的節點提供驅動程式庫載客服務能力，就會加入含有 fuchsia.hardware.gizmo.Service 鍵和 fuchsia.hardware.gizmo.Service.DriverTransport 鍵的屬性。這些值會與子項驅動程式庫在繫結規則中使用的對應繫結程式庫變數相符。
在建立複合節點規格時，產生的程式碼仍然很有用，因為通常在主面板驅動程式庫中發生。如果規格想根據這些優惠與節點進行比對，您必須手動為規格的屬性填寫優惠資訊。
我們可以利用自動產生的程式碼目標，從複合式節點規格建立程式碼存取這個繫結程式庫的常數。
複合節點規格建立者 (BUILD.gn)
C++
source_set("bindlib_usage_cpp") {
sources = [ "bindlib_usage.cc" ]
deps = [ ":my_fidl_target_bindlib_cpp" ]
}
Rust
rustc_binary("bindlib_usage_rust") {
edition = "2021"
source_root = "bindlib_usage.rs"
sources = [ "bindlib_usage.rs" ]
deps = [ ":my_fidl_target_bindlib_rust" ]
}
複合式節點規格建立者程式碼
C++
#include <bind/fuchsia/gizmo/protocol/cpp/bind.h>
std::string test_protocol_key = bind_fuchsia_gizmo_protocol::TESTINGPROTOCOL;
std::string test_protocol_value = bind_fuchsia_gizmo_protocol::TESTINGPROTOCOL_ZIRCONTRANSPORT;
Rust
fn main() {
let _test_protocol_key: &str = bind_fuchsia_gizmo_protocol::TESTINGPROTOCOL;
let _test_protocol_value: &str = bind_fuchsia_gizmo_protocol::TESTINGPROTOCOL_ZIRCONTRANSPORT;
}