Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

设备枚举测试

系统级驱动程序拓扑验证

在开发新驱动程序、修改驱动程序绑定规则或将旧版 DFv1 驱动程序迁移到新驱动程序框架 (DFv2) 时，务必要验证所有预期设备是否在系统拓扑中枚举。设备枚举测试 (device-enumeration-test) 针对实际目标环境（模拟器或物理硬件）运行，以确保驱动程序树成功初始化，而不会发生崩溃、挂起或回归。

虽然单元测试和 DriverTestRealm 会验证各个驱动程序或隔离的组件 realm，但设备枚举测试会验证集成系统。它们可确认驱动程序是否绑定到其父节点、发布预期的子节点，以及是否允许在主板上正确组装复合设备。

设备枚举测试概览

设备枚举测试会连接到 fuchsia.driver.development/Manager (GetNodeInfo) FIDL 协议，以便在系统启动期间检查驱动程序拓扑中的设备节点树。

每个目标板（aemu_x64、qemu_x64、vim3、nelson 以及特定于供应商的板）都定义了一个必需的节点别名列表，这些别名必须在驱动程序发现完成后存在。如果必需的设备节点在超时时间内未能成功枚举，则测试失败，表明堆栈中的驱动程序未能绑定、崩溃或遇到错误。

发现可用的设备枚举测试

您可以通过运行带有 --dry 标志的 fx test 来列出环境中的可用设备和驱动程序主机枚举测试：

fx test --dry device-enumeration

fx test --dry driver-host-enumeration

运行设备枚举测试

在运行设备枚举测试之前，请确保您的有效 build 目录 (fx use) 和目标设备（fx set-device 或 fx -t <device> test ...）与被测主板相匹配。

根据目标板是否将枚举测试作为封装测试或 bootfs 测试，使用以下两种主要执行方法之一：

1. 使用 `fx test` 运行打包的测试 (`fuchsia_unittest_package`)

如果测试是针对联网 build（例如 minimal 或 workbench 产品，其中软件包服务和 SSH 处于活跃状态）构建为标准组件软件包 (fuchsia_unittest_package)，则使用 fx test 通过软件包服务动态执行该测试：

如果测试软件包目标尚未包含在您的有效 build 配置 (tests.json) 中，请使用 fx add-test 添加该目标：
```
fx add-test //path/to/test:device-enumeration-test-myboard
fx build
```

使用 fx test 运行测试，并使用 --package 和 -o（或指定完整网址）：

fx test --package device-enumeration-test-myboard -o

PKG="device-enumeration-test-myboard"
fx test "fuchsia-pkg://fuchsia.com/${PKG}#meta/${PKG}.cm" -o

2. 通过 SSH 或串行直接运行 bootfs 测试 (`bootfs_test`)

如果目标主板在 bootfs（例如 /boot/test/...）内配置了枚举测试，请勿直接运行 fx test /boot/test/...，因为 bootfs_test 目标默认情况下不会通过标准 SSH 测试运行程序流水线运行。

而是直接在已启动的目标设备上执行 /boot/test/ 二进制文件：

通过 SSH 执行（minimal build）：如果目标设备正在运行将二进制文件嵌入 bootfs 中的联网 build（例如 minimal.<board>），请通过 SSH 在已启动的设备上直接运行该二进制文件：
```
ffx target ssh "/boot/test/device-enumeration-test-myboard-bin"
```
通过串行执行（bringup build）：如需在 bringup 映像上进行早期启动测试，请使用预配置的 bringup_with_tests.<board> 产品 bundle（例如 bringup_with_tests.iris），该 bundle 会自动嵌入 bootfs 测试二进制文件，而无需手动组装替换 (--assembly-override)。由于 bringup 映像在运行时不需要网络发现或软件包服务器，因此请在 fx serial 内执行二进制文件。

3. 运行驱动程序主机枚举测试 (`driver-host-enumeration-test`)

除了验证设备节点别名 (device-enumeration-test) 之外，主板还定义了驱动程序主机枚举测试 (driver-host-enumeration-test)，以验证主板上的驱动程序是否按预期分组到驱动程序主机中 (*_host_golden.json)。

由于驱动程序主机枚举测试通过 FIDL (fuchsia.driver.development/Manager) 连接来查询在启动期间 (GetDriverHostInfo) 在目标设备上运行的有效驱动程序主机，因此您的有效 build 目录 (fx use) 和配置的目标设备 (fx set-device) 必须与被测主板（例如 iris.minimal）相匹配。

如需针对实时目标设备（例如 iris 板）运行驱动程序主机枚举测试，请执行以下操作：

切换到主板的 build 目录，然后设置目标设备：
```
fx use out/iris.minimal
fx set-device <device-name>
```
如果测试目标尚未包含在您的有效 build 配置 (tests.json) 中，请使用 fx add-test 添加该目标并进行 build：
```
fx add-test //vendor/google/iris/board/drivers/iris:driver-host-enumeration-test-iris
fx build
```

使用 fx test 运行测试，并使用 --package 和 -o：

fx test --package driver-host-enumeration-test-iris -o

CQ 中的自动化验证

在 Gerrit 中上传驱动程序更改或新的主板配置以供代码审核时，您可以使用 Choose Tryjobs 选择特定于主板的启动 tryjob 构建器（例如 bringup.iris-debug），在持续集成中自动验证设备枚举。

使用程序集开发者替换项将现有枚举测试添加到 build

如果代码库中已存在设备枚举测试（或 bootfs 测试软件包，例如 //vendor/google/iris/enumeration:bootfs_test_files），您可以使用 assembly_developer_overrides() 将其包含在本地 build 中，而无需修改树内产品目标。

在本地 BUILD.gn 文件（通常为 //local/BUILD.gn）中定义程序集替换项：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("my_enumeration_overrides") {
  bootfs_files_labels = [
    "//vendor/google/iris/enumeration:bootfs_test_files",
  ]
}

使用 fx set 配置 build 时应用替换：

fx set bringup.iris --assembly-override //local:my_enumeration_overrides
fx build

组装 bringup.iris 产品软件包时，指定的 bootfs 测试文件会自动直接嵌入到 bootfs 映像中，这样您就可以通过串行端口 (fx serial) 运行测试。

何时以及如何更新设备枚举测试

每当您进行会改变主板节点拓扑的更改时，都必须更新主板的设备枚举测试，例如：

向电路板添加新驱动程序或设备。
重命名现有节点别名或更改节点属性。
将驱动程序从 DFv1 迁移到 DFv2，其中节点名称或父子拓扑发生变化。

测试来源位置

树内主板测试：标准树内主板的源定义和预期节点列表位于 //zircon/system/utest/device-enumeration/ 中。例如，请参阅 boards/aemu_x64.cc 和 boards/vim3.cc。
供应商主板测试：对于特定于供应商或树外的主板，枚举测试定义位于其各自的供应商代码库中（例如，位于 //vendor/google/<board>/enumeration/ 下）。

修改枚举测试时，请将新节点别名添加到相应主板测试文件中的 kNodeMonikers 数组，以便自动化验证能够捕获驱动程序堆栈中未来出现的任何回归问题。

更新驱动程序主机枚举黄金文件

在驱动程序宿主之间添加、移除或重新定位驱动程序（或更改 cml/bind 文件中的并置属性）时，预期的驱动程序宿主分组 (ExpectedDriverHost) 会发生变化。修改主板的驱动程序主机拓扑时，请同时更新相应的黄金 JSON 文件 (*_host_golden.json) 以及驱动程序更改，以确保验证通过。