驅動程式記錄

您可以讓驅動程式庫使用 Driver Framework 記錄程式庫，將記錄訊息傳送至 syslog。

如何寫入記錄

新增依附元件

C++

如要在 C++ 驅動程式庫中使用記錄程式庫，請將下列依附元件新增至 BUILD.gn：

fuchsia_cc_driver("my_driver") {
  deps = [
    "//sdk/lib/driver/logging/cpp",
  ]
}

如果驅動程式使用 Bazel，請將依附元件新增至 BUILD.bazel：

fuchsia_cc_driver(
    name = "my_driver",
    deps = [
        "@fuchsia_sdk//pkg/driver_logging_cpp",
    ],
)

荒漠油廠

如要在 Rust 驅動程式庫中使用記錄功能，請將 log Crate 依附元件新增至 BUILD.gn：

fuchsia_rust_driver("my_driver") {
  deps = [
    "//third_party/rust_crates:log",
  ]
}

如果驅動程式使用 Bazel，請將依附元件新增至 BUILD.bazel：

fuchsia_rust_driver(
    name = "my_driver",
    deps = [
        "@crate_index//:log",
    ],
)

寫入記錄訊息

C++

在 C++ 驅動程式庫原始碼中，加入記錄器標頭：

#include <lib/driver/logging/cpp/logger.h>

Driver Framework 會在 fdf 命名空間中提供與各嚴重性等級對應的記錄函式：

  • fdf::trace(...)
  • fdf::debug(...)
  • fdf::info(...)
  • fdf::warn(...)
  • fdf::error(...)
  • fdf::fatal(...)

這些函式使用 std::format 樣式的字串格式化 ({})：

// Basic message
fdf::info("Initializing driver");

// Formatted arguments
fdf::info("Configured device with {} endpoints and {} buffers",
          num_endpoints, num_buffers);

// Formatting hex or padded values
fdf::debug("Register address: {:#x}, value: {:02x}", reg_addr, val);

設定 zx::result 和 zx::status 的格式

Fuchsia 提供 zx::result 和 zx::status 的專用 std::formatter 實作項目。您可以直接將這些型別傳遞至格式字串，而不需呼叫 .status_string()：

zx::result<uint32_t> result = ReadRegister();
if (result.is_error()) {
  fdf::error("Failed to read register: {}", result);
  return result.take_error();
}

荒漠油廠

在 Rust 驅動程式庫原始碼中，從 log Crate 匯入記錄巨集：

use log::{debug, error, info, trace, warn};

驅動程式架構會初始化驅動程式庫元件的標準 log Facade，並將記錄檔轉送至 LogSink。您可以使用標準記錄巨集：

  • trace!(...)
  • debug!(...)
  • info!(...)
  • warn!(...)
  • error!(...)

這些巨集使用標準 Rust 格式字串：

// Basic message
info!("Initializing driver");

// Formatted arguments
info!("Configured device with {num_endpoints} endpoints and {num_buffers} buffers");

// Formatting hex or padded values
debug!("Register address: {reg_addr:#x}, value: {val:02x}");

// Formatting errors or Zircon status
if let Err(status) = result {
    error!("Failed to read register: {status:?}");
}

如何閱讀記錄

查看驅動程式庫記錄檔

Fuchsia 會使用驅動程式的驅動程式庫路徑名稱和名稱標記驅動程式記錄。您可以使用 ffx log 篩選及查看這些項目：

ffx log --filter <driver_name>

如要進一步瞭解如何篩選、串流及查詢記錄，請參閱「查看記錄」一文。

記錄嚴重性等級

記錄嚴重性由高至低依序為：

  • FATAL (僅限 C++)
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE

根據預設，系統會將嚴重性為 INFO 以上的記錄訊息傳送至 syslog。系統預設會在產生者端抑制 DEBUG 和 TRACE 嚴重程度，避免不必要的負擔。

控管記錄嚴重程度

如要啟用嚴重性較低的記錄 (例如 DEBUG 和 TRACE)，您可以在執行階段或建構時間調整驅動程式庫的最低記錄層級。

使用 ffx log 進行執行階段設定

您可以使用 ffx log --set-severity，為執行中的驅動程式庫動態設定最低記錄嚴重性：

ffx log --set-severity <component_selector>#<SEVERITY>

舉例來說，如要透過路徑名稱為驅動程式庫啟用 DEBUG 記錄：

ffx log --set-severity bootstrap/boot-drivers:dev.sys.pci#DEBUG

這會將更新要求傳送至元件的 LogSettings，並持續保留，直到您重新啟動元件或再次更新嚴重程度設定為止。

透過產品組裝進行建構時間設定

如要在產品組裝中設定初始記錄層級，請在平台設定中指定 component_log_initial_interests，或透過產品組裝的開發人員覆寫。

如要透過開發人員覆寫設定這項功能，請將下列內容新增至 //local/BUILD.gn：

# //local/BUILD.gn:
import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("sdhci-debug-logs") {
    platform = {
        diagnostics = {
            component_log_initial_interests = [
                {
                    component = "fuchsia-boot:///sdhci#meta/sdhci.cm"
                    log_severity = "debug"
                },
            ]
        }
    }
}

然後使用 --assembly-override 旗標執行 fx set：

fx set <product.board> --assembly-override=//local:sdhci-debug-logs

這會將最低記錄層級設為 DEBUG，啟用 DEBUG 和嚴重程度較高的記錄。