设计文档：尚硅谷 FreeRTOS 笔记重构计划
日期：2026-07-17
来源：尚硅谷嵌入式技术之FreeRTOS实时操作系统 V1.0.3
目标目录：raw/Joplin/嵌入式+Linux/FreeRTOS学习笔记/
目标芯片：STM32F103ZET6（Cortex-M3）
参考设计：docs/superpowers/specs/2026-07-15-stm32-silicon-valley-ingest-design.md
工作流参考：docs/如何将他人文档整理为LLM-Wiki笔记.md
1. 笔记分篇（共 16 篇）
总览
| # | 文件名 | 对应课程章节 | 配套代码项目 |
| -- | ------ | ----------- | ----------- |
| 01 | 01-实时操作系统基础.md | 第 1 章（操作系统介绍 + FreeRTOS 简介） | — |
| 02 | 02-任务调度与状态管理.md | 第 2 章（多任务/调度策略/任务状态/滴答/上下文切换/空闲任务） | — |
| 03 | 03-FreeRTOS移植指南.md | 第 3 章（源码结构 + HAL 移植 + 寄存器移植 + 配置文件说明） | 00_HAL_Key |
| 04 | 04-数据类型命名与配置详解.md | 第 3 章后半（数据类型/命名规范/FreeRTOSConfig.h 全项） | — |
| 05 | 05-任务创建与删除.md | 第 4 章（动态创建 + 静态创建 + 删除） | 01, 02 |
| 06 | 06-任务挂起与恢复.md | 第 5 章（单任务挂起/恢复 + 调度器挂起/恢复） | 03 |
| 07 | 07-中断管理与临界段.md | 第 6 章（临界区/BASEPRI/中断安全 API/延迟中断处理） | 04 |
| 08 | 08-时间片调度与延时管理.md | 第 7 章 + 第 9 章（时间片/vTaskDelay/vTaskDelayUntil） | 05, 08 |
| 09 | 09-任务状态查询与运行时统计.md | 第 8 章（状态查询 API/vTaskList/vTaskGetRunTimeStats） | 06, 07 |
| 10 | 10-消息队列.md | 第 10 章（队列创建/发送/接收/多队列） | 09 |
| 11 | 11-信号量机制.md | 第 11 章（二值信号量/计数型/优先级翻转/互斥信号量） | 10, 11, 12, 13 |
| 12 | 12-队列集.md | 第 12 章（队列集创建/添加/选择读取） | 14 |
| 13 | 13-事件标志组.md | 第 13 章（事件组创建/置位/等待） | 15 |
| 14 | 14-任务通知.md | 第 14 章（通知模拟信号量/消息队列/事件标志组三种模式） | 16, 17, 18 |
| 15 | 15-软件定时器与Tickless低功耗.md | 第 15 章 + 第 16 章（定时器/一次性/周期/Tickless 模式） | 19, 20 |
| 16 | 16-内存管理.md | 第 17 章（heap_1~5 算法/pvPortMalloc/vPortFree/xPortGetFreeHeapSize） | 21 |
分篇依据
- 每篇对应课程中一个独立概念群，确保每篇可独立阅读
- 代码项目按功能归属分配到对应笔记
- 以"介绍 → 工作原理 → API → 实验 → 速查表 → 避坑"结构组织
2. 每篇笔记模板
统一的 Markdown 模板，参考 STM32 笔记格式：
---
tags: [source-summary]
type: source
source: "尚硅谷嵌入式技术之FreeRTOS实时操作系统 V1.0.3 — {对应课程章节}"
author: "尚硅谷研究院"
date: 2026-07-17
created: 2026-07-17
---
# {主题名称}
> **用生活理解**：{一句话类比，用生活中的例子解释}
## {概念}介绍
### 基本概念
{是什么、有什么用、解决什么问题}
### 工作原理
{框图说明 + 文字描述}
> 参考：FreeRTOS 官方文档 §X.X
### 核心 API
| 函数 | 参数 | 功能简述 |
| ---- | ---- | -------- |
| xxx | ... | ... |
## {实验/案例}
### 需求描述
{实验要实现的功能}
### 软件设计
**文件：{代码项目相对路径}/Core/Src/freertos_demo.c**
c
// 核心代码段，直接从项目复制，保留完整函数
// 每行 API 调用标注通俗解释
### 关键配置
c
// FreeRTOSConfig.h 中本实验特有的配置项
## 核心函数速查表
| 函数 | 参数 | 返回值 | 功能简述 |
| ---- | ---- | ------ | -------- |
| xxx | ... | ... | ... |
## 常见问题与避坑
硬性要求
- Frontmatter：必须包含
tags: [source-summary], type: source, source, author, date, created
- 通俗类比：每篇开头必须有一句
> **用生活理解**：，用生活场景类比技术概念
- 代码注释：代码中每行 API 调用必须有中文注释说明其作用；保留
// 按位或: 保持其他位不变 这类位操作注释（如有）
- 文件标注：每段代码前标注来源文件路径（相对于 FreeRTOS 学习笔记根目录或外部源码目录）
- API 速查表：每篇结尾汇总本笔记涉及的 API 函数
- 常见问题：每篇结尾必须有"常见问题与避坑"章节
3. 代码策略
3.1 代码来源
所有代码示例直接来源于F:\Baidu\尚硅谷\尚硅谷嵌入式技术之FreeRTOS实时操作系统\03_代码\下的 22 个 Keil 项目（编号 00~21）。
3.2 提取规则
- 核心演示代码从
Core/Src/freertos_demo.c 提取
- 保留完整函数体，不打断逻辑
- 删除重复的模板代码（
start_task 骨架在不同项目中几乎一致，在 05 笔记中完整展示一次即可，后续笔记中简写）
- 删除 HAL 初始化骨架（
main.c 中的 HAL_Init(), SystemClock_Config(), MX_GPIO_Init() 等，与 FreeRTOS 无关）
FreeRTOSConfig.h 中与本实验特殊相关的配置项（非通用基线）必须在笔记中说明
3.3 通用模板代码简化
所有项目共有的 start_task → taskENTER_CRITICAL() → 创建工作任务的模式，在 05 笔记完整展示后，从 06 起可简写为：
// 创建工作任务的代码与 05 笔记相同，此处省略
// 完整模板见 05-任务创建与删除.md
3.4 代码路径引用格式
**代码来源**：`03_代码/09_消息队列/Core/Src/freertos_demo.c`
4. 图片策略
4.1 源图片
原始笔记 F:\Baidu\尚硅谷\尚硅谷嵌入式技术之FreeRTOS实时操作系统\01_笔记\images\media\ 包含 48 张 PNG 图片（image1.png ~ image48.png）。
4.2 筛选标准
| 保留 |
删除 |
| 调度策略对比图 |
IDE 安装/配置截图 |
| 任务状态转换图 |
Keil 工程添加文件步骤截图 |
| 就绪列表位图 |
CubeMX 配置截图 |
| 上下文切换流程 |
下载链接/官网页面截图 |
| 队列结构图 |
文件目录结构截图（源码结构等可文字描述） |
| 信号量机制图 |
选项框勾选截图 |
| 优先级反转时序 |
数值/文字设置截图 |
| 事件组位结构图 |
代码编辑界面截图（代码已在正文中） |
| heap 算法对比 |
与 FreeRTOS 功能无关的配图 |
| 定时器状态机 |
|
4.3 重命名规则
- 全部小写英文蛇形命名：
{主题}_{内容}.png
- 示例：
task_state_diagram.png, scheduling_preemption_vs_cooperative.png
- 映射表在实现计划中详细列出
4.4 存放位置
精选后的图片存放在 raw/Joplin/嵌入式+Linux/FreeRTOS学习笔记/assets/，笔记内用相对路径引用：
5. 每篇笔记内容大纲
01-实时操作系统基础.md
| 章节 |
内容概要 |
| 基本概念 |
裸机开发的局限性、OS vs 裸机、通用 OS vs RTOS |
| 工作原理 |
计算机系统三层模型（硬件/OS/应用） |
| FreeRTOS简介 |
发展历史（2003→2017 AWS收购）、特点、优势 |
| 核心API |
— |
| 速查表 |
— |
| 常见问题 |
开源≠免费？RTOS 与 Linux 的区别 |
02-任务调度与状态管理.md
| 章节 |
内容概要 |
| 基本概念 |
任务、内核、多任务处理 |
| 工作原理 |
调度策略（抢占式/时间片/协程式）、4 种任务状态（运行/就绪/阻塞/挂起）、就绪列表位图、滴答计数器、上下文切换流程 |
| 空闲任务 |
自动创建、作用（释放内存/计数/低功耗） |
| 核心API |
— |
| 速查表 |
— |
| 常见问题 |
阻塞 vs 挂起本质区别、时间片提前结束条件 |
03-FreeRTOS移植指南.md
| 章节 |
内容概要 |
| 源码结构 |
FreeRTOS/FreeRTOS-Plus/Tools，Source 目录 7 个 .c + include + portable |
| HAL库移植 |
目录添加源码、Keil 工程添加 Group、FreeRTOSConfig.h 修改（xPortPendSVHandler/vPortSVCHandler）、stm32f1xx_it.c 修改（SVC/PendSV 注释、SysTick 回调） |
| 寄存器移植 |
同上 + main.c 添加 SysTick_Handler |
| 配置文件说明 |
三类配置项：INCLUDE_、config开头、其他 |
| 移植检查清单 |
关键步骤核对表 |
| 常见问题 |
HAL+SysTick 冲突、卡死排查 |
04-数据类型命名与配置详解.md
| 章节 |
内容概要 |
| 数据类型 |
TickType_t/BaseType_t/StackType_t 等定义与场景 |
| 命名规范 |
前缀规则（v/x/ux/pv/h等）、函数命名、宏命名、数据类型命名 |
| FreeRTOSConfig.h |
全部配置项分组说明（基础/内存/钩子/时间片/中断/函数使能）带推荐值 |
| 速查表 |
数据类型、命名前缀对照表 |
| 常见问题 |
config 值设置不当的后果 |
05-任务创建与删除.md
| 章节 |
内容概要 |
| 基本概念 |
任务控制块 TCB、任务堆栈、任务句柄 |
| 工作原理 |
xTaskCreate 动态分配 vs xTaskCreateStatic 静态分配 |
| 核心API |
xTaskCreate/xTaskCreateStatic/vTaskDelete |
| 实验1 |
动态创建 3 个任务，task3 按键删除 task1（项目 01） |
| 实验2 |
静态创建 3 个任务（项目 02），涉及 vApplicationGetIdleTaskMemory/TimerTaskMemory |
| 关键配置 |
configSUPPORT_STATIC_ALLOCATION=1 |
| 速查表 |
创建/删除 API |
| 常见问题 |
删除后句柄置 NULL 的重要性 |
06-任务挂起与恢复.md
| 章节 |
内容概要 |
| 基本概念 |
挂起态本质（暂停，不参与调度） |
| 核心API |
vTaskSuspend/vTaskResume/vTaskSuspendAll/xTaskResumeAll/vTaskList |
| 实验 |
4 个按键控制：挂起/恢复单任务、挂起/恢复调度器（项目 03） |
| 速查表 |
挂起/恢复 API |
| 常见问题 |
挂起 vs 阻塞 vs 删除深度对比 |
07-中断管理与临界段.md
| 章节 |
内容概要 |
| 基本概念 |
Cortex-M 中断优先级、BASEPRI 寄存器 |
| 工作原理 |
临界区（taskENTER_CRITICAL/EXIT_CRITICAL）、中断安全 API（FromISR 后缀）、延迟中断处理（PendSV） |
| 核心API |
taskENTER_CRITICAL/taskEXIT_CRITICAL/portDISABLE_INTERRUPTS/portENABLE_INTERRUPTS |
| 实验 |
KEY1 禁用中断、KEY2 启用中断（项目 04） |
| 关键配置 |
configMAX_SYSCALL_INTERRUPT_PRIORITY |
| 速查表 |
中断管理 API |
| 常见问题 |
临界区内不要调用阻塞 API |
08-时间片调度与延时管理.md
| 章节 |
内容概要 |
| 基本概念 |
时间片轮转调度、相对延时 vs 绝对延时 |
| 工作原理 |
同等优先级任务轮流执行一个时间片、vTaskDelay 漂移问题、vTaskDelayUntil 固定周期 |
| 核心API |
vTaskDelay/vTaskDelayUntil/xTaskGetTickCount |
| 实验1 |
同优先级 2 个任务时间片轮转（项目 05），临界区保护临界段 |
| 实验2 |
vTaskDelay vs vTaskDelayUntil 对比（项目 08） |
| 关键配置 |
configUSE_TIME_SLICING、configTICK_RATE_HZ |
| 速查表 |
时间管理 API |
| 常见问题 |
vTaskDelayUntil 必须使用 while(1) 开头获取 tick |
09-任务状态查询与运行时统计.md
| 章节 |
内容概要 |
| 基本概念 |
任务运行时信息、堆栈余量 |
| 核心API |
uxTaskPriorityGet/vTaskPrioritySet/uxTaskGetNumberOfTasks/uxTaskGetSystemState/vTaskGetInfo/xTaskGetCurrentTaskHandle/xTaskGetHandle/uxTaskGetStackHighWaterMark/eTaskGetState/vTaskList/vTaskGetRunTimeStats |
| 实验1 |
完整状态查询 API 套件一次性演示（项目 06） |
| 实验2 |
运行时统计打印（项目 07），需高精度定时器 |
| 关键配置 |
configUSE_TRACE_FACILITY、configUSE_STATS_FORMATTING_FUNCTIONS、configGENERATE_RUN_TIME_STATS |
| 速查表 |
查询/统计 API |
| 常见问题 |
运行时间统计需要额外硬件定时器 |
10-消息队列.md
| 章节 |
内容概要 |
| 基本概念 |
队列是什么（任务间数据传递的 FIFO 缓冲区）、队列长度/项大小 |
| 工作原理 |
队列内部结构（环形缓冲区/等待列表）、写时拷贝 |
| 核心API |
xQueueCreate/xQueueSend/xQueueReceive |
| 实验 |
2 个队列：queue1 传按键值、big_queue 传指针（项目 09） |
| 关键配置 |
configQUEUE_REGISTRY_SIZE |
| 速查表 |
队列 API |
| 常见问题 |
portMAX_DELAY 等待、队列满时的阻塞、消息队列与全局变量的选择 |
11-信号量机制.md
| 章节 |
内容概要 |
| 基本概念 |
信号量是"钥匙"还是"计数器"？二值/计数/互斥的区别 |
| 工作原理 |
基于队列实现、计数信号量累加、互斥信号量的优先级继承机制 |
| 核心API |
vSemaphoreCreateBinary/xSemaphoreCreateCounting/xSemaphoreCreateMutex/xSemaphoreGive/xSemaphoreTake/uxSemaphoreGetCount |
| 实验1 |
二值信号量：task1 Give → task2 Take（项目 10） |
| 实验2 |
计数信号量：KEY1 累加计数（项目 11） |
| 实验3 |
优先级反转：低优先级任务持有信号量被高优先级等待（项目 12） |
| 实验4 |
互斥信号量：优先级继承解决反转（项目 13） |
| 关键配置 |
configUSE_COUNTING_SEMAPHORES、configUSE_MUTEXES、configUSE_RECURSIVE_MUTEXES |
| 速查表 |
信号量 API |
| 常见问题 |
二值信号量与互斥量的选择、优先级反转的触发条件与解决方案 |
12-队列集.md
| 章节 |
内容概要 |
| 基本概念 |
队列集用于同时等待队列和信号量 |
| 工作原理 |
队列集内部机制：成员注册、事件通知 |
| 核心API |
xQueueCreateSet/xQueueAddToSet/xQueueSelectFromSet |
| 实验 |
队列集包含一个队列和一个二值信号量（项目 14） |
| 关键配置 |
configUSE_QUEUE_SETS=1 |
| 速查表 |
队列集 API |
| 常见问题 |
队列集中不要单独删除成员 |
13-事件标志组.md
| 章节 |
内容概要 |
| 基本概念 |
事件标志组是位的集合，任务等待特定位组合 |
| 工作原理 |
24 位可用（RTOS 保留高 8 位）、等待逻辑（AND/OR） |
| 核心API |
xEventGroupCreate/xEventGroupSetBits/xEventGroupWaitBits |
| 实验 |
KEY1 置位 BIT0、KEY2 置位 BIT1、task2 等待两个位全部置位（项目 15） |
| 速查表 |
事件标志组 API |
| 常见问题 |
等待完成后自动清除位（pdTRUE）的使用 |
14-任务通知.md
| 章节 |
内容概要 |
| 基本概念 |
任务通知是轻量级 IPC，每个 TCB 内置 32 位通知值 |
| 工作原理 |
通知值可作信号量（计数递减）/消息队列（覆写值）/事件组（置位），比独立 IPC 快 45% |
| 核心API |
xTaskNotifyGive/ulTaskNotifyTake/xTaskNotify/xTaskNotifyWait |
| 实验1 |
通知模拟信号量（项目 16） |
| 实验2 |
通知模拟消息队列（项目 17）使用 eSetValueWithOverwrite |
| 实验3 |
通知模拟事件标志组（项目 18）使用 eSetBits |
| 速查表 |
任务通知 API |
| 常见问题 |
通知不能用于 ISR 到多任务的分发、v10.4 后通知数组支持 |
15-软件定时器与Tickless低功耗.md
| 章节 |
内容概要 |
| 基本概念 |
软件定时器基于 Tick 计数、不同于硬件定时器 |
| 工作原理 |
定时器状态（休眠/运行/暂停）、一次性 vs 周期型、定时器命令队列、定时器服务任务 |
| Tickless |
低功耗模式原理、configUSE_TICKLESS_IDLE、PRE_SLEEP_PROCESSING/POST_SLEEP_PROCESSING |
| 核心API |
xTimerCreate/xTimerStart/xTimerStop（软件定时器）、configUSE_TICKLESS_IDLE（低功耗） |
| 实验1 |
一次性定时器 + 周期型定时器，按键启动/停止（项目 19） |
| 实验2 |
Tickless 模式：休眠时关闭 GPIO 时钟（项目 20） |
| 关键配置 |
configUSE_TIMERS、configTIMER_TASK_PRIORITY、configTIMER_QUEUE_LENGTH、configTIMER_TASK_STACK_DEPTH、configUSE_TICKLESS_IDLE |
| 速查表 |
定时器 API + Tickless 配置项 |
| 常见问题 |
定时器回调中不要调用阻塞 API、Tickless 模式的最小空闲时间配置 |
16-内存管理.md
| 章节 |
内容概要 |
| 基本概念 |
FreeRTOS 内存管理需求、5 种 heap 算法的设计哲学 |
| 工作原理 |
|
|
---- |
|
heap_1 |
|
heap_2 |
|
heap_3 |
|
heap_4 |
|
heap_5 |
| 核心API |
pvPortMalloc/vPortFree/xPortGetFreeHeapSize |
| 实验 |
KEY1 分配 20 字节、KEY2 释放（项目 21） |
| 关键配置 |
configTOTAL_HEAP_SIZE、configSUPPORT_DYNAMIC_ALLOCATION |
| 速查表 |
内存管理 API |
| 常见问题 |
heap 大小不足时的处理策略、碎片化监控 |
6. 目标目录结构
raw/Joplin/嵌入式+Linux/FreeRTOS学习笔记/
├── assets/ # 精选图片（预计 15~25 张）
│ ├── task_state_diagram.png
│ ├── scheduling_preemption.png
│ ├── scheduling_timeslice.png
│ ├── ready_list_bitmap.png
│ ├── ready_list_same_priority.png
│ ├── context_switch.png
│ ├── queue_structure.png
│ ├── priority_inversion.png
│ ├── priority_inheritance.png
│ ├── event_group_bits.png
│ ├── timer_states.png
│ ├── heap_comparison.png
│ └── ...（根据实际图片内容命名）
├── 01-实时操作系统基础.md
├── 02-任务调度与状态管理.md
├── 03-FreeRTOS移植指南.md
├── 04-数据类型命名与配置详解.md
├── 05-任务创建与删除.md
├── 06-任务挂起与恢复.md
├── 07-中断管理与临界段.md
├── 08-时间片调度与延时管理.md
├── 09-任务状态查询与运行时统计.md
├── 10-消息队列.md
├── 11-信号量机制.md
├── 12-队列集.md
├── 13-事件标志组.md
├── 14-任务通知.md
├── 15-软件定时器与Tickless低功耗.md
└── 16-内存管理.md
7. Wiki 更新
重构完成后必须执行的维基更新：
7.1 更新 wiki/source-freertos.md
7.2 更新 wiki/index.md
- FreeRTOS 章节保持与已有 Wiki 页面的
[[wikilink]] 连接
- 更新原始笔记路径映射
7.3 追加 wiki/log.md
- 记录本次重构操作
- 注明 11 篇旧笔记被 16 篇新笔记替代
8. 硬性约束
- 不修改
raw/ 以外的文件（Wiki 除外：source-freertos.md, index.md, log.md）
- 所有代码必须来自真实项目文件，不凭空编写代码
- 每行 API 代码必须标注通俗解释注释
- 每篇必须有通俗类比（
> **用生活理解**：）
- 图片必须经过筛选，不盲目全部复制
- 16 篇一次完成，不分批次
- 旧 11 篇笔记覆盖前先确认备份（实际已不存在，直接新建）
