【嵌入式高级开发】23 分层架构与HAL设计_从模块化到平台无关

分层架构与HAL设计：从模块化到平台无关

本文探讨嵌入式系统中分层架构的设计范式及其在硬件抽象层（HAL）中的工程实践。核心观点包括：分层架构的本质不是"代码分文件夹"，而是依赖关系的单向约束；HAL不是"驱动函数的重新命名"，而是硬件能力与软件需求之间的翻译层；Zephyr的Device Model通过"设备树声明 + 函数指针API + 编译期初始化"的三元组合，实现了嵌入式领域最接近工业标准的跨平台抽象；理解分层架构的代价与收益，是从"写能工作的代码"到"设计能演进的系统"的思维跃迁。

---

一、核心矛盾：为什么"分文件夹"不等于分层架构？

1.1 问题驱动：一个"分层了但没有真正分层"的项目

假设你接手了一个"已经分层"的嵌入式项目，目录结构如下：

project/
├── app/
│   ├── main.c
│   └── temperature_monitor.c
├── hal/
│   ├── hal_i2c.c
│   ├── hal_spi.c
│   └── hal_gpio.c
├── driver/
│   ├── sht30.c          /* 温湿度传感器 */
│   ├── lcd_st7789.c     /* 显示屏 */
│   └── flash_w25q.c     /* 外部Flash */
└── bsp/
    └── board_init.c

看起来层次分明，但打开代码后你发现：

• temperature_monitor.c 直接调用了 HAL_I2C_Mem_Read()，跳过了中间所有层
• sht30.c 里硬编码了GPIO引脚号 GPIO_PIN_5，而这个引脚在另一块板子上是 GPIO_PIN_7
• hal_i2c.c 里出现了 printf("I2C timeout, retrying...") —— HAL层在打印日志，这是应用层的职责
• board_init.c 里同时配置了时钟、初始化了传感器、设置了LED状态——BSP层在干应用层的活

**核心矛盾：物理上的文件分层不等于逻辑上的依赖分层。真正的分层架构约束的是"谁可以调用谁"，而不是"文件放在哪个文件夹"。当依赖关系混乱时，分层只是装饰性的目录结构。**citeweb_search:20#1web_search:20#11

1.2 物理直觉：依赖关系的单向性

分层架构的黄金法则是单向依赖——上层可以调用下层，下层绝不可以调用上层。这种约束不是人为的代码规范，而是信息隐藏原理在软件架构中的直接映射。

想象一个工厂的生产线：

• 原材料（硬件）进入底层
• 经过加工（驱动层处理寄存器）
• 组装成零件（HAL层提供统一接口）
• 组合成产品（中间件层提供功能模块）
• 最终交付给客户（应用层实现业务逻辑）

如果零件供应商（HAL层）可以直接联系客户（应用层）修改订单，或者原材料供应商（驱动层）可以决定产品的外观设计，这个工厂的生产流程就会崩溃。软件架构同理。citeweb_search:20#1

1.3 工程启示：四层模型的职责边界

在嵌入式领域，一个实用的分层模型通常包含四层：citeweb_search:20#1web_search:20#11

层级	职责	核心问题	反模式
应用层（Application）	业务逻辑、用户交互、数据流编排	“用户想要什么？”	直接操作寄存器、硬编码硬件参数
中间件层（Middleware）	协议栈、算法库、RTOS抽象	“功能如何组合？”	混入硬件细节、与特定RTOS绑定
HAL层（Hardware Abstraction）	统一硬件接口、屏蔽芯片差异	“硬件能做什么？”	简单封装厂商库函数、不做语义转换
驱动层（Driver）	寄存器操作、中断处理、DMA配置	“如何操作寄存器？”	包含业务逻辑、直接调用上层回调

关键洞察：HAL层不是"把HAL_GPIO_WritePin改成gpio_set_pin"这种命名层面的封装。真正的HAL需要完成语义转换——将硬件的"引脚电平高低"转换为应用的"LED亮灭"，将"I2C地址+寄存器"转换为"读取温度值"。

1.4 现代延伸：从四层到六层的演进

在更复杂的系统中（如Linux、Zephyr），四层模型会进一步细化：citeweb_search:20#11

扩展层级	新增职责	典型代表
Arch层	CPU架构抽象（ARM/RISC-V/x86）	Zephyr的arch/目录
SOC层	芯片级抽象（时钟、电源、复位）	Zephyr的soc/目录
Board层	板级抽象（引脚复用、外设连接）	Zephyr的boards/目录

这种细化的价值在于：当从STM32F103迁移到STM32F407时，只需更换SOC层和Board层，HAL层以上的代码完全不变。

---

二、HAL的本质：硬件能力与软件需求的翻译层

2.1 核心矛盾：厂商HAL库为什么不是真正的HAL？

STM32的HAL库、Nordic的nrfx库、ESP-IDF的driver库——这些厂商提供的库通常被直接称为"HAL"，但它们本质上只是寄存器操作的封装，而非真正的硬件抽象。citeweb_search:20#13

真正的HAL需要回答三个问题：

1. 能力抽象：硬件能做什么？（如"发送数据"而非"写DR寄存器"）
2. 语义转换：如何将硬件能力映射到软件需求？（如"读取温度"而非"I2C读0x44地址"）
3. 平台无关：同一套接口如何在不同芯片上实现？

2.2 物理直觉：HAL是"契约"而非"封装"

厂商库封装的是"如何操作硬件"，HAL定义的是"硬件承诺提供什么服务"。两者的差异可以用一个类比理解：

• 厂商库像是汽车维修手册——告诉你如何拆开引擎、调整气门
• HAL像是驾驶执照考试标准——定义了"加速"、“刹车”、"转向"的统一操作规范，不关心引擎是V6还是V8

HAL的核心价值在于：让上层代码只依赖"能力契约"，而不依赖"实现细节"。

2.3 工程启示：HAL接口设计的五个原则

/* 原则1：接口命名描述能力，而非操作 */
/* 差 */
int hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);
/* 好 */
int sensor_bus_write(uint8_t dev_addr, uint8_t reg_addr, const uint8_t *data, uint16_t len);

/* 原则2：配置与操作分离 */
typedef struct {
    uint32_t frequency;      /* 总线频率 */
    uint8_t  addr_mode;      /* 7位或10位地址 */
} i2c_bus_cfg_t;

int i2c_bus_init(i2c_bus_t *bus, const i2c_bus_cfg_t *cfg);
int i2c_bus_transfer(i2c_bus_t *bus, uint8_t dev_addr, 
                     const uint8_t *tx_data, uint16_t tx_len,
                     uint8_t *rx_data, uint16_t rx_len);

/* 原则3：错误码语义化 */
typedef enum {
    HAL_OK = 0,
    HAL_ERR_INVALID_PARAM,   /* 参数错误 */
    HAL_ERR_TIMEOUT,         /* 操作超时 */
    HAL_ERR_BUS_BUSY,        /* 总线被占用 */
    HAL_ERR_DEVICE_NACK,     /* 设备无响应 */
    HAL_ERR_DMA_ERROR        /* DMA传输错误 */
} hal_status_t;

/* 原则4：上下文指针支持多实例 */
typedef struct i2c_bus i2c_bus_t;  /* 不透明类型 */

/* 原则5：异步回调接口 */
typedef void (*i2c_transfer_cb_t)(hal_status_t status, void *user_ctx);
int i2c_bus_transfer_async(i2c_bus_t *bus, /* ... */, i2c_transfer_cb_t cb, void *user_ctx);

反直觉发现：好的HAL接口应该让使用者不需要知道底层硬件是什么芯片。如果你发现自己在写#ifdef STM32F1xx或#ifdef NRF52840这样的条件编译，说明HAL的抽象层级还不够高，或者抽象边界画错了。

2.4 现代延伸：Zephyr的Device Model——HAL的工业级实现

Zephyr RTOS的Device Model是嵌入式领域最接近工业标准的HAL设计。其核心数据结构是一个极简的设备描述符：citeweb_search:20#5web_search:20#7

struct device {
    const char *name;        /* 设备名称 */
    const void *config;      /* 只读配置（寄存器地址、IRQ号等） */
    const void *api;         /* API函数指针表 */
    void * const data;       /* 运行时可变数据（信号量、缓冲区等） */
};

这个设计的精妙之处在于三元分离：

• config：编译期确定的硬件参数（通过设备树注入）
• api：编译期确定的函数指针表（驱动注册时填充）
• data：运行期可变的状态数据（每个设备实例独立）

上层应用通过统一的子系统API访问设备，而驱动程序通过填充api结构体提供具体实现。这种"接口与实现分离"的模式，与Linux内核的file_operations结构体一脉相承，但更加轻量，适合资源受限的嵌入式设备。citeweb_search:20#6web_search:20#9

---

三、Zephyr Device Model深度解析

3.1 核心矛盾：如何在编译期完成设备初始化？

传统嵌入式开发中，设备初始化通常发生在main()函数中，按顺序调用各驱动的init()函数。这种方式的问题是：

• 初始化顺序依赖开发者手动维护
• 新增设备需要修改main()函数
• 不同板卡的初始化代码差异大，难以复用

Zephyr的解决方案是编译期设备注册 + 初始化等级排序。citeweb_search:20#7web_search:20#0

3.2 物理直觉：链接器段与初始化顺序

Zephyr通过GCC的__attribute__((section(...)))扩展，将设备结构体放置到特定的内存段中：

#define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn,                       data, cfg_info, level, prio, api)                  static const struct device_config _CONCAT(__config_, dev_name)           __attribute__((__section__(".devconfig.init"))) = {                     .name = drv_name,                                                   .init = (init_fn),                                                  .config_info = (cfg_info)                                       };                                                              static struct device _CONCAT(__device_, dev_name)                      __attribute__((__section__(".init_" #level #prio))) = { .config = &_CONCAT(__config_, dev_name), .driver_api = api, .driver_data = data }

链接脚本将这些段按初始化等级排序，内核启动时按顺序遍历并调用init()函数。这种设计的工程价值在于：citeweb_search:20#7

• 声明即注册：驱动开发者只需调用DEVICE_DEFINE宏，无需修改任何全局初始化列表
• 等级化初始化：PRE_KERNEL_1（最早，如中断控制器）→ PRE_KERNEL_2（如定时器）→ POST_KERNEL（如串口）→ APPLICATION（应用级设备）
• 同等级优先级：同一等级内的设备按prio参数排序

3.3 工程启示：设备树与驱动的绑定

Zephyr使用**设备树（DeviceTree）**描述硬件拓扑，驱动程序通过设备树节点获取硬件参数。这种"硬件描述与驱动代码分离"的范式，是HAL设计的最高形态。citeweb_search:20#0web_search:20#3

/* 设备树片段：I2C总线上的温湿度传感器 */
&i2c1 {
    sht30@44 {
        compatible = "sensirion,sht30";
        reg = <0x44>;
        label = "SHT30";
        status = "okay";
    };
};

/* 驱动代码：通过设备树宏获取配置 */
#define SHT30_DT_INST(inst) DT_INST(inst, sensirion_sht30)

static const struct sht30_config sht30_cfg_0 = {
    .bus = DEVICE_DT_GET(DT_PARENT(SHT30_DT_INST(0))),
    .addr = DT_REG_ADDR(SHT30_DT_INST(0)),
};

static struct sht30_data sht30_data_0;

/* 注册设备：编译期完成 */
DEVICE_DT_DEFINE(SHT30_DT_INST(0), sht30_init, NULL,
                 &sht30_data_0, &sht30_cfg_0,
                 POST_KERNEL, CONFIG_SENSOR_INIT_PRIORITY,
                 &sht30_api);

关键洞察：DEVICE_DT_DEFINE宏在编译期完成了三件事：

1. 从设备树提取硬件参数（I2C总线引用、设备地址）
2. 创建device结构体并放入初始化段
3. 将驱动API与设备实例绑定

这意味着：**应用程序运行时，所有设备已经初始化完毕，直接通过device_get_binding()或DEVICE_DT_GET()获取设备句柄即可使用。**citeweb_search:20#0

3.4 现代延伸：API继承与多态

Zephyr的Device Model支持API继承，允许子系统扩展父系统的API：citeweb_search:20#5

/* 父API：通用传感器 */
__subsystem struct sensor_driver_api {
    int (*sample_fetch)(const struct device *dev, enum sensor_channel chan);
    int (*channel_get)(const struct device *dev, enum sensor_channel chan,
                       struct sensor_value *val);
};

/* 子API：温湿度传感器扩展 */
__subsystem struct temp_humidity_driver_api {
    struct sensor_driver_api parent_api;  /* 必须作为第一个成员 */
    int (*set_heater)(const struct device *dev, bool enable);
};

/* 驱动实现 */
static DEVICE_API(temp_humidity, sht30_api) = {
    .parent_api = {
        .sample_fetch = sht30_sample_fetch,
        .channel_get = sht30_channel_get,
    },
    .set_heater = sht30_set_heater,
};

这种设计的价值在于：一个实现了temp_humidityAPI的设备，同时也可以被当作sensor设备使用。这是C语言中结构体继承的经典模式，与Linux内核的container_of宏异曲同工。

---

四、实战：虚拟温湿度传感器的HAL设计

4.1 核心矛盾：如何为一个不存在的硬件设计HAL？

设计HAL的最佳实践是先设计接口，再实现驱动。这种"接口优先"的方法强迫开发者从"使用者视角"思考，而不是从"硬件能力视角"思考。以下为一个虚拟温湿度传感器SHT30设计完整的HAL。citeweb_search:20#1

4.2 物理直觉：从需求到接口的逆向推导

假设应用层的需求是：

• 读取当前温度（摄氏度，保留两位小数）
• 读取当前湿度（百分比，保留两位小数）
• 设置采样精度（低/中/高）
• 启用/禁用内部加热器（用于防结露）
• 获取设备状态（正常/故障/校准中）

从这些需求出发，HAL接口应该屏蔽所有I2C协议细节。

4.3 工程启示：完整的HAL实现

第一步：定义HAL接口（sht30_hal.h）

#ifndef SHT30_HAL_H
#define SHT30_HAL_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* 前向声明：隐藏实现细节 */
struct sht30_device;

/* 采样精度 */
typedef enum {
    SHT30_PRECISION_LOW,     /* 单次采样，低功耗 */
    SHT30_PRECISION_MEDIUM,  /* 默认精度 */
    SHT30_PRECISION_HIGH     /* 最高精度，功耗最大 */
} sht30_precision_t;

/* 设备状态 */
typedef enum {
    SHT30_STATUS_OK,
    SHT30_STATUS_BUSY,       /* 正在采样 */
    SHT30_STATUS_ERROR,      /* 通信错误 */
    SHT30_STATUS_CALIBRATE   /* 校准中 */
} sht30_status_t;

/* 温湿度数据 */
typedef struct {
    int16_t temperature;   /* 摄氏度 × 100（如 2510 表示 25.10°C） */
    uint16_t humidity;     /* 百分比 × 100（如 4560 表示 45.60%） */
    uint32_t timestamp;    /* 采样时间戳 */
} sht30_reading_t;

/* 设备配置 */
typedef struct {
    sht30_precision_t precision;
    bool heater_enabled;
    uint16_t sample_interval_ms;  /* 自动采样间隔，0表示手动 */
} sht30_config_t;

/* 默认配置 */
#define SHT30_DEFAULT_CONFIG {     .precision = SHT30_PRECISION_MEDIUM,     .heater_enabled = false,     .sample_interval_ms = 0 }

/* 回调函数类型 */
typedef void (*sht30_callback_t)(const sht30_reading_t *reading, void *user_ctx);

/* API函数 */

/**
 * @brief 初始化SHT30设备
 * @param bus_name I2C总线设备名称（如"I2C_1"）
 * @param dev_addr I2C设备地址（通常为0x44或0x45）
 * @param cfg 配置参数，NULL则使用默认配置
 * @return 设备句柄，NULL表示失败
 */
struct sht30_device *sht30_init(const char *bus_name, uint8_t dev_addr,
                                   const sht30_config_t *cfg);

/**
 * @brief 反初始化，释放资源
 */
void sht30_deinit(struct sht30_device *dev);

/**
 * @brief 单次采样（阻塞模式）
 * @return 0成功，负值错误码
 */
int sht30_sample(struct sht30_device *dev, sht30_reading_t *reading);

/**
 * @brief 启动连续采样（非阻塞，通过回调返回数据）
 */
int sht30_start_continuous(struct sht30_device *dev, sht30_callback_t cb, void *user_ctx);

/**
 * @brief 停止连续采样
 */
int sht30_stop_continuous(struct sht30_device *dev);

/**
 * @brief 设置采样精度
 */
int sht30_set_precision(struct sht30_device *dev, sht30_precision_t precision);

/**
 * @brief 控制内部加热器
 */
int sht30_set_heater(struct sht30_device *dev, bool enable);

/**
 * @brief 获取设备状态
 */
sht30_status_t sht30_get_status(const struct sht30_device *dev);

/**
 * @brief 软复位设备
 */
int sht30_soft_reset(struct sht30_device *dev);

#ifdef __cplusplus
}
#endif

#endif /* SHT30_HAL_H */

第二步：实现HAL层（sht30_hal.c）

#include "sht30_hal.h"
#include "i2c_bus.h"   /* 底层I2C总线HAL */
#include <string.h>
#include <stdlib.h>

/* SHT30命令定义 */
#define SHT30_CMD_MEAS_HIGH    0x2C06  /* 高精度测量 */
#define SHT30_CMD_MEAS_MEDIUM  0x2C0D  /* 中精度测量 */
#define SHT30_CMD_MEAS_LOW     0x2C10  /* 低精度测量 */
#define SHT30_CMD_READ_STATUS  0xF32D  /* 读取状态 */
#define SHT30_CMD_SOFT_RESET   0x30A2  /* 软复位 */
#define SHT30_CMD_HEATER_ON    0x306D  /* 加热器开启 */
#define SHT30_CMD_HEATER_OFF   0x3066  /* 加热器关闭 */

/* 设备实例结构体（对上层隐藏） */
struct sht30_device {
    i2c_bus_t *bus;              /* I2C总线句柄 */
    uint8_t addr;                /* I2C地址 */
    sht30_config_t config;      /* 当前配置 */
    sht30_status_t status;      /* 当前状态 */
    sht30_callback_t callback;  /* 连续采样回调 */
    void *callback_ctx;          /* 回调上下文 */
    bool continuous_mode;       /* 是否处于连续采样模式 */
};

/* 精度到命令的映射 */
static uint16_t precision_cmd_map[] = {
    [SHT30_PRECISION_LOW]    = SHT30_CMD_MEAS_LOW,
    [SHT30_PRECISION_MEDIUM] = SHT30_CMD_MEAS_MEDIUM,
    [SHT30_PRECISION_HIGH]   = SHT30_CMD_MEAS_HIGH,
};

/* CRC8校验（SHT30使用） */
static uint8_t sht30_crc8(const uint8_t *data, uint8_t len) {
    uint8_t crc = 0xFF;
    for (uint8_t i = 0; i < len; i++) {
        crc ^= data[i];
        for (uint8_t j = 0; j < 8; j++) {
            crc = (crc & 0x80) ? ((crc << 1) ^ 0x31) : (crc << 1);
        }
    }
    return crc;
}

/* 发送命令 */
static int sht30_send_cmd(struct sht30_device *dev, uint16_t cmd) {
    uint8_t buf[2] = {cmd >> 8, cmd & 0xFF};
    return i2c_bus_write(dev->bus, dev->addr, buf, 2);
}

/* 读取测量数据 */
static int sht30_read_measurement(struct sht30_device *dev, sht30_reading_t *reading) {
    uint8_t buf[6];
    int ret = i2c_bus_read(dev->bus, dev->addr, buf, 6);
    if (ret != 0) {
        dev->status = SHT30_STATUS_ERROR;
        return ret;
    }

    /* 验证CRC */
    if (sht30_crc8(buf, 2) != buf[2] || sht30_crc8(buf + 3, 2) != buf[5]) {
        dev->status = SHT30_STATUS_ERROR;
        return -1;  /* CRC错误 */
    }

    /* 转换温度：T = -45 + 175 × (raw / 65535) */
    uint16_t temp_raw = (buf[0] << 8) | buf[1];
    reading->temperature = (int16_t)((-4500 + 17500 * temp_raw / 65535));

    /* 转换湿度：RH = 100 × (raw / 65535) */
    uint16_t hum_raw = (buf[3] << 8) | buf[4];
    reading->humidity = (uint16_t)(10000 * hum_raw / 65535);

    reading->timestamp = get_system_tick();  /* 假设有系统时钟 */
    dev->status = SHT30_STATUS_OK;

    return 0;
}

/* 初始化 */
struct sht30_device *sht30_init(const char *bus_name, uint8_t dev_addr,
                                   const sht30_config_t *cfg) {
    struct sht30_device *dev = malloc(sizeof(struct sht30_device));
    if (!dev) return NULL;

    memset(dev, 0, sizeof(*dev));

    dev->bus = i2c_bus_open(bus_name);
    if (!dev->bus) {
        free(dev);
        return NULL;
    }

    dev->addr = dev_addr;
    dev->config = cfg ? *cfg : (sht30_config_t)SHT30_DEFAULT_CONFIG;
    dev->status = SHT30_STATUS_OK;

    /* 软复位设备 */
    if (sht30_send_cmd(dev, SHT30_CMD_SOFT_RESET) != 0) {
        i2c_bus_close(dev->bus);
        free(dev);
        return NULL;
    }

    /* 等待复位完成（1ms） */
    delay_ms(1);

    return dev;
}

void sht30_deinit(struct sht30_device *dev) {
    if (!dev) return;
    if (dev->continuous_mode) {
        sht30_stop_continuous(dev);
    }
    i2c_bus_close(dev->bus);
    free(dev);
}

int sht30_sample(struct sht30_device *dev, sht30_reading_t *reading) {
    if (!dev || !reading) return -1;

    dev->status = SHT30_STATUS_BUSY;

    /* 发送测量命令 */
    uint16_t cmd = precision_cmd_map[dev->config.precision];
    if (sht30_send_cmd(dev, cmd) != 0) {
        dev->status = SHT30_STATUS_ERROR;
        return -1;
    }

    /* 等待测量完成（取决于精度） */
    uint16_t delay = (dev->config.precision == SHT30_PRECISION_HIGH) ? 15 :
                     (dev->config.precision == SHT30_PRECISION_MEDIUM) ? 6 : 4;
    delay_ms(delay);

    /* 读取数据 */
    return sht30_read_measurement(dev, reading);
}

int sht30_set_precision(struct sht30_device *dev, sht30_precision_t precision) {
    if (!dev || precision > SHT30_PRECISION_HIGH) return -1;
    dev->config.precision = precision;
    return 0;
}

int sht30_set_heater(struct sht30_device *dev, bool enable) {
    if (!dev) return -1;
    uint16_t cmd = enable ? SHT30_CMD_HEATER_ON : SHT30_CMD_HEATER_OFF;
    int ret = sht30_send_cmd(dev, cmd);
    if (ret == 0) {
        dev->config.heater_enabled = enable;
    }
    return ret;
}

sht30_status_t sht30_get_status(const struct sht30_device *dev) {
    return dev ? dev->status : SHT30_STATUS_ERROR;
}

int sht30_soft_reset(struct sht30_device *dev) {
    if (!dev) return -1;
    int ret = sht30_send_cmd(dev, SHT30_CMD_SOFT_RESET);
    if (ret == 0) {
        delay_ms(1);
    }
    return ret;
}

/* 连续采样（简化实现：基于定时器回调） */
static void sht30_timer_callback(void *ctx) {
    struct sht30_device *dev = ctx;
    if (!dev->continuous_mode) return;

    sht30_reading_t reading;
    if (sht30_read_measurement(dev, &reading) == 0 && dev->callback) {
        dev->callback(&reading, dev->callback_ctx);
    }
}

int sht30_start_continuous(struct sht30_device *dev, sht30_callback_t cb, void *user_ctx) {
    if (!dev || !cb || dev->continuous_mode) return -1;

    dev->callback = cb;
    dev->callback_ctx = user_ctx;
    dev->continuous_mode = true;

    /* 启动定时器（假设有软件定时器服务） */
    timer_start(dev->config.sample_interval_ms, sht30_timer_callback, dev);

    return 0;
}

int sht30_stop_continuous(struct sht30_device *dev) {
    if (!dev || !dev->continuous_mode) return -1;

    dev->continuous_mode = false;
    timer_stop(sht30_timer_callback, dev);

    return 0;
}

第三步：底层I2C总线HAL（i2c_bus.h / i2c_bus.c）

/* i2c_bus.h */
#ifndef I2C_BUS_H
#define I2C_BUS_H

#include <stdint.h>
#include <stddef.h>

/* 不透明的I2C总线句柄 */
typedef struct i2c_bus i2c_bus_t;

/* 打开I2C总线 */
i2c_bus_t *i2c_bus_open(const char *name);

/* 关闭I2C总线 */
void i2c_bus_close(i2c_bus_t *bus);

/* I2C写操作 */
int i2c_bus_write(i2c_bus_t *bus, uint8_t dev_addr, const uint8_t *data, uint16_t len);

/* I2C读操作 */
int i2c_bus_read(i2c_bus_t *bus, uint8_t dev_addr, uint8_t *data, uint16_t len);

/* I2C组合传输（写后读，用于寄存器访问） */
int i2c_bus_write_read(i2c_bus_t *bus, uint8_t dev_addr,
                        const uint8_t *tx_data, uint16_t tx_len,
                        uint8_t *rx_data, uint16_t rx_len);

#endif

/* i2c_bus.c - STM32 HAL实现示例 */
#include "i2c_bus.h"
#include "stm32f1xx_hal.h"  /* 厂商HAL库 */
#include <stdlib.h>
#include <string.h>

struct i2c_bus {
    I2C_HandleTypeDef *hi2c;  /* STM32 HAL句柄 */
    uint32_t timeout;
};

static I2C_HandleTypeDef hi2c1;  /* 全局HAL句柄 */

i2c_bus_t *i2c_bus_open(const char *name) {
    (void)name;  /* 简化：只支持I2C1 */

    i2c_bus_t *bus = malloc(sizeof(i2c_bus_t));
    if (!bus) return NULL;

    bus->hi2c = &hi2c1;
    bus->timeout = 100;  /* 100ms超时 */

    /* 初始化HAL I2C（假设MX_I2C1_Init已在其他地方调用） */
    return bus;
}

void i2c_bus_close(i2c_bus_t *bus) {
    free(bus);
}

int i2c_bus_write(i2c_bus_t *bus, uint8_t dev_addr, const uint8_t *data, uint16_t len) {
    HAL_StatusTypeDef status = HAL_I2C_Master_Transmit(
        bus->hi2c, dev_addr << 1, (uint8_t *)data, len, bus->timeout);
    return (status == HAL_OK) ? 0 : -1;
}

int i2c_bus_read(i2c_bus_t *bus, uint8_t dev_addr, uint8_t *data, uint16_t len) {
    HAL_StatusTypeDef status = HAL_I2C_Master_Receive(
        bus->hi2c, dev_addr << 1, data, len, bus->timeout);
    return (status == HAL_OK) ? 0 : -1;
}

int i2c_bus_write_read(i2c_bus_t *bus, uint8_t dev_addr,
                        const uint8_t *tx_data, uint16_t tx_len,
                        uint8_t *rx_data, uint16_t rx_len) {
    HAL_StatusTypeDef status = HAL_I2C_Mem_Read(
        bus->hi2c, dev_addr << 1, tx_data[0], I2C_MEMADD_SIZE_8BIT,
        rx_data, rx_len, bus->timeout);
    return (status == HAL_OK) ? 0 : -1;
}

第四步：应用层使用（app_temperature.c）

#include "sht30_hal.h"
#include <stdio.h>

static void on_temperature_read(const sht30_reading_t *reading, void *ctx) {
    (void)ctx;
    printf("Temperature: %d.%02d°C, Humidity: %d.%02d%%\n",
           reading->temperature / 100, abs(reading->temperature % 100),
           reading->humidity / 100, reading->humidity % 100);
}

void temperature_monitor_init(void) {
    sht30_config_t cfg = {
        .precision = SHT30_PRECISION_HIGH,
        .heater_enabled = false,
        .sample_interval_ms = 2000,  /* 每2秒采样 */
    };

    struct sht30_device *sht30 = sht30_init("I2C_1", 0x44, &cfg);
    if (!sht30) {
        printf("Failed to initialize SHT30\n");
        return;
    }

    /* 启动连续采样 */
    sht30_start_continuous(sht30, on_temperature_read, NULL);
}

4.4 现代延伸：向Zephyr Device Model的演进

上述HAL设计可以进一步演进为Zephyr风格的Device Model：

/* Zephyr风格的设备API定义 */
__subsystem struct sht30_driver_api {
    int (*sample)(const struct device *dev, struct sensor_value *temp,
                  struct sensor_value *hum);
    int (*set_precision)(const struct device *dev, sht30_precision_t precision);
    int (*set_heater)(const struct device *dev, bool enable);
};

/* 应用层通过统一设备接口访问 */
const struct device *sht30 = DEVICE_DT_GET(DT_NODELABEL(sht30));
struct sensor_value temp, hum;
sensor_sample_fetch(sht30);
sensor_channel_get(sht30, SENSOR_CHAN_AMBIENT_TEMP, &temp);
sensor_channel_get(sht30, SENSOR_CHAN_HUMIDITY, &hum);

这种演进的价值在于：应用层代码从"知道设备是SHT30"变为"知道需要温湿度数据"，实现了从"设备驱动"到"数据服务"的抽象升级。citeweb_search:20#0web_search:20#6

---

五、可视化架构

5.1 知识图谱

5.2 总体结构图

5.3 各模块设计图

5.4 协同设计图

5.5 接口对接图

5.6 完整三层架构总览图

5.7 时序/状态机图：HAL初始化流程

5.8 因果/根因链图：分层失效的根因

5.9 对比/权衡矩阵图：厂商库 vs 自定义HAL vs Zephyr Device Model

5.10 闭环控制详图：HAL错误处理链

5.11 链路预算分解图：HAL调用开销

---

六、总结：从代码到架构的认知跃迁

层级	机制	核心思想	与前面章节的呼应
语法层	头文件与接口声明	信息隐藏的语法载体	延续：模块化编译链接中的接口契约
结构层	四层/六层模型	依赖关系的单向约束	深化：从文件组织到调用关系的维度提升
语义层	HAL接口设计	能力抽象与语义转换	跃迁：从"操作硬件"到"提供服务"
系统层	Zephyr Device Model	编译期初始化与设备树绑定	综合：函数指针、内存对齐、模块化的大成
生态层	厂商驱动 + 社区生态	可复用性与可移植性的平衡	前瞻：为后续RTOS章节做铺垫

理解分层架构与HAL设计，不是学会如何创建文件夹和命名文件，而是建立一种**“架构视角”——当你面对一个新的硬件设备时，你看到的不是一堆需要操作的寄存器，而是一组需要被抽象的能力**、需要被翻译的语义、以及需要被约束的依赖关系。

这种视角让你能够：

• 预判"分层失效"的信号（跨层调用、职责泄漏、条件编译泛滥）
• 设计HAL接口时，从"使用者需要什么"出发，而非"硬件能提供什么"出发
• 评估Zephyr等工业级框架时，理解其设计决策背后的工程权衡
• 在资源受限与可维护性之间，做出符合项目阶段的理性选择

从"函数指针回调"到"有限状态机"，从"内存对齐位域"到"分层架构HAL"——这四篇文章构成了一条从"C语言语法"到"嵌入式系统设计"的完整认知路径。下一章，我们将在此基础上引入中断与异常——HAL在硬件事件驱动场景中的最硬核应用。

---

参考与延伸阅读

• Zephyr Project Documentation: Device Driver Model - 官方驱动模型文档
• Zephyr Project Documentation: Devicetree - 设备树使用指南
• 《嵌入式软件分层架构设计》- lucky-Tang，CSDN博客
• 《Linux设备驱动程序》第三版 - Jonathan Corbet 等，VFS与设备模型章节
• 《代码整洁之道》（Clean Code）- Robert C. Martin，依赖关系管理章节
• MISRA C:2012 Rule 8.1 - 类型应当显式声明