總覽
本指南說明如何使用複合節點規格,將複合節點新增至 Driver Framework。本文假設您熟悉下列項目:
建立複合節點
複合節點是 如要建立複合節點,您必須:
- 在驅動程式中定義複合式節點規格
- 使用符合規範的繫結規則建立複合式驅動程式
當
- 找到相符的複合驅動程式後,驅動程式管理員會在拓樸中找到與每個父項規格相符的節點。每個相符的節點都會成為組合節點的父項。
- 所有父項規格相符後,驅動程式管理員會建立複合節點,並將節點設為父項,然後將複合驅動程式繫結至該節點。主節點和節點名稱由複合式驅動程式提供。
定義複合式節點規格
複合節點規格是一組父項規格,用於定義複合節點的父項。每個父項規格都包含下列項目:
- 繫結規則 -
- 屬性:父項規格中的屬性,用於比對複合式驅動程式的繫結規則。這些屬性遵循相同的格式,與節點屬性相同。
繫結規則
繫結規則可用於尋找並比對節點與父項規格。節點屬性會根據繫結規則進行評估,如果相符,節點就會成為組合的父項。
父項規格的繫結規則由接受和遭拒的屬性值清單組成。為了符合繫結規則,節點屬性必須包含所有接受的節點屬性值,而非任何遭拒的屬性值。
舉例來說,如果父項規格包含繫結規則:
- 接受
fuchsia.BIND_PROTOCOL
值:15 和 17 - 拒絕
fuchsia.BIND_PLATFORM_DEV_VID
值「Intel」
接著,如果裝置的 fuchsia.BIND_PROTOCOL
屬性值為 15 或 17,且不含 fuchsia.BIND_PLATFORM_DEV_VID
屬性的「Intel」值,則裝置會繫結至節點。
判斷繫結規則
判斷應採用何種繫結規則的程序,與繫結語言中的繫結規則相同。如要判斷繫結規則,您必須先找出要繫結的節點屬性。
您可以使用 ffx driver list-devices -v
指令列印節點拓撲中每個節點的屬性:
Name : i2c-1-56
Topo Path: sys/platform/i2c-0/aml-i2c/i2c/i2c-1-56
Driver : fuchsia-boot:///#driver/i2c.so
Flags : MUST_ISOLATE | BOUND
Proto : ZX_PROTOCOL_I2C (24)
3 Properties
[ 1/ 3] : Key fuchsia.BIND_I2C_BUS_ID Value 0x000001
[ 2/ 3] : Key fuchsia.BIND_I2C_ADDRESS Value 0x000038
[ 3/ 3] : Key "fuchsia.hardware.i2c.Service" Value "fuchsia.hardware.i2c.Service.ZirconTransport"
轉儲作業中的節點屬性為:
fuchsia.I2C_BUS_ID
= 0x01fuchsia.I2C_ADDRESS
= 0x38fuchsia.hardware.i2c.Service
= fuchsia.hardware.i2c.Service.ZirconTransport
您可以透過繫結程式庫 (例如 src/devices/bind 中的繫結程式庫) 搜尋屬性值。在本例中,由於節點是 I2C 節點,因此屬性值會在 fuchsia.i2c.bind 中找到。
fuchsia.i2c.bind
extend uint fuchsia.BIND_I2C_BUS_ID {
I2C_A0_0 = 0,
I2C_2 = 1,
I2C_3 = 2,
};
extend uint fuchsia.BIND_I2C_ADDRESS {
BACKLIGHT = 0x2C,
ETH = 0x18,
FOCALTECH_TOUCH = 0x38,
AMBIENTLIGHT = 0x39,
AUDIO_CODEC = 0x48,
GOODIX_TOUCH = 0x5d,
TI_INA231_MLB = 0x49,
TI_INA231_SPEAKERS = 0x40,
TI_INA231_MLB_PROTO = 0x46,
};
我們也會從 FIDL 程式庫產生繫結程式庫,這就是 fuchsia.hardware.i2c.Service
項目及其值 fuchsia.hardware.i2c.Service.ZirconTransport
的來源。詳情請參閱generated-bind-libraries。
這樣一來,我們就能將節點屬性重新對應至:
fuchsia.hardware.i2c.Service
=fuchsia.hardware.i2c.Service.ZirconTransport
fuchsia.BIND_I2C_BUS_ID
=fuchsia.i2c.BIND_I2C_BUS_ID.I2C_2
fuchsia.BIND_I2C_ADDRESS
=fuchsia.i2c.BIND_I2C_ADDRESS.FOCALTECH_TOUCH
您可以透過驅動程式原始碼中的產生程式庫,存取繫結程式庫值。詳情請參閱 繫結程式庫 codegen 教學課程。
我們可以定義下列繫結規則,以便與這些屬性相符:
accept fuchsia.hardware.i2c.Service { fuchsia.hardware.i2c.Service.ZirconTransport }
accept BIND_I2C_BUS_ID { fuchsia.i2c.BIND_I2C_BUS_ID.I2C_2 }
accept BIND_I2C_ADDRESS { fuchsia.i2c.BIND_I2C_ADDRESS.FOCALTECH_TOUCH }
使用 Driver Framework v1 (DFv1) 進行編寫
在 DFv1 中,複合節點規格是使用 DDK 編寫的。編寫繫結規則的函式位於 composite-node-spec.h
中。使用 DDK 程式庫和繫結程式庫 codegen 值,我們可以編寫以下內容:
const ddk::BindRule kI2cBindRules[] = {
ddk::MakeAcceptBindRule(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
ddk::MakeAcceptBindRule(bind_fuchsia::I2C_BUS_ID,
bind_fuchsia_i2c::BIND_I2C_BUS_ID_I2C_2),
ddk::MakeAcceptBindRule(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
使用 Driver Framework v2 (DFv2) 編寫程式
在 DFv2 中,會為 fuchsia.driver.framework
FIDL 程式庫中的 composite_node_spec.fidl
編寫複合節點規格。sdk/lib/driver/component/cpp
中的 composite_node_spec.h
程式庫可用來簡化繫結規則的定義程序。
使用該程式庫和繫結程式庫 codegen 值,我們可以編寫以下內容:
auto i2c_bind_rules = std::vector {
MakeAcceptBindRule(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
MakeAcceptBindRule(bind_fuchsia::I2C_BUS_ID,
bind_fuchsia_i2c::BIND_I2C_BUS_ID_I2C_2),
MakeAcceptBindRule(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
屬性
屬性是鍵/值組合,用於將父項規格與複合驅動程式的繫結規則相符。這些屬性與節點屬性相同,因此採用相同的格式。屬性金鑰可以是整數或字串,而屬性值可以是整數、布林值、字串或列舉類型。
使用 Driver Framework v1 (DFv1) 進行編寫
在 DFv1 中,複合節點規格是使用 DDK 編寫,而用來編寫繫結規則的函式則位於 composite-node-spec.h
中。使用 DDK 程式庫和繫結程式庫 codegen 值,我們可以編寫以下內容:
const device_bind_prop_t kI2cProperties[] = {
ddk::MakeProperty(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
ddk::MakeProperty(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
使用 Driver Framework v2 (DFv2) 編寫程式
在 DFv2 中,複合節點規格是針對 fuchsia.driver.framework FIDL 程式庫中的 composite_node_spec.fidl
編寫。//sdk/lib/driver/component/cpp
中的 node_add_args.h
程式庫可用於簡化繫結規則的定義。
auto i2c_properties[] = std::vector {
ddk::MakeProperty(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
新增複合節點規格
建立複合節點規格時,需要在驅動程式管理員中定義並新增一組父項規格。
平台匯流排組合
如果複合節點需要來自節點的父項,則可透過 platform_bus.fidl
API 新增複合節點規格。這適用於 DFv1 和 DFv2。
/// Adds a composite node specification to the bus. This will add a platform device specified
/// by |node| and insert a node into the composite node specification that matches the device.
AddCompositeNodeSpec(struct {
node Node;
spec fuchsia.driver.framework.CompositeNodeSpec;
}) -> () error zx.Status;
平台 Bus API 使用 composite_node_spec.fidl
中定義的相同 CompositeNodeSpec
結構。如需操作說明,請參閱「使用 FIDL 定義複合節點規格」。
舉例來說,假設我們定義了下列複合節點規格:
auto bind_rules = std::vector{
driver::MakeAcceptBindRule(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
driver::MakeAcceptBindRule(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_i2c::BIND_I2C_ADDRESS_BACKLIGHT),
};
auto properties = std::vector{
driver::MakeProperty(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
driver::MakeProperty(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_i2c::BIND_I2C_ADDRESS_BACKLIGHT),
};
auto spec = std::vector{
fuchsia_driver_framework::ParentSpecification{
.bind_rules = bind_rules,
.properties = properties,
},
};
定義複合節點規格後,板卡驅動程式就能透過 PlatformBus
FIDL 通訊協定連線至平台匯流排,並使用用戶端端點呼叫 AddCompositeNodeSpec()
。
AddCompositeNodeSpec()
呼叫會為根據節點欄位資料建立的平台裝置,將父項規格插入指定的複合節點規格,然後將修改後的複合節點規格新增至 Driver Framework。然後建立並新增平台裝置。
fpbus::Node dev;
dev.name() = "backlight";
dev.vid() = PDEV_VID_TI; // 0x10
dev.pid() = PDEV_PID_TI_LP8556; // 0x01
dev.did() = PDEV_DID_TI_BACKLIGHT; // 0x01
auto endpoints =
fdf::CreateEndpoints<fuchsia_hardware_platform_bus::PlatformBus>();
if (endpoints.is_error()) {
return endpoints.error_value();
}
fdf::WireSyncClient<fuchsia_hardware_platform_bus::PlatformBus> pbus =
endpoints->client;
auto result = pbus.buffer(arena)->AddCompositeNodeSpec(
fidl::ToWire(fidl_arena, dev),
fidl::ToWire(fidl_arena, spec), false);
if (!result.ok()) {
zxlogf(ERROR, "AddCompositeNodeSpec request failed: %s",
result.FormatDescription().data());
return result.status();
}
呼叫 AddCompositeNodeSpec()
後,下列複合節點規格會新增至 Driver Framework:
Name : backlight
Driver : fuchsia-boot:///#meta/ti-lp8556.cm
Nodes : 2
Node 0 : None
3 Bind Rules
[ 1/ 3] : Accept "fuchsia.BIND_PLATFORM_DEV_VID" { 0x000010 }
[ 2/ 3] : Accept "fuchsia.BIND_PLATFORM_DEV_PID" { 0x000001 }
[ 2/ 3] : Accept "fuchsia.BIND_PLATFORM_DEV_DID" { 0x000001 }
3 Properties
[ 1/ 3] : Key "fuchsia.BIND_PLATFORM_DEV_VID" Value 0x000010
[ 2/ 3] : Key "fuchsia.BIND_PLATFORM_DEV_PID" Value 0x000001
[ 3/ 3] : Key "fuchsia.BIND_PLATFORM_DEV_DID" Value 0x000001
Node 1 : None
2 Bind Rules
[ 1/ 2] : Accept "fuchsia.hardware.i2c.Service" { "fuchsia.hardware.i2c.Service.ZirconTransport" }
[ 2/ 2] : Accept "fuchsia.BIND_I2C_ADDRESS" { 0x00002C }
2 Properties
[ 1/ 2] : Key "fuchsia.hardware.i2c.Service" Value "fuchsia.hardware.i2c.Service.ZirconTransport"
[ 2/ 2] : Key "fuchsia.BIND_I2C_ADDRESS" Value 0x00002C
}
第一個父項規格是由 AddCompositeSpec()
插入,並與平台裝置相符,其中包含 fpbus::Node dev
中提供的 VID、PID 和 DID 的繫結規則和屬性。其餘的上層規格則來自傳入的複合節點規格。
驅動程式架構 v1 (DFv1)
在 DFv1 中,驅動程式庫可透過 DdkAddCompositeNodeSpec()
函式,透過 DDK 程式庫新增複合節點規格。
驅動程式必須先在 spec.h 程式庫中定義 CompositeNodeSpec
。使用上述的繫結規則和屬性,我們就可以定義具有 I2C 父項規格的 CompositeNodeSpec
:
const ddk::BindRule kI2cBindRules[] = {
ddk::MakeAcceptBindRule(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
ddk::MakeAcceptBindRule(bind_fuchsia::I2C_BUS_ID,
bind_fuchsia_i2c::BIND_I2C_BUS_ID_I2C_2),
ddk::MakeAcceptBindRule(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
const device_bind_prop_t kI2cProperties[] = {
ddk::MakeProperty(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
ddk::MakeProperty(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
auto spec = ddk::CompositeNodeSpec(kI2cBindRules, kI2cProperties);
您可以使用 AddParentSpec()
新增任何其他節點。舉例來說,如果想為 GPIO 解讀接腳新增父項規格,可以編寫下列內容:
const ddk::BindRule kGpioInterruptRules[] = {
ddk::MakeAcceptBindRule(bind_fuchsia::PROTOCOL,
bind_fuchsia_gpio::BIND_PROTOCOL_DEVICE),
ddk::MakeAcceptBindRule(bind_fuchsia::GPIO_PIN,
bind_fuchsia_amlogic_platform_s905d2::GPIOZ_PIN_ID_PIN_4),
};
const device_bind_prop_t kGpioInterruptProperties[] = {
ddk::MakeProperty(bind_fuchsia::PROTOCOL,
bind_fuchsia_gpio::BIND_PROTOCOL_DEVICE),
ddk::MakeProperty(bind_fuchsia_gpio::FUNCTION,
bind_fuchsia_gpio::FUNCTION_TOUCH_INTERRUPT)};
desc.AddParentSpec(kGpioInterruptRules, kGpioInterruptProperties);
您可以透過 set_metadata()
函式,將中繼資料傳遞至複合節點規格的複合函式。
CompositeNodeSpec
準備就緒後,您可以使用 DdkAddCompositeNodeSpec()
新增:
auto status = DdkAddCompositeNodeSpec("ft3x27_touch", spec);
由於 CompositeNodeSpec
遵循建構工具模式,因此可以簡化為:
auto status =
DdkAddCompositeNodeSpec("ft3x27_touch",
ddk::CompositeNodeSpec(kFocaltechI2cRules, kFocaltechI2cProperties)
.AddParentSpec(kGpioInterruptRules, kGpioInterruptProperties)
.set_metadata(metadata);
Driver Framework v2 (DFv2)
在 DFv2 中,我們使用 fuchsia.driver.framework
Fidl API 中的 CompositeNodeManager
新增複合節點規格。
@discoverable
protocol CompositeNodeManager {
/// Add the given spec to the driver manager.
AddSpec(CompositeNodeSpec) -> () error CompositeNodeSpecError;
};
使用 FIDL 定義複合節點規格
CompositeNodeSpec
結構體是在 composite_node_spec.fidl
中定義。您可以使用 sdk/lib/driver/component/cpp
程式庫中的 spec.h
和 node_add_args.h
函式,定義父項規格的繫結規則和屬性。
使用程式庫,我們可以為 I2C 節點和 gpio-interrupt 節點定義複合節點規格,並使用父項規格:
auto i2c_bind_rules = std::vector {
MakeAcceptBindRule(bind_fuchsia_hardware_i2c::SERVICE,
bind_fuchsia_hardware_i2c::SERVICE_ZIRCONTRANSPORT),
MakeAcceptBindRule(bind_fuchsia::I2C_BUS_ID,
bind_fuchsia_i2c::BIND_I2C_BUS_ID_I2C_2),
MakeAcceptBindRule(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
auto i2c_properties[] = std::vector {
ddk::MakeProperty(bind_fuchsia::I2C_ADDRESS,
bind_fuchsia_focaltech_platform::BIND_I2C_ADDRESS_TOUCH),
};
auto gpio_interrupt_bind_rules = std::vector {
MakeAcceptBindRule(bind_fuchsia::BIND_PROTOCOL,
bind_fuchsia_gpio::BIND_PROTOCOL_DEVICE),
MakeAcceptBindRule(bind_fuchsia::GPIO_PIN,
bind_fuchsia_amlogic_platform_s905d2::GPIOZ_PIN_ID_PIN_4),
};
auto gpio_interrupt_properties[] = std::vector {
ddk::MakeProperty(bind_fuchsia::BIND_PROTOCOL,
bind_fuchsia_gpio::FUNCTION_TOUCH_INTERRUPT),
};
auto nodes = std::vector{
fdf::ParentSpec{
.bind_rules = i2c_bind_rules,
.properties = i2c_properties,
},
fdf::ParentSpec{
.bind_rules = gpio_interrupt_bind_rules,
.properties = gpio_interrupt_properties,
},
};
auto spec = fdf::CompositeNodeSpec {.name = "fo", .nodes = nodes};
新增複合式節點規格
如要將複合節點規格新增至 CompositeNodeManager
,您必須連線至服務:
auto client = incoming()->Connect<fdf::CompositeNodeManager>();
if (client.is_error()) {
FDF_LOG(ERROR, "Failed to connect to CompositeNodeManager: %s",
zx_status_get_string(client.error_value()));
return client.take_error();
}
fidl::SharedClient<fdf::CompositeNodeManager> composite_node_manager;
composite_node_manager.Bind(std::move(client.value()), dispatcher());
然後呼叫 API:
composite_node_manager->AddSpec(std::move(spec))
.Then([this](
fidl::Result<fdf::CompositeNodeManager::AddSpec>& create_result) {
if (create_result.is_error()) {
FDF_LOG(ERROR, "AddSpec failed: %s",
create_result.error_value().FormatDescription().c_str());
return;
}
FDF_LOG(INFO, "Succeeded adding spec");
});
定義複合式驅動程式繫結規則
複合驅動程式是只綁定至複合節點的驅動程式。驅動程式是透過繫結規則定義,詳情請參閱複合繫結規則。
比對程序
比對程序是將複合驅動程式的繫結規則套用至父項規格的屬性。只要符合下列條件,系統就會成功比對:
- 所有父項規格都必須與複合式繫結規則中的節點相符
- 所有非選用複合繫結規則節點都必須與父項規格相符。
比對結果不得模棱兩可:
- 每個父項規格都必須只對應至一個複合繫結規則節點
- 每個複合繫結規則節點最多只能與一個父項規格相符。選用的繫結規則可能會與零個父項規格相符。
- 節點不必依序配對
- 如果發生不確定的情況,系統會顯示警告訊息。
編寫繫結規則
以上述範例來說,假設我們想在父項規格中使用下列屬性,將其繫結至複合節點規格:
i2c parent specification properties {
fuchsia.hardware.i2c.Service: fuchsia.hardware.i2c.Service.ZirconTransport,
fuchsia.BIND_I2C_ADDRESS: fuchsia.focaltech.platform.BIND_I2C_ADDRESS_TOUCH,
}
gpio-interrupt parent specification properties {
fuchsia.BIND_PROTOCOL: fuchsia.gpio.BIND_PROTOCOL_DEVICE,
fuchsia.gpio.FUNCTION: fuchsia.gpio.FUNCTION.TOUCH_INTERRUPT,
}
我們可以編寫複合繫結規則,讓規則與父項規格相符:
composite focaltech_touch;
using fuchsia.gpio;
using fuchsia.hardware.i2c;
using fuchsia.i2c;
primary node "i2c" {
fuchsia.hardware.i2c.Service == fuchsia.hardware.i2c.Service.ZirconTransport;
fuchsia.BIND_I2C_ADDRESS == fuchsia.i2c.BIND_I2C_ADDRESS.FOCALTECH_TOUCH;
}
node "gpio-int" {
fuchsia.BIND_PROTOCOL == fuchsia.gpio.BIND_PROTOCOL.DEVICE;
fuchsia.gpio.FUNCTION == fuchsia.gpio.FUNCTION.TOUCH_INTERRUPT;
}
偵錯
如要確認複合節點是否已成功建立,並嘗試繫結複合驅動程式,您可以查看記錄,找出類似以下的陳述式:
Binding driver fuchsia-boot:///#meta/focaltech.cm
如要確認已成功新增複合節點規格,並與複合驅動程式相符,請執行下列指令:
ffx driver list-composite-node-specs -v
這會輸出類似以下的結果:
Name : ft3x27_touch
Driver : fuchsia-boot:///#meta/focaltech.cm
Nodes : 2
Node 0 : "i2c" (Primary)
3 Bind Rules
[ 1/ 3] : Accept "fuchsia.hardware.i2c.Service" { "fuchsia.hardware.i2c.Service.ZirconTransport" }
[ 2/ 3] : Accept "fuchsia.BIND_I2C_BUS_ID" { 0x000001 }
[ 3/ 3] : Accept "fuchsia.BIND_I2C_ADDRESS" { 0x000038 }
2 Properties
[ 1/ 2] : Key "fuchsia.hardware.i2c.Service" Value "fuchsia.hardware.i2c.Service.ZirconTransport"
[ 2/ 2] : Key "fuchsia.BIND_I2C_ADDRESS" Value 0x000038
Node 1 : "gpio-int"
2 Bind Rules
[ 1/ 2] : Accept "fuchsia.BIND_PROTOCOL" { 0x000014 }
[ 2/ 2] : Accept "fuchsia.BIND_GPIO_PIN" { 0x000004 }
2 Properties
[ 1/ 2] : Key "fuchsia.BIND_PROTOCOL" Value 0x000014
[ 2/ 2] : Key "fuchsia.gpio.FUNCTION" Value "fuchsia.gpio.FUNCTION.TOUCH_INTERRUPT"
如果複合節點規格沒有相符的複合驅動程式,輸出內容會類似以下內容:
Name : focaltech_touch
Driver : None
Nodes : 2
Node 0 : None
3 Bind Rules
[ 1/ 3] : Accept "fuchsia.hardware.i2c.Service" { "fuchsia.hardware.i2c.Service.ZirconTransport" }
[ 2/ 3] : Accept "fuchsia.BIND_I2C_BUS_ID" { 0x000001 }
[ 3/ 3] : Accept "fuchsia.BIND_I2C_ADDRESS" { 0x000038 }
1 Properties
[ 1/ 2] : Key "fuchsia.hardware.i2c.Service" Value "fuchsia.hardware.i2c.Service.ZirconTransport"
[ 2/ 2] : Key "fuchsia.BIND_I2C_ADDRESS" Value 0x000038
Node 1 : None
2 Bind Rules
[ 1/ 2] : Accept "fuchsia.BIND_PROTOCOL" { 0x000014 }
[ 2/ 2] : Accept "fuchsia.BIND_GPIO_PIN" { 0x000004 }
2 Properties
[ 1/ 2] : Key "fuchsia.BIND_PROTOCOL" Value 0x000014
[ 2/ 2] : Key "fuchsia.gpio.FUNCTION" Value "fuchsia.gpio.FUNCTION.TOUCH_INTERRUPT