對駕駛使用檢查功能

先決條件

如果您不熟悉 Inspect，建議閱讀下列頁面：

簡介

駕駛人可以使用檢查功能。不過，由於駕駛人並非元件，因此必須特別考量。

請參考下列系統拓撲圖：

系統拓撲圖，顯示透過 VMO 和 Tree 服務公開檢查資料的元件和驅動程式。

圖表圖例：

灰色：元件。 藍色：顯示 out/diagnostics 目錄內容的元件命名空間。紫色：out/diagnostics/* 檢查檔案的內容。

元件可以透過下列方式公開檢查資料：

  • VMO 檔案：通常稱為 root.inspect
  • 樹狀結構服務：fuchsia.inspect.Tree 通訊協定的服務檔案

元件可以公開一或多個這類檔案。在上圖中，元件 foo 和 echo 會公開單一檔案。不過，driver_manager 會公開多個檔案，每個裝置對應一個 VMO 檔案。

這是因為每個裝置都不是元件，因此 driver_manager 會匯總檢查 VMO 並自行發布。這是從元件和驅動程式庫公開檢查資料的主要差異，會影響透過選取器查詢資料的方式。

如要查詢 foo 和 echo 元件的資料，可以透過特定選取器表示。例如 core/foo:root/child1:prop1、core/echo:root/child1:prop1。即使屬性和節點的呼叫方式相同，您也可以使用專屬的查詢方式，因為您可以使用路徑名稱來識別這些屬性和節點。

不過，就驅動程式而言，建議所有裝置都公開檢查階層，其中根目錄有一個子項，且子項名稱為裝置名稱，這樣使用選取器查詢資料時，就能獲得更優質的體驗。所有其他屬性和節點都是這個子項的子項。

在上圖中，您可以分別查詢 bootstrap/driver_manager:root/device_a:failures 和 bootstrap/driver_manager:root/device_b:failures。如果 device_a 和 device_b 都沒有透過 root/{device name} 節點公開檢查 VMO，且所有屬性都位於該節點中，您就無法區分兩者，且選取器 bootstrap/driver_manager:root:failures 會同時比對兩者。

包括在驅動程式中檢查

這些步驟逐步說明如何在驅動程式中加入檢查功能。如需包含 Inspect 的驅動程式庫完整範例，請參閱下列範例測試驅動程式。

  1. 在 BUILD.gn 中，將 zircon 檢查程式庫新增至驅動程式庫依附元件：

    deps = [
    ...
    "//zircon/system/ulib/inspect",
],

  2. 在驅動程式中加入這個標頭：

    #include <lib/inspect/cpp/inspect.h>

  3. 在裝置類別中建立 Inspector 執行個體：

    class TestDevice {
 …
 private:
     inspect::Inspector inspect_;
}

    您可以使用這個函式建立屬性和子項，建構檢查樹狀結構：

    TestDevice::TestDevice() {
    state_ = inspect_.GetRoot().CreateString("state","invalid");
    // inspect is a tree; You can add children and structure your data.
    performance_ = inspect_.GetRoot().CreateChild("performance");
    call_count_ = performance_.CreateUint("call_count",0);
    total_time_ = performance_.CreateUint("total_time(ms)",0);
    ...
}

TestDevice::SetState(State s) {
  call_count_.Add(1);
  ...
    case kActive:
      state_.Set("active");
}

    檢查功能目前支援各種屬性類型，例如整數、字串、陣列、布林值、雙精度浮點數、直方圖。

    檢查是 RAII，因此請記得保留要更新的屬性參照，否則這些屬性會從檢查 VMO 中移除。

    class TestDevice {
 …
 private:
     inspect::Inspector inspect_;
     inspect::StringProperty state_;
     inspect::Node performance_;
     inspect::UintProperty call_count_;
     inspect::UintProperty total_time_;
}

    您可以將屬性和節點新增至 inspect::ValueList，而非保留對這些屬性和節點的參照。 這會將屬性和節點的生命週期與 inspect::ValueList 的生命週期繫結。請注意，為方便起見，inspect::Inspector 剛好是 ValueList。

    inspect_.GetRoot().CreateString("name","test device",&inspect_);
inspect_.GetRoot().CreateString("config_params",config,&inspect_);

  4. 將檢查 VMO 匯出至驅動程式管理器。

    zx_status Bind() {
  …
    DdkAdd(ddk::DeviceAddArgs("test").set_inspect_vmo(inspect_.DuplicateVmo()));
}

    每部裝置只能發布一個檢查 VMO。

  5. 完成，現在你可以查看驅動程式庫的檢查資料。

    • 裝置檢查檔案位於 class/<protocol>/xxx.inspect
    • 使用 iquery 檢查資料
    iquery
    fx iquery show bootstrap/driver_manager --file class/ethernet/000.inspect

// To view all of driver_manager and driver host
fx iquery show bootstrap/driver_manager

  6. 執行 fx snapshot，並檢查 inspect.json 中是否有檢查資料。請注意，意見回饋元件不屬於啟動程序，因此只使用啟動程序建構版本時，拍攝快照並無太大用處。在這些情況下，建議使用 iquery，該函式可在啟動檔案系統中使用 (如果您在其他產品中工作，請參閱下文)。

在啟動檔案系統中加入 iquery

bringup產品和所有*_eng產品都已在啟動檔案系統中包含 iquery，因此如果您使用這些產品，可以略過本節。

如果您正在處理其他產品，且需要在啟動檔案系統中提供 iquery，請將下列項目新增至 fx set：

fx set core.x64 --args='product_bootfs_labels+=["//bundles:diagnostics-eng"]'