这份文档解决的是「在 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 上的差异

附录 B API 速查表

按用途分组的常用 API，重点标注「能否在 ISR 使用」。完整列表以官方参考手册为准。

B.1 任务控制

B.2 队列与流缓冲

B.3 信号量与互斥量

B.4 任务通知与事件组

B.5 定时器与临界区

B.6 中断上下文对照（最重要的一张）

附录 C 驱动代码模板

可直接复制修改的骨架代码。

C.1 驱动头文件骨架

#ifndef __DRV_TEMPLATE_H
#define __DRV_TEMPLATE_H

#include "drv_common.h"
#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ============ 配置 ============ */
typedef struct {
    uint32_t speed_hz;
    uint8_t  mode;
    uint8_t  cs_gpio;
} tpl_cfg_t;

/* ============ 句柄 ============ */
typedef struct {
    tpl_cfg_t          cfg;
    SemaphoreHandle_t  lock;
    SemaphoreHandle_t  done;
    StaticSemaphore_t  lock_mem;
    StaticSemaphore_t  done_mem;
    drv_stats_t        stats;
    uint8_t            inited;
} tpl_handle_t;

/* ============ API ============
 * 说明：
 *   - 以下函数均只能在任务上下文调用，不可在 ISR 中调用
 *   - timeout_ms = 0 表示非阻塞；大于 0 表示最多阻塞该毫秒数
 *   - 返回值：0/正数表示成功（字节数），负数为 drv_err_t 错误码
 */
drv_err_t tpl_init  (tpl_handle_t *h, const tpl_cfg_t *cfg);
drv_err_t tpl_deinit(tpl_handle_t *h);
int32_t   tpl_write (tpl_handle_t *h, const uint8_t *buf, uint32_t len, uint32_t timeout_ms);
int32_t   tpl_read  (tpl_handle_t *h, uint8_t *buf, uint32_t len, uint32_t timeout_ms);
drv_err_t tpl_ioctl (tpl_handle_t *h, uint32_t cmd, void *arg);

#ifdef __cplusplus
}
#endif
#endif /* __DRV_TEMPLATE_H */

C.2 驱动实现骨架

#include "drv_template.h"

drv_err_t tpl_init(tpl_handle_t *h, const tpl_cfg_t *cfg)
{
    if (!h || !cfg) return DRV_ERR_PARAM;
    memset(h, 0, sizeof(*h));
    h->cfg = *cfg;

    /* 1. 硬件初始化（BSP 层，无 RTOS 调用） */
    if (bsp_tpl_hw_init(&cfg->speed_hz) != 0) return DRV_ERR_HW;

    /* 2. 同步对象（静态创建，避免堆碎片） */
    h->lock = xSemaphoreCreateMutexStatic(&h->lock_mem);
    h->done = xSemaphoreCreateBinaryStatic(&h->done_mem);   /* 初值 0 */

    /* 3. 中断优先级与使能 —— 必须落在阈值以内 */
    NVIC_SetPriority(TPL_IRQn, DRV_IRQ_PRIO_TPL);
    NVIC_EnableIRQ(TPL_IRQn);

    h->inited = 1;
    return DRV_OK;
}

int32_t tpl_write(tpl_handle_t *h, const uint8_t *buf, uint32_t len, uint32_t timeout_ms)
{
    if (!h || !h->inited) return DRV_ERR_NOT_INIT;
    if (!buf || len == 0) return DRV_ERR_PARAM;

    if (xSemaphoreTake(h->lock, ms_to_ticks_safe(timeout_ms)) != pdTRUE) {
        h->stats.lock_timeout++;  return DRV_ERR_BUSY;
    }
    bsp_tpl_start_write(buf, len);
    if (xSemaphoreTake(h->done, ms_to_ticks_safe(timeout_ms)) != pdTRUE) {
        bsp_tpl_abort();  h->stats.xfer_timeout++;
        xSemaphoreGive(h->lock);  return DRV_ERR_TIMEOUT;
    }
    xSemaphoreGive(h->lock);
    h->stats.xfer_cnt++;  h->stats.xfer_bytes += len;
    return (int32_t)len;
}

void TPL_IRQHandler(void)
{
    BaseType_t xWoken = pdFALSE;
    if (bsp_tpl_flag_done())  { bsp_tpl_clear_done();  xSemaphoreGiveFromISR(g_h.done, &xWoken); }
    if (bsp_tpl_flag_error()) { bsp_tpl_clear_error(); g_h.stats.err_cnt++; }
    portYIELD_FROM_ISR(xWoken);
}

C.3 环形缓冲区（完整实现）

/* ringbuf.h —— 单写者 / 单读者无锁实现 */
#ifndef __RINGBUF_H
#define __RINGBUF_H
#include <stdint.h>

#define RB_SIZE  256                   /* 必须是 2 的幂 */
#define RB_MASK  (RB_SIZE - 1)

typedef struct { volatile uint32_t head; volatile uint32_t tail; uint8_t buf[RB_SIZE]; } rb_t;

static inline void     rb_init(rb_t *r)                { r->head = r->tail = 0; }
static inline uint32_t rb_used(const rb_t *r)          { return (r->head - r->tail) & RB_MASK; }
static inline uint32_t rb_free(const rb_t *r)          { return RB_MASK - rb_used(r); }
static inline int      rb_full(const rb_t *r)          { return ((r->head + 1) & RB_MASK) == r->tail; }
static inline int      rb_empty(const rb_t *r)         { return r->head == r->tail; }

static inline int rb_put(rb_t *r, uint8_t b)           /* 写者（常为 ISR） */
{
    if (rb_full(r)) return -1;
    r->buf[r->head] = b;
    r->head = (r->head + 1) & RB_MASK;
    return 0;
}

static inline int rb_get(rb_t *r, uint8_t *b)          /* 读者（常为任务） */
{
    if (rb_empty(r)) return -1;
    *b = r->buf[r->tail];
    r->tail = (r->tail + 1) & RB_MASK;
    return 0;
}
#endif

C.4 总线看门狗

/* bus_watchdog.c —— 周期性检查总线是否卡死并触发恢复 */
typedef struct {
    const char *name;
    int (*is_busy)(void);
    int (*recover)(void);
    uint32_t busy_cnt;
    uint32_t max_cnt;
    uint32_t recover_total;
} bus_wdt_t;

void bus_wdt_tick(bus_wdt_t *w)                 /* 由软件定时器或任务周期调用 */
{
    if (w->is_busy()) {
        if (++w->busy_cnt >= w->max_cnt) {
            if (w->recover() == 0) w->recover_total++;
            w->busy_cnt = 0;
        }
    } else {
        w->busy_cnt = 0;
    }
}

C.5 驱动自检钩子

/* 上电自检：验证关键假设，避免「配置错了还继续跑」 */
typedef struct { const char *name; int (*check)(void); } self_test_t;

static const self_test_t g_self_tests[] = {
    { "sysclk",   check_sysclk    },     /* 时钟频率与设计值一致？ */
    { "irq_prio", check_irq_prio  },     /* 中断优先级落在阈值内？ */
    { "heap",     check_heap_size },     /* 堆余量足够？ */
    { "uart1",    check_uart1     },     /* 回环测试或读 ID */
    { "flash",    check_flash_id  },     /* 读 JEDEC ID */
};

void run_self_tests(void)
{
    for (size_t i = 0; i < ARRAY_SIZE(g_self_tests); i++) {
        int r = g_self_tests[i].check();
        LOG("[SELFTEST] %-8s %s\n", g_self_tests[i].name, r == 0 ? "OK" : "FAIL");
        if (r != 0) g_boot_flags |= (1 << i);      /* 记录，供后续诊断读取 */
    }
}

附录 D 调试与测试脚本

下面这些小工具建议直接放进项目，平时看着没用，出问题时能省几个小时。

D.1 栈水位与堆余量打印

/* 通过串口命令或按键触发，输出所有任务的栈水位与堆余量 */
void cli_cmd_mem(int argc, char **argv)
{
    TaskStatus_t *st;
    UBaseType_t cnt = uxTaskGetNumberOfTasks();
    st = pvPortMalloc(cnt * sizeof(TaskStatus_t));
    if (!st) { LOG("oom\n"); return; }

    cnt = uxTaskGetSystemState(st, cnt, NULL);
    LOG("%-12s %-6s %-6s %-8s\n", "NAME", "PRIO", "STATE", "STACK_LEFT");
    for (UBaseType_t i = 0; i < cnt; i++) {
        LOG("%-12s %-6u %-6c %-8u\n",
            st[i].pcTaskName,
            (unsigned)st[i].uxCurrentPriority,
            "RBDXS"[st[i].eCurrentState],
            (unsigned)st[i].usStackHighWaterMark);
    }
    vPortFree(st);

    LOG("heap free=%u  min_ever=%u\n",
        (unsigned)xPortGetFreeHeapSize(),
        (unsigned)xPortGetMinimumEverFreeHeapSize());
}

D.2 中断频率与执行时间测量

/* 用 DWT 周期计数器测 ISR 执行时间与间隔（Cortex-M3/M4/M7 可用） */
void dwt_init(void)
{
    CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk;
    DWT->CYCCNT = 0;
    DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk;
}

typedef struct { uint32_t cnt; uint32_t max_cycles; uint32_t last; uint32_t min_interval; } isr_stat_t;
static isr_stat_t g_isr_stat;

void XXX_IRQHandler(void)
{
    uint32_t t0 = DWT->CYCCNT;
    /* --- ISR 主体 --- */
    uint32_t dt = DWT->CYCCNT - t0;

    g_isr_stat.cnt++;
    if (dt > g_isr_stat.max_cycles) g_isr_stat.max_cycles = dt;
    uint32_t now = xTaskGetTickCountFromISR();
    uint32_t gap = now - g_isr_stat.last;
    if (g_isr_stat.cnt > 1 && gap < g_isr_stat.min_interval) g_isr_stat.min_interval = gap;
    g_isr_stat.last = now;
}

/* 换算：cycles / (SystemCoreClock / 1e6) = 微秒 */

D.3 串口压力测试

/* 回环压测：TX 与 RX 短接，连续 N 轮，比对内容并输出统计 */
void cli_cmd_uart_stress(int argc, char **argv)
{
    const uint32_t rounds = 10000;
    static uint8_t tx[256], rx[256];

    for (uint32_t r = 0; r < rounds; r++) {
        for (uint32_t i = 0; i < sizeof(tx); i++) tx[i] = (uint8_t)(i + r);
        if (drv_uart_write(&g_uart, tx, sizeof(tx), 500) != (int)sizeof(tx)) {
            LOG("[FAIL] write @%u\n", (unsigned)r); return;
        }
        uint32_t got = 0;
        while (got < sizeof(tx)) {
            int n = drv_uart_read(&g_uart, rx + got, sizeof(tx) - got, 100);
            if (n <= 0) { LOG("[FAIL] read timeout @%u\n", (unsigned)r); return; }
            got += (uint32_t)n;
        }
        if (memcmp(tx, rx, sizeof(tx)) != 0) { LOG("[FAIL] mismatch @%u\n", (unsigned)r); return; }
    }
    LOG("[OK] %u rounds  timeout=%u overrun=%u\n",
        (unsigned)rounds, (unsigned)g_uart.stats.rx_timeout, (unsigned)g_uart.stats.overrun);
}

D.4 存储读写压力测试

/* 写入 N 次并回读校验，统计错误与耗时 */
void cli_cmd_flash_stress(int argc, char **argv)
{
    const uint32_t addr_start = 0x00100000;
    const uint32_t blocks     = 256;
    static uint8_t buf[4096];

    uint32_t t0 = xTaskGetTickCount();
    for (uint32_t b = 0; b < blocks; b++) {
        uint32_t addr = addr_start + b * sizeof(buf);
        for (uint32_t i = 0; i < sizeof(buf); i++) buf[i] = (uint8_t)(i + b);

        if (flash_erase(addr, 4096) != 0) { LOG("[FAIL] erase @0x%08X\n", addr); return; }
        if (flash_write(addr, buf, sizeof(buf)) != 0) { LOG("[FAIL] write @0x%08X\n", addr); return; }
        if (flash_verify(addr, buf, sizeof(buf)) != 0) { LOG("[FAIL] verify @0x%08X\n", addr); return; }
    }
    uint32_t dt = xTaskGetTickCount() - t0;
    LOG("[OK] %u blocks in %u ms\n", (unsigned)blocks, (unsigned)dt);
}

D.5 掉电测试

/* 掉电测试：写操作进行中随机断电，重复后检查数据一致性
 * 做法：
 *   1. 设备上电后先检查「上次是否完成」标志
 *   2. 若未完成，走恢复流程（回滚到上一份完整数据）
 *   3. 重新执行写入，写完后置「完成」标志
 * 判据：连续 1000 次随机掉电后，关键数据始终可读且为最近一次完整提交的版本
 */
typedef struct {
    uint32_t seq;        /* 递增序列号，用于判断哪份更新 */
    uint32_t crc;        /* 数据校验 */
    uint8_t  data[512];
} commit_t;

/* 双份交替写（A/B 备份）：任何时刻至少有一份完整 */
int commit_write(commit_t *slot_a, commit_t *slot_b, const uint8_t *data, uint32_t len)
{
    commit_t *target = (slot_a->seq <= slot_b->seq) ? slot_a : slot_b;
    uint32_t new_seq = ((slot_a->seq > slot_b->seq) ? slot_a->seq : slot_b->seq) + 1;

    memcpy(target->data, data, len);
    target->crc = crc32(target->data, len);
    target->seq = new_seq;                 /* 序列号最后写，作为提交点 */
    return 0;
}

附录 E 驱动发布前检查清单

逐条打勾再发布。这份清单是本指南所有「纪律」的汇总，建议在评审会上逐条过。

E.1 中断与并发

• 所有外设中断优先级都在 configMAX_SYSCALL_INTERRUPT_PRIORITY 以内（数值 ≥ 阈值）
• ISR 里只使用带 FromISR 后缀的 API，没有任何阻塞调用
• ISR 里没有使用 Mutex、printf、浮点运算、长循环
• 每个 FromISR 调用之后都正确配了 portYIELD_FROM_ISR
• ISR 处理了所有可能的中断标志，包括错误/溢出位（不会中断风暴）
• ISR 执行时间已测量，最大值在可接受范围内（建议 < 10 μs）
• 临界区长度已检查，没有在临界区内调用任何可能阻塞的 API
• 任务与 ISR 共享的数据要么用环形缓冲，要么用短临界区保护
• 多任务访问同一外设时用的是 Mutex（不是二进制信号量）
• 多把锁的获取顺序全局一致，且带超时回退

E.2 阻塞与超时

• 所有可能阻塞的 API 都有超时参数，且没有在驱动内部写 portMAX_DELAY
• 超时时间按最坏情况估算（取 datasheet 最大值 × 安全系数）
• pdMS_TO_TICKS 的换算考虑了 tick 粒度（低于 1 tick 时不会退化成 0）
• 超时后的硬件状态已明确定义（取消 / 复位 / 保留），并有对应处理
• 队列/缓冲满或空时的行为已明确（丢弃 / 覆盖 / 返回错误）并已计数
• 驱动 API 的头文件注释写清了「会不会阻塞」「阻塞多久」

E.3 内存与栈

• DMA 缓冲区是静态数组，已按 Cache Line 对齐（或设为 Non-cacheable）
• DMA 缓冲区不在栈上，不在运行期动态分配
• 带 Cache 的平台上，DMA 前后正确执行了 Clean / Invalidate
• 所有任务栈水位已测量，余量 > 25%
• 堆的历史最低余量 > 20%，或已改为全静态分配
• 驱动不在运行期动态申请内存（或在 init 时一次性申请完毕）
• 已实现栈溢出钩子与 malloc 失败钩子

E.4 异常与恢复

• 所有驱动 API 对非法参数、未初始化状态都有明确的错误返回（不崩溃）
• 总线类外设（I2C / SPI / SDIO / CAN）有超时检测与恢复流程
• 恢复动作有次数统计与阈值，超过阈值会进入降级或安全模式
• 看门狗由独立任务 + 任务存活检查喂狗，不在中断里喂
• HardFault 处理会保存 PC / LR / CFSR 等关键寄存器（或存 NoInit RAM）
• 已做异常注入测试（拔线、断电、从设备复位）并验证能恢复
• 关键数据的写入是提交式的（双份 + 序列号 + CRC）

E.5 低功耗与性能

• 若启用 tickless，驱动已实现 suspend / resume 钩子且支持回滚
• 唤醒后先恢复时钟树，再恢复外设
• 用作唤醒源的中断已确认在该低功耗模式下可用
• 休眠电流已实测，符合设计目标
• 吞吐率、中断延迟、CPU 占用已测量并记录为回归基线
• 没有任务长期处于就绪态导致空闲任务进不去

E.6 代码与文档

• 编译无警告（至少 -Wall -Wextra，建议 -Werror）
• 已跑静态分析（cppcheck 或同类工具）并处理高危项
• 命名、注释、目录结构符合团队规范
• 对外 API 注释写清了三件事：能否在 ISR 调用、会不会阻塞、超时后硬件状态
• 驱动统计结构完整（传输数、超时数、错误数、溢出数、最大 ISR 时间）
• 已提供 changelog、Known Issues 与依赖版本清单
• 功能 / 并发 / 压力 / 稳定性测试报告已完成并归档
• 量产配置（优化打开、调试关闭）下已重跑一遍完整测试
• 最终固件与源码 tag 已绑定，可追溯

附录 F 术语表

附录 G 参考资料

文档版本：v1.0 · 章节：20 章 + 7 附录 · 图示：23 张 · 基线：FreeRTOS Kernel V11.x（示例）