STM32 RT-Thread Nano最小工程构建：从CubeMX配置到Keil移植实战

1. 从零开始的RT-Thread Nano工程构建：为什么选择它？

如果你正在使用STM32这类资源受限的MCU，又厌倦了裸机编程里那些繁琐的状态机、延时和中断管理，想引入一个轻量级的“操作系统”来让代码结构更清晰、任务调度更省心，那么RT-Thread Nano绝对是你应该优先考虑的对象。它不是那个功能庞大的完整版RT-Thread，而是一个高度精简、可深度裁剪的实时内核，最小体积可以压缩到惊人的3KB ROM和1KB RAM以内。这意味着，即使你的芯片只有32KB Flash和4KB RAM，它也能轻松入住，为你带来多线程、信号量、邮箱等基础但至关重要的实时操作系统特性。

很多工程师第一次接触RTOS时，会被复杂的移植步骤和工程配置劝退。网上教程要么过于简单只给步骤不说原理，要么直接丢出一个庞大的标准版工程让人无从下手。而RT-Thread Nano的设计哲学就是“极简入门，按需裁剪”。它官方提供了与Keil MDK、IAR以及STM32CubeMX的无缝集成支持，特别是通过CubeMX的图形化配置，可以让你在几分钟内就搭建起一个可以运行多线程的“最小系统”工程框架，把精力从环境搭建迅速转移到业务逻辑开发上。

这篇文章，我就以一个STM32F103C8T6（也就是常说的“蓝桥杯”核心板）为例，手把手带你走通使用Keil5和STM32CubeMX快速建立RT-Thread Nano最小裁剪工程的完整流程。我会重点解释每一个配置选项背后的意义，告诉你哪些可以剪掉，哪些必须保留，并分享我在实际项目中积累的关于内存管理、线程栈大小设置、以及如何避免常见启动失败问题的“踩坑”经验。我们的目标不是仅仅让一个LED灯闪烁，而是构建一个稳定、可扩展、真正能为你的项目服务的基础工程模板。

2. 工程骨架搭建：CubeMX与Keil5的协同作战

在开始点鼠标之前，我们需要明确工具链。这里选择STM32CubeMX + Keil MDK-ARM的组合，这是国内STM32开发者最主流、生态最完善的环境。CubeMX负责芯片选型、时钟树配置、外设初始化和RTOS中间件的引入，生成高度可读的初始化代码；Keil则作为我们的代码编辑、编译和调试主力。

2.1 CubeMX项目创建与基础外设配置

首先，打开STM32CubeMX，点击“New Project”。在芯片选择器中，输入“STM32F103C8”，选择我们目标芯片“STM32F103C8Tx”。这颗芯片有64KB Flash和20KB RAM，对于运行Nano内核和几个简单任务绰绰有余。

项目创建成功后，我们进入配置界面。第一步是配置系统核心的时钟。对于F103，通常使用外部8MHz晶振（HSE），通过PLL倍频到72MHz系统主频。在“Clock Configuration”标签页，进行如下操作：

1. 在“Pinout & Configuration”页的“RCC”高亮选项下，将“High Speed Clock (HSE)”设置为“Crystal/Ceramic Resonator”。
2. 切换到“Clock Configuration”标签页，你会看到一个图形化的时钟树。在“Input frequency”处输入8（MHz），然后在“System Clock Mux”处选择“PLLCLK”。
3. 接着配置PLL：将“PLL Source Mux”选择为“HSE”，然后将“PLL Mul”设置为9倍频。这样，8MHz * 9 = 72MHz，就是我们的系统时钟（SYSCLK）。此时，AHB总线时钟（HCLK）通常也设置为72MHz，APB1总线时钟（PCLK1）设置为36MHz（最大频率），APB2总线时钟（PCLK2）设置为72MHz。CubeMX会自动计算并显示所有分频器的值，确保它们不超限。

注意：时钟配置是系统稳定运行的基石。如果配置错误，轻则外设工作异常，重则芯片无法启动。务必根据芯片数据手册的时钟树图进行核对。对于F103，要确保PCLK1（APB1）不超过36MHz，这是定时器、I2C、USART2/3等外设所在的总线。

接下来，我们配置一个最简单的GPIO输出，用于后续验证线程是否在运行。比如，我们点亮连接在PC13引脚上的LED（很多最小系统板将此引脚用于LED）。在“Pinout & Configuration”页的左侧，找到“GPIO”选项，点击展开。在右侧的芯片引脚图上找到PC13，点击它，选择“GPIO_Output”。然后在下方出现的“Configuration”面板中，可以设置该引脚的用户标签（User Label）为“LED”，这样生成的代码中就会用LED_GPIO_Port和LED_Pin这样的宏，提高代码可读性。初始输出电平可以设置为低电平（Low）。

2.2 引入RT-Thread Nano中间件

这是核心步骤。在左侧的“Middleware”分类中，找到“RT-Thread”。点击它，在右侧出现的配置面板中，将“Mode”从“Disable”改为“Enabled (nano)” 。

一旦启用，下方会出现一系列RT-Thread Nano的配置选项。这里就是我们进行“最小裁剪”的关键战场。为了构建一个最精简的工程，我们进行如下初始设置：

• Kernel Settings:
  • Tick： 系统时钟节拍频率，默认1000 (1ms)。对于大多数应用，1ms的精度足够，且能提供较好的响应性。如果你的应用对功耗极其敏感，可以降低此值（如100Hz，即10ms一个tick），但会牺牲时间精度。
  • Max priority： 最大优先级数，默认32。对于小型应用，8或16也足够。优先级数越少，内核调度开销略小。我们先保持32。
  • Tick implementation： 选择“SysTick”。这是最标准的方式，利用Cortex-M内核的内置SysTick定时器产生中断，无需额外硬件定时器。
  • Heap Size： 这是RT-Thread Nano动态内存堆的大小，至关重要！Nano内核和线程创建、信号量等对象都需要从这片堆中分配内存。对于最小工程，我们可以先设置为2048（2KB）。后续根据实际创建的线程和对象数量可以调整。
• Shell Settings：直接关闭（Disable）。Shell（命令行组件）虽然强大，但它会引入额外的代码体积和依赖（如串口驱动、文件系统等），不符合我们“最小裁剪”的目标。我们初期调试可以通过点灯或者简单的串口打印来实现。
• Device Drivers：全部关闭。Nano版的设备驱动框架相对独立，为了最小化，我们暂时不使用RT-Thread的设备驱动模型，而是直接使用CubeMX生成的HAL库函数来操作外设（如HAL_GPIO_TogglePin）。这样更直接，代码量也更小。
• Components：全部关闭。包括FinSH（已随Shell关闭）、文件系统、网络等，这些都是“增量化”的组件，初期一概不要。

完成这些配置后，你的RT-Thread Nano配置应该看起来非常清爽，只包含了最核心的内核调度功能。

2.3 生成工程代码

点击CubeMX顶部的“Project Manager”标签页，进行工程生成设置：

• Project Name： 给你的工程起个名字，例如rt-thread_nano_demo。
• Project Location： 选择一个干净的目录。
• Toolchain / IDE： 选择“MDK-ARM V5”。（即使你安装的是Keil5，也选这个）。
• Code Generator：
  • 勾选“Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral”，这会让每个外设的代码单独成文件，结构清晰。
  • 勾选“Backup previously generated files when re-generating”，这是个好习惯，避免误覆盖。
  • 在“Generated files”下，选择“Copy only the necessary library files”，这能减少工程目录的杂乱。

最后，点击右上角的“GENERATE CODE”按钮。CubeMX会生成Keil工程文件（.uvprojx）和所有初始化代码。如果提示安装固件包，确认安装即可。

3. Keil5工程深度适配与内核集成

用Keil5打开刚刚生成的工程文件。首先，我们需要检查并确保RT-Thread Nano的源码已经被正确添加到工程中。在Keil的“Project”侧边栏，你应该能看到一个名为Middlewares\RT-Thread的分组，里面包含了kernel、libcpu等源文件。如果没有，你需要手动添加。

3.1 手动添加Nano源码（备用方案）

有时CubeMX生成可能不完整。最可靠的方式是从RT-Thread官方GitHub仓库获取Nano源码。你可以下载完整的RT-Thread源码，然后找到rt-thread\bsp目录下对应你芯片型号的示例，或者直接使用rt-thread\libcpu和rt-thread\src目录下的核心文件。但对于快速入门，RT-Thread官网提供了“软件包”形式的Nano，可以直接导入Keil。

更简单的方法是：在Keil工程上右键，选择“Manage Project Items”。在“Groups”中添加一个组，命名为“RT-Thread”。然后点击“Add Files”，导航到CubeMX工程目录下的Middlewares/RT-Thread文件夹（如果CubeMX已生成），添加所有.c文件。通常关键文件包括：

• src/目录下的：clock.c,components.c,device.c,idle.c,ipc.c（进程间通信）,irq.c,kservice.c,mem.c（内存管理）,mempool.c,object.c,scheduler.c,thread.c,timer.c。
• libcpu/arm/cortex-m3/（以Cortex-M3为例）目录下的：context_iar.S或context_gcc.S或context_keil.S（根据编译器选择，Keil选context_keil.S），以及cpuport.c。

此外，还需要将对应的头文件路径添加到工程设置中。右键工程名，选择“Options for Target”。在“C/C++”标签页的“Include Paths”里，添加以下路径（根据你的实际目录调整）：

.\Middlewares\RT-Thread\include .\Middlewares\RT-Thread\libcpu\arm\cortex-m3 .\Middlewares\RT-Thread\src

3.2 修改启动文件与分散加载

这是移植RTOS最关键也最容易出错的一步。RT-Thread Nano需要接管SysTick中断和PendSV中断，用于系统时钟滴答和上下文切换。

首先，找到Keil工程中的启动文件，通常是startup_stm32f103xe.s（对于大容量型号）。我们需要修改它：

1. 找到SysTick_Handler(系统滴答定时器中断) 和PendSV_Handler(可挂起的系统服务中断) 这两条中断服务程序（ISR）的入口。
2. 将这两条语句注释掉（在汇编中每行前面加;）。例如：

   ; 原来的： ; SysTick_Handler [WEAK] ; B . ; 修改为： ; SysTick_Handler [WEAK] ; B . ; 或者直接删除这两行（但注释掉更安全，便于回溯）

3. 为什么这么做？因为RT-Thread Nano在它的board.c或drv_common.c文件里，会重新实现这两个中断处理函数rt_hw_tick_isr()和rt_hw_context_switch()（或类似函数），它们内部会调用SysTick_Handler和PendSV_Handler。如果我们不注释掉启动文件中的弱定义，链接器可能会链接到启动文件中这个空的弱符号，导致RT-Thread的中断服务程序永远不会被调用，系统自然无法调度。

其次，检查堆栈大小。在启动文件的开头，你会看到类似下面的汇编常量定义：

Stack_Size EQU 0x00000400 Heap_Size EQU 0x00000200

这里的Stack_Size是单片机**主栈（MSP）**的大小，用于中断上下文和内核初始化。Heap_Size是标准C库（如malloc/free）使用的堆大小。请注意：这个Heap_Size和我们在CubeMX里为RT-Thread配置的Heap Size（动态内存堆）是两回事！RT-Thread Nano有自己的内存管理，通常不使用这个由启动文件定义的堆。为了节省RAM，我们可以将启动文件中的Heap_Size设得很小（如0x200），甚至为0。而Stack_Size建议保持一定大小（如0x400），因为中断发生时使用的是主栈。

RT-Thread Nano线程运行时使用的是各自的线程栈，这部分内存是从我们配置的RT-Thread堆（Heap Size）里分配的。因此，整个系统的内存布局是：主栈（启动文件定义） + C库堆（启动文件定义，通常不用） + RT-Thread堆（CubeMX配置） + 全局/静态变量。

3.3 编写第一个应用线程：让LED闪烁

现在，硬件和内核都已就绪，是时候创建我们的第一个线程了。我们不建议将代码写在CubeMX生成的main.c的main函数里，而是新建一个应用文件，例如app.c。

在app.c中，我们首先包含必要的头文件：

#include "rtthread.h" #include "main.h" // 包含HAL库和GPIO引脚定义 #include "gpio.h"

然后，定义线程控制块和线程栈。线程控制块是一个结构体，内核用它来管理线程；线程栈是线程运行时保存局部变量、函数调用地址等信息的私有内存区域。

/* 定义线程控制块指针 */ static rt_thread_t led_thread = RT_NULL; /* 定义线程栈 */ ALIGN(RT_ALIGN_SIZE) // 栈地址对齐 static rt_uint8_t led_thread_stack[256]; // 为线程分配256字节的栈空间

栈大小256字节对于这个简单的闪烁任务足够了。如果线程内部函数调用层次深、局部变量多，需要加大。

接着，编写线程入口函数。这是一个永不返回的函数，通常包含一个无限循环。

/* 线程入口函数 */ static void led_thread_entry(void *parameter) { while (1) { HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin); // 翻转LED引脚电平 rt_thread_mdelay(500); // 睡眠500毫秒，让出CPU控制权 } }

注意，我们使用rt_thread_mdelay(500)而不是HAL_Delay(500)。这是关键区别！HAL_Delay是忙等待，会阻塞CPU；而rt_thread_mdelay是RT-Thread提供的睡眠函数，它会让当前线程挂起，进入阻塞状态，同时调度器会切换到其他就绪的线程去执行，极大地提高了CPU利用率。

最后，在main.c的main函数中，在MX_RT_Thread_Init()（这是CubeMX生成的RT-Thread初始化函数）调用之后，创建并启动这个线程。

int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_RT_Thread_Init(); // RT-Thread内核初始化 /* 创建LED线程 */ led_thread = rt_thread_create("led", // 线程名字 led_thread_entry, // 入口函数 RT_NULL, // 入口函数参数 sizeof(led_thread_stack), // 栈大小 10, // 线程优先级，数字越小优先级越高 20); // 线程时间片，单位是tick（时钟节拍） /* 如果创建成功，启动线程 */ if (led_thread != RT_NULL) { rt_thread_startup(led_thread); } else { // 线程创建失败处理（例如点亮另一个错误LED） } /* 启动RT-Thread调度器 */ rt_system_scheduler_start(); /* 调度器启动后不会返回 */ while (1) { } }

这里有几个参数需要理解：

• 线程优先级 (10)： 优先级数字越小，优先级越高。0通常保留给空闲线程。我们可以设置LED线程为一个较低的优先级（如10）。
• 线程时间片 (20)： 当多个线程优先级相同时，调度器会采用时间片轮转调度。每个线程运行完指定的时间片（这里是20个tick，即20ms）后，如果还没主动让出CPU，会被强制切换。对于我们的例子，只有一个用户线程，这个参数作用不大。

rt_thread_startup函数会将线程状态设置为就绪态，并放入就绪队列。rt_system_scheduler_start()则会启动调度器，从此RT-Thread开始接管系统的调度权，main函数本身会变成一个优先级最低的“后台线程”。

4. 编译、下载与调试：验证最小系统运行

点击Keil的“Rebuild”按钮编译工程。如果一切配置正确，应该能编译通过，并且可以在下方的“Build Output”窗口看到编译信息，重点关注代码（Code）和只读数据（RO Data）的大小，以及RAM（RW Data + ZI Data）的使用情况。

将编译生成的.axf或.hex文件下载到你的STM32开发板。如果LED开始以1秒的周期（亮500ms，灭500ms）闪烁，那么恭喜你，RT-Thread Nano最小系统已经成功运行！

4.1 可能遇到的坑与排查手段

然而，现实往往不会一帆风顺。以下是几个常见的启动失败场景和排查思路：

1. 程序下载后无反应，LED不亮：

   • 检查时钟配置： 这是头号嫌疑犯。用示波器或逻辑分析仪测量主时钟（MCO引脚输出）或某个定时器输出的PWM信号，看频率是否正确。或者，在SystemClock_Config函数里，在设置完时钟后，通过一个GPIO翻转来简单测试。
   • 检查中断向量表： 确认启动文件修改正确，SysTick_Handler和PendSV_Handler已被注释。一个检查方法是，在RT-Thread的board.c文件中找到rt_hw_tick_isr函数，在里面加一句GPIO翻转操作，下载运行后用示波器看是否有波形。如果没有，说明SysTick中断没进来。
   • 堆栈溢出： 这是RTOS调试中最常见的问题之一。线程栈分配不足，会导致内存越界，破坏其他数据，最终导致硬件错误（HardFault）。你可以将线程栈适当调大（如从256改为512），看是否解决问题。更专业的做法是使用RT-Thread提供的rt_threadshell命令（如果使能了FinSH）来查看线程栈使用情况，或者在rt_hw_hard_fault_exception函数中设置断点，当发生HardFault时停下来，查看调用栈和内存。

2. LED闪烁频率不对：

   • 检查RT_TICK_PER_SECOND： 在rtconfig.h（通常由CubeMX生成或需要手动从RT-Thread源码复制）中，定义了RT_TICK_PER_SECOND，它必须和CubeMX中配置的Tick值一致。默认是1000，即1ms一个tick。如果你的rt_thread_mdelay(500)延时了5秒，那可能是这里配置成了100。
   • 检查SysTick重装载值： RT-Thread初始化时会根据RT_TICK_PER_SECOND和系统时钟频率重新配置SysTick定时器。确保系统时钟频率（如72MHz）的宏定义（SystemCoreClock）是正确的。这个值通常在system_stm32f1xx.c中定义，并由SystemClock_Config函数更新。

3. 创建第二个线程后系统卡死：

   • 检查RT-Thread堆大小： 这是最可能的原因。每个线程控制块和线程栈都从RT-Thread堆中分配。在CubeMX中配置的Heap Size可能不够。假设你创建了两个线程，每个线程栈256字节，加上线程控制块和一些内核对象，可能就需要1KB以上。如果堆大小只配置了1024字节，分配完可能就所剩无几，导致后续内存分配失败。务必在rtconfig.h或CubeMX配置中增大RT_HEAP_SIZE。
   • 检查线程优先级： 确保没有两个线程被设置为相同的、且非常高的优先级，并且都不主动让出CPU（即都不调用rt_thread_delay、rt_sem_take等阻塞函数）。这会导致高优先级线程一直运行，低优先级线程永远得不到执行，看起来像卡死。合理的做法是，高优先级线程执行完关键任务后应主动延时或等待事件。

4.2 进阶裁剪：让工程变得更小

现在工程已经运行，但你可能对编译出的体积还不满意。我们可以进行更深度的裁剪，进一步压缩ROM和RAM占用。

• 裁剪内核功能： 在rtconfig.h文件中，有一大批以RT_USING_开头的宏定义。例如：

  • RT_USING_SEMAPHORE: 信号量。如果你的应用只有线程延时，没有同步通信需求，可以关闭。
  • RT_USING_MUTEX: 互斥锁。
  • RT_USING_EVENT: 事件集。
  • RT_USING_MAILBOX/RT_USING_MESSAGEQUEUE: 邮箱/消息队列。
  • RT_USING_MEMPOOL: 内存池。
  • RT_USING_HEAP: 动态内存堆。这个不能关，否则无法创建线程。 关闭不需要的IPC（进程间通信）机制，可以显著减少代码体积。原则是：用到什么，打开什么。

• 优化编译器选项： 在Keil的“Options for Target” -> “C/C++”中，可以设置优化等级。选择“Optimization for size” (-Os) 可以最大程度优化代码大小。但要注意，高优化等级可能会调试带来一些困难（如变量被优化掉）。

• 使用--gc-sections链接选项： 在“Options for Target” -> “Linker”中，勾选“Use Memory Layout from Target Dialog”通常即可。确保“Linker”标签下的“Misc controls”里可能有--gc-sections（移除未使用的段）。这允许链接器删除未被引用的函数和数据，对于裁剪库函数特别有效。

经过一番裁剪，一个只包含线程调度、延时和信号量等基本功能的RT-Thread Nano内核，其ROM占用完全可以控制在10KB以下，RAM占用（全局变量+主栈+第一个线程栈）在3-4KB左右，这对于许多低成本STM32项目来说已经非常具有吸引力。

通过以上步骤，我们不仅成功搭建了一个可运行的RT-Thread Nano最小工程，更重要的是，我们理解了从时钟配置、内核移植、线程创建到内存管理的完整链条，以及如何根据实际需求进行裁剪和优化。这个最小工程，就是你未来所有基于RT-Thread Nano的嵌入式项目的坚实起点。