这份文档解决的是「在 FreeRTOS 上如何把一个外设写成可量产、可维护的驱动」的问题：它不重复官方 API 手册，而是把分层边界 → 中断优先级 → 同步原语选型 → 驱动 API 规范 → 各外设实现要点 → 并发与内存治理 → 低功耗与故障恢复 → 调试测试串成一条可复用的流水线，并把每一步的纪律（ISR 能做什么、阻塞必须有超时、硬件必须可恢复）固化成检查项。新人按第 1→18 章通读即可上手；老手直接翻第 19 章速查表与附录 E 检查清单。

这份文档的三条硬约束

与相邻文档的分工

第 1 章 文档总览

这一章先把边界划清楚：这份文档给谁用、基于什么版本与平台、用到哪些术语，以及本版相对最初的 10 章骨架到底扩充了什么。边界不清是驱动返工的头号原因。

1.1 编写目的、适用范围与读者

本指南用于规范基于 FreeRTOS（及其衍生发行版，如 AWS FreeRTOS、ESP-IDF、RT-Thread 之外的 FreeRTOS 移植、各类厂商 SDK 内置 FreeRTOS）的外设驱动开发，目标是让不同背景的工程师在同一套模型上协作，把「个人调通过的经验」沉淀成「团队可复用的规范」。

适用范围：Cortex-M（M0/M3/M4/M7/M33）、Cortex-A、RISC-V 等主流 MCU/MPU 平台上的 FreeRTOS 外设驱动；外设覆盖 UART、SPI、I2C、ADC、GPIO/EXTI、Timer/PWM、CAN、DMA、存储类（SPI NOR/NAND、SD、eMMC）。不适用范围：Linux 用户态/内核态驱动、纯裸机轮询系统、RTOS 内核自身移植（仅在第 3 章给出与驱动相关的配置项）。

1.2 版本与平台基线

版本基线必须写在文档第一页。下表为示例基线，项目立项时按实际情况替换并冻结；所有 API 名称、配置项、行为描述都以此为准。

1.3 术语、缩写与参考文档

1.4 从 10 章骨架到 20 章：本版扩充清单

原始骨架给出的 10 章覆盖了「分层 / 配置 / 原语 / ISR 模板 / 共享保护 / 选型 / 流程 / 坑 / FreeRTOS+IO / 调试」这条主线，已经是正确的。本版在此基础上做三件事：补深度、补宽度、补闭环。下表逐条说明补了什么、为什么补。

第 2 章 驱动模型与分层架构

这一章解决「驱动到底该怎么切层」的问题。分层不是为了好看，而是为了让每一层都能独立验证、独立复用，并且让「在 ISR 里能调什么」有一个不需要靠记忆的物理边界。

2.1 为什么 FreeRTOS 没有统一驱动框架

FreeRTOS 的定位是实时内核，不是操作系统发行版。它提供的是任务调度、同步原语、时间管理与内存管理，不提供类似 Linux 的 device model / bus / driver / device tree 这一整套抽象。原因是：

• 目标硬件跨度极大：从 8 位 MCU 到多核 Cortex-A，统一抽象的代价对低端器件不可接受。
• 实时性优先：任何统一框架都会引入间接层与运行时开销，与硬实时诉求冲突。
• 历史路径：官方曾推出 FreeRTOS+IO 作为可选组件，提供 FreeRTOS_open/read/write/ioctl 统一接口，但早已不再主推，新项目不建议依赖。自研一层薄接口是业界主流做法。

2.2 四层分层模型

四层各自的输入与输出：

2.3 各层职责与硬纪律

L2 BSP 层：必须保持「无 RTOS 依赖」

• 只做寄存器读写、时钟使能、引脚复用、DMA 描述符配置。
• 不调用任何 FreeRTOS API，也不调用任何会阻塞的库函数。
• 好处：可以在裸机工程里直接复用验证；换 RTOS 时这一层零改动；单元测试可脱离 RTOS 跑。

L3 驱动接口层：只负责「线程安全」与「时序」

• 把 L2 的裸能力包装成带阻塞/超时语义的 API。
• 管理与该外设绑定的同步对象（信号量、队列、互斥量）。
• 定义错误码、超时策略、重试策略。

ISR：只做三件事

• 读中断状态寄存器、清中断标志（顺序很重要，见 4.4）。
• 把少量数据搬进环形缓冲区，或置位状态。
• 调用 *FromISR API 通知任务，必要时 portYIELD_FROM_ISR。

2.4 线程安全边界：什么只能在任务里调

这张图是第 4、5、12 章的总纲。判断规则只有一条：会导致阻塞或上下文切换的 API，一律不能在 ISR 和临界区里调用。

2.5 与 Linux 驱动模型的关键差异

很多工程师是先看 Linux 驱动再转 RTOS 的，下表把关键差异一次讲清，避免把 Linux 的习惯带进来。

2.6 代码目录与文件组织规范

目录结构建议如下。核心原则是 BSP 与驱动分离、接口与实现分离、配置与代码分离。

project/
├── App/                     # L4 应用层：业务任务
│   ├── app_comm.c
│   └── app_sensor.c
├── Drivers/                 # L3 驱动接口层：对外 API + 同步逻辑
│   ├── drv_uart.h / drv_uart.c
│   ├── drv_spi.h  / drv_spi.c
│   ├── drv_i2c.h  / drv_i2c.c
│   ├── drv_adc.h  / drv_adc.c
│   └── common/
│       ├── drv_common.h     # 错误码、句柄类型、通用宏
│       ├── ringbuf.h/.c     # 环形缓冲区
│       └── bus_watchdog.c   # 总线看门狗
├── BSP/                     # L2 硬件底层：纯寄存器操作，无 RTOS 依赖
│   ├── bsp_uart.c
│   ├── bsp_spi.c
│   └── bsp_gpio.c
├── Middlewares/
│   ├── FreeRTOS/
│   │   ├── Source/          # 内核源码（不改）
│   │   └── FreeRTOSConfig.h # 唯一配置入口
│   └── fatfs / littlefs     # 文件系统（第 11 章）
└── Tests/                   # 单元测试 / HIL 用例（第 18 章）

命名约定建议：

第 3 章 内核配置与移植基线

驱动能不能稳定，一半取决于 FreeRTOSConfig.h 写得对不对。这一章不罗列全部配置项，只讲与驱动强相关的那些：中断优先级、tick、堆、同步原语开关、调试开关，以及最容易配错的地方。

3.1 FreeRTOSConfig.h 全景分组

把配置项按「它管什么」分成六组，改配置时先定位到组，再改具体项，避免牵一发动全身。完整可直接复制的模板见附录 A。

3.2 Cortex-M 中断优先级与两个关键宏

两个宏的语义必须记牢：

/* Cortex-M：优先级数值越小，优先级越高（与直觉相反） */
#define configKERNEL_INTERRUPT_PRIORITY         (0xFF)   /* 内核自身：SysTick / PendSV / SVC，必须最低 */
#define configMAX_SYSCALL_INTERRUPT_PRIORITY    (0x10)   /* 阈值：数值 >= 此值的中断才允许调 FromISR API */

要点：

• configMAX_SYSCALL_INTERRUPT_PRIORITY = 0x10 是「未移位」的写法（高 4 位有效），对应 4 位优先级下的数值 1；若写 0x50 则对应数值 5。不同库（CMSIS / STM32 HAL）对「是否移位」的约定不同，移植时务必对照所用 port 的说明。
• 中断优先级高于阈值（数值更小）：不能调用任何 FreeRTOS API，也不会被内核的关中断操作屏蔽——适合极硬实时场景，但驱动里绝大多数中断不应放这里。
• 中断优先级等于或低于阈值（数值更大或相等）：允许调 FromISR，且在内核临界区期间会被屏蔽。
• SysTick / PendSV 必须设为最低优先级，否则会抢占应用中断，破坏实时性。

3.3 tick 速率、时钟源与 SysTick

• tick 与超时：pdMS_TO_TICKS(ms) 换算时，若 ms 小于一个 tick 周期，结果可能是 0 或 1——必须明确是否接受「立即返回」还是「至少等一个 tick」（见 13.3）。
• 时钟源：configCPU_CLOCK_HZ 与 configSYSTICK_CLOCK_HZ 填错会让延时与波特率整体偏快/偏慢，是最隐蔽的移植 bug 之一。
• 运行时统计：开启 configGENERATE_RUN_TIME_STATS 需要一个 比 tick 快 10~100 倍的硬件定时器（见 17.1）。

3.4 heap_1 ~ heap_5 选型

3.5 必开的调试与断言开关

/* 开发阶段建议全开，量产按附录 A.5 收紧 */
#define configASSERT(x)            if((x)==0) { taskDISABLE_INTERRUPTS(); for(;;); }
#define configCHECK_FOR_STACK_OVERFLOW    2      /* 2 = 检查更严格，开销略大 */
#define configUSE_MALLOC_FAILED_HOOK      1      /* 分配失败钩子 */
#define configUSE_TRACE_FACILITY          1      /* 任务列表 / 状态查询 */
#define configGENERATE_RUN_TIME_STATS     1      /* CPU 占用统计（需硬件定时器） */
#define configUSE_STATS_FORMATTING_FUNCTIONS 1   /* vTaskList / vTaskGetRunTimeStats */

3.6 高频配置错误清单

第 4 章 中断管理与 ISR 设计

这一章是整份文档的地基。FreeRTOS 驱动出问题，十有七八出在中断：优先级配错、ISR 里干了不该干的事、忘了请求上下文切换、临界区关太久。

4.1 NVIC 优先级分组与数值语义

Cortex-M 的优先级寄存器通常为 8 位，芯片只实现高 N 位（常见 N=4，即 16 级）。CMSIS 里用 NVIC_SetPriority(IRQn, priority) 写的是已对齐的裸值，而 STM32 HAL 的 HAL_NVIC_SetPriority(IRQn, PreemptPriority, SubPriority) 需要先调用 HAL_NVIC_SetPriorityGrouping() 确定分组再做换算——两种写法混用是移植期最常见的事故源。

/* 推荐：统一用 CMSIS 写裸值，避免分组换算带来的歧义 */
#define DRV_IRQ_PRIO_UART   6     /* 数值 >= configMAX_SYSCALL 对应值，允许调 FromISR */
NVIC_SetPriority(USART1_IRQn, DRV_IRQ_PRIO_UART);
NVIC_EnableIRQ(USART1_IRQn);

/* 不推荐但常见：HAL 写法，必须先确认分组 */
HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4);   /* 4 位抢占，0 位子优先级 */
HAL_NVIC_SetPriority(USART1_IRQn, 6, 0);

4.2 FromISR 规则与 portYIELD_FROM_ISR

规则只有三条，但每条都要形成肌肉记忆：

1. ISR 里只能用带 FromISR 后缀的 API；
2. 这些 API 会通过一个 BaseType_t *pxHigherPriorityTaskWoken 出参告诉你「是否有更高优先级任务被唤醒」；
3. 退出 ISR 前必须把这个标志交给 portYIELD_FROM_ISR()，否则高优先级任务要等到下一个 tick 才运行。

void USART1_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;   /* 必须初始化为 pdFALSE */

    if (USART1->ISR & USART_ISR_TC) {                /* ① 判状态 */
        USART1->ICR = USART_ICR_TCCF;                /* ② 清标志 */
        xSemaphoreGiveFromISR(xUartTxDone, &xHigherPriorityTaskWoken);   /* ③ 通知 */
    }

    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);    /* ④ 必要切换 */
}

还有一种更省事的写法：如果 ISR 里只有一个 FromISR 调用，可以用返回值直接判断：

BaseType_t xWoken = pdFALSE;
xWoken = xSemaphoreGiveFromISR(xSem, &xWoken);
if (xWoken == pdTRUE) { taskYIELD(); }      /* 等价写法，语义更直观 */

4.3 延迟中断处理 Deferred Interrupt

当 ISR 里要做的事超过「清标志 + 搬几个字节」时，就应该改用延迟处理：ISR 只负责通知，处理逻辑放在一个高优先级任务里跑。这是 FreeRTOS 里没有 workqueue 的替代方案。

两种实现方式

/* 方式 A：任务通知（最轻量，FreeRTOS 推荐） */
TaskHandle_t xUartTaskHandle;      /* 创建任务时保存句柄 */

void USART1_IRQHandler(void)
{
    BaseType_t xWoken = pdFALSE;
    uint32_t isr = USART1->ISR;
    if (isr & USART_ISR_RXNE) {
        uint8_t b = USART1->RDR;                    /* 读数据即清标志（部分芯片） */
        ringbuf_put_isr(&g_rxbuf, b);               /* 入环形缓冲 */
        vTaskNotifyGiveFromISR(xUartTaskHandle, &xWoken);   /* 通知 */
    }
    portYIELD_FROM_ISR(xWoken);
}

void vUartTask(void *arg)
{
    for (;;) {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);    /* 阻塞等待通知 */
        /* 在这里做协议解析、数据处理 —— 可以慢，可以调任何 API */
        uint8_t b;
        while (ringbuf_get(&g_rxbuf, &b) == 0) {
            proto_feed(b);                          /* 应用层回调，可耗时 */
        }
    }
}

4.4 ISR 标准模板与禁令清单

完整可复制的模板（以 UART 发送完成 + 接收双事件为例）：

/* ===== drv_uart.c ===== */
static SemaphoreHandle_t xTxDone;      /* 发送完成：二进制信号量，初值 0 */
static StreamBufferHandle_t xRxStream; /* 接收：流缓冲 */
static TaskHandle_t xRxTask;           /* 接收处理任务句柄 */

void USART1_IRQHandler(void)
{
    BaseType_t xWoken = pdFALSE;
    uint32_t isr = USART1->ISR;

    /* --- 发送完成 --- */
    if (isr & USART_ISR_TC) {
        USART1->ICR = USART_ICR_TCCF;                       /* 清标志 */
        xSemaphoreGiveFromISR(xTxDone, &xWoken);            /* 通知发送方 */
    }

    /* --- 接收非空 --- */
    if (isr & USART_ISR_RXNE) {
        uint8_t byte = (uint8_t)USART1->RDR;                /* 读 RDR 清标志 */
        xStreamBufferSendFromISR(xRxStream, &byte, 1, &xWoken);
    }

    /* --- 溢出等异常：必须处理，否则中断风暴 --- */
    if (isr & USART_ISR_ORE) {
        USART1->ICR = USART_ICR_ORECF;
        g_uart_stats.overrun++;
    }

    portYIELD_FROM_ISR(xWoken);
}

4.5 临界区与中断屏蔽的正确用法

FreeRTOS 提供三种「保护」手段，强度与代价各不相同，选错就会出问题。

/* 短临界区：只包住真正共享的那几行 */
taskENTER_CRITICAL();
g_tick_count = x;               /* 任务与 ISR 共享的短变量 */
g_flag = 1;
taskEXIT_CRITICAL();

/* 禁止：临界区里调用任何可能阻塞的 API */
taskENTER_CRITICAL();
xQueueReceive(q, &d, 100);      /* ✗ 绝对禁止：关中断期间阻塞 = 死锁 */
taskEXIT_CRITICAL();

4.6 Cortex-A / RISC-V 上的差异