• 嵌入式
• 驱动开发
• 通信
• 物联网

本篇技术指南以 tinyusb 仓库中的设计决策文档 docs/superpowers/specs/2026-08-24-rtt-skill-design.md 为骨架，完整还原 SEGGER RTT 从.claude/skills/target-debug/内联技巧晋升为独立rttskill 的决策依据、实测证据、后端矩阵与工具落地方式，并结合仓库中的真实实现（tools/rtt.py、lib/SEGGER_RTT、HIL 测试）展开原理级讲解。读完本文，你将理解：为什么 RTT 适合作为"传输核心 + 控制台层"的独立技能、哪些探针/后端组合可靠、哪些被实测否决，以及如何用rtt.py在无 UART、无 VCOM 的板卡上拿到 printf 控制台与双向输入。

决策：从内联技巧晋升为独立 skill

在 2026-08-24 之前，SEGGER RTT 的使用方式是把相关经验内联写在.claude/skills/target-debug/的 SKILL.md 里，作为"固件行为异常时"的调试手段之一。本次设计决策将其晋升为独立 skill：.claude/skills/rtt/，职责边界明确为：

• 传输核心（transport core）：让字节经任意调试探针在 RTT channel 上进出；
• 控制台层（console layer）：HIL（hardware-in-the-loop）测试平台随附的双向控制台工具。

而消费方专用层保持各自归属：SystemView 的编解码与授权问题留在 sysview skill，TU_LOG 打印约定留在目标调试技能，调试方法论（decision flow）仍由 target-debug 承载。rttskill 与其他技能通过交叉引用（cross-reference）协作，而不是把一切吸收进来。

设计文档同时记录：该方案在 2026-08-24 获得用户批准晋升，且 skill 名称正式确定为rtt。分支为rttconsole-skill，作者会话涵盖 lpc4088 handoff（测量）、sysview handoff（机制与探针矩阵）、以及本会话（验证与决策）。

晋升评分：4 项标准得 3/4

晋升标准定义在 docs/superpowers/specs/2026-07-09-claude-agents-workflows-design.md 的 "Skill vs technique — promotion criteria" 一节（设计文档注明该小节只存在于claude/add-systemview-debug分支，需通过git show读取）。四项标准中满足三项及以上即可晋升，RTT 得3/4：

1. 自带工具（Ships tooling）——满足。提交d98e77bac引入的hil_util.JlinkRtt提供了：按序列号选择探针、动态端口分配、非阻塞双向 socket、进程组（process-group）级清理；本次计划再为其加上一层薄 CLI。先例是hil和code-size这两个 skill——它们都是"包装仓库内版本化工具"的形态；而"基于已安装工具的菜谱（recipes）"正是 RTT 在本次代码诞生之前的形态（这也是 SWO 只有 1.5/4 分、停留在 technique 层面的原因，详见SWO_SKILL_HANDOFF.md）。

2. 能独立回答自己的路由问题（Answers its own routed question）——满足。"给这块板一个控制台 / printf I/O，且没有 UART、没有 VCOM" 这个问题来自 HIL 平台与板卡 bring-up 场景，这些场景永远不会加载 target-debug（其触发条件是固件行为异常）。缺少这条路由的实际代价可测：lpc4088 会话中曾花一小时重新踩中一个已经写在target-debug/SKILL.md:249-253的坑——这正是独立路由缺失的代价。

3. 携带验证状态（Carries validation state）——满足。内容包括：下文的可测工具矩阵、sysview 周期完成的 13 板 OpenOCD 读路径战役、WCH SDI 的 A/B 对照证明、SAMD5x DSU 的坑、锁移植示例、各探针的约束清单。

4. 长但条件相关（Long but conditionally relevant）——满足。传输知识有一页以上的篇幅，大多数 target-debug 会话用不到，而 HIL 会话在 target-debug 里又找不到。

实测证据：skill 必须携带的事实

lpc4088 会话（LPC4088 + LPC-Link2，J-Link 固件 611000000，SWD 4 MHz）

设计文档注明：该数据来自单板测量，验证阶段需在更多硬件上复测。核心结论：

• JLinkExe -RTTTelnetPort <port> -AutoConnect 1：6/6 全可靠。能交付开机缓冲的启动突发（boot burst），单次调用接受过 8550 字节写入。这是被证明可行的独立路径（proven standalone path）。
• 排空速率 24.6 KiB/s（10.0 秒内排空 253,127 字节），对抗一个饱和 printf 固件——该固件实际产生了 689,896 行，RTT 只交付了0.6%。结论：RTT 控制台受排空速率限制，饱和时是丢数据的（drain-limited and lossy under saturation），且丢包发生在目标端（NO_BLOCK_SKIP 模式 + 默认 1 KB 缓冲区）。
• JLinkRTTLogger：0/6 全失败——即使给了-RTTAddress也报 "RTT Control Block not found"，而控制块本身用 SWD 能直接读到。原因是该工具只在 attach 时搜索一次，从不重试。设计结论：永远不要建立在它之上（Never build on it）。
• JLinkGDBServer -RTTTelnetPort（无 GDB 客户端挂接）：端口是打开的，但从未定位到控制块（在这块板上）。注意：target-debug 里 "GDBServer + JLinkRTTClient" 的菜谱是在 GDB 已挂接的流程里被验证过的，而 CLAUDE.md 里的菜谱在其他部件上有效——应把两者当作**部件间差异（per-part variance）**分别记录，不要强行"修正"成互相矛盾的单一结论。
• OpenOCD（jaylink 驱动）操作这个 J-Link 固件探针：传输失败（LIBUSB_ERROR_TIMEOUT、jaylink_swd_io() failed），探针直接从 USB 掉线，需要物理重新插拔——发生两次，可复现。永久规则：绝不要把 OpenOCD 指向这类探针（即运行 J-Link OB 固件的调试板载探针，如 LPC-Link2）。而真正的 SEGGER J-Link 在 jaylink 下工作正常——这在 sysview 战役中是常规操作（metro_m4_express）。

sysview 周期（分支claude/add-systemview-debug，2026-08-12 的 13 板战役）

• OpenOCD 读路径已验证：rtt setup <精确控制块地址> …; rtt start; rtt server start <port> <ch>在 ST-Link、CMSIS-DAP 与 J-Link 探针上均验证通过（见 test/hil/sysview_ci.py）。精确控制块地址来自arm-none-eabi-nm <elf> | grep _SEGGER_RTT，优于全 RAM 扫描（全 RAM 扫描更慢，且软复位后可能误命中陈旧 RAM 内容）。
• 真正的传输需求是"内核运行时的自主内存访问"：ARM memory-AP（零侵入）满足；RISC-V 的 SBA（System Bus Access）在实现了的核上满足。WCH QingKe SDI 两者皆无——其 Debug Module 抽象命令会扰动运行中的内核；A/B 对照证明：在 USB 流量开始约 1.9 秒时把内核"杀死"。因此按传输类型的规则是：SDI 只允许 halt→read→resume / 事后转储（post-mortem dump），绝不做实时流。
• SAMD5x + OpenOCD 的坑：在会话内通过 DSU CPU Reset Extension 执行reset run会让内核被挂住（held）——当烧录步骤已经复位过板卡时，应attach 时不带复位（一般偏好：只 attach 采集，attach-only capture）。
• 锁移植示例：设计文档引用hw/bsp/ch583/sysview_rtt_lock_wch.h（QingKe CSR 0x800 花括号作用域保存/恢复；通用 RISC-V 锁会因 mcause=2 陷入）。注意该文件存在于 sysview 分支，当前主线仓库尚未包含；仓库中可直接查阅的是 lib/SEGGER_RTT/Config/SEGGER_RTT_Conf.h 的SEGGER_RTT_LOCK()/SEGGER_RTT_UNLOCK()机制（见下文"机制扩充"）。
• 排空层级：J-Link 原生 > OpenOCD 轮询——只在 SystemView 带宽级别才重要（可用缓冲 2048–8192 字节）；控制台日志实际中从不溢出排空能力。

核心机制：控制块、环形缓冲区与缓冲模式

设计文档为"概念"章节沉淀了 RTT 机制要点，本文结合 lib/SEGGER_RTT/RTT/SEGGER_RTT.c 与 lib/SEGGER_RTT/Config/SEGGER_RTT_Conf.h 扩充如下：

• 控制块_SEGGER_RTT：以魔数"SEGGER RTT"标识。结构上先有acID[16]、MaxNumUpBuffers、MaxNumDownBuffers，随后是aUp[]数组，每个上缓冲（up-buffer）是 6 个字的描述符{sName, pBuffer, SizeOfBuffer, WrOff, RdOff, Flags}——tools/rtt.py的dump_ring()正是按这个布局读取描述符（偏移 0x18 起每环 24 字节），先读计数再校验 channel 范围，避免越界读 RAM。
• 环形缓冲：目标写WrOff，必须由 HOST 回写RdOff才能排空（drain）——这是传输的关键动作。
• 三种缓冲模式：
  • NO_BLOCK_SKIP：日志默认。缓冲满即丢新数据——饱和时丢包发生在目标端；
  • NO_BLOCK_TRIM：不阻塞，但可裁剪；
  • BLOCK_IF_FIFO_FULL：目标自旋等待——在中断（ISR）里是危险的。
• 事后模式（post-mortem）：SEGGER_RTT_WriteWithOverwriteNoLock——目标自行拖动RdOff，环形缓冲保留最后 N 字节，无需活着的 host。
• Channel 0 = "Terminal" 控制台；SystemView 会在同一控制块上声明自己的 "SysView" 上缓冲——两者可在同一个控制块上共存。
• 配置默认值（仓库实际内容）：BUFFER_SIZE_UP默认 1024 字节、SEGGER_RTT_MAX_NUM_UP_BUFFERS/SEGGER_RTT_MAX_NUM_DOWN_BUFFERS默认 3，SEGGER_RTT_LOCK()在裸机下默认为空（#ifndef SEGGER_RTT_LOCK时定义为空操作），在多任务/多核/中断场景才需要按平台定义带中断屏蔽的锁。这解释了设计文档中"1 KB 默认缓冲 + NO_BLOCK_SKIP"的丢包结论：饱和 printf 下首 KB 之后的新数据全部被跳过。

Gotchas：skill 集中管理的经验教训

设计文档明确了以下坑点，全部要求在 skill 中集中记录（这也是当初 lpc4088 会话丢失一小时的原因——经验写在 target-debug 深处而没人会去看）：

• 控制块只在目标第一次 printf 之后才存在：早期 reader 什么都读不到；JLinkRTTLogger正是因此放弃。
• 控制台独占探针（The console owns the probe）：必须在打开控制台之前完成烧录与复位；挂接期间绝不复位。
• 未排空的 NO_BLOCK_SKIP 环形缓冲保留的是开机后的第一个 KB，而不是楔形尾部（wedge tail）——读旧数据前先想清楚你要哪一段。
• 始终按序列号选探针（-USB <sn>/adapter serial）：测试台架同时运行多个探针。
• 两个探针同时接一个 SWD 头会把目标"楔住"（wedge）。

v1 后端矩阵

v1 中JlinkRtt/CLI 仅支持 J-Link；OpenOCD 的控制台写入支持只有在 ci-rig 阶段验证通过后才加入。设计文档同时明确非目标：时序/性能分析（etm-trace、sysview、parked swo-trace）、SystemView 编解码与授权、TU_LOG 约定、调试决策流（target-debug）、Espressif USB-Serial-JTAG 控制台（esp-target-debug）、WCH SDI 实时流（不可能——见矩阵）。

工具落地：tools/rtt.py 双角色实现

工具的唯一实现落在 tools/rtt.py（设计文档称为 "Tooling home"），其定位与设计要点在仓库代码中完全可查：

• stdlib-only 可导入模块 + CLI 双角色：_SocketRtt是共享 socket 控制台基类（错误契约统一为RttError：stall、closed、dead/reset server 全部归入这一类，RuntimeError子类），派生JlinkRtt（J-Link 路由）与OpenocdRtt（OpenOCD 路由）。CLI 通过--backend显式选择路由，无默认值。
• 依赖方向：harness → tools，绝不允许 tools → harness。hil_util在 test/hil/helper/hil_util.py 中通过importlib.util动态加载tools/rtt.py并再导出JlinkRtt、OpenocdRtt、RttError、RTT_BANNER_RE、strip_banner——HIL 平台继续以hil_util.JlinkRtt寻址，兼容旧调用方。
• harness-critical 分类：因为hil_util在导入期就加载该文件，它被ci_select的 full rule 与test/hil/归为一类（见 test/hil/test/test_ci_select.py），并由 pre-commit 的hil-test钩子覆盖（test/hil/test/test_hil_rtt.py）。该测试文件确认了：五个导出名齐全（test_hil_util_reexports_the_rtt_classes）、hil_remote.py必须 stagetools/rtt.py（否则整个 harness 导入即崩）、以及RTT_BANNER_RE必须滤掉全部三行 J-Link banner（包括中间那行不带SEGGER前缀的探针型号串，如J-Link OH3、J-Trace H9），同时不能误滤真实目标输出（Hello from TinyUSB、ID 1a86:8010 SN 7FD88F0604B5）。
• 先例：code-sizeskill 包装tools/metrics_compare_base.py——skill 只是 md 文档，指向工具本身。open_board_console()暂时保留在 test/hil/hil_test.py，pool-check 化是后续文档而非本 PR。

CLI 三条路由（来自 tools/rtt.py 文档字符串）

# J-Link 路由（console/capture，仅 channel 0） rtt.py --backend jlink --probe <sn> --device <JLINK_DEVICE> [--seconds N] [-i] # OpenOCD 路由（原生探针：ST-Link/CMSIS-DAP；console/capture，任意 channel） rtt.py --backend openocd [--probe <sn>] [--vid-pid "0xVVVV 0xPPPP"] \ --cfg "-f interface/stlink.cfg -f target/stm32h7x.cfg" \ (--elf <flashed.elf> | --addr 0x2000xxxx) [--channel N] [--seconds N] [-i] [--reset-before-attach] # 从目标开机起采集（SystemView） # 事后环形转储（J-Link，不 halt —— debug-AP 读取） rtt.py --backend jlink --dump <out.bin> --probe <sn> --device <JLINK_DEVICE> \ (--elf <flashed.elf> | --addr 0x...)

参数要点（源码级）：

• --probe传探针序列号（JLinkExe 的-USB/ openocd 的adapter serial）；--vid-pid仅 openocd 可用且必须是"0xVVVV 0xPPPP"格式——openocd 对畸形值只警告并以 0 退出，静默不生效，所以工具直接拒绝。
• --elf与--addr二选一：nm_rtt_addr()用arm-none-eabi-nm（可用环境变量RTT_NM覆盖）解析_SEGGER_RTT符号地址；--addr是 nm 无法读文件（架构不符、无工具链）时的出路。
• --reset-before-attach仅 openocd：会话内reset run+sleep 2000再 attach，专供必须从字节 0 解码的流（SystemView 的 Init 记录只在开机时发一次）。设计上强制顺序：rtt start需要控制块已存在于 RAM；SAMD5x（DSU 复位后内核 held）与 WCH（扰动目标）上禁用。
• --dump走 J-Link 路由：mem32读描述符、校验MaxNumUpBuffers与 channel 范围、savebin整环落盘，并用"文件必须等于完整环大小"来证明 savebin 成功（JLinkExe 脚本内命令失败也会以 0 退出，只有文件字节数是铁证）。
• -i交互模式：stdin 转发有门控——pump_stdin()等待目标输出（或 5 秒）后才开始转发，因为 J-Link telnet 路由在 Commander 定位到控制块之前会静默丢弃客户端字节（实测：即时发送的 'ping' 消失，延迟发送的 'ping' 才被回显）。
• 探测端口用free_ports()动态分配（板子并行跑，SEGGER 默认端口会冲突）；服务器输出 spool 到临时文件，避免 64 KiB 管道积压让单线程服务器静默卡死；进程组级 teardown 保证服务器不霸占探针（Windows 用taskkill /PID <pid> /T /F，POSIX 用killpg的 graceful→force 阶梯）。

与 HIL 平台的集成语义

test/hil/hil_test.py 的open_console_reset()把"复位与打开控制台"的顺序写成了契约：RTT 控制台独占探针，所以必须先复位再打开（环形缓冲会保住开机突发）；而 VCOM 能承受复位，所以先开后复位才能抓到 banner。两种顺序都必要，因为 host 测试匹配的行（挂载消息、枚举消息）每次开机只打印一次。serial_write_all()把hil_util.RttError当作与串口超时同级的"排空停止"失败语义——板卡测试失败而非 harness 崩溃；故意不用裸RuntimeError，以免把NotImplementedError等 harness bug 误报成板卡行为异常。

文档编辑计划：curated-skills 的最小 diff 规则

晋升的同时要做最小化文档改动（"smallest possible diffs"）：

• target-debug/SKILL.md：保留采集通道表格行与排空模型警告；两段采集菜谱和 RTTLogger/GDBServer 段落缩成一行并指向rtt；手工环形读取菜谱（nm/mem32/savebin）移入rtt的 §post-mortem。
• CLAUDE.mdGDB 节的 RTT 行变为"构建标志 + 指针"。
• hil/SKILL.md增加一行路由说明——这正是能避免"丢失的一小时"的修复。
• sysview/SKILL.md的指针推迟到该分支合并，且需先向用户提议；当前不动sysview_ci.py与 sysview skill。

验证策略：dogfood 优先，全部板卡跟进

用户指定的验证路径分两步：

1. 先在本地 htpc 长凳上 dogfood：ea4088_quickstart走 LPC-Link2（重新插拔；对它的 OpenOCD 尝试直接跳过）与raspberry_pi_pico2走 J-Trace（昵称jtrace，序列号私有；现已接线到 pico2；RP2350 用rp2350_m33_0，绝不用自定义 JLinkScript）。只按 SKILL.md 文本操作（dogfood = REFACTOR 的输入）。
2. 然后在 ci.lan 台架上跑全部板卡，按传输类型做 smoke 采集，逐行记录进.claude/skills/rtt/boards.md。排除项如实记录：esptool 板（构建中没有 SEGGER-RTT 路径，用 USB-Serial-JTAG 控制台代替）；tm4c（台架未配置探针路径）。

小结

从这份设计决策记录可以提炼出 tinyusb 仓库对调试工具的成熟态度：先测量、后决策——lpc4088 的 6/6 与 0/6 对照、sysview 的 13 板读路径验证、WCH SDI 的 A/B 证明，全部沉淀为 skill 的"携带状态"；工具先于文档——tools/rtt.py作为 stdlib-only 的可导入模块 + CLI 先落地，hil_util再导出保持兼容；矩阵化表达约束——同一探针在不同后端下可能是"已验证 / 未验证 / 禁止"三种状态，绝不把部件间差异抹平成单一结论。对于在无 UART、无 VCOM 板卡上要"给块板一个控制台"的开发者，直接以rtt.py --backend jlink --probe <sn> --device <JLINK_DEVICE> -i起步即可，但务必记住三条红线：控制块要等第一次 printf；控制台独占探针（先烧录复位、挂接后不复位）；饱和下 RTT 是排空受限且有损的——默认 1 KB 的 NO_BLOCK_SKIP 环，保住的是开机后的第一 KB，而不是最新的尾巴。

• 嵌入式
• 驱动开发
• 通信
• 物联网