简介：一套基于GD32F303C微控制器移植UCOSIII实时操作系统的实践工程，面向嵌入式开发者和RTOS初学者，以LED闪烁任务为例，演示任务创建、优先级调度、中断管理及时间片轮转等核心机制。压缩包共164个文件，包括73个C语言源码、73个头文件、9个汇编文件、6个启动文件，以及Keil工程配置（uvproj/uvopt），整体仅1.17MB，目录层级清晰，适合按模块阅读。已有1354人学习使用。通过该工程可完整了解UCOSIII在Cortex-M4平台上的移植流程，如启动代码与堆栈内存初始化、中断向量表配置、RCC系统时钟设置，以及GPIO驱动和RTOS定时器的编写方法；还可借助Keil调试器观察任务切换过程与LED闪烁时序，为后续复杂嵌入式应用开发提供扎实的实践基础。 上周整理工作盘，又翻出一个标志性的老工程，压缩包名字就叫GD32F303C_UCOSIII.rar。这个东西说白了，就是把 Micrium 的 μC/OS-III 实时操作系统完整移植到兆易创新 GD32F303C 这颗主控上的整套工程，里面包含源码、移植层、配置文件和几个现成的测试任务。很多人看到这名字可能会觉得奇怪：GD32 不是能直接照着 STM32 的工程改吗，为什么还要单独搞一套 UCOSIII 移植？
这里我得先泼一盆冷水。GD32F303C 虽然硬件上是 Cortex-M4 内核，引脚习惯上也尽量向 ST 看齐，但它的外设库、时钟树、启动流程和中断处理细节跟 ST 有不小差别。UCOSIII 的移植恰恰就卡在这些底层细节上，不是简单改个宏定义就能跑起来的。这篇文章就把这个工程从里到外拆一遍，包括 UCOSIII 的源码结构、GD32F303C 上必须改动的文件、SysTick 和 PendSV 的中断配置、FPU 现场保存的坑，以及我在实际调试中真实踩过的几个问题。
1. 项目全貌：从压缩包名字看透整个工程
1.1 拆开命名：GD32F303C和UCOSIII分别意味着什么
先看硬件端。GD32F303C 系列用的是 Arm Cortex-M4F 内核，主频最高 120MHz，带单精度浮点运算单元（FPU）。常见子型号包括 GD32F303CBT6 和 GD32F303CCT6，分别对应 128KB 和 256KB Flash，封装都是 LQFP48，SRAM 在 32KB 到 48KB 之间。这个容量跑一个小型 RTOS 工程绰绰有余，而且它和 STM32F103 的引脚定义高度相似，很多板子可以直接换芯片，这也是这系列芯片在国产替代浪潮里特别火的原因。
再看软件端。UCOSIII 是一个可裁剪、可抢占的实时操作系统内核，和老一代 UCOSII 相比，它支持不限数量的任务、时间片轮转调度、内建信号量、互斥量、消息队列和软件定时器。任务优先级从 0 开始，数值越小优先级越高，空闲任务自动占用最低优先级。
至于.rar后缀，说明这是一整套打包工程而不是零散源码。一个合格的 UCOSIII 工程压缩包，至少应该包含三块内容：uC/CPU 移植层、uC/LIB 库、uC/OS-III 内核源码与配置。拿到手之后应该能直接编译烧录、看到 LED 或串口在跑任务，而不是还得自己东拼西凑。
1.2 这种工程在什么场景下会用到
我的判断是，这个工程主要出现在三类场景里。
第一类是产品从裸机向 RTOS 升级。比如一个设备里同时要处理按键扫描、OLED 刷新、传感器采集、串口通信、电机控制，裸机的while(1)主循环会越写越长，某个阻塞操作稍微卡一下，其他任务就被拖累。这时候把 UCOSIII 移植上去，每个功能独立成一个任务，用优先级和延时把它们调度开，实时性会好很多。
第二类是国产化替代项目。原来用 STM32F103 + UCOSII 的产品，现在要换到 GD32F303C，顺便把内核升级到 UCOSIII。这种场景特别容易踩坑，因为很多人想当然地以为把startup_stm32f103.s换成 GD32 的启动文件就完事了，结果一进 OSStart 就 HardFault。
第三类是学习或课程设计。RTOS 移植是嵌入式学习里绕不开的一关，GD32 平台比 STM32 多了一些本地化的坑，能把它调通，对中断向量、启动文件、任务切换机制的理解会上一个台阶。
2. 移植前的准备工作与架构选型
2.1 把UCOSIII源码包里的目录结构搞清楚
很多人拿到 UCOSIII 源码就懵了，文件夹一大堆，不知道哪些要拷进工程里。其实核心就三个目录，归属关系非常清晰。
uC/CPU 是 CPU 移植层，负责封装关中断、开中断、数据对齐等与内核强相关的操作。uC/LIB 是内存和字符串库，提供mem_*、str_*一类函数，避免依赖编译器自带的 C 库。uC/OS-III 是内核本体，里面又分成 Source 目录、Ports 目录和 Cfg 配置目录。Source 里是纯 C 的内核源码，基本不用动；Ports 目录下针对不同架构提供移植文件，我们要重点关注ARM-Cortex-M4/Generic子目录；Cfg 里有os_cfg.h和os_cfg_app.h，系统时钟频率、任务数量、调试功能都在这配置。
实际搭建工程时，我习惯把这些目录原样拷贝到工程的Middlewares文件夹下，然后通过 Keil 的分组管理把文件分门别类加入。这样以后升级 UCOS 版本，替换整个目录就行，不用逐个文件去核对。
2.2 基础工程模板怎么选：官方库优先
移植 RTOS 之前，必须先有一个能跑通的裸机工程。我的建议是直接用 GD32 官方固件库，而不是图省事把 STM32 的工程改过来。GD32F30x 标准外设库的 API 风格和 ST 老标准库有点像，但函数名、初始化结构体和寄存器定义都有差异，混着用会非常难受。
基础工程至少要验证两件事：一是 GPIO 能点亮一个 LED，二是串口能打印一行字符串。这两个功能看着简单，但能同时验证内核时钟是否配置正确、系统主频变量SystemCoreClock是否准确、引脚复用是否正常。我见过太多人一上来就拷贝完整工程，出了问题连是哪一层出错都分不清，所以这个前置检查不能省。
2.3 动手前必须确认的三个芯片级事实
开始移植之前，有三件和芯片强相关的事实必须搞清楚，否则后面写代码就是猜。
第一，内核和中断向量。GD32F303C 是 Cortex-M4，SysTick 和 PendSV 都是内核级异常，中断编号在 CMSIS 库里分别是SysTick_IRQn和PendSV_IRQn。UCOSIII 的任务切换完全依赖 PendSV，这个不要搞错。
第二，FPU 是否启用。Cortex-M4F 带 FPU，如果任务里有浮点运算，这就涉及上下文切换时是否保存 FPU 寄存器。需要提前想好，别等代码里写了个float变量之后才满世界找问题。
第三，时钟树。GD32F303C 最高主频 120MHz，外部晶振常见 8MHz，PLL 倍频倍数和 STM32F103 的 72MHz 方案不一样。系统初始化函数SystemInit()会在启动文件中被调用，但前提是你用的是 GD32 自带的system_gd32f30x.c。SysTick 的时钟源也要确认是挂在 AHB 上，否则SysTick_Config()计算的装载值就不对。
3. 移植全过程实录
3.1 需要手工介入的两类文件
UCOSIII 的大多数源码是不用改的，可以直接拷贝进工程。真正需要手工介入的只有两类：CPU 移植层文件和应用配置文件。
第一类是 CPU 移植层，最常见的是os_cpu_c.c、os_cpu_a.asm和os_cpu.h。Cortex-M4 的移植文件和 Cortex-M3 的有很多相似之处，但 FPU 的处理差异很大，建议直接用 UCOS 官方移植包中ARM-Cortex-M4/Generic目录下的文件，不要拿 M3 的硬改。第二类是os_cfg.h和os_cfg_app.h，这里面定义了任务数量、时基频率、是否启用统计任务等选项。
工程文件分组可以这样排：
| 分组 | 包含文件 | 说明 |
|---|---|---|
| UCOS-CORE | os_core.c、os_task.c、os_time.c等 | 内核本体，一般不动 |
| UCOS-CPU | cpu_core.c、cpu_c.c、cpu_a.asm | CPU 移植层 |
| UCOS-PORT | os_cpu_c.c、os_cpu_a.asm | 内核与 CPU 之间的桥接 |
| UCOS-CONFIG | os_cfg.h、os_cfg_app.h | 系统配置 |
| BSP | bsp.c、usart.c、gpio.c | 板级支持 |
3.2 中断与时钟：最关键的几行配置
这里要强调一个原则：SysTick 和 PendSV 的抢占优先级必须是最低的。这么做的原因很简单，PendSV 会被我们主动触发，用来在中断结束后执行任务切换，如果它的优先级比某个外设中断高，那这个外设中断就可能被任务切换打断，破坏临界区保护，这是不允许的。
先配置优先级分组，我习惯用 GD32 库接口写成全抢占模式：
nvic_priority_group_set(NVIC_PRIGROUP_4);然后给两个内核异常设置最低优先级。GD32F303C 的 NVIC 只有 4 位优先级，所以最低优先级是 15：
NVIC_SetPriority(PendSV_IRQn, 15); NVIC_SetPriority(SysTick_IRQn, 15);接着配置 SysTick 作为 UCOSIII 的时基。UCOSIII 的os_cfg_app.h里有一个OS_CFG_TICK_RATE_HZ，常见的值是 1000，也就是 1ms 一个 tick。SysTick 的重装载值就是系统主频除以这个频率：
SysTick_Config(SystemCoreClock / OS_CFG_TICK_RATE_HZ);如果SystemCoreClock是 120000000，那么重装载值就是 120000，也就是每 1ms 进一次 SysTick 中断。这里要提醒一句，GD32 固件库里的systick_config()函数是给裸机延时用的，它会在内部使能 SysTick 并占用这个中断。在 RTOS 工程里绝对不能调用它，否则和 UCOSIII 的时基冲突，任务调度会立刻乱套。
3.3 任务的创建与启动流程
UCOSIII 的启动流程很固定，就是 OSInit 初始化内核、创建任务、OSStart 启动调度器。一个最小可运行的任务模板长这样：
#include "gd32f30x.h" #include "includes.h" #define TASK1_STK_SIZE 512u #define TASK2_STK_SIZE 512u static CPU_STK task1_stk[TASK1_STK_SIZE]; static CPU_STK task2_stk[TASK2_STK_SIZE]; static OS_TCB task1_tcb; static OS_TCB task2_tcb; static void task1(void *p_arg) { (void)p_arg; while (DEF_TRUE) { gpio_bit_set(GPIOC, GPIO_PIN_13); OSTimeDlyHMSM(0, 0, 0, 200); gpio_bit_reset(GPIOC, GPIO_PIN_13); OSTimeDlyHMSM(0, 0, 0, 200); } } static void task2(void *p_arg) { (void)p_arg; while (DEF_TRUE) { printf("task2 running\\r\\n"); OSTimeDlyHMSM(0, 0, 1, 0); } } int main(void) { OS_ERR err; bsp_init(); OSInit(&err); OSTaskCreate(&task1_tcb, "task1", task1, 0, 3, task1_stk, TASK1_STK_SIZE, 0, 0, 0, OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR, &err); OSTaskCreate(&task2_tcb, "task2", task2, 0, 4, task2_stk, TASK2_STK_SIZE, 0, 0, 0, OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR, &err); OSStart(&err); }任务栈大小的选择，这里有几个实操规律可以分享。任务栈单位是 4 字节，512 就是 2KB。没有浮点运算的任务，512 起步基本够用；有浮点运算、调用打印函数、操作文件系统这种深调用任务，建议先给 1024，跑一段时间后用OS_TaskStkChk()查看实际水位再往下压。不要一开始就给得很小，然后做各种极限裁剪，RTOS 跑挂一大半是栈溢出。
3.4 如果你要用浮点运算：FPU的移植处理
GD32F303C 是带硬件浮点单元的，用得好是福利，用不好是陷阱。UCOSIII 在 Cortex-M4 带 FPU 的移植层里专门提供了一个开关，叫OS_CPU_ARM_FPU_EN，在os_cpu.h里定义成 1 才能让任务切换时保存 FPU 的寄存器现场。
同时，编译器的宏定义也要跟上。在 Keil 里，如果使用 MDK-ARM 工具链，需要确认 Target 选项里的 Floating Point Hardware 选为 Single Precision；在 C/C++ 的预处理宏里加上__FPU_PRESENT=1和__FPU_USED=1。这两个宏会让底层库知道当前内核带 FPU，从而在启动时使能 FPU 单元。
还有一个容易被忽略的点：Cortex-M4 的 AAPCS 调用约定要求栈按 8 字节对齐，而 FPU 的lazy stacking特性会在中断压栈时多保存 FPSCR 和 S16-S31 寄存器，也就是额外占约 104 字节。任务栈如果没预留这部分空间，第一个浮点运算任务调用OSTimeDly让出 CPU 的时候，大概率直接触发 HardFault。这也是为什么我建议浮点任务栈直接给 1024 的原因。
4. 常见问题与排查技巧实录
4.1 启动阶段HardFault的三种典型原因
UCOSIII 移植过程中，最容易崩溃的是 OSStart 前后这一段，而 HardFault 的原因基本集中在三个地方。
第一种是启动文件的栈开得太小。很多 GD32 官方例程为了精简，启动文件里Stack_Size只给了 0x400，也就是 1KB。RTOS 启动后，特权模式和中断处理都用 MSP，栈小了很容易在第一个任务调度时溢出。我把这个值直接改成 0x1000，也就是 4KB，反正 SRAM 足够，留足余量。
第二种是任务栈没有 8 字节对齐。CPU_STK数组默认就是按 4 字节对齐的，但如果你在某个 2 字节对齐的局部结构体后声明任务栈，就可能破坏对齐。保险的做法是在声明任务栈时用__ALIGNED(8)修饰，或者干脆把任务栈放到文件作用域，让编译器自己按最严格对齐处理。
第三种是 FPU 的宏没有统一。编译器认为没有 FPU，而移植层又启用了OS_CPU_ARM_FPU_EN，这种不一致会导致启动时 FPU 扩展寄存器区域的访问异常。排查方法也很简单，把所有涉及 FPU 的宏统一成一套配置即可。
4.2 任务不切换、串口乱码怎么定位
任务能创建但就是不切换，先别急着怀疑调度器有问题。我从自己的项目里总结了一个由快到慢的排查顺序。
第一步，看 SysTick 中断有没有触发。在SysTick_Handler里打个断点，如果完全不进，说明中断没有使能或时基配置有问题。第二步，看 PendSV 有没有被触发。UCOSIII 的时基中断会调用OS_CPU_SysTickHandler()，然后触发 PendSV 进行任务切换，如果这里没动作，大概率是os_cpu_a.asm中的 PendSV 入口没有被链接到启动文件的向量表。
第三步是检查串口乱码。这个现象通常不是通信问题，而是时钟配置错了。如果SystemCoreClock值和实际 PLL 输出不一致，不仅 SysTick 的延时时间不准，串口波特率也会偏，打印出来全是乱码。解决方法是确认system_gd32f30x.c里的__SYSTEM_CLOCK宏是否和板载晶振匹配。
4.3 调试器辅助确认栈与优先级
最后说一个我特别常用的调试方法，虽然朴素，但非常有效。在任务切换后，打开调试器的寄存器窗口，观察当前使用的是 PSP 还是 MSP。任务正常运行时，应该使用 PSP；中断或异常处理时，使用 MSP。如果发现任务凭空消失或者反复进入 HardFault，可以先查看 PSP 的值是否落在对应任务栈的StkBasePtr和StkLimitPtr范围内。不在范围内，十有八九是栈越界。
优先级方面也有个可以自查的小技巧。把 SysTick 和 PendSV 的优先级全部设置成 15 之后，可以用一个外设中断（比如串口中断）把优先级故意设成 0。如果任务在串口收发时出现卡死，说明你这个外设中断在不断抢占内核调度，导致任务切换时机被无限延后。这时候不是去改调度器，而是应该审视自己的中断服务函数是否做了太多事情，把耗时处理挪到任务里。
我个人的习惯是，拿到一个新硬件平台，会先写一个最简单的双任务点灯工程，每个任务只管翻转 LED，一个用 500ms 周期，另一个用 300ms 周期。确认两个 LED 能以不同节奏闪烁后，再逐步加串口、加信号量、加浮点运算。这个慢速起步的过程看起来很基础，但能帮你把每一个硬件相关的问题隔离在最干净的场景里，排查效率远高于等一个大型应用工程跑挂了再回头找原因。
本文还有配套的精品资源，点击获取
