# 设计文档：尚硅谷 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 笔记格式：

```markdown
---
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  | ...  | ...    | ...      |

## 常见问题与避坑
```

### 硬性要求

1. **Frontmatter**：必须包含 `tags: [source-summary]`, `type: source`, `source`, `author`, `date`, `created`
2. **通俗类比**：每篇开头必须有一句 `> **用生活理解**：`，用生活场景类比技术概念
3. **代码注释**：代码中每行 API 调用必须有中文注释说明其作用；保留 `// 按位或: 保持其他位不变` 这类位操作注释（如有）
4. **文件标注**：每段代码前标注来源文件路径（相对于 FreeRTOS 学习笔记根目录或外部源码目录）
5. **API 速查表**：每篇结尾汇总本笔记涉及的 API 函数
6. **常见问题**：每篇结尾必须有"常见问题与避坑"章节

---

## 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 起可简写为：

```c
// 创建工作任务的代码与 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/`，笔记内用相对路径引用：

```markdown
![任务状态转换图](assets/task_state_diagram.png)
```

---

## 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 | 需要线程安全 malloc | 包装 C 库函数 | 依赖编译器 |
| | heap_4 | 默认推荐 | 合并相邻空闲块 | 大块释放后碎片 |
| | heap_5 | 不连续 RAM 堆 | 跨内存区域分配 | 实现复杂 |
| 核心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`

- 笔记列表改为 16 篇新笔记
- 更新代码项目映射表

### 7.2 更新 `wiki/index.md`

- FreeRTOS 章节保持与已有 Wiki 页面的 `[[wikilink]]` 连接
- 更新原始笔记路径映射

### 7.3 追加 `wiki/log.md`

- 记录本次重构操作
- 注明 11 篇旧笔记被 16 篇新笔记替代

---

## 8. 硬性约束

1. **不修改 `raw/` 以外的文件**（Wiki 除外：`source-freertos.md`, `index.md`, `log.md`）
2. **所有代码必须来自真实项目文件**，不凭空编写代码
3. **每行 API 代码必须标注通俗解释注释**
4. **每篇必须有通俗类比**（`> **用生活理解**：`）
5. **图片必须经过筛选**，不盲目全部复制
6. **16 篇一次完成**，不分批次
7. **旧 11 篇笔记覆盖前先确认备份**（实际已不存在，直接新建）