utrace

utrace 是一款针对嵌入式应用的基于仪器化的性能分析工具。它旨在跨平台、异步友好且开销低。utrace 的操作原理受到优秀的 defmt 日志库 的启发。

使用方法

面向主要用户的 API 有两个过程宏，可以用来插入仪器化——属性 #[trace] 和函数式 [trace_here]。可能的用法示例如下

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

}

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

}

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

当 #[trace] 对异步函数进行仪器化时，默认情况下将报告相应的 future 创建、丢弃和 poll 扩展的瞬间。

虽然跟踪仪器本身是平台无关的，但它需要一种从 dut 到主系统传输数据的方法。

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

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

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

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

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

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

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

transport_rtt

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

Trace 数据解释

从传输层获取的 Trace 数据需要解释。Trace 数据的解释在 utrace_parser 模块中的 interpret_trace_data 函数中实现。

用于跟踪解释所需的元数据存储在输出 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 crate。此 crate 的软件包提供了一个名为 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 捕获。