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

裝置列舉測試

系統層級的驅動程式庫拓撲驗證

開發新驅動程式、修改驅動程式庫繫結規則，或將舊版 DFv1 驅動程式遷移至新版驅動程式庫架構 (DFv2) 時，請務必確認所有預期裝置都會在系統拓撲中列舉。裝置列舉測試 (device-enumeration-test) 會針對實際目標環境 (模擬器或實體硬體) 執行，確保驅動程式庫樹狀結構順利初始化，不會發生當機、停止回應或回歸情形。

單元測試和 DriverTestRealm 會驗證個別驅動程式或獨立元件領域，而裝置列舉測試則會驗證整合式系統。他們會確認驅動程式庫是否繫結至父項節點、發布預期的子項節點，以及允許複合裝置在主機板上正確組裝。

裝置列舉測試總覽

裝置列舉測試會連線至 fuchsia.driver.development/Manager (GetNodeInfo) FIDL 通訊協定，以便在系統啟動期間檢查驅動程式庫程式拓撲中的裝置節點樹狀結構。

每個目標開發板 (aemu_x64、qemu_x64、vim3、nelson，以及供應商專屬開發板) 都會定義必要節點代號清單，驅動程式庫探索完成後必須存在這些代號。如果必要裝置節點在逾時前無法列舉，測試就會失敗，表示堆疊中的驅動程式庫無法繫結、當機或發生錯誤。

探索可用的裝置列舉測試

如要列出環境中可用的裝置和驅動程式代管程序列舉測試，請執行 fx test 並加上 --dry 旗標：

fx test --dry device-enumeration

fx test --dry driver-host-enumeration

執行裝置列舉測試

執行裝置列舉測試前，請確認有效建構目錄 (fx use) 和目標裝置 (fx set-device 或 fx -t <device> test ...) 與測試中的開發板相符。

視目標開發板是否將列舉測試納入封裝測試或 bootfs 測試，使用下列兩種主要執行方法之一：

1. 使用 `fx test` 執行封裝測試 (`fuchsia_unittest_package`)

如果測試是針對網路建構 (例如套件服務和 SSH 處於啟用狀態的 minimal 或 workbench 產品) 建構為標準元件套件 (fuchsia_unittest_package)，請使用 fx test，透過套件服務動態執行測試：

如果測試套件目標尚未納入有效建構設定 (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_test`)

如果目標開發板在 bootfs 內設定列舉測試 (例如 /boot/test/...)，請勿直接執行 fx test /boot/test/...，否則 bootfs_test 目標預設不會透過標準 SSH 測試執行元件管道執行。

請直接在啟動的目標上執行 /boot/test/ 二進位檔：

透過 SSH 執行 (minimal 建構)：如果目標執行的是網路建構 (例如 minimal.<board>)，且該建構將二進位檔內嵌在 bootfs 中，請透過 SSH 在已啟動的裝置上直接執行二進位檔：
```
ffx target ssh "/boot/test/device-enumeration-test-myboard-bin"
```
透過序列執行 (bringup 建構)：如要對 bringup 映像檔進行早期啟動測試，請使用預先設定的 bringup_with_tests.<board> 產品組合 (例如 bringup_with_tests.iris)，這會自動嵌入 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)，因此作用中建構目錄 (fx use) 和設定的目標裝置 (fx set-device) 必須與測試中的開發板 (例如 iris.minimal) 相符。

如要對實際目標裝置 (例如 iris 板) 執行驅動程式代管程序列舉測試，請按照下列步驟操作：

切換至開發板的建構目錄，然後設定目標裝置：
```
fx use out/iris.minimal
fx set-device <device-name>
```
如果測試目標尚未納入有效建構設定 (tests.json)，請使用 fx add-test 新增並建構：
```
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 中上傳驅動程式庫變更或新的主機板設定以供程式碼審查時，您可以選取主機板專屬的啟動作業建構工具 (例如 bringup.iris-debug)，然後使用「選擇試用作業」，在持續整合中自動驗證裝置列舉。

使用組件開發人員覆寫，將現有列舉測試新增至建構作業

如果程式碼集已存在裝置列舉測試 (或啟動檔案系統測試套件，例如 //vendor/google/iris/enumeration:bootfs_test_files)，您可以使用 assembly_developer_overrides() 將其納入本機建構作業，而不需修改樹狀結構內產品目標。

在本地 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 設定建構時，請套用覆寫：

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

組裝 bringup.iris 產品套件時，指定的啟動檔案系統測試檔案會自動直接嵌入啟動檔案系統映像檔，方便您透過序列埠 (fx serial) 執行測試。

何時及如何更新裝置列舉測試

每當您進行變更，導致開發板的節點拓撲發生變化時，都必須更新開發板的裝置列舉測試，例如：

在主機板上新增驅動程式庫或裝置。
重新命名現有節點別名或變更節點屬性。
將驅動程式庫從 DFv1 遷移至 DFv2，其中節點名稱或父項/子項拓撲會變更。

測試來源位置

樹內開發板測試：標準樹狀結構內開發板的來源定義和預期節點清單位於 //zircon/system/utest/device-enumeration/。例如 boards/aemu_x64.cc 和 boards/vim3.cc。
供應商開發板測試：如果是供應商專屬或樹狀結構外的開發板，列舉測試定義會位於各自的供應商存放區中 (例如 //vendor/google/<board>/enumeration/ 下方)。

修改列舉測試時，請將新節點代號新增至對應主機板測試檔案中的 kNodeMonikers 陣列，以便自動驗證功能日後偵測到驅動程式庫堆疊中的任何迴歸。

更新驅動程式代管程序列舉黃金檔案

在驅動程式庫主機之間新增、移除或重新定位驅動程式 (或變更 cml/繫結檔案中的並置屬性) 時，預期的驅動程式代管程序分組 (ExpectedDriverHost) 會變更。修改開發板的驅動程式代管程序拓撲時，請一併更新對應的黃金 JSON 檔案 (*_host_golden.json) 和驅動程式庫變更，確保驗證通過。