驱动程序日志记录

您可以使用驱动程序框架日志记录库让驱动程序将日志消息发送到 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

如需在 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>

驱动程序框架在 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

在 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 会使用驱动程序的 moniker 和名称标记驱动程序日志。您可以使用 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 发送更新请求，该请求会一直存在，直到您重启组件或再次更新其严重程度设置。

通过产品组装进行 build-time 配置

如需在产品组装中设置初始日志级别，请在平台配置中或通过产品组装的开发者替换项指定 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 及更高级别的严重性日志。