简介嵌入式开发中实时操作系统与命令行接口的集成常是调试痛点。示例包面向嵌入式开发者演示如何借助JLink的RTT Viewer在不中断程序执行的情况下对FreeRTOS系统进行命令交互与运行时监控尤其适合需要远程查看任务状态或动态调整参数的调试场景。压缩包共6个文件以4个C源文件和2个头文件构成其中RTT_CmdConsole.c与RTT_CLI.c负责RTT通道的命令收发FreeRTOS_CLI.c实现命令注册、解析与执行RTT_CLI_commands.c与RTT_CLI.h提供自定义命令的扩展入口头文件统一声明接口整体仅19KB结构精炼。目前已有284人学习浏览适合正在研究RTOS调试、或希望获取轻量级CLI控制台方案的开发者。通过该例程可理解RTT Viewer与FreeRTOSCLI的完整对接流程学习自定义命令的编写方法并直接复用这套低开销调试框架提高系统状态查看与远程控制效率。1. FreeRTOS调试为什么需要CLIbyRTT Viewer从串口到RTT的切换调试FreeRTOS任务时最怕的就是任务卡死却不知道卡在哪一行。传统方案是在串口中断里加打印但printf本身会阻塞任务尤其在中断里调用更是危险。这个CLIbyRTT Viewer.zip不再依赖串口而是借助RTTReal-Time Transfer把FreeRTOS的CLI命令通道搬到调试器上让task list、内存查看、动态命令输入都走同一条高速链路。它适合手里有仿真器、正在调FreeRTOS任务调度和内存问题的开发者也适合想把命令行交互能力嵌入固件却没有多余串口资源的场景。接下来会把它的实现和用法一步步拆开。2. RTT与FreeRTOS CLI先搞懂传输链路再动手2.1 RTT的读写模型内存环形缓冲与不阻塞的关键RTT不是USB转串口那种外设而是调试器和目标MCU之间共用的一块内存区域。目标端往环形缓冲区写调试器端在PC上读。这个读写过程在目标侧只是普通内存拷贝没有中断、没有外设等待所以在FreeRTOS里CLI输出不会像串口那样因为波特率或FIFO满而阻塞任务。这点对任务实时性至关重要——一个长时间运行的printf会让串口耗尽CPU时间而在RTT里只是几个周期完成的内存写入。RTT控制块在RAM中占用一段固定结构最前面是标识字符串用于调试器扫描内存时识别。标识后面是每个通道的读写索引和缓冲区指针。调试器通过读取索引判断是否有新数据目标侧通过写索引通知调试器。整个链路不需要一个外部中断也不依赖调试器的连接速度所以即使调试器以100Hz轮询目标侧也不会感知到延迟。环形缓冲的容量直接影响调试体验。工具包默认把每个channel的缓冲区设为2048字节。如果任务日志输出很频繁比如每毫秒几十行2048字节可能只够几十条消息就会被覆盖。下表对比了常见缓冲区和行为缓冲区大小典型用途副作用512字节轻量状态输出容易覆盖日志不连续2048字节常规CLI交互长命令输出可能截断8192字节高频日志CLIRAM占用大低速MCU要谨慎写策略也很关键。常见做法是NoBlockSkip缓冲区满时丢弃新数据另一种是NoBlockTrim满时覆盖最旧数据。CLIbyRTT Viewer默认用Skim模式保证最新日志优先但在调任务卡死时我更推荐临时改成覆盖模式让旧数据也能被读走之后再调回。中断和任务并发访问同一个RTT channel时写索引可能被破坏。工具包在cli_rtt_transport.c里提供临界区保护宏默认关闭。如果你在中断服务函数里也调用RTT输出必须打开这个宏否则会出现丢数据甚至HardFault。这个坑在第四章会专门讲。2.2 FreeRTOS CLI的注册机制命令表怎么挂到RTT上FreeRTOS官方维护的FreeRTOSCLI组件核心是一张命令注册表。每个命令就是一个结构体包含命令字符串、帮助文本、回调函数和参数个数。调试器端输入命令后CLI组件会在表里匹配字符串找到对应回调执行然后把输出写到缓冲区。这个命令结构体定义大致长这样typedef struct CLI_Command_Definition_t { const char *pcCommand; /* 命令关键字 */ const char *pcHelpString; /* help输出 */ BaseType_t (*pxCommandInterpreter)(const char *pcWriteBuffer, size_t xWriteBufferLen, const char *pcCommandString); BaseType_t xMinimumNumberOfParameters; } CLI_Command_Definition_t;CLIbyRTT Viewer做的事情很简洁提供一个cli_rtt_transport.c把FreeRTOSCLI默认的输入输出函数替换成RTT读写函数。原本FreeRTOSCLI驱动串口时需要自己实现一个函数从串口收字符另一个函数往串口发字符。现在这两个函数直接对RTT缓冲区操作FreeRTOSCLI那套解析逻辑完全不用动。这种设计的好处是如果你项目里已经在用FreeRTOSCLI那集成这个工具包只需要做三件事把cli_rtt_transport.c加进工程在初始化时创建CLI任务然后保证RTT控制块可以被调试器识别。命令注册表还是原来那张不冲突。工具包里demo代码创建了一个优先级为1的CLI任务栈大小1024字在Cortex-M4上约4KB。为什么不用更高优先级因为CLI命令执行过程中可能会调用某些阻塞型API比如等待互斥锁如果CLI任务优先级高于业务任务可能反过来拖慢业务逻辑。所以默认低优先级是对的除非你要输入的命令必须高实时响应。命令注册的失败率比你想的高。常见原因是configASSERT没有打开注册失败直接忽略直到调试时才发现命令不存在。所以集成后第一件事就是打开configASSERT并在注册函数后面断言返回值。工具包在每个demo例程里都写了这行断言但很多人会出于减小代码体积把它注释掉结果后面排查浪费了一整天。另外FreeRTOSCLI官方还提供FreeRTOS_CLIEndCommand等内部状态机。当命令回调需要多段输出时返回pdTRUE表示还有更多内容返回pdFALSE表示输出结束。这个规则不处理好你会在RTT界面看到命令输出只显示一半就停了。具体细节在第五章的自定义命令部分展开。3. 把CLIbyRTT Viewer跑起来PC端与嵌入式端联调3.1 PC端查看器启动与参数解释工具包解压后PC端是一个Python脚本rtt_viewer.py。这个脚本做的事情是连接调试器、定位RTT控制块、循环读取channel 0和channel 1的数据并把channel 0收到的文本当成CLI输入把开发者敲的命令写回目标侧RTT缓冲区。启动命令如下python rtt_viewer.py --if swd --speed 4000 --device cortex-m4 --rtt-channel 0 --log-channel 1参数说明--if调试接口类型常见值是swd或jtag。SWD只占用两根线适合大多数调试场景JTAG在需要同时调试多核时再用。--speed调试接口时钟频率单位kHz。不是串口波特率。默认4000表示4MHz如果飞线较长或目标板电源不稳降到1000会更稳。--device目标芯片或内核型号。脚本会根据它向调试器固件发送配置。没有对应型号时可以用cortex-m4这类通用内核名。--rtt-channelCLI命令使用的RTT通道编号。工具包约定channel 0是CLI。--log-channel日志输出使用的通道编号。工具包约定channel 1是日志。如果你的板子调试器不能自动识别RTT控制块脚本也支持手动指定地址python rtt_viewer.py --rtt-addr 0x20000000这个地址需要从工程的map文件里查或者用调试器内存查看功能确认。手动指定地址不推荐因为每次编译如果固件布局变了地址会漂移。但有些情况下自动识别失败手动指定是唯一办法。脚本启动后如果一切正常会显示一个类似串口终端的界面。界面没有复杂控件就是输入框加输出框。输入help回车能看到FreeRTOSCLI提示符。如果你需要同时看两个通道脚本会把channel 0和channel 1的输出交错显示并加一个字符前缀区分。3.2 嵌入式端集成步骤代码加到工程里第一步把cli_rtt_transport.c和cli_rtt_transport.h复制到你的工程目录同时确认FreeRTOSCLI的源码freertos_cli.c已经编译进工程。第二步在main函数或初始化任务里调用RTT缓冲区的初始化然后创建CLI任务。下面是一段从demo里精简的初始化代码/* cli_demo_init.c */ #include FreeRTOS.h #include task.h #include cli_rtt_transport.h #include FreeRTOS_CLI.h static void vCLITask(void *pvParameters) { /* 注册FreeRTOS内置命令 */ const CLI_Command_Definition_t *pxCommands[] { xTaskStatsCommand, xHeapUsageCommand, xHelpCommand, }; for (int i 0; i 3; i) { BaseType_t xResult FreeRTOS_CLIRegisterCommand(pxCommands[i]); configASSERT(xResult pdPASS); } /* 进入CLI处理循环 */ for (;;) { vCLITransportProcess(); /* 从RTT读输入并处理 */ } } void vStartCLI(void) { vCLITransportInit(0); /* 初始化RTT channel 0 */ xTaskCreate(vCLITask, cli, 1024, NULL, 1, NULL); }逻辑说明vCLITask先注册三个内置命令然后进入一个死循环由vCLITransportProcess不断从RTT channel 0读取输入交给FreeRTOS_CLI解析。vCLITransportInit负责初始化环形缓冲区和RTT控制块。参数说明xTaskCreate的栈大小是1024字如果预编译宏configTOTAL_HEAP_SIZE比较小可以减到768但会降低输出长文本时的余量。优先级设为1避免影响业务任务。注意xTaskStatsCommand等命令结构体定义在FreeRTOS_CLI内部你需要包含它导出的头文件。如果编辑器报未定义去FreeRTOSCLI的examples目录找或者用官方文档里的注册方式。3.3 联调验证流程先看到help再谈其他集成后烧录固件。烧录完成后不要急着打开脚本先用调试器确认目标芯片已经运行RTT控制块确实存在于内存。通常调试器连接后会自动发现控制块有些调试器需要你在连接设置里开启搜索RTT控制块选项否则即使固件里有RTTPC端也找不到。启动脚本后如果第一屏就有CLI提示符说明链路通了。输入help回车应该能看到命令列表。如果看不到先看4.1的排查。一个很关键的验证点让目标任务周期打印日志到channel 1同时通过CLI敲一个命令改变任务行为确认输出通道互不干扰。这个验证在每次代码修改后做一次能提前暴露很多隐蔽的集成错误。具体做法是在某个任务里每500毫秒写一条task alive到channel 1然后从CLI输入task-stats观察两边的输出是否同时出现在界面上。如果CLI命令阻塞了日志输出说明通道的临界区保护没有配对。另外联调时最好把P C端脚本的日志级别调到debug这样能看到每次轮询时RTT控制块的索引变化。索引不增长说明目标侧没有写索引增长但内容不显示说明PC端读取失败。这两类问题的排查方向完全不同。4. 排查与避坑RTT Viewer与FreeRTOS的6个常见问题4.1 现象RTT通道没输出但程序正常跑原因RTT控制块的符号没有导出给调试器。有些工程链接时把未引用的RTT缓冲区垃圾回收掉了或者调试器在连接时没扫描到控制块。解决在链接脚本里保留RTT控制块所在的段或者显示定义一个全局指针强制引用RTT控制块。工具包的文档里有一段示例用__attribute__((used))修饰控制块变量确保编译器不优化掉。我一般还会在工程里加一个volatile变量指向它防止整个段被linker删除。4.2 现象任务列表打印到一半卡住原因RTT缓冲区满了调试器还没读走而写策略设成了NoBlockSkip缓冲区满则丢弃新数据且不再写。CLI命令一次输出很长比如task-stats输出几百字节2048字节的缓冲区不够用。解决把RTT缓冲区调到4096或8192或者把写模式改成NoBlockTrim覆盖旧数据。覆盖模式会丢最老的数据但不会卡住命令执行。在调试任务调度问题时应优先保证命令不卡丢日志可以接受。工具包里默认给了缓冲区和写策略的宏改起来不用动代码。4.3 现象输入命令没反应PC端没有回显原因PC端脚本连接的是日志通道而不是CLI通道。工具包默认CLI在channel 0日志在channel 1。如果你用--rtt-channel 1启动你输入的命令写进了日志通道CLI任务根本不读它。解决检查启动参数确保--rtt-channel 0。同时检查嵌入式端vCLITransportInit传入的channel编号和脚本一致。这两个值必须匹配否则就是对着空气喊话。4.4 现象在中断里调用RTT写函数导致HardFault原因中断打断了正在执行的CLI输出两个上下文同时操作环形缓冲区写索引导致索引错乱缓冲区被写坏。解决中断里不要直接写RTT。正确做法是给CLI任务发任务通知让它在任务上下文中执行输出。如果必须在中断里输出关键信息用独立的channel并加临界区保护但这样会增加中断执行时间不建议做。工具包的cli_rtt_transport.c里有一个vRTTWriteString函数里面用了taskENTER_CRITICAL但只有在打开宏configRTT_SUPPORT_ISR时才启用。没有打开宏时如果中断里调用就会踩坑。4.5 现象CLI任务栈溢出检测触发原因FreeRTOS_CLIProcessCommand内部使用一个本地缓冲区来拼接输出如果输出命令忘了调用FreeRTOS_CLIOutput缓冲区可能会不断累积导致栈爆。另外自定义命令回调里用了过大的局部数组也会踩栈。解决把CLI任务栈从1024提高到2048并在工程中开启configCHECK_FOR_STACK_OVERFLOW。开启后如果溢出会在FreeRTOS的hook函数里捕获至少能定位到是CLI任务的问题。我还建议用uxTaskGetStackHighWaterMark监控CLI任务的空闲栈空间把它输出到channel 1就能看到栈的余量变化。4.6 现象PC端脚本报No RTT control block found原因固件没有运行、调试器连接时程序停在复位向量、或者固件里根本没初始化RTT控制块。解决确认main函数里已经调用vCLITransportInit。如果固件跑起来了仍然报错手动指定RTT控制块地址试试。地址可以在调试器的内存窗口搜索RTT标识字符串控制块头部固定有8字节标识来获取。注意区分大小写标识字符串是ASCII码不要搜成Unicode。5. 进阶玩法自定义命令和实时诊断5.1 注册自定义命令把调试动作变成命令行操作CLIbyRTT Viewer的扩展性在于任何你能用C写出来的调试动作都能注册成一条命令。我在调某套协议栈时就把消息重发、连接状态、缓存水位全部注册成命令不用每次重新编译烧录。注册自定义命令的模板在工具包里结构体定义和回调函数原型如下static BaseType_t prvDumpBufCommand(const char *pcWriteBuffer, size_t xWriteBufferLen, const char *pcCommandString) { int idx 0; /* pcCommandString是用户输入的原命令用于解析参数 */ sscanf(pcCommandString, dumpbuf %d, idx); if (idx sizeof(g_aucBuffer)) { snprintf(pcWriteBuffer, xWriteBufferLen, index out of range\n); return pdFALSE; } snprintf(pcWriteBuffer, xWriteBufferLen, buf[%d]0x%02x\n, idx, g_aucBuffer[idx]); return pdFALSE; } static const CLI_Command_Definition_t xDumpBufCommand { dumpbuf, dumpbuf idx: print one byte from buffer\n, prvDumpBufCommand, 1 };逻辑说明回调函数把格式化文本写到pcWriteBuffer函数返回pdTRUE表示还有更多输出返回pdFALSE表示输出结束。这里的snprintf长度限制是xWriteBufferLen不要写死否则如果CLI内部只提供128字节的缓冲你的snprintf可能越界。参数说明sscanf从pcCommandString解析命令后的数字。xMinimumNumberOfParameters字段设为1表示该命令至少需要一个参数。如果用户只输入dumpbuf不带参数CLI组件会直接输出帮助字符串而不调用你的回调。自定义命令的常见坑回调函数里调用了阻塞API比如vTaskDelay会让CLI任务停在那里后续命令全部排队。所以自定义命令里的操作应当尽量短小如果需要耗时操作就只启动一个标志让业务任务去做。比如你要触发一次固件重启可以在命令回调里设置g_bRebootRequested pdTRUE然后等待主循环执行重启。5.2 RTT双通道做实时任务状态输出CLI命令是按需查询但调实时性问题时你需要持续观察任务状态变化。CLIbyRTT Viewer在初始化时把channel 0留给CLIchannel 1留给日志。你可以在一个定时器任务里周期性输出任务栈高水位和CPU占用比如每2秒一次。工具包里没有强制要求你用什么输出函数但demo里建议直接操作channel 1的写接口避开CLI的格式解析void vLogTaskStats(void *param) { TickType_t xLastWakeTime xTaskGetTickCount(); for (;;) { vTaskDelayUntil(xLastWakeTime, pdMS_TO_TICKS(2000)); vRTTWriteString(1, task stats poll\n); /* 这里可以调用task统计API获取栈高水位 */ } }逻辑说明vRTTWriteString的第一个参数是channel编号第二个是字符串。PC端脚本的--log-channel 1会抓取这个通道的数据并显示。参数说明2000毫秒是定时周期你可以改成500毫秒观察更细的抖动但输出会变多覆盖模式下会丢掉更早的日志。注意channel 1输出的内容不会进入CLI解析所以即使包含特殊字符也不会被误执行。如果你之前一直在用串口printf看日志切到RTT后会有一种明显感受日志刷新快了一个数量级而且不占用任何外设资源。代价是调试器必须一直连着一旦拔出调试器RTT输出就彻底消失这点和串口完全不同要提前习惯。6. 让CLIbyRTT Viewer成为调试习惯验证技巧与收尾现在我每次调FreeRTOS都会强制走一遍这个验证流程用CLIbyRTT Viewer连上后先跑一遍help再敲task-stats看任务列表接着在channel 1上连续输出100条日志确认两个通道互不干扰。这一套流程跑完才敢说RTT链路是稳定的。有个小技巧可以分享把PC端脚本的输出重定向到文件用来做回归测试。比如你在CLI里输入一条命令期望得到特定输出那就写一个简单的Python脚本调用rtt_viewer.py并比对结果。这样每次修改固件后重新跑一遍能在几分钟内发现命令输出变化很大概率能提前暴露行为变更。做法很简单在rtt_viewer.py里加一个--batch模式要求它启动后自动执行一条命令并退出。我踩过最深的坑是忘了断开调试器就把固件烧进量产板结果现场人员反馈设备日志空白。后来我在工具包的配置说明里特意加了这句话RTT是调试期工具不是运行期日志方案。从那以后我每次交付代码前都会把RTT相关代码用宏开关包起来量产固件默认关闭需要诊断时再打开。希望这个CLIbyRTT Viewer能帮你把FreeRTOS的调试效率提起来尤其是那些串口不够用、任务调度诡异的问题。希望帮到你。本文还有配套的精品资源点击获取