danielomg22212/freertos-noteshttps://github.com/danielomg22212/freertos-notes

完整版本点击链接 https://github.com/danielomg22212/freertos-notes

FreeRTOS笔记：核心概念、API用法、查找方法与避坑

这不是一份普通的 FreeRTOS 笔记，而是一份面向真实嵌入式开发场景整理的 RTOS 学习与实战手册。

它从任务调度、队列、信号量、互斥量、事件组、软件定时器、任务通知等核心机制出发，把 FreeRTOS 最常用、最容易踩坑、最值得掌握的内容系统串起来，并结合 CubeMX、CMSIS-RTOS、原生 FreeRTOS API、中断 FromISR 规则、栈/堆排查、HardFault 调试等实际开发问题进行整理。

这份笔记的目标不是让你“看过 FreeRTOS”，而是帮助你真正建立 RTOS 工程思维：知道什么时候该用任务，什么时候该用队列，什么时候该用信号量或互斥量，如何让中断和任务正确协作，如何定位任务不运行、队列收不到、栈溢出、内存不足等常见问题。

适合嵌入式初学者系统入门，也适合已经写过裸机程序、准备转向 RTOS 项目开发的同学作为长期查阅手册，由经验丰富的工程师编写。

笔记不是简单堆 API，而是按“核心概念 -> 使用场景 -> 常用函数 -> 代码示例 -> 排错思路”的方式整理，适合用于快速入门、复习回顾和实际项目开发时查阅。

本文基于原有 FreeRTOS 笔记重新整理，由danielomg22212编写，目标不是堆资料，而是帮助初学者快速建立下面几种能力：

1. 知道 FreeRTOS 各组件解决什么问题。
2. 知道任务、队列、信号量、互斥量、事件组、定时器该怎么选。
3. 看懂常用 API 的函数原型和参数。
4. 在没有 AI 帮助时，能自己查函数、查配置、查字段、查源码。
5. 避开 STM32 + CubeMX + FreeRTOS 开发中最常见的坑。

1. FreeRTOS 最核心总纲

FreeRTOS 是一个实时操作系统内核。它主要帮你解决：

多个任务如何并发运行。
任务之间如何通信。
任务之间如何同步。
共享资源如何保护。
定时任务如何执行。
中断和任务如何协作。
系统内存、栈、优先级如何管理。

最重要的对象：

对象	解决什么问题	常见 API
Task 任务	把程序拆成多个并发执行的函数	xTaskCreate()、vTaskDelay()
Queue 队列	任务之间传数据	xQueueCreate()、xQueueSend()、xQueueReceive()
Semaphore 信号量	同步事件、计数资源	xSemaphoreGive()、xSemaphoreTake()
Mutex 互斥量	保护共享资源	xSemaphoreCreateMutex()
Event Group 事件组	等待多个事件组合	xEventGroupSetBits()、xEventGroupWaitBits()
Software Timer 软件定时器	延时后执行回调或周期执行回调	xTimerCreate()、xTimerStart()
Task Notification 任务通知	轻量级任务同步/计数/事件	xTaskNotifyGive()、ulTaskNotifyTake()

最关键选择公式：

要并发执行一段逻辑，用 Task。
要传结构化数据，用 Queue。
只通知“发生了某件事”，优先用 Task Notification 或 Binary Semaphore。
要保护共享资源，用 Mutex。
要等待多个条件组合，用 Event Group。
要周期或延时触发轻量回调，用 Software Timer。
中断里通知任务，用 FromISR 版本 API。

2. FreeRTOS 的运行模型

2.1 任务不是进程

在 MCU 上使用 FreeRTOS 时，任务之间通常共享同一个地址空间。

这意味着：

全局变量所有任务都能访问。
多个任务同时访问同一个全局变量会产生竞争。
中断和任务同时访问同一个变量也会产生竞争。

所以原笔记里的提醒非常重要：

RTOS 下全局变量要谨慎使用。
共享变量必须考虑互斥、临界区、volatile、队列或事件同步。

常见错误：

int flag = 0;

void TaskA(void *arg)
{
    while (1) {
        if (flag) {
            // do something
            flag = 0;
        }
    }
}

void TaskB(void *arg)
{
    flag = 1;
}

更好的做法：

任务间传数据：用 Queue。
任务间通知事件：用 Task Notification / Semaphore / Event Group。
共享外设：用 Mutex。
短时间保护变量：用 Critical Section。

2.2 任务状态

任务常见状态：

Running   正在运行
Ready     就绪，等 CPU
Blocked   阻塞，等待时间、队列、信号量、事件
Suspended 挂起，不参与调度
Deleted   删除

常见状态变化：

vTaskDelay()             Running -> Blocked
xQueueReceive(... wait)  Running -> Blocked
xSemaphoreTake(... wait) Running -> Blocked
vTaskSuspend()           任意状态 -> Suspended
vTaskResume()            Suspended -> Ready

2.3 优先级

FreeRTOS 中：

优先级数值越大，优先级越高。

例如：

#define TASK_LOW_PRIO   1
#define TASK_MID_PRIO   3
#define TASK_HIGH_PRIO  5

调度原则：

高优先级 Ready 任务会优先运行。
同优先级任务一般按时间片轮转。
低优先级任务只有在高优先级任务阻塞或让出 CPU 时才运行。

初学者常见优先级建议：

中断后处理任务：较高优先级。
控制循环任务：中高优先级。
通信解析任务：中等优先级。
日志/显示任务：低优先级。
空闲统计/后台任务：低优先级。

3. CubeMX 配置重点

3.1 CubeMX FreeRTOS 页面

原笔记截图：CubeMX 中 FreeRTOS 的主要配置入口。

常见配置项：

配置项	作用
Tasks and Queues	创建任务和队列
Timers and Semaphores	创建软件定时器、信号量
Mutexes	创建互斥量
Events	创建事件组
FreeRTOS Heap Usage	查看堆使用
Config Parameters	内核参数
Include Parameters	API 功能裁剪
Advanced Settings	代码生成方式