📚 课程目录第3章 HAL库架构与编程模型

3. HAL库架构与编程模型：从分层到回调，一套完整的驱动思维

说实话，HAL库刚出来那会儿，我挺抵触的。总觉得标准外设库用得好好的，干嘛要换？直到我在一个项目里同时要驱动三个I2C传感器、两个SPI屏幕，还得兼顾低功耗——标准库那套直接操作寄存器的写法，代码量翻倍不说，移植起来简直要命。后来硬着头皮用了HAL，嗯，真香。

这一章，我就带你拆解HAL库的核心架构。搞懂了这些，你写驱动会顺手很多。

3.1 HAL库的分层结构：三层隔离，各司其职

HAL库不是一坨代码堆在一起的。它分了清晰的三层，每一层只管自己的事。我画了张图，你先看个全貌。

这三层的关系，说白了就是：你写应用代码，调HAL的API，HAL再去操作寄存器。每一层都只跟相邻层通信，不越级。

应用层：你的main.c、中断回调、任务函数。这一层只关心业务逻辑，不关心寄存器地址。
HAL中间层：核心驱动代码。每个外设对应一组API，比如HAL_UART_Transmit、HAL_I2C_Master_Transmit。这一层封装了所有硬件差异。
底层硬件抽象层：LL库和BSP。直接操作寄存器，处理中断向量表。一般不需要你动，除非做底层移植。

我的习惯： 做产品时，我通常只改应用层和BSP层。HAL中间层基本不动。这样换芯片型号时，应用代码几乎不用改，只换BSP和HAL包就行。省心。

3.2 句柄机制：每个外设的“身份证”

HAL库里有个核心概念——句柄（Handle）。你可以把它理解成每个外设的“身份证”加“档案袋”。

以前用标准库，你要操作一个UART，得记住它的一堆寄存器地址：USART1->SR、USART1->DR、USART1->CR1……代码里到处都是宏定义。HAL库换了个思路：把所有跟这个外设相关的信息——寄存器基址、当前状态、配置参数、回调函数指针——打包成一个结构体。你只需要传递这个结构体指针就行。

// 以UART为例，句柄结构体长这样（简化版）
typedef struct __UART_HandleTypeDef
{
    USART_TypeDef *Instance;        // 外设寄存器基址
    UART_InitTypeDef Init;          // 初始化配置（波特率、数据位等）
    uint8_t *pTxBuffPtr;            // 发送缓冲区指针
    uint16_t TxXferSize;            // 发送数据长度
    uint16_t TxXferCount;           // 剩余发送字节数
    uint8_t *pRxBuffPtr;            // 接收缓冲区指针
    uint16_t RxXferSize;            // 接收数据长度
    uint16_t RxXferCount;           // 剩余接收字节数
    DMA_HandleTypeDef *hdmatx;      // 发送DMA句柄指针
    DMA_HandleTypeDef *hdmarx;      // 接收DMA句柄指针
    HAL_LockTypeDef Lock;           // 锁状态
    __IO HAL_UART_StateTypeDef gState;  // 全局状态
    __IO HAL_UART_ErrorTypeDef ErrorCode; // 错误码
} UART_HandleTypeDef;

你看，一个句柄里包含了：硬件资源 + 配置参数 + 运行状态 + DMA关联 + 错误信息。所有东西都在一个结构体里，清晰得很。

句柄机制的好处：

多实例支持：你可以定义两个UART句柄，一个给UART1，一个给UART2，互不干扰。
状态追踪：随时查看gState就知道外设在忙还是空闲。
错误隔离：每个句柄有自己的ErrorCode，出问题能精确定位。

我曾经踩过的坑： 句柄一定要用 & 取地址传给HAL函数。我见过有人直接传句柄本身（值传递），结果HAL函数里改了副本，原句柄纹丝不动。调试了一下午才发现。记住：HAL函数参数都是指针。

3.3 超时机制：别让程序卡死在那

嵌入式系统最怕什么？死等。一个外设没响应，程序就卡在某个循环里出不来。HAL库用超时机制解决了这个问题。

几乎所有带阻塞的HAL函数，都有一个Timeout参数。比如：

// 阻塞发送，超时1000毫秒
HAL_StatusTypeDef status = HAL_UART_Transmit(&huart1, data, len, 1000);
if (status == HAL_TIMEOUT)
{
    // 超时处理：重试、复位外设、或者报错
    Error_Handler();
}

超时是怎么实现的？HAL库内部维护了一个tick计数器（通常由SysTick定时器提供，每1ms递增一次）。阻塞函数里会不断检查当前tick与起始tick的差值，如果超过设定的Timeout值，就返回HAL_TIMEOUT。

这里有个关键点：超时机制依赖SysTick中断。如果你在某个临界区里关了全局中断，或者SysTick被更高优先级的中断阻塞了，那超时就不准了。我遇到过这种情况，调试时发现明明设了5秒超时，结果等了半分钟才返回——原来是某个中断服务函数写得太长，把SysTick给堵了。

建议： 超时时间别设得太极限。一般通信类的操作，设个100-500ms比较合理。如果频繁超时，先检查硬件连接，别盲目加大超时值。

3.4 三种模式：轮询、中断、DMA，怎么选？

HAL库为每个外设提供了三种操作模式。我整理了一张对比表，你一看就明白。

模式	CPU占用	实时性	数据量	典型场景
轮询（Polling）	高（一直等）	低	小（单字节/短帧）	调试打印、按键扫描、简单传感器读取
中断（Interrupt）	中（触发时才响应）	高	中等（几十到几百字节）	UART接收不定长数据、按键中断、定时器
DMA（Direct Memory Access）	低（硬件搬运）	高	大（几百字节以上）	音频播放、高速ADC采集、SPI Flash读写

三种模式的API命名也很规律：

轮询：HAL_UART_Transmit()、HAL_I2C_Master_Transmit() —— 阻塞执行，直到完成或超时。
中断：HAL_UART_Transmit_IT()、HAL_I2C_Master_Transmit_IT() —— 启动传输后立即返回，传输完成触发中断。
DMA：HAL_UART_Transmit_DMA()、HAL_I2C_Master_Transmit_DMA() —— 启动传输后立即返回，DMA控制器自动搬运数据。

怎么选？我个人的经验是：

调试阶段：先用轮询，简单粗暴，好排查问题。
生产代码：能用中断就别用轮询，能用DMA就别用中断。CPU的时间很宝贵，别浪费在等待上。
注意：DMA虽然省CPU，但会占用总线带宽。如果多个DMA通道同时跑，可能会有总线冲突。我在一个项目里同时用了UART DMA和SPI DMA，结果偶尔出现数据错位，后来给DMA通道设了优先级才解决。

3.5 回调函数体系：HAL的“事件通知”机制

回调函数是HAL库的精髓。它解决了“什么时候该做什么事”的问题。

你想想看，如果用轮询，你得在主循环里不断检查外设状态：数据到了没？发送完了没？用中断模式就不一样了——外设自己会通知你。HAL库把这种通知机制做成了回调函数。

每个外设都有几个固定的回调函数，你只需要在应用层实现它们：

// UART接收完成回调（中断/DMA模式通用）
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART1)
    {
        // 收到一个字节，处理它
        ProcessReceivedByte(rx_buffer);
        // 重新启动接收，等待下一个字节
        HAL_UART_Receive_IT(huart, rx_buffer, 1);
    }
}

// UART发送完成回调
void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
{
    // 发送完成，可以释放缓冲区或通知任务
    tx_busy = 0;
}

// 错误回调
void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart)
{
    // 出错了，记录错误码，尝试恢复
    LogError(huart->ErrorCode);
    HAL_UART_Abort(huart);  // 中止当前传输
}

回调函数的调用时机是固定的：

传输完成：调用 XxxCpltCallback
传输一半（DMA模式）：调用 XxxHalfCpltCallback
出错：调用 XxxErrorCallback
外设事件（如GPIO中断）：调用 HAL_GPIO_EXTI_Callback

回调函数的使用原则：

快进快出：回调函数里不要做耗时操作，比如打印长字符串、延时。它们是在中断上下文里调用的。
不要阻塞：不要在回调里调用另一个阻塞的HAL函数，容易造成嵌套中断或死锁。
善用标志位：回调里只设标志位，真正的处理放到主循环或任务里。

我曾经犯过的错： 在UART接收回调里直接调了HAL_Delay(10)，结果系统直接死机。为什么？因为HAL_Delay依赖SysTick中断，而UART中断优先级比SysTick高，SysTick被堵住了，HAL_Delay永远等不到tick递增。死锁。从那以后，我回调里只用标志位和队列。

3.6 小结：HAL库的编程模型，其实就一句话

搞懂了上面这些，你会发现HAL库的编程模型其实很统一：

定义句柄：声明一个外设句柄，配置好参数。
初始化：调用 HAL_Xxx_Init()，传入句柄指针。
选择模式：根据场景选轮询、中断还是DMA。
实现回调：在回调函数里处理结果。
检查状态：通过句柄的 gState 和 ErrorCode 监控运行情况。

这套模型，不管是UART、I2C、SPI还是定时器，都通用。你学会一个，就等于学会了所有外设的驱动写法。这就是HAL库的设计哲学——统一接口，降低学习成本。