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 spans 的瞬间。

跟踪信息的时间戳和传输

尽管跟踪插桩本身是跨平台的，但它需要一种获取时间戳和从 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捕获。