RTT

读取您的固件通过 SEGGER RTT 打印的内容。启用 rtt feature 之后，您还可以往它的下行通道写入，于是一个 cargo test 就能驱动一个交互式控制台。有两条路径，它们的行为并不相同。

路径	Feature	方向	传输方式
`debug.rtt()`	无	只读	HTTP 流
`debug.rtt_interactive()`	`rtt`	可读可写	Socket.IO，Box 0.35.0 及以上

请优先使用交互式会话。单向流产出的是原始的 HTTP 分块传输帧，而不是干净的负载 —— 见下面的警告。

交互式会话

启用该 feature

[dev-dependencies]
lager = { package = "lager-net", version = "0.4", features = ["rtt"] }

rtt feature 隐含启用 blocking。它没有异步版本。

打开一个会话

use lager::{LagerBox, RttOptions};
use std::time::Duration;

let lager = LagerBox::from_env()?;
let dbg = lager.debug("debug1");

dbg.connect()?;                    // required first, see below
let mut rtt = dbg.rtt_interactive()?;

gdbserver 必须已经在运行。 没有先连接就调用 rtt_interactive() 会以 Error::Stream 失败，信息是 No debugger connection found for net 'debug1'. Start one first。

`RttOptions`

pub struct RttOptions {
    pub channel: u32,               // default 0
    pub search_addr: Option<u64>,   // RAM start for the control-block search
    pub search_size: Option<u64>,   // size of the RAM region to search
    pub chunk_size: Option<u64>,    // box-side read chunk, J-Link only
}

channel 同时决定两个方向上的通道。chunk_size 只对交互式会话有效；单向的 HTTP 流会忽略它。

方法

方法	说明
`netname()`	该会话所流式接收的调试 Net
`channel()`	RTT 通道，双向通用
`backend()`	调试后端，`"jlink"` 或 `"openocd"`
`read()`	在超时时间内到达的字节；可能为空
`try_read()`	已经缓冲的字节，不等待
`wait_for()`	一直累积，直到出现指定的标记
`write()`	向目标的下行通道写入原始字节
`write_str()`	向下行通道写入一个字符串
`stop()`	干净地停止，释放 Box 的 RTT telnet 端口

方法参考

`read(timeout: Duration) -> Result<Vec<u8>>`

在 timeout 时间内到达的上行通道字节，有多少给多少。

let chunk = rtt.read(Duration::from_secs(3))?;
print!("{}", String::from_utf8_lossy(&chunk));

目标空闲时，read() 会把整个超时时间等满。在轮询循环里请改用 try_read()，否则每一轮迭代都要花掉整个超时时长。

`try_read() -> Result<Vec<u8>>`

已经收到的字节，不等待。没有缓冲内容时返回空 vector。

`wait_for(needle: &[u8], timeout: Duration) -> Result<Vec<u8>>`

不断累积输出，直到出现 needle。 返回： 直到该标记为止、并且包含该标记的全部内容。标记之后的字节会继续留在缓冲区里，供下一次读取。空标记会立即返回；没找到则是 Error::Timeout。

let banner = rtt.wait_for(b"boot complete", Duration::from_secs(10))?;

`write(data: &[u8]) -> Result<()>` 和 `write_str(s: &str) -> Result<()>`

写入目标的 RTT 下行通道。

写入要求固件在该通道上声明了下行缓冲区。仅有 defmt-rtt 只提供上行缓冲区，而在没有下行缓冲区时，目标会静默丢弃您写入的内容 —— 该调用仍然返回 Ok(())。这是目标侧的事实，而不是传输失败，所以该 crate 没有错误可以报告。

`stop() -> Result<()>`

干净地停止。它会消耗掉该会话。把会话 drop 掉同样会停止它，但 stop() 会把错误暴露出来，而不是吞掉。

单向流

debug.rtt() 和 debug.rtt_with(&RttOptions) 返回一个 RttStream，它实现了 std::io::Read。它不需要任何 cargo feature，也不需要 Socket.IO。

RttStream 产出的是原始的 HTTP 分块传输帧，而不是干净的负载。 一次读取返回的字节形如 384\r\nblink 46823 period=500ms\n...，其中 384 是十六进制的分块长度。把它包进 BufReader 再按行迭代，得到的会是 "64"、"384" 和空字符串，与真正的固件输出交替出现。一个十六进制的分块长度和一行由您的固件打印出来的内容，在形式上无法区分。这个问题记录在 lager-rs#5。在它修复之前，需要可解析输出的场合请用 rtt_interactive()。交互式路径是干净的。

示例

驱动固件控制台并对回复做断言

use lager::LagerBox;
use std::time::Duration;

let lager = LagerBox::from_env()?;
let dbg = lager.debug("debug1");

dbg.connect()?;
let mut rtt = dbg.rtt_interactive()?;

rtt.wait_for(b"ready", Duration::from_secs(10))?;
rtt.write_str("version\n")?;
let reply = rtt.wait_for(b"\n", Duration::from_secs(2))?;
assert!(String::from_utf8_lossy(&reply).contains("v1."));

rtt.stop()?;
dbg.disconnect(false)?;

在目标空闲时收集启动输出而不被阻塞

use std::time::{Duration, Instant};

let mut log = Vec::new();
let deadline = Instant::now() + Duration::from_secs(5);
while Instant::now() < deadline {
    log.extend_from_slice(&rtt.try_read()?);
    std::thread::sleep(Duration::from_millis(50));
}
println!("{}", String::from_utf8_lossy(&log));

说明

Box 的 RTT telnet 端口只接受一个客户端。 在同一个探针和同一个通道上开第二个会话，会被以 Error::Stream 和 RTT port 9090 is already in use by another session 拒绝。同一个探针上的两个不同通道属于不同端口，可以同时运行。
字节是原始的。defmt 输出是压缩的二进制，必须经 defmt-print -e <elf> 管道处理；wait_for 只在纯文本控制台上才帮得上忙。
连接确认的超时是 30 秒，比 UART 的 15 秒更宽。多出来的时间用于在 RAM 中搜索 RTT 控制块，以及在 gdbserver 稳定下来的过程中重试 telnet 挂接。
会话会在 Socket.IO 握手时带上网关 bearer 令牌，因此受网关保护的 Box 无需额外配置即可使用。
需要 Box 软件 0.35.0 或更高版本。更旧的 Box 会给出 Error::UnsupportedByBox。

入门

开发

电源与仿真

测量

I/O 与通信

实用工具

指南

交互式会话

启用该 feature

打开一个会话

`RttOptions`

方法

方法参考

`read(timeout: Duration) -> Result<Vec<u8>>`

`try_read() -> Result<Vec<u8>>`

`wait_for(needle: &[u8], timeout: Duration) -> Result<Vec<u8>>`

`write(data: &[u8]) -> Result<()>` 和 `write_str(s: &str) -> Result<()>`

`stop() -> Result<()>`

单向流

示例

驱动固件控制台并对回复做断言

在目标空闲时收集启动输出而不被阻塞

说明

​交互式会话

​启用该 feature

​打开一个会话

​RttOptions

​方法

​方法参考

​read(timeout: Duration) -> Result<Vec<u8>>

​try_read() -> Result<Vec<u8>>

​wait_for(needle: &[u8], timeout: Duration) -> Result<Vec<u8>>

​write(data: &[u8]) -> Result<()> 和 write_str(s: &str) -> Result<()>

​stop() -> Result<()>

​单向流

​示例

​驱动固件控制台并对回复做断言

​在目标空闲时收集启动输出而不被阻塞

​说明

交互式会话

启用该 feature

打开一个会话

`RttOptions`

方法

方法参考

`read(timeout: Duration) -> Result<Vec<u8>>`

`try_read() -> Result<Vec<u8>>`

`wait_for(needle: &[u8], timeout: Duration) -> Result<Vec<u8>>`

`write(data: &[u8]) -> Result<()>` 和 `write_str(s: &str) -> Result<()>`

`stop() -> Result<()>`

单向流

示例

驱动固件控制台并对回复做断言

在目标空闲时收集启动输出而不被阻塞

说明