单片机与物联网 / 系统课时
HAL 库调用模型
HAL 库调用模型
本课解决“为什么 HAL API 总要传句柄、初始化后如何判断成功、异步操作完成后代码从哪里继续”的问题。你将用一条完整调用链理解句柄、初始化函数、状态返回值与回调函数之间的关系。
学习目标
- 解释 HAL 句柄保存了哪些配置与运行状态
- 根据
HAL_StatusTypeDef正确处理调用结果 - 区分阻塞调用、非阻塞启动和回调通知
句柄是外设的软件上下文
HAL 句柄通常是 UART_HandleTypeDef、TIM_HandleTypeDef 或 ADC_HandleTypeDef 这样的结构体。它不仅保存外设实例地址和初始化参数,还可能保存锁、状态、错误码、DMA 句柄以及正在处理的数据指针。
以串口为例,huart2.Instance 指向具体 USART 外设,huart2.Init 保存波特率、数据位和停止位等配置。后续发送、接收和中断处理都通过同一个句柄找到对应外设及其当前状态。

初始化函数建立硬件与句柄状态
CubeMX 通常生成 MX_USART2_UART_Init()。该函数先填写句柄中的初始化字段,再调用 HAL_UART_Init()。HAL 初始化内部还会触发 HAL_UART_MspInit(),用于配置外设时钟、GPIO 复用和中断资源。
调用顺序可以概括为:准备句柄参数、初始化底层资源、写入外设寄存器、更新句柄状态。若底层时钟或引脚未正确配置,即使应用层参数看起来正确,初始化仍可能失败或无法通信。
返回状态必须显式处理
多数 HAL 函数返回 HAL_StatusTypeDef,常见值包括 HAL_OK、HAL_ERROR、HAL_BUSY 和 HAL_TIMEOUT。不要默认调用一定成功,尤其是超时、并发访问或外设状态异常时。
下面是片段示例,依赖 CubeMX 已生成并成功初始化的 huart2,以及串口终端连接到对应引脚。代码同时演示状态判断和错误处理。
#include "main.h"
#include <string.h>
extern UART_HandleTypeDef huart2;
void App_SendBootMessage(void)
{
const char message[] = "HAL UART ready\r\n";
HAL_StatusTypeDef status;
status = HAL_UART_Transmit(
&huart2,
(const uint8_t *)message,
(uint16_t)strlen(message),
100
);
if (status != HAL_OK) {
Error_Handler();
}
}预期结果:
HAL UART ready实际串口号、波特率和引脚由工程配置决定;若发送超时或外设忙,程序会进入 Error_Handler(),而不是继续假设数据已经发出。
阻塞、IT 与 DMA 三种调用方式
阻塞 API 会在函数内部等待传输完成或超时,例如 HAL_UART_Transmit()。它最容易使用,但等待期间 CPU 无法处理同一执行流中的其他任务。
带 _IT 的 API 使用中断推进传输,带 _DMA 的 API 使用 DMA 搬运数据。它们通常只负责启动操作,函数返回 HAL_OK 不代表传输已经完成,只表示请求已被接受。完成、半完成或错误事件会通过回调函数通知应用。
| 调用方式 | 函数返回时 | 完成通知 | 适用场景 |
|---|---|---|---|
| 阻塞 | 操作完成或超时 | 返回值 | 短数据、初始化阶段 |
| 中断 | 操作已启动 | 完成回调 | 中等数据量、需要并发处理 |
| DMA | DMA 已启动 | DMA/HAL 回调 | 大数据量、降低 CPU 占用 |
回调函数连接驱动与业务
HAL 提供弱定义回调,应用可以实现同名函数覆盖默认实现。例如,HAL_UART_TxCpltCallback() 会在中断或 DMA 发送完成后被调用。回调中应先确认句柄对应的外设,再设置标志或投递事件。
#include "main.h"
extern UART_HandleTypeDef huart2;
volatile uint8_t uart2_tx_done = 0;
void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
{
if (huart->Instance == USART2) {
uart2_tx_done = 1;
}
}这是片段示例,依赖先调用 HAL_UART_Transmit_IT() 或 HAL_UART_Transmit_DMA()。预期结果是传输完成后 uart2_tx_done 由 0 变为 1;可在调试器监视窗口或主循环中检查该变量。
回调通常运行在中断上下文,不应执行长时间阻塞、动态分配或复杂日志输出。更安全的做法是在回调中只记录状态,再由主循环或 RTOS 任务处理后续业务。
常见误区
把 HAL_OK 当成异步操作已经完成,是最常见的错误之一。对 _IT 和 _DMA 调用,真正的完成依据是对应回调或句柄状态。
另一个误区是复制句柄后分别使用。句柄包含运行状态,多个副本会导致状态不同步。应用应围绕 CubeMX 生成的全局句柄进行封装,而不是创建未经初始化的替代对象。