對駕駛使用檢查功能

必要條件

如果您不熟悉檢查功能，建議您詳閱下列頁面：

說明

駕駛人可使用檢查功能。不過，由於驅動程式並非元件，因此必須考量一些特別注意事項。

請參考以下系統拓撲圖：

圖 1：拓撲範例

圖表圖例：

灰色：元件。藍色：顯示外出/診斷目錄內容的元件命名空間。紫色：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 之間，則不會有差異。

包括檢查驅動程式

下列步驟會逐步引導您在驅動程式中加入檢查功能。如需內含檢查功能的完整驅動程式庫範例，請參閱測試驅動程式範例。

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

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

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

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

  3. 在裝置類別中建立檢查器執行個體：

    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 是值清單。

    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 檢查檢查資料
    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"]'