4. HAL 接口分类：控制接口、数据接口、配置接口、状态接口、事件回调接口
在硬件抽象层（HAL）架构设计中，接口分类是驱动移植与模块解耦的核心基础。合理的接口分类能够将底层硬件操作与上层业务逻辑彻底分离，使驱动代码具备跨平台可移植性。根据接口的语义特征与调用方式，HAL 接口通常划分为五大类：控制接口、数据接口、配置接口、状态接口与事件回调接口。每一类接口承担不同的职责，遵循不同的设计约束。
核心原则：接口分类的本质是“关注点分离”。控制接口关注“做什么”，数据接口关注“传什么”，配置接口关注“设什么”，状态接口关注“查什么”，事件回调接口关注“通知谁”。这五类接口共同构成 HAL 层的完整语义边界。
4.1 控制接口（Control Interface）
控制接口用于向硬件设备发送操作指令，驱动设备执行特定的动作或状态转换。这类接口通常为同步阻塞或异步启动调用，不携带大量数据，而是以命令码或枚举值作为参数。
- 典型场景：启动电机、打开阀门、复位传感器、使能外设时钟。
- 设计特征：参数少（通常 1~3 个）、返回值简单（成功/失败/错误码）、执行时间可预期。
- 命名规范：动词 + 对象，如
HAL_ADC_Start()、HAL_UART_Abort()。
移植要点：控制接口内部应封装硬件寄存器操作或外设指令序列，上层调用者无需关心底层是 GPIO 电平翻转还是 SPI 命令写入。移植时只需替换底层寄存器地址与操作时序。
4.2 数据接口（Data Interface）
数据接口负责在 HAL 层与上层模块之间传输数据块。与控制接口不同，数据接口关注的是数据内容的搬运，而非设备动作的触发。数据接口通常包含读/写两个方向，并可能涉及 DMA、中断或轮询三种传输模式。
| 传输模式 | 特点 | 适用场景 | 典型接口 |
|---|---|---|---|
| 轮询（Polling） | CPU 循环等待，占用高 | 数据量小、实时性要求低 | HAL_SPI_Transmit() |
| 中断（Interrupt） | 非阻塞，CPU 可处理其他任务 | 数据量中等、响应要求高 | HAL_UART_Receive_IT() |
| DMA（Direct Memory Access） | 硬件搬运，CPU 零参与 | 大数据量、高速传输 | HAL_I2C_Mem_Read_DMA() |
移植陷阱：不同 MCU 的 DMA 通道映射、FIFO 深度、对齐要求差异巨大。数据接口的 HAL 层必须将 DMA 配置参数（如源地址递增、数据宽度）封装在内部，上层只传递缓冲区指针与长度。
4.3 配置接口（Configuration Interface）
配置接口用于在运行时或初始化阶段设置硬件设备的工作参数。这类接口通常接受结构体指针作为参数，结构体中包含所有可配置项。配置接口的设计质量直接影响驱动的灵活性与可移植性。
- 典型参数：波特率、采样率、极性、阈值、工作模式、滤波器系数。
- 设计模式：使用配置结构体（Configuration Struct）集中管理，避免散落的 Set/Get 函数。
- 生命周期：配置接口通常在初始化阶段调用一次，部分参数支持运行时动态调整。
// 推荐的配置接口设计模式
typedef struct {
uint32_t baudrate; // 波特率
uint8_t data_bits; // 数据位：5/6/7/8
uint8_t stop_bits; // 停止位：1/1.5/2
uint8_t parity; // 校验位：NONE/ODD/EVEN
uint8_t flow_control; // 流控：NONE/RTS/CTS/RTS_CTS
} HAL_UART_ConfigTypeDef;
HAL_StatusTypeDef HAL_UART_Init(UART_HandleTypeDef *huart,
HAL_UART_ConfigTypeDef *config);
移植最佳实践：配置结构体中的参数应使用平台无关的数据类型（如 uint32_t、uint8_t），避免直接暴露硬件寄存器位域。不同 MCU 的时钟频率差异应在 HAL 层内部通过预编译宏或查表方式补偿，上层配置接口保持不变。
4.4 状态接口（Status Interface）
状态接口用于查询硬件设备的当前运行状态、错误标志或资源占用情况。这类接口是只读的，不会改变硬件状态。状态接口通常返回一个状态结构体或枚举值，包含设备级与通道级的状态信息。
| 状态类别 | 典型状态量 | 接口示例 |
|---|---|---|
| 设备状态 | 就绪/忙碌/错误/超时 | HAL_ADC_GetState() |
| 错误状态 | 溢出/帧错误/校验错误/仲裁丢失 | HAL_CAN_GetError() |
| 资源状态 | FIFO 剩余深度/DMA 传输进度 | HAL_UART_GetRxFifoLevel() |
4.5 事件回调接口（Event Callback Interface）
事件回调接口是 HAL 层向上层模块主动通知异步事件的机制。当硬件发生特定事件（如数据接收完成、传输错误、DMA 传输结束）时，HAL 层通过注册的函数指针调用上层处理函数。这是实现非阻塞驱动的关键接口类型。
- 注册方式：在初始化阶段通过结构体或单独的函数注册回调函数指针。
- 调用上下文：通常在中断服务函数（ISR）中被调用，因此回调函数必须短小、不可阻塞。
- 弱定义机制：HAL 层提供
__weak默认实现，允许上层选择性覆盖。
// 事件回调接口设计示例
typedef struct {
void (*TxCpltCallback)(UART_HandleTypeDef *huart); // 发送完成
void (*RxCpltCallback)(UART_HandleTypeDef *huart); // 接收完成
void (*ErrorCallback)(UART_HandleTypeDef *huart); // 错误发生
void (*AbortCpltCallback)(UART_HandleTypeDef *huart); // 中止完成
} HAL_UART_CallbackTypeDef;
// 弱定义默认实现（可被上层覆盖）
__weak void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart) {
// 默认空实现，用户可重写
}
关键约束：回调函数在 ISR 上下文中执行，严禁在回调内部调用可能引起阻塞的 HAL 接口（如
HAL_Delay()、HAL_UART_Transmit() 轮询模式）。如需复杂处理，应使用“中断下半部”机制（如任务通知、信号量）将处理推迟到任务上下文。
4.6 五类接口的协作关系
在实际的 HAL 驱动中，五类接口并非孤立存在，而是相互配合形成完整的驱动生命周期。以下表格总结了各类接口的协作场景：
| 场景 | 控制接口 | 数据接口 | 配置接口 | 状态接口 | 事件回调 |
|---|---|---|---|---|---|
| 初始化 | — | — | 调用配置 | 查询就绪 | 注册回调 |
| 数据传输 | 启动传输 | 读写数据 | 调整参数 | 查询进度 | 传输完成 |
| 错误处理 | 中止操作 | — | 重新配置 | 读取错误码 | 错误通知 |
| 低功耗管理 | 进入/退出 | — | 设置唤醒源 | 查询电源状态 | 唤醒通知 |
架构建议：在 HAL 层代码组织上，建议将五类接口分别放在独立的源文件中（如
hal_uart_control.c、hal_uart_data.c、hal_uart_config.c、hal_uart_status.c、hal_uart_callback.c），便于移植时按需替换。头文件可统一暴露，但内部实现完全解耦。