1. 为什么拿 Keil MDK 跑 freeRTOS demo:一块 STM32F103 上的最小验证闭环
很多人第一次接触 freeRTOS,卡住的不是任务、队列这些概念,而是代码写完了,怎么让它真的在板子上跑起来。在代码开发工具这条链路上,Keil MDK(uVision4)配一块 STM32F103 是最省事的组合:工程里已经把 freeRTOS 源码、启动文件、命令行实现都摆好了,开箱就能编译烧写,串口一接就能敲命令。这篇笔记围绕一个现成的 demo 工程,把打开、编译、烧写、串口敲命令这条闭环拆开讲,顺带说清楚每一步的前置条件和容易翻车的地方。适合刚上手 RTOS、手头有 F103 板子、想先看到现象再回头啃源码的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 用代码开发工具打开工程:Keil uVision4 的目录结构与首次编译
2.1 工程包里到底有什么:源码、器件支持包与启动文件
拿到一个「开箱即可编译烧写」的 MDK demo 工程,先别急着点 Build,花两分钟把目录看一遍,后面报错能省一半排查时间。典型的工程根目录下会有这么几类东西:工程文件本身(.uvproj 或 .uvprojx)、应用层代码(main.c、串口驱动、命令行实现)、freeRTOS 源码目录、启动文件 startup_stm32f10x_*.s,以及一个可选的目标输出目录。freeRTOS 的源码通常分两块放:Source 下是 tasks.c、queue.c、list.c 这些内核文件,portable 下按编译器分目录,Keil 用的是 ARMCC,所以要找 portable/RVDS/ARM_CM3 这一支,里面是 port.c 和 portmacro.h。这两块只要缺一个,编译阶段就会报一堆未定义符号。
除了工程自带的文件,还有一样东西不在工程目录里,但决定了能不能打开:器件支持包(Device Family Pack)。STM32F103 属于 Cortex-M3 内核,Keil 需要装对应的 STM32F1 系列 DFP,装完之后新建工程时才能在器件列表里选到具体型号,工程里的启动文件、寄存器定义、Flash 算法也都依赖它。判断方法很直接:双击打开 .uvproj,如果弹出提示说器件不支持或者找不到 device,基本就是这一步没做。工程能正常打开、Project 窗口里的文件树带图标显示、Options for Target 里 Device 页能显示型号,这三条同时满足,才算前置条件齐了。
还有一个小细节值得先看一眼:工程路径里有没有中文和空格。ARMCC 这套工具链对路径的处理不如现在的编译器宽容,路径里带空格时,某些自定义的 build 步骤或者 include 路径会解析失败,报错信息还特别含糊,看起来像是头文件找不到,实际是路径被截断了。我一般的习惯是把工程放到一个纯英文、无空格的短路径下,比如某个盘符根目录下的工作目录,再打开编译。这一步不花时间,但能避免很多「明明文件在,就是编不过」的玄学问题。
2.2 从打开到 Build:编译输出窗口里该看什么
工程打开之后,Project 窗口里的文件树是按 Group 组织的,常见分组是启动文件、CMSIS、外设驱动、freeRTOS 内核、freeRTOS 端口、应用层。这个分组不影响编译结果,但影响你找文件的速度。第一次编译前,先确认工具栏上的 Target 下拉框选的是你要的那个目标(有些工程会同时留 Debug 和 Release 两个 Target),然后按 F7 或者点 Build 按钮。Build 和 Rebuild 的区别在于前者只编改动过的文件,后者全部重编;第一次打开建议直接 Rebuild,避免拿到别人机器上的中间产物导致链接阶段出怪问题。
编译完成后,输出窗口最后会打印一段 Program Size,格式大致是 Code、RO-data、RW-data、ZI-data 四个数字。这四个值的含义值得记一下:Code 是代码段大小,RO-data 是只读数据(常量、字符串),RW-data 是已初始化的全局变量,ZI-data 是零初始化的全局变量和栈堆。对 freeRTOS 工程来说,ZI-data 里很大一部分是任务的栈空间和内核对象,数值偏大是正常的,但如果它接近甚至超过芯片的 SRAM 容量,运行阶段就会出现栈溢出、任务莫名卡死这类问题,而且现象往往和代码逻辑对不上,很容易误判。所以第一次编译完,把 SRAM 总量和 ZI-data 对一下,是个成本很低的好习惯。
输出窗口里另一类信息是 Warning。demo 工程常见的 Warning 有两类:一类是未使用的变量或参数,这类可以忽略;另一类是函数隐式声明,这类要留意,往往是头文件没包含或者 include 路径顺序不对,编译能过但链接时可能找不到符号,或者运行行为和预期不一致。我一般会把 Warning 数量当成一个信号:如果比预期多出一大截,先别烧写,回头看看是不是某个 Group 的文件被排除在编译之外了,或者某个宏没打开。
编译通过之后,工程目录下会生成 .axf 或 .hex 文件,这就是后面烧写要用的产物。.axf 带调试信息,配合调试器可以做源码级单步;.hex 是纯二进制加地址信息,适合用外部烧写工具。Keil 的下载流程默认用 .axf,所以只要编译成功,下载这一步不需要额外转换。
2.3 编译不过时的三个前置条件
第一次打开别人的工程编不过,绝大多数情况逃不出三个原因。第一个是器件支持包缺失或版本不匹配,现象是打开工程就提示器件不支持,或者编译时报寄存器定义相关的错误。解决办法是在 Pack Installer 里装对应系列的 DFP,装完重启 IDE 再打开工程。第二个是 include 路径失效,工程里配置的路径是原作者的绝对路径,换台机器就对不上,现象是头文件找不到。这种情况在 Options for Target 的 C/C++ 页里把 Include Paths 检查一遍,改成相对路径或者本机实际路径就行。
第三个原因比较隐蔽:编译器版本。Keil uVision4 时代默认用 ARMCC,后来的版本可能切到 ARMCLANG,两者对某些语法和宏的处理不一样。如果工程是按老编译器写的,用新编译器打开可能报一些看起来毫无道理的语法错误。这时候要么在 Target 设置里切回兼容的编译器版本,要么按报错逐个改代码。对只想先跑起来看现象的 demo 来说,前者更省事。
| 现象 | 大概率原因 | 处理方向 |
|---|---|---|
| 打开工程提示器件不支持 | DFP 未安装或版本不符 | Pack Installer 补装对应系列 |
| 编译报头文件找不到 | Include Paths 是绝对路径 | 改成相对路径或本机路径 |
| 语法错误集中在老写法上 | 编译器版本切换 | Target 里切回 ARMCC |
注意:改完 Options for Target 里的任何路径或器件设置,重新编译前先执行一次 Rebuild,避免旧的中间文件干扰判断。
3. 烧写与串口命令行:让 freeRTOS 真正跑起来
3.1 Options for Target 里的 Debug 与 Flash Download
编译通过只是说明代码能生成,离板子上跑起来还差烧写这一步。打开 Options for Target,切到 Debug 页,这里要选对调试器类型:手头是 ST-Link、J-Link 还是板载的 ULINK,选错的话点下载会直接提示找不到设备。选完之后点旁边的 Settings,确认 Port 选的是 SW 而不是 JTAG,绝大多数 F103 小板子引出的是 SWD 的两根线。在 Settings 的 SW Device 区域应该能看到芯片的 IDCODE,看得到说明调试器和芯片已经握手成功,看不到就是接线、供电或者驱动的问题,这时候不用往下走,先把这一层解决。
再切到 Flash Download 页,这里有两个设置值得确认。一是 Programming Algorithm 列表里要有对应容量的 Flash 算法,F103 不同型号的 Flash 容量不一样,算法选错了会出现「擦除成功但校验失败」或者下载到一半报错。二是勾选 Reset and Run,这样下载完芯片会自动复位运行,不用手动按复位键。不勾也能用,但调试阶段容易误以为程序没跑起来,实际上是芯片还停在下载后的状态。
配置好之后点 Download 按钮,输出窗口会依次打印擦除、编程、校验的过程。任何一步报错都别急着重复点,先看报错文本:提示算法不匹配就回去改 Flash 算法,提示目标无响应就回去查调试器连接,提示校验失败一般是供电不稳或者 Flash 被读保护了。读保护这种情况在小板子上偶尔会遇到,表现是能连上但一写就失败,需要先解除保护再烧。
3.2 串口终端怎么接:中断收数、命令行解析
这个 demo 的命令行入口是串口,代码上是用中断接收串口数据来实现命令行的调用。硬件接线就三根:板子的 TX 接 USB 转串模块的 RX,RX 接 TX,GND 对 GND。很多人第一次接只接了两根信号线忘了共地,现象是终端里偶尔能收到几个乱码字符,看起来像波特率不对,实际是电平参考不一致。
终端软件这边,波特率和工程里 USART 初始化时设的要一致,数据位 8、无校验、1 位停止位,这是最常见的配置。终端模式选文本模式,敲命令用;如果要看原始字节,再切到十六进制模式。打开串口后如果一片空白,先按一下板子的复位键,很多 demo 会在启动时打印一行版本信息或者提示符,有输出就说明链路通了。
代码层面,中断接收加命令行解析的骨架大致是这样,工程里用的是标准外设库还是 HAL,以你打开的文件为准,下面按标准外设库的写法示意:
c复制/* 串口中断:只负责把字节搬进队列,不做任何解析和打印 */
void USART1_IRQHandler(void)
{
BaseType_t woken = pdFALSE;
if (USART_GetITStatus(USART1, USART_IT_RXNE) != RESET) {
uint8_t ch = USART_ReceiveData(USART1);
/* 队列满时直接丢弃,绝不在中断里等待 */
xQueueSendFromISR(uart_rx_queue, &ch, &woken);
USART_ClearITPendingBit(USART1, USART_IT_RXNE);
}
portYIELD_FROM_ISR(woken);
}
这段代码有两个关键点。第一,中断里只做数据搬运,收到一个字节就丢进队列,然后立刻退出。解析、比较命令、打印结果这些耗时操作全部放到任务里做,这是 freeRTOS 下串口收数的基本纪律。第二,xQueueSendFromISR 的第三个参数用于在中断退出时触发一次任务切换,如果中断里唤醒了更高优先级的任务,portYIELD_FROM_ISR 会让它在中断返回后立刻运行,而不是等到下一个系统节拍。
任务侧的解析逻辑是另一个循环:
c复制static void cli_task(void *arg)
{
char line[64];
uint8_t idx = 0, ch;
for (;;) {
/* 阻塞等待,不占用 CPU */
if (xQueueReceive(uart_rx_queue, &ch, portMAX_DELAY) == pdTRUE) {
if (ch == '\r' || ch == '\n') {
line[idx] = '\0';
if (idx > 0) {
cli_exec(line); /* 命令表里查名字,命中就调处理函数 */
}
idx = 0; /* 一行结束,缓冲清零 */
} else if (idx < sizeof(line) - 1) {
line[idx++] = ch; /* 留一个字节给结束符 */
}
}
}
}
line 的长度决定了单条命令最多能敲多长,64 字节对 demo 够用;如果后面要加带参数的长命令,这个值要跟着调。portMAX_DELAY 表示队列空时任务一直阻塞,把 CPU 让给其他任务,这也是为什么中断里不能直接解析:解析放任务里,CPU 才有机会在等串口数据的时候去跑别的任务。
命令的匹配通常是一张表:
c复制typedef struct {
const char *name;
void (*handler)(int argc, char **argv);
} cli_cmd_t;
static const cli_cmd_t cmd_table[] = {
{ "help", cmd_help },
{ "ver", cmd_ver },
};
表里加一行,就多一条命令;解析时按空格切分参数,拿第一个词去表里顺序比对。demo 工程自带的那几条命令就是按这个结构组织的,读一遍 cli_exec 的实现,后面自己加命令就是照葫芦画瓢。
3.3 用几条命令验证调度器活着
烧写完成、串口打开之后,先敲一条帮助命令。有回显说明三件事同时成立:串口收发链路通、中断能进、命令行任务被调度到了。这三件事里任何一件不成立,终端都不会有反应,所以第一条命令的意义不在于它输出了什么,而在于它证明整条链路是活的。
接着可以敲几条验证任务调度的命令。如果工程里打开了任务统计相关的宏,vTaskList 能把当前所有任务的名字、状态、优先级、剩余栈空间打印出来,这是判断「任务到底跑没跑」最直接的手段。表格里能看到每个任务的状态是 Running、Ready、Blocked 还是 Suspended,命令行任务平时应该处于 Blocked(等队列),敲命令的瞬间变成 Ready 再变 Running,这个状态变化本身就是调度器在工作的证据。
再往下可以敲一条让某个任务延时或者翻转 LED 的命令,观察现象是否符合预期。这一步的价值在于把「命令行能响应」升级成「命令行能驱动业务逻辑」,证明命令处理函数和任务之间的配合没问题。到这一步,这个 demo 的验证闭环就算走完了:编译产物在板子上跑着,freeRTOS 的调度器在转,串口命令行可以交互。
| 验证目标 | 敲什么 | 看什么 |
|---|---|---|
| 串口链路 + 中断 | help | 有无回显、提示符是否出现 |
| 任务调度 | 任务列表类命令 | 各任务状态与剩余栈 |
| 业务驱动 | 控制类命令 | LED 或外设的实际变化 |
4. 代码开发工具用顺手之后的避坑清单:五个高频翻车点
4.1 现象:编译零错误,一点下载就报找不到设备
输出窗口显示 Build 成功,点 Download 却弹出目标无响应的提示,反复点也没用。原因基本在调试链路这一层:调试器驱动没装好、SWD 两根线接反或者没接、板子没独立供电、又或者调试引脚被程序里配置成了普通 IO。最后一种最容易被忽略,如果之前的程序把 SWD 引脚复用掉了,芯片上电后调试器就连不上,只能通过复位时机或者 BOOT 引脚方式恢复。解决顺序是先确认 Settings 里能看到 IDCODE,看不到就查线和供电,看得到但下载失败再回去查 Flash 算法。
4.2 现象:串口终端里全是乱码,或者干脆没反应
乱码第一反应是波特率,但实际问题往往更基础:TX 和 RX 没有交叉、没有共地、终端软件选错了串口。这三条排查完再回头看波特率,确认终端设置和工程里 USART 初始化保持一致。还有一种情况是终端能收到板子上电时打印的一行信息,但敲什么命令都没回显,这说明发送方向通、接收方向不通,重点查板子的 RX 那根线和中断是否真的使能了。
4.3 现象:命令行敲两三条就卡死,复位后又正常
这个现象在 demo 阶段很典型,根因通常是队列长度给得太小,连续输入时字节被丢弃,导致某一行命令不完整,解析时卡在等待换行符上;或者在中断处理函数里直接调用了打印函数,串口发送本身是阻塞的,中断里等发送完成会把整个系统拖住。解决办法是把打印挪到任务里,中断只负责收;队列长度按「一行最长字符数 × 2」来估,留出余量。任务栈也要看一眼,命令行任务里如果用了比较大的局部数组,栈给小了会直接踩到别的任务的内存。
4.4 现象:换一台电脑打开工程,提示器件不匹配
工程本身没坏,是那台电脑上没装对应系列的器件支持包,或者装的是不同版本的包。Keil 的器件信息、启动文件、Flash 算法都跟着包走,包不对,工程里的型号就解析不出来。处理办法是装同系列同版本的 DFP,装完重启 IDE。团队协作时这个问题会反复出现,比较稳妥的做法是在工程说明里写清楚依赖的器件包系列,而不是只丢一个工程压缩包。
4.5 现象:同一份代码,别人的机器编出来能跑,自己的跑飞
先对比两边的编译输出,重点看 Program Size 里的 ZI-data 和 Code 差多少。差异过大通常是某个宏没打开或者某个文件被排除编译了,比如调试打印相关的宏,一边开了另一边没开,代码路径就不一样。还有一种情况是优化等级不同,高优化等级下某些没加 volatile 的全局变量会被优化掉,中断里改、任务里读的变量如果不加 volatile,行为会变得非常诡异,这类问题在调试器里看变量值都正常,跑起来就是不对。
提示:接手别人的 Keil 工程,第一件事是把 Options for Target 里的 Device、Debug、Flash Download、C/C++ 四页截图存一份,出问题时和自己机器上的逐项对比,比盲猜快得多。
5. 把 demo 改成自己的命令行工具:加一条命令的完整路径
demo 跑通之后,最有价值的动作是加一条自己的命令,把「看现象」变成「改代码」。改法不复杂:在命令表里加一行,写一个处理函数,编译烧写,串口敲一下。比如加一条打印当前系统节拍的命令:
c复制static void cmd_tick(int argc, char **argv)
{
/* 打印内核节拍计数,用来观察调度器运行了多久 */
printf("tick = %lu\r\n", (unsigned long)xTaskGetTickCount());
}
static const cli_cmd_t cmd_table[] = {
{ "help", cmd_help },
{ "ver", cmd_ver },
{ "tick", cmd_tick }, /* 新增的一行 */
};
xTaskGetTickCount 返回的是内核启动以来的节拍数,敲两次看数值是否在增长,就能判断调度器是否还在正常运转。这个函数在任务上下文里调用是安全的,不要在中断里调。加完命令后先 Rebuild 再下载,下载完复位,串口敲 tick 两次,两次数值不同就说明新命令生效了。
验证新命令时有个小技巧:先敲一条已知能用的老命令,确认链路正常,再敲新命令。如果老命令有回显、新命令没反应,问题就在命令表或者处理函数里,不用怀疑串口和烧写。这种「先证链路、再证新增」的顺序,比一上来就盯着新代码看要快。
加命令的过程中还有两个参数值得留意。一是命令表数组的长度,如果代码里用 sizeof(cmd_table)/sizeof(cmd_table[0]) 来算条目数,加行不用改别的地方;如果是写死的循环上限,加命令时记得同步改。二是处理函数的参数个数,解析器按空格切分后传 argc 和 argv,处理函数里取参数之前先判断 argc,不然敲了个不带参数的命令,处理函数里去读 argv[1] 就越界了。
从那以后我每次拿到一个新的 MDK demo 工程,都会先按「器件包、路径、编译输出、下载配置、串口接线」这五项过一遍,再动手改代码,顺序反了就容易在环境问题上耗掉半天。希望这些步骤能帮到你,少走几段弯路。
