utrace

utrace是一个基于仪器的嵌入式应用程序性能分析工具。它旨在跨平台、异步友好且低开销。utrace的操作原理受到了出色的defmt日志库的启发。

用法

主要的用户API是两个过程宏，可以用于插入仪器 - 属性#[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]) {
    ...
}

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

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

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

到你的Cargo.toml。

跟踪数据解释

存储在输出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 捕获跟踪数据。