📚 课程目录第2章硬件抽象层(HAL)设计

硬件抽象层(HAL)设计：让代码与芯片解耦的艺术

做嵌入式移植，最头疼的是什么？我猜很多人会说：「换一颗芯片，代码重写一遍」。没错，这就是没有硬件抽象层的下场。今天咱们聊聊HAL——这个让嵌入式软件真正可移植的基石。

HAL的概念与作用

硬件抽象层，说白了就是在芯片寄存器和你写的业务逻辑之间，加一层「翻译官」。它不关心底层寄存器怎么配，只提供统一的接口。

举个例子。你写了一个LED闪烁程序，用STM32时操作GPIOB->ODR，换成GD32就得改GPIOB->BSRR。有了HAL，你只需要调用hal_gpio_write(LED_PIN, 1)，底层怎么实现，HAL帮你搞定。

HAL的核心价值：

可移植性：换芯片不改上层代码
可测试性：可以mock硬件接口做单元测试
可维护性：硬件变更只影响HAL层
代码复用：一套驱动库跑遍全系列芯片

我在一个物联网项目中吃过亏。当时团队赶进度，直接在应用层操作寄存器。后来客户要求换更低成本的芯片，好家伙，整整两个月都在改驱动代码。从那以后，我定了个规矩：任何项目，第一天先把HAL接口定义好。

HAL接口设计原则

设计HAL接口，我总结了四个字：稳、简、全、纯。

原则	说明	反面案例
稳	接口参数类型固定，不随芯片变化	用uint32_t传GPIO引脚号，而不是枚举
简	每个接口只做一件事	一个函数既初始化又读写还关中断
全	覆盖常用外设的典型操作	只提供发送不提供接收
纯	不掺杂业务逻辑	在HAL里做数据校验或协议解析

我的个人习惯：接口命名统一用 hal_<外设>_<操作> 格式。比如 hal_uart_send、hal_i2c_read。这样看函数名就知道它在哪一层。

典型HAL实现示例

咱们看三个最常用的外设：GPIO、UART、I2C。我直接上代码，边看边讲。

GPIO HAL

/* hal_gpio.h - 硬件抽象层GPIO接口 */
#ifndef HAL_GPIO_H
#define HAL_GPIO_H

#include <stdint.h>

/* 引脚电平定义 */
#define HAL_GPIO_LOW  0
#define HAL_GPIO_HIGH 1

/* 初始化GPIO引脚为输出模式 */
void hal_gpio_init_output(uint8_t pin);

/* 初始化GPIO引脚为输入模式 */
void hal_gpio_init_input(uint8_t pin);

/* 写引脚电平 */
void hal_gpio_write(uint8_t pin, uint8_t level);

/* 读引脚电平 */
uint8_t hal_gpio_read(uint8_t pin);

/* 翻转引脚电平 */
void hal_gpio_toggle(uint8_t pin);

#endif /* HAL_GPIO_H */

你看，接口里没有任何芯片相关的信息。pin 用 uint8_t，不管你是STM32的PA0还是GD32的PB1，上层代码不用改。

底层实现呢？以STM32为例：

/* hal_gpio_stm32.c - STM32平台实现 */
#include "hal_gpio.h"
#include "stm32f1xx_hal.h"

/* 引脚号到GPIO端口的映射表 */
static GPIO_TypeDef* port_map[] = {
    GPIOA, GPIOB, GPIOC, GPIOD
};

void hal_gpio_write(uint8_t pin, uint8_t level)
{
    uint8_t port = pin / 16;
    uint8_t bit  = pin % 16;
    
    if (level == HAL_GPIO_HIGH)
        HAL_GPIO_WritePin(port_map[port], 1 << bit, GPIO_PIN_SET);
    else
        HAL_GPIO_WritePin(port_map[port], 1 << bit, GPIO_PIN_RESET);
}

我曾经踩过的坑：一开始把引脚号直接映射到寄存器位，结果换芯片时引脚映射全乱套。后来统一用「端口号×16 + 引脚号」的编码方式，移植时只需要改映射表，上层代码纹丝不动。

UART HAL

/* hal_uart.h */
#ifndef HAL_UART_H
#define HAL_UART_H

#include <stdint.h>

/* UART配置参数 */
typedef struct {
    uint32_t baudrate;
    uint8_t  data_bits;    /* 5, 6, 7, 8 */
    uint8_t  stop_bits;    /* 1 or 2 */
    uint8_t  parity;       /* 0: none, 1: odd, 2: even */
} hal_uart_config_t;

/* 初始化UART */
int32_t hal_uart_init(uint8_t uart_id, hal_uart_config_t *cfg);

/* 发送数据 */
int32_t hal_uart_send(uint8_t uart_id, const uint8_t *data, uint32_t len);

/* 接收数据（阻塞） */
int32_t hal_uart_receive(uint8_t uart_id, uint8_t *buf, uint32_t len, uint32_t timeout_ms);

/* 注册接收回调（非阻塞） */
void hal_uart_set_rx_callback(uint8_t uart_id, void (*cb)(uint8_t data));

#endif /* HAL_UART_H */

这里有个设计细节：配置参数用结构体而不是分开传。为什么？你想想看，如果以后要加流控、加校验位，结构体只需要加字段，接口签名不用变。这就是「稳」的体现。

I2C HAL

/* hal_i2c.h */
#ifndef HAL_I2C_H
#define HAL_I2C_H

#include <stdint.h>

/* I2C传输标志 */
#define HAL_I2C_NO_STOP  0
#define HAL_I2C_GEN_STOP 1

/* 初始化I2C */
int32_t hal_i2c_init(uint8_t i2c_id, uint32_t speed_khz);

/* 写从设备 */
int32_t hal_i2c_write(uint8_t i2c_id, uint8_t slave_addr, 
                      const uint8_t *data, uint32_t len, uint8_t stop);

/* 读从设备 */
int32_t hal_i2c_read(uint8_t i2c_id, uint8_t slave_addr,
                     uint8_t *buf, uint32_t len);

/* 写后读（复合操作） */
int32_t hal_i2c_write_read(uint8_t i2c_id, uint8_t slave_addr,
                           const uint8_t *wdata, uint32_t wlen,
                           uint8_t *rbuf, uint32_t rlen);

#endif /* HAL_I2C_H */

I2C的接口我特别加了 write_read 这个复合操作。为什么？因为很多传感器（比如MPU6050）都是先写寄存器地址再读数据。如果拆成两次调用，中间可能被中断打断，导致通信失败。这是实战中总结出来的经验。

HAL层移植实战

好了，理论讲完，咱们来真的。假设你有一个项目，原来跑在STM32F103上，现在要移植到GD32F303上。怎么做？

第一步：分析差异

先列个表，看看两个芯片的外设差异：

外设	STM32F103	GD32F303	影响
GPIO	GPIOA~G，每组16脚	GPIOA~E，每组16脚	引脚映射表需调整
UART	USART1~3	USART0~4	外设编号不同
I2C	I2C1~2	I2C0~1	基地址和时钟配置不同

第二步：编写新平台的HAL实现

你不需要改 hal_gpio.h、hal_uart.h 这些头文件。只需要新建 hal_gpio_gd32.c、hal_uart_gd32.c，把接口函数用GD32的SDK重新实现一遍。

第三步：编译验证

把新文件加入工程，编译。如果报错，99%是映射表或时钟配置的问题。我一般先测GPIO——点亮一个LED，确认最基础的IO操作没问题，再测UART打印，最后测I2C通信。

避坑指南：移植时最容易出问题的是时钟配置。不同芯片的外设时钟树差异很大。我习惯在 hal_init 里统一做时钟使能，而不是分散在各个外设的初始化函数里。这样移植时只需要改一个地方。

下面这张图，是我做HAL层设计时常用的分层结构：

看到没？移植时你只需要动「HAL实现层」和「芯片SDK层」这两块。上面的应用层和HAL接口层，一个字都不用改。这就是HAL的魅力。

总结一下HAL移植的关键点：

接口先行：先定义好.h文件，再写实现
映射表驱动：用查表法处理引脚和外设编号的差异
时钟统一管理：在HAL初始化层集中配置时钟
分步验证：GPIO → UART → I2C，逐层确认

嗯，HAL这块内容就这些。说白了，它就是一层「薄薄的胶水」，把硬件和业务粘在一起，但又随时可以撕开换新的。做嵌入式移植，把这层设计好了，后面能省下大把头发。