绑定规则教程

本指南介绍了如何为驱动程序编写绑定规则，使其绑定到所需的设备。其中介绍了如何查找节点属性，然后使用绑定语言为其编写绑定规则。

本指南假定您熟悉驱动程序绑定。

节点属性的当前状态

目前，节点属性是在绑定库和 C++ 头文件中定义的。过去，节点属性是基于整数的键值对，被描述为 C++ 结构体。所有属性均在 C++ 头文件中定义，绑定规则是驱动程序源代码的一部分。

不过，绑定系统最近进行了改进，以便使用绑定语言在单独的文件中定义绑定规则，并且节点属性可以支持基于字符串的键（具有布尔值、字符串、整数或枚举值）。

目前正在进行迁移，以便将所有驱动程序从旧绑定系统迁移到新系统。正在绑定库中重新定义 C++ 头文件中的节点属性。例如，所有设备协议 ID 绑定值都已硬编码到 protodefs.h 中。现在，每个设备协议都在各自的绑定库中进行定义，该库包含协议 ID 的定义以及与协议相关联的其他节点属性。绑定库全部位于 src/devices/bind。

在迁移完成之前，需要同时支持新旧绑定系统。

节点属性的未来状态

绑定迁移完成后，我们可以停止支持旧的基于整数的节点属性，并移除 C++ 定义，例如 protodefs.h 和 binding_priv.h。所有属性都将在绑定库中进行定义，键将完全基于字符串。

您可以更新现有媒体资源，以便利用新系统的功能。例如，BIND_COMPOSITE 属性是仅针对复合设备设置的标志。不过，由于旧系统仅支持整数值，因此属性值会使用整数而不是布尔值。移除旧绑定系统后，属性值可更改为布尔值。

可以进行的其他更改是如何表示 VID。我们可以使用 VID 名称，而不是为 VID 分配唯一的整数。例如，Intel VID 目前由整数值 0x8 表示：

library fuchsia.intel.platform;

extend uint fuchsia.BIND_PLATFORM_DEV_VID {
  INTEL = 0x8,
};

使用新绑定系统时，VID 可以用字符串值甚至枚举表示。

查询节点属性

使用 ffx 驱动程序 list-devices

ffx driver list-devices -v 命令会按以下格式输出树中每台设备的属性：

Name     : _TZ_
Moniker  : root.sys.platform.pt.acpi._TZ_
Driver   : None
5 Properties
[ 1/  5] : Key fuchsia.BIND_PROTOCOL Value 0x1F
[ 2/  5] : Key fuchsia.BIND_PCI_VID Value 0x1AF4
[ 3/  5] : Key fuchsia.BIND_PCI_DID Value 0x1052
[ 4/  5] : Key fuchsia.COMPOSITE_BIND Value 1
[ 5/  5] : Key "fuchsia.acpi.HID" Value "GFSH0005"

驱动程序源代码中的驱动程序属性

添加子设备时，驱动程序可以提供与绑定规则匹配的属性。因此，您可以通过驱动程序源代码找到要绑定的属性。

在 DFv1 中，源代码中的节点属性由“Properties”和“String Properties”表示。属性包含基于整数的键和值。不过，字符串属性包含基于字符串的键和值，可以是整数、布尔值、字符串或枚举。

在以下代码段中，驱动程序会添加具有 BIND_PROTOCOL 属性和“ENABLE_TEST”字符串属性的设备。

device_add_args_t args = {};
args.version = DEVICE_ADD_ARGS_VERSION;
args.name = "parent";
args.ops = &dev_ops;

zx_device_str_prop_t str_props[] = {
      zx_device_str_prop_t{.key = "ENABLE_TEST",
                           .property_value = str_prop_bool_val(true)}
};
args.str_props = str_props;
args.str_prop_count = std::size(str_props);

device_add(parent, &args, &dev);

在 DFv2 中，节点属性由 fuchsia.driver.framework FIDL 库中的 NodeProperty 结构体表示：

auto properties = fidl::VectorView<fdf::wire::NodeProperty>(arena, 2);
properties[0] = fdf::MakeProperty(arena, BIND_PROTOCOL, ZX_PROTOCOL_PCI);
properties[1] = fdf::MakeProperty(arena, "ENABLED_TEST", true);

auto args = fdf::wire::NodeAddArgs::Builder(arena)
                  .name(arena, "sample-child")
                  .properties(properties)
                  .Build();

在绑定库中定义属性

当我们从驱动程序从旧绑定系统迁移到新驱动程序时，会在新系统上的绑定库中重新定义旧属性。这些绑定库位于 src/devices/bind 目录中。

任何新属性都应在绑定库中进行定义。

旧绑定系统中的属性

大多数旧节点属性键和值都在 binding_priv.h 和 protodefs.h 中定义。

binding_priv.h 包含硬编码的属性键。系统会为每个属性键分配一个唯一的整数值。在新的绑定系统中，这些键使用 fuchsia.BIND_ 前缀重新定义。例如，BIND_PROTOCOL 会变为 fuchsia.BIND_PROTOCOL，BIND_COMPOSITE 会变为 fuchsia.BIND_COMPOSITE。

protodefs.h 包含设备协议的硬编码 ID 值。

设备协议绑定库

protodefs.h 中的每个设备协议都应该有自己的绑定库，其中包含其协议 ID 和相关属性。例如 fuchsia.i2c 绑定库，它不仅定义了协议 ID 值，还定义了其他 i2c 相关属性：

library fuchsia.i2c;

extend uint fuchsia.BIND_PROTOCOL {
  DEVICE = 24,
  IMPL = 25,
};

extend uint fuchsia.BIND_I2C_CLASS {
  HID = 0x01,
};

extend uint fuchsia.BIND_I2C_ADDRESS {
  BACKLIGHT = 0x2C,
  ETH = 0x18,
  FOCALTECH_TOUCH = 0x38,
  AMBIENTLIGHT = 0x39,
};

协议 ID 值与 protodefs.h 中定义的值一致：

DDK_PROTOCOL_DEF(I2C,                     24,   "i2c", 0)
DDK_PROTOCOL_DEF(I2C_IMPL ,               25,   "i2c-impl", 0)

IMPL 值表示实现并提供 i2c 协议的驱动程序。DEVICE 代表使用 IMPL 协议并提供 DEVICE 协议的核心驱动程序。

编写绑定规则

本部分介绍了如何为驱动程序绑定的当前状态编写绑定规则。对于仅绑定到上述属性集的绑定规则，您需要编写以下代码：

using fuchsia.acpi;
using fuchsia.pci;

fuchsia.BIND_PROTOCOL == fuchsia.pci.BIND_PROTOCOL.DEVICE;
fuchsia.BIND_PCI_VID == fuchsia.pci.BIND_PCI_VID.VIRTIO;
fuchsia.BIND_PCI_DID == fuchsia.pci.BIND_PCI_DID.VIRTIO_DEV_TYPE_INPUT;
fuchsia.BIND_COMPOSITE == 1;
fuchsia.acpi.HID == "GFSH0005";

属性键

整数键名称在 binding_priv.h 中定义，并且带有“fuchsia”前缀。例如，dm dump 中的键 0x03 被确定为 fuchsia.BIND_COMPOSITE，因为 binding_priv.h 包含以下内容：

#define BIND_FLAGS 0x0000          // value of the flags register
#define BIND_PROTOCOL 0x0001       // primary protocol of the device
#define BIND_AUTOBIND 0x0002       // if this is an automated bind/load
#define BIND_COMPOSITE 0x003       // Whether this is a composite device

属性值

由于属性与 PCI 相关联，因此匹配值可在 fuchsia.pci.bind 库中找到。通过将 0x001af4 与 fuchsia.BIND_PCI_VID 中的值进行匹配可找到 fuchsia.pci.BIND_PCI_VID.VIRTIO。

extend uint fuchsia.BIND_PCI_VID {
  TEST = 0x0eff,
  AMD = 0x1002,
  REALTEK = 0x10ec,
  NVIDIA = 0x10de,
  GOOGLE = 0x1ae0,
  VIRTIO = 0x1af4,
  BROADCOM = 0x14e4,
  ATHEROS = 0x168c,
  INTEL = 0x8086,
};

如果绑定库中缺少某个值，您需要在新的或现有的绑定库中添加缺失的定义。或者，您可以直接为该值编写绑定规则：

fuchsia.BIND_PCI_VID == 0x1af4;

不过，最好在绑定库中定义一个值。

复合绑定规则

复合绑定规则会采用相同的流程。对于要为其编写绑定规则的节点，您可以输出节点属性并为其编写绑定规则。

假设您想要编写复合绑定规则，其中包含一个绑定到上述示例的节点，以及另一个绑定到以下代码的节点：

Name     : I2C2
Moniker  : root.sys.platform.pt.acpi.I2C2
Driver   : None
6 Properties
[ 1/  6] : Key fuchsia.BIND_ACPI_ID           Value 0x000034
[ 2/  6] : Key fuchsia.BIND_PCI_TOPO          Value 0x0000aa
[ 3/  6] : Key fuchsia.BIND_ACPI_BUS_TYPE     Value 0x000001
[ 4/  6] : Key "fuchsia.hardware.acpi.Device" Value true
[ 5/  6] : Key fuchsia.BIND_PROTOCOL          Value 0x00001e
[ 6/  6] : Key "fuchsia.platform.DRIVER_FRAMEWORK_VERSION" Value 0x000002

然后，您可以编写以下内容：

using fuchsia.acpi;
using fuchsia.pci;

primary node "pci_sample" {
  fuchsia.BIND_PROTOCOL == fuchsia.pci.BIND_PROTOCOL.DEVICE;
  fuchsia.BIND_PCI_VID == fuchsia.pci.BIND_PCI_VID.VIRTIO;
  fuchsia.BIND_PCI_DID == fuchsia.pci.BIND_PCI_DID.VIRTIO_DEV_TYPE_INPUT;
  fuchsia.BIND_COMPOSITE == 1;
  fuchsia.acpi.HID == "GFSH0005";
}

node "acpi" {
  fuchsia.driver.framework.dfv2 == true;
  fuchsia.BIND_ACPI_ID == 0x000034;
  fuchsia.BIND_PCI_TOPO == 0x0000aa;
  fuchsia.BIND_ACPI_BUS_TYPE == 0x000001;
}

可选节点

可选节点是指并非必须存在于设备组中才能发挥作用的节点 以匹配一个复合驱动程序。 这仅在使用设备组时受支持，在 普通旧版复合，其中拓扑中的节点与复合驱动程序匹配。

在绑定规则中，将 optional 放在 node 关键字前面会标记该节点 可选。按照惯例，所有可选节点都应该在 常规额外节点

可选节点用于编写更加通用的复合驱动程序规则。对于 例如，HID 按钮驱动程序支持 9 种不同的按钮类型（音量调高、摄像头静音等）， 但并不是所有的硬件设备上都有所有这些按钮。具有可选节点 绑定规则可以编写为与平台无关，因此板级驱动程序可以创建 与 HID 按钮驱动程序支持的任意按钮集组合而成。

绑定规则示例

分支绑定规则

绑定语言支持通过 if 语句进行分支，但有一些限制。

If 语句必须包含 else 代码块并且为终端。此限制通过明确执行分支来提高可读性。由于 if 语句后无法跟踪任何语句，因此通过绑定规则可以轻松跟踪路径。

if fuchsia.hardware.tee.Service == fuchsia.hardware.tee.Service.ZirconTransport {
  fuchsia.BIND_PLATFORM_DEV_VID == fuchsia.platform.BIND_PLATFORM_DEV_VID.GENERIC;
} else {
  fuchsia.BIND_PLATFORM_DEV_VID == fuchsia.platform.BIND_PLATFORM_DEV_VID.QEMU;
}

支持嵌套 if 语句，前提是它们遵循相关限制。例如：

if fuchsia.driver.framework.dfv2 == true {
  if fuchsia.acpi.hid == "PNP0303" {
    true;
  } else {
    fuchsia.acpi.first_cid == "PNP0303";
  }
} else {
  fuchsia.BIND_PROTOCOL == fuchsia.acpi.BIND_PROTOCOL.DEVICE;
}

排除多个属性值

要拒绝一个键的多个属性值，可以将不等性条件语句连在一起。例如，如果您需要拒绝多个 fuchsia.BIND_PCI_DID 值，则可以执行以下操作：

fuchsia.BIND_PCI_DID != 0x191b;
fuchsia.BIND_PCI_DID != 0x1912;
fuchsia.BIND_PCI_DID != 0x191d;
fuchsia.BIND_PCI_DID != 0x1902;
fuchsia.BIND_PCI_DID != 0x1916;
fuchsia.BIND_PCI_DID != 0x191e;