单片机与物联网 / 系统课时

HAL 库调用模型

HAL 库调用模型

本课解决“为什么 HAL API 总要传句柄、初始化后如何判断成功、异步操作完成后代码从哪里继续”的问题。你将用一条完整调用链理解句柄、初始化函数、状态返回值与回调函数之间的关系。

学习目标

  • 解释 HAL 句柄保存了哪些配置与运行状态
  • 根据 HAL_StatusTypeDef 正确处理调用结果
  • 区分阻塞调用、非阻塞启动和回调通知

句柄是外设的软件上下文

HAL 句柄通常是 UART_HandleTypeDef、TIM_HandleTypeDef 或 ADC_HandleTypeDef 这样的结构体。它不仅保存外设实例地址和初始化参数,还可能保存锁、状态、错误码、DMA 句柄以及正在处理的数据指针。

以串口为例,huart2.Instance 指向具体 USART 外设,huart2.Init 保存波特率、数据位和停止位等配置。后续发送、接收和中断处理都通过同一个句柄找到对应外设及其当前状态。

HAL 句柄与调用链流程图

初始化函数建立硬件与句柄状态

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,以及串口终端连接到对应引脚。代码同时演示状态判断和错误处理。

c
#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();
    }
}

预期结果:

text
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 发送完成后被调用。回调中应先确认句柄对应的外设,再设置标志或投递事件。

c
#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 生成的全局句柄进行封装,而不是创建未经初始化的替代对象。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

HAL 库调用模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通