utrace

utrace 是一个基于插装的应用程序性能分析工具。它旨在具有平台无关性、异步友好和低开销。utrace 的工作原理受到出色的 defmt 日志库 的启发。

用法

面向主要用户的应用程序接口是两个过程宏，可用于插入插装 - 属性 #[trace] 和函数式的 [trace_here]。可能的用法在以下代码片段中展示

#[utrace::trace]
async fn do_something() {

}

#[utrace::trace]
fn do_something_else() {

}

{
    utrace::trace_here!();
    ...
    ...
}

当 #[trace] 对异步函数进行插装时，将默认报告相应的未来创建、丢弃和轮询跨度的时间点。

追踪信息时间戳和传输

虽然追踪插装本身是平台无关的，但它需要从 DUT 到主机系统获取时间戳和传输数据的方式。

要向库提供时间戳函数，请使用 #[timestamp] 宏。例如

#[utrace::timestamp]
fn utrace_timestamp_fn() -> u64 {
    (Tim15::now() - <Tim15 as Monotonic>::ZERO).to_micros()
}

在当前版本中，时间戳函数的签名必须是 rust fn() -> u64。

要定义传输，使用 #[default_transport] 标注函数，如下所示

#[utrace::default_transport]
pub fn write(buf: &[u8]) {
    ...
}

当前实现提供在 utrace_rtt crate 中基于 RTT 的传输实现。

注意，当前实现需要临界区实现。例如，如果您使用单核 ARM MCU，您可以在 Cargo.toml 中添加

cortex-m = { version = "0.7.7", features = ["critical-section-single-core"] }

。

追踪数据解释

用于跟踪解释的元数据存储在输出 elf 二进制文件中。正确打包此元数据需要在二进制链接期间将 utrace_linker.x 脚本传递给链接器。这可以通过在 build.rs 脚本中添加类似以下内容来实现：

println!("cargo::rustc-link-arg=-Tutrace_linker.x");

或者通过添加

rustflags = [
  "-C", "link-arg=-Tutrace_linker.x"
]

到您的 .cargo/config.toml 文件中。第一种方法应优先于第二种方法。

要提取元数据和解释跟踪数据流，应使用 utrace_parser 包。该包的软件包提供了一个名为 utrace-capture 的二进制文件，可以从 TCP 连接或 stdin 接收原始跟踪流，并将跟踪信息写入 chrome://tracing 格式。要安装它，执行

cargo install --locked utrace_parser --features="cli"

假设使用 OpenOCD 进行 DUT 接口。在这种情况下，您应该在 OpenOCD 初始化脚本中添加如下内容：

rtt setup 0x20000000 0x20000 "SEGGER RTT"
rtt server start 9001 0
rtt start

这将告诉 OpenOCD 在端口 9001 上监听，并将通道 0 的原始 RTT 数据发送给连接的客户端。在此配置下捕获和保存跟踪流，请运行

utrace-capture <path to firmware elf executable> --tcp localhost:9001 --out-ct trace_out

跟踪将被捕获在 trace_out_xxx.json 文件中。要完成捕获，请按 Ctrl+C。如果您使用 Chrome 浏览器，则可以使用 chrome://tracing 打开这些跟踪，或者使用 Perfetto UI。

注意，probe-rs (cargo embed) 的 RTT 功能尝试连接到服务器，而不是监听端口，因此您需要使用 --tcp-server 标志，例如

utrace-capture <path to firmware elf executable> --tcp-server 0.0.0.0:9001 --out-ct trace_out

跟踪数据也可以使用 --stdin 标志从 stdin 捕获。