STM32 上用 SEGGER RTT 实现微秒级日志与波形调试

串口打印这件事，做到一定阶段就会发现它不太够用。前阵子调一个电机驱动的项目，主循环里一个 20kHz 的 PWM 中断在跑，只要在中断里塞一句printf，波形立刻就开始抖——不是因为打印慢，而是因为串口发送本身要占时间，115200 的波特率发一行 60 字符的日志要 5ms 左右，这 5ms 里中断被拖住，控制环直接就乱了。后来把日志换成 SEGGER RTT，同样一行数据从"毫秒级"降到"微秒级"，波形稳住了，调试信息还一点没少。这篇就把 STM32 上用 RTT 做日志的整套东西讲透：它凭什么快、源码怎么搬进工程、缓冲区该开多大、中断里能不能打、以及那些我第一次移植时踩得比较惨的坑。

RTT 的全称是 Real Time Transfer，本质上是调试器通过后台访问目标芯片 RAM 的一块共享内存来搬运数据。目标端只负责往环形缓冲区里写，主机端（调试器软件）负责定时来读。写内存这件事在 Cortex-M 上就是几十个周期的memcpy，所以在中断里调用也不会把时序搞崩。它适合谁？适合那些串口被业务占满、或者对时序敏感、或者板子上根本没引出 UART 的场合。前提是你手上有支持 RTT 的调试探针，这一点后面会专门说清楚。

1. 别急着拆串口：RTT 解决的到底是哪几个具体问题

1.1 printf 重定向在真实项目里卡在哪几个点

很多人对串口打印的印象还停留在"能用就行"，直到项目变复杂。第一个卡点是引脚资源，一块板子上 UART 通常只有三到四路，一路给上位机通信、一路给模组、一路给传感器，轮到调试口的时候往往已经没有了。第二个卡点是时序侵入，printf走阻塞发送的时候，CPU 在等发送寄存器空，这段时间里如果来了高优先级中断，中断响应会被推迟；就算改成 DMA 发送，也要额外维护发送队列和完成标志，代码复杂度上来了。

第三个卡点是半主机（semihosting）的坑。Keil 和 IAR 里默认的printf如果不重定向，会走调试器的半主机调用，一旦脱离调试器运行就会卡死在BKPT指令上，现象是"下载进去不跑，连着调试器就正常"，新手很容易在这里耗掉半天。第四个卡点是量产阶段，产线测试工装根本没接串口，想看一眼启动日志都看不到。

RTT 把这几个问题一起绕开了：它不占任何外设引脚，不依赖 UART 外设，不需要重定向fputc，也不走半主机。目标端写入操作就是纯内存拷贝，写完就返回，中断延迟几乎不受影响。

1.2 RTT、SWO、半主机、串口 DMA 四者的取舍

Cortex-M3/M4/M7 上还有个常见方案是 SWO（ITM），用单线输出，速度也不错。但它的问题在于：第一，M0/M0+ 内核压根没有 ITM；第二，SWO 的引脚复用经常和别的功能冲突；第三，很多便宜的调试探针不支持 SWO 输出。RTT 则对内核没有硬性要求，只要有 RAM 就能跑。

半主机前面说了，脱离调试器就废。串口 DMA 是个稳妥方案，但要占引脚、要配 DMA 通道、要在 DMA 中断里回收缓冲，工程量比想象中大。RTT 的工程量主要集中在"搬 4 个源文件 + 改几行配置"，之后就一劳永逸。

表里的耗时是我在 72MHz 主频、60 字节一行条件下的粗略实测，仅作量级参考，具体数值跟主频、缓冲区大小、格式化函数的实现都有关系。

1.3 RTT 的边界：它不是万能的

说清楚 RTT 不能干什么，比说它能干什么更重要。第一，它必须依赖支持 RTT 的调试探针和配套的主机软件，换一个不支持该功能的探针就直接歇菜。第二，调试器断开之后，目标端写进缓冲区的数据没有任何人读取，缓冲区一满就开始丢数据或者阻塞，所以 RTT 是调试期工具，不是现场日志方案。第三，缓冲区是静态分配的 RAM，开多大就占多大，在 RAM 紧张的芯片上要算着来。

第四，如果程序进入了深度低功耗模式，调试连接状态本身就可能被破坏，RTT 也就无从谈起。第五，复位之后主机端需要重新建立连接，某些工具会自动重连，某些需要手动点一下。把这些边界记清楚，后面遇到现象时能少走很多弯路。

2. 控制块与环形缓冲：微秒级输出是怎么做到的

2.1 控制块里到底存了什么

RTT 的所有状态都在一块结构体里，叫控制块（Control Block），全局只有一个实例，开头是一段固定字符串"SEGGER RTT"。这串字符不是装饰，它是主机端定位控制块的锚点——调试器连上芯片后，会在 RAM 范围里扫描这段特征字符串，扫到之后就认为找到了 RTT 控制块，后续所有读写都基于这个地址偏移来计算。

控制块里依次存放：ID 字符串、上行缓冲区数量、下行缓冲区数量、以及若干组缓冲区描述符。每个描述符包含缓冲区大小、当前读指针、当前写指针、缓冲区标志位和缓冲区名字的指针。上行的意思是"目标端写、主机端读"，也就是日志输出；下行的意思是"主机端写、目标端读"，用于给芯片下发命令或者参数。

缓冲区本身的存储空间是独立的静态数组，描述符里只存指针和大小。所以你在配置头文件里改缓冲区大小时，改的是数组长度，描述符会跟着变。这里有个细节值得注意：缓冲区名字的指针指向的字符串常量必须放在 Flash 里并且不能被链接器优化掉，否则主机端读到的就是一个野指针，显示出来的通道名是乱码。

2.2 环形缓冲区里读写指针是怎么转的

上行缓冲区的本质是一个 FIFO 环形队列，但它的读写双方完全异步：写的一方是 CPU，读的一方是调试器通过后台内存访问。为了保证这个异步过程不出错，RTT 在写入时用了两个技巧。

第一个技巧是写入顺序：先把数据memcpy到WrOff指向的位置，把指针推到新位置，最后才更新描述符里的WrOff字段。这样主机端看到的要么是"指针还没动、数据是旧的"，要么是"指针动了、数据已经完整"，不会出现"指针动了但数据只写了一半"的中间态。第二个技巧是指针更新的原子性，在 32 位总线上对齐访问本身就是原子的，所以单个字段的更新不需要额外的关中断保护。

主机端读取时也有对应的判断：如果RdOff小于WrOff，说明数据是一段连续的；如果RdOff大于WrOff，说明写指针已经绕回缓冲区头部，数据分两段，要先读到末尾再从头读。这套逻辑在主机软件里实现，目标端不用操心。

2.3 缓冲区开多大才算合适，算一遍就清楚了

这大概是移植时最常被问到的问题。缓冲区太小，主机来不及取就溢出；太大，白占 RAM。计算方法其实很简单，看你最坏情况下的数据产生速率和主机的取数周期。

假设你的日志平均每行 80 字节，正常情况每秒 100 行，也就是 8000 字节/秒；但故障排查时可能瞬时爆发，比如某个中断连续打 200 行。主机软件在连接状态下通常是毫秒级轮询，就算按 10ms 的保守周期算，稳态下也只需要 80 字节的余量。真正要覆盖的是突发：200 行 × 80 字节 = 16000 字节，这显然不现实。

所以实际做法是做取舍：缓冲区开 2KB 到 4KB，覆盖住几十行的突发，剩下的靠"限流"来解决——在代码层面给日志加频率限制，同一个位置每秒最多打 N 次。我在实际项目里用 2KB 上行缓冲加限流宏，跑了几个月没出过丢数据的问题。如果确实需要记录大块数据，比如一次导出 64KB 的采样数组，那就该走多通道加上大缓冲，或者干脆用专门的二进制数据传输通道，不要塞进日志通道。

3. 把 RTT 搬进工程：从源码到第一行打印

3.1 需要拷哪几个文件，为什么是这几个

RTT 的源码包里有十几个文件，但真正需要加进工程的只有寥寥几个，其余的要么是给特定编译器准备的系统调用封装，要么是给 RTOS 用的适配层。

我的建议是：先只加前四个，把最小可用路径跑通。系统调用那个文件在需要复用已有printf代码的时候再加，因为它会把标准库的输出全部导向 RTT，如果工程里还有别的地方依赖串口输出，容易冲突。汇编加速版本留到后面优化阶段再说，第一次移植不要引入额外的复杂度。

3.2 配置头文件里几个必须过一遍的项

SEGGER_RTT_Conf.h里有几十个宏，但真正影响功能的就那么几个。BUFFER_SIZE_UP决定上行缓冲区大小，默认值通常是 1KB，我一般改成 2048 或者 4096。BUFFER_SIZE_DOWN是下行缓冲，如果不做命令交互，保持很小的默认值（比如 16 字节）就够了。

SEGGER_RTT_MAX_NUM_UP_BUFFERS和SEGGER_RTT_MAX_NUM_DOWN_BUFFERS是通道数量，默认 3 个。如果只用通道 0 打日志，可以改成 1，能省下几个描述符的空间。SEGGER_RTT_PRINTF_BUFFER_SIZE是格式化函数的临时缓冲区，默认值通常够用，但如果你要打印很长的字符串（比如一次性打印一整帧报文），记得把它调大，否则会被截断。

还有两个容易被忽略的宏：SEGGER_RTT_MODE_DEFAULT和锁的实现。前者决定缓冲区满时的行为，NO_BLOCK_SKIP是跳过新数据，NO_BLOCK_TRIM是尽量写入能写下的部分，BLOCK_IF_FIFO_FULL是死等。默认是跳过，这在调试期最安全。后者是SEGGER_RTT_LOCK()/UNLOCK()，默认实现是基于 PRIMASK 的关中断，一般不用改，但如果你在关中断已经很长的临界区里调用了 RTT，就要留意嵌套问题。

3.3 内存占用要提前算，别等链接报错

RTT 的 RAM 开销是静态确定的，链接阶段就能看到。以 2KB 上行、16 字节下行、3 个通道为例，缓冲区数组本身是 2048 + 16×3 = 2096 字节左右，控制块结构体大概几百字节，加起来 2.5KB 上下。这个量级在 20KB RAM 的芯片上还扛得住，在 8KB RAM 的小芯片上就要谨慎。

如果 RAM 实在紧张，有个折中办法：把上行缓冲区缩小到 512 字节，同时把日志量压下来，只在关键路径打点。另外注意控制块默认落在.bss段，会被启动代码清零，这没问题，因为 RTT 内部做了惰性初始化——第一次调用写函数时会检查控制块的 ID 首字节，如果为空就先写入"SEGGER RTT"标识并初始化各个指针。所以不需要你在main里手动调初始化函数。

但如果你的工程有自定义的分散加载文件或者把.bss放到了外部 RAM，就要确认调试器能不能访问那块内存。外部 SDRAM 如果初始化之前就被访问，读回来全是错的数据，主机端扫描不到 ID 字符串，表现就是"RTT 连不上"。

3.4 第一次验证的步骤

验证顺序建议是这样：先编译通过，确认没有重复定义和缺头文件的错误；然后下载运行，让程序跑到至少执行过一次 RTT 输出的位置；接着打开主机端软件连接目标，选择正确的芯片型号和接口速度；最后看输出窗口有没有内容。

如果窗口是空的，别急着改代码，先在调试器的内存窗口里手动搜一下"SEGGER RTT"这个字符串。搜到了说明控制块在，问题出在主机端连接或者数据没写进去；搜不到说明控制块被优化掉了、被放到不可访问区域了，或者程序压根没跑到初始化那一步。这个二分法能砍掉一大半的排查时间。

4. API 层怎么用才不别扭

4.1 格式化函数的开销，以及什么时候该绕开它

SEGGER_RTT_printf是个精简版实现，支持%d、%u、%x、%s、%c、%p这些常用格式，但不支持浮点。第一次用的人经常会写SEGGER_RTT_printf(0, "temp=%.2f\n", t);，结果输出一堆乱码或者直接没输出，还以为是 RTT 坏了。

另外要注意，格式化的开销远大于传输本身。一次带三个整数参数的printf，在 72MHz 上可能要几十微秒，而真正写进缓冲区只花一两微秒。所以在高频中断里，能拼字符串就别用格式化：用SEGGER_RTT_WriteString打固定文本，用SEGGER_RTT_Write打二进制结构体，把解析工作放到主机端去做，这才是 RTT 的正确打开方式。

举个例子，我采集三轴加速度的时候不打印文本，而是把三个int16_t打包成一个 6 字节结构体直接写进通道 1，主机端用配套工具按二进制解析并画波形。这样每次写入只有几微秒，采样率轻松上到几千赫兹，比打文本高效得多。

4.2 多通道分流的实际用法

通道 0 留给人类可读的日志，通道 1 放二进制数据，通道 2 放高频的打点信息，这是比较常见的分法。好处是不同性质的数据互不干扰：文本日志刷屏不会把波形数据冲掉，高频打点也不会把日志窗口塞满。

使用上只要在写函数的第一个参数里指定通道号就行。需要注意的是通道号不能超过配置里设定的最大数量，超了会被直接忽略并且不报错，这种静默失败很难查。我在配置里把通道数设成 3，然后写代码时用枚举代替硬编码数字，避免记错。

下行通道则是另一套用法：主机端在输入框里敲字符，目标端用SEGGER_RTT_HasKey()查询有没有数据，有就SEGGER_RTT_Read()读出来。基于这个可以做一个极简的命令行，支持运行时改参数、打印状态、触发自检。这个功能在整机联调的时候特别好用，不用重新烧录就能切换工作模式。

4.3 二次封装：分级、模块标签、时间戳

直接在业务代码里到处写SEGGER_RTT_printf(0, ...)是会失控的，半年后回头看根本不知道哪条日志是谁打的。我的做法是封一层宏，把等级、模块名、时间戳统一加上去。

#define LOG_LEVEL_ERROR 1 #define LOG_LEVEL_INFO 2 #define LOG_LEVEL_DBG 3 #ifndef LOG_LEVEL_CUR #define LOG_LEVEL_CUR LOG_LEVEL_INFO #endif #define LOG_TAG "MOTOR" #define LOGF(lv, tag, fmt, ...) \ do { \ if ((lv) <= LOG_LEVEL_CUR) { \ SEGGER_RTT_printf(0, "[%08lu][%s][%s] " fmt "\n", \ (unsigned long)get_tick_ms(), \ tag, level_name(lv), ##__VA_ARGS__); \ } \ } while (0)

时间戳用系统滴答或者 DWT 的周期计数器都行，前者直观、后者精度高。分级宏的价值在于发布版本可以把LOG_LEVEL_CUR调到ERROR，编译器的死代码消除会把整条日志连同格式化参数一起干掉，既省 Flash 又省运行时间，比运行时判断效率高得多。

还有一个实用技巧是加频率限制。同一条日志如果在中断里每秒触发上千次，再大的缓冲区也扛不住。用一个静态计数器记录上次打印的时间戳，间隔小于设定值就直接返回，这样既保留了"出过这个事件"的信息，又不会把通道冲爆。

#define LOG_THROTTLE_MS 100 static uint32_t last_ms = 0; uint32_t now = get_tick_ms(); if (now - last_ms >= LOG_THROTTLE_MS) { last_ms = now; LOGF(LOG_LEVEL_INFO, LOG_TAG, "over current, val=%d", cur); }

5. 中断、DMA 与多任务环境下的安全性

5.1 锁机制到底锁了什么

RTT 内部的锁是通过宏实现的临界区保护，默认在 Cortex-M 上是保存 PRIMASK、关中断、执行、恢复 PRIMASK。它保护的临界区长度只有一次memcpy加几次指针更新，通常在一微秒以内，所以对中断延迟的影响可以忽略。

但这里有个容易被忽略的点：如果你的代码本身就在一个关中断的临界区里，再调用 RTT，那么 RTT 恢复 PRIMASK 的时候会把中断重新打开，导致外层临界区被"捅破"。这是个经典的重入问题。解决办法是在外层临界区里不要打日志，或者把 RTT 的锁换成支持嵌套计数的实现。我在早期项目里就因为这个出过一次偶发的数据竞争，现象是每隔几天出现一次外设配置被改错，查了很久才定位到临界区嵌套。

5.2 中断里到底能不能打日志

能，但有前提。第一，单次写入的数据量要短，最好控制在几十字节以内，因为临界区时间跟数据长度成正比。第二，不要在最高优先级的中断里打，比如有些系统把看门狗喂狗或者故障保护放在最高优先级，那里打日志会挤压更关键任务的响应。第三，绝对不要用BLOCK_IF_FIFO_FULL模式，缓冲区满的时候会在中断里死等，等主机来取数据，而主机可能压根没连着，结果就是整机卡死。

我的习惯是在中断里只记"事件发生了"，把具体的上下文信息留给任务层去补齐。比如 ADC 过流中断里只写一个字节的标志，主循环看到标志后再打印完整的电压电流值。这样中断里的开销稳定在几微秒，任务层的日志又足够详细。

5.3 RTOS 下的并发调用

FreeRTOS 这类系统里，多个任务同时调用 RTT 是安全的，因为内部锁已经保证了互斥。但要注意优先级反转的变种：高优先级任务在等锁，而低优先级任务正持锁执行memcpy，这段时间高优先级任务被阻塞。因为临界区极短，实际影响微乎其微，但如果你的日志数据特别长（比如一次写 4KB），就要考虑拆成多次小写入。

另一个坑是任务栈。SEGGER_RTT_printf内部有临时缓冲区，如果是在栈上分配的，调用时消耗的栈空间会明显增加。在栈只有 512 字节的任务里打长日志，很容易栈溢出，现象是随机跑飞，而且往往在别的地方报错，极难定位。把任务栈加够，或者改用WriteString避开格式化缓冲区，都能规避这个问题。

6. 现场那些抓狂的问题：完整排查链路

6.1 连着调试器能打印，一断开程序就跑飞

这个现象几乎百分百是缓冲区满导致的阻塞。检查两处：一是配置里的默认模式是不是被改成了BLOCK_IF_FIFO_FULL，二是代码里有没有显式调用设置模式的函数。默认值本来是跳过模式，但有些工程模板里被人改过，或者从别处抄来的初始化代码带了一句SEGGER_RTT_SetFlagsUpBuffer(0, SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL)，这行代码在连着调试器时看不出问题，一旦断开就变成定时炸弹。

排查方法是：断开调试器，用示波器或者逻辑分析仪看程序是否在某个固定的位置停住，然后在可疑位置前后加 GPIO 翻转。如果确认是卡在写函数里，那基本就锁定是阻塞模式了。

6.2 输出乱码、缺字符、显示不完整

乱码分两种。一种是主机端看到的全是乱码符号，这通常是缓冲区里残留了上次运行的旧数据，主机端把旧数据当成了有效日志。解决方法是让程序在启动时清一次缓冲区，或者在主机端点一下清屏按钮重新连接。另一种是间歇性的字符错位，这种多半是多个执行流同时写同一通道造成的——虽然内部有锁，但如果你的工程里同时链接了两份 RTT 源码（比如两个库都带了），就会出现两个控制块、两套缓冲区，主机端扫到了其中一个，另一个的写入自然就乱了。检查方法是在 map 文件里搜一下_SEGGER_RTT符号出现了几次。

丢字符的另一个原因是缓冲区太小导致的跳过模式生效。这种情况下日志会静默丢失且没有任何提示，只能靠把缓冲区调大或者加限流来解决。判断方法是临时把缓冲区放大四倍，如果问题消失，那就确认是容量问题。

6.3 复位之后主机端就卡住不动了

调试器软件在连接状态下会缓存控制块地址。芯片复位后，控制块被重新初始化，指针清零，但主机端还拿着旧地址和旧状态，有时候会显示成连接正常但就是没数据。这时候需要手动断开重连，或者用软件里的自动重连选项。

还有一个更隐蔽的原因：如果程序里用了看门狗，复位频繁发生，主机端每次刚连上就又断了，表现出来就是"一直连不上"。这时候先把看门狗关掉再调试，能省下大量时间。我见过有人在这个现象上耗了一整天，最后发现是喂狗任务被自己的日志拖慢了。

6.4 加了 Cache 的芯片上读到的数据是旧的

Cortex-M7 这类带 D-Cache 的芯片上，CPU 写缓冲区时数据可能停留在 Cache 里没落到 RAM，而调试器是通过总线直接读 RAM 的，读到的就是旧值。表现是日志延迟出现、内容错位，甚至整段丢失。

解决办法是在 RTT 的配置里把缓冲区所在的内存区域设为不可缓存（MPU 配置），或者在每次写完之后手动做一次 Cache 清理。前者更彻底，后者开销大。如果缓冲区放在 DTCM 里就没这个问题，因为 DTCM 本来就不经过 Cache。这也是为什么很多人在 M7 上移植 RTT 时会特意把控制块放到 DTCM 段。

7. 性能实测与发布版本的处理策略

7.1 几种输出方式的实际耗时对比

我在 168MHz 主频的 Cortex-M4 上做过一组对比，输出内容是一行 60 字节左右的固定文本，重复一万次取平均，结果如下表。数字只代表量级，不同芯片、不同优化等级会有差异。

从表里能看出一个关键结论：真正的开销大头是格式化，不是传输。所以在高频路径上，把要输出的数据打包成结构体直接写二进制，比优化缓冲区大小有效得多。

7.2 发布版本怎么处理这些日志

发布版本不能把 RTT 源码直接删掉，因为现场出问题时你还想留个后门。我的做法是保留 RTT，但把日志等级调到只输出错误，同时在编译选项里开-ffunction-sections和-fdata-sections，链接时加--gc-sections，这样没被引用的格式化函数和字符串常量会被自动裁掉，Flash 占用能降下来一大截。

更进一步可以做双份配置：调试配置里缓冲区 4KB、日志等级全开；发布配置里缓冲区 512 字节、只留错误级。用两个不同的配置文件，通过构建系统的宏切换，这样两份产物互不干扰，也不会出现"发布了才发现日志把 RAM 吃光"的情况。

还有一个细节是错误日志的持久化。RTT 在无调试器连接时数据无人接收，缓冲区满了就丢，所以它不能作为现场故障记录手段。真正需要追溯现场问题时，得靠独立的日志存储方案，比如写到内部 Flash 的日志扇区或者外挂存储芯片。RTT 在这里的角色是"开发期的显微镜"，不是"现场的黑匣子"，这个定位一开始就要摆正。

7.3 用 RTT 做波形观察的一个小技巧

除了打日志，RTT 还能当低成本的波形通道用。把采样值按固定格式打包写进通道 1，主机端工具按二进制解析，就能实时画出曲线，采样率做到几千赫兹没问题。相比外接 DAC 或者串口上传，这条路不需要任何额外硬件。

关键是格式要固定：定长结构体、固定字节序，主机端配置好字段偏移和类型就能直接解析。不要用变长格式，也不要混着文本一起写，否则解析会错位。我一般会在每个采样块前面加一个固定的同步字，解析端先搜同步字再读数据，这样即使中间丢了一两个包也能自动重新对齐。

最后分享一个我自己的习惯：接手任何新板子，第一件事就是把 RTT 跑通，只写四行代码——系统时钟、GPIO 翻转、RTT 初始化验证、主循环打印心跳。这四行能看到的东西比想象中多：时钟配错了心跳频率就不对，复位异常心跳就出不来，栈溢出了心跳会断。把它当成一个最小的可观测性底座，后面所有调试都建立在这上面，效率会比每次重新接线、重新配串口高出一大截。