2. Zephyr I2C 驱动架构：设备树绑定、驱动层、API层、硬件抽象层(HAL)的层次关系

Zephyr RTOS 的 I2C 驱动采用分层解耦设计，从上到下依次为：API 层、驱动层、硬件抽象层 (HAL)，并通过设备树绑定完成硬件描述与实例化。理解这四层的关系是进行时序故障排查的基础。

2.1 四层架构总览

下图展示了 Zephyr I2C 驱动的完整层次结构及数据流向：

2.2 设备树绑定层 (Device Tree Binding)

设备树是 Zephyr 硬件描述的核心机制。I2C 控制器及其从设备都在设备树中声明，编译时生成对应的宏定义供驱动使用。

2.2.1 I2C 控制器节点示例

// i2c1: i2c@40005400 {
//     compatible = "st,stm32-i2c-v2";
//     reg = <0x40005400 0x400>;
//     clocks = <&rcc STM32_CLOCK_BUS_APB1 0x20000000>;
//     interrupts = <31 0>, <32 0>;
//     interrupt-names = "event", "error";
//     pinctrl-0 = <&i2c1_sda_pb7 &i2c1_scl_pb6>;
//     pinctrl-names = "default";
//     status = "okay";
//     label = "I2C_1";
//     clock-frequency = <I2C_BITRATE_STANDARD>;  // 100kHz
// };

2.2.2 关键绑定字段说明

2.3 驱动层 (Driver Layer)

驱动层是 I2C 时序控制的核心，负责实现 API 层定义的标准接口，并直接操作 HAL 层提供的寄存器读写宏。

2.3.1 驱动层核心结构

// 驱动实例结构体
struct i2c_stm32_data {
    const struct device *clock;
    uint32_t bitrate_cfg;          // 从设备树解析的时钟配置
    struct k_sem bus_lock;         // 总线锁，防止并发访问
    uint32_t state;                // 当前状态：空闲/忙/错误
};

// 驱动配置结构体（编译时生成）
struct i2c_stm32_config {
    uint32_t base_addr;            // 从 DT_REG_ADDR 获取
    uint32_t clock_frequency;      // 从 DT_PROP 获取
    const struct pinctrl_dev_config *pcfg;
};

2.3.2 驱动层关键函数与时序关系

2.3.3 驱动层时序配置流程

static int i2c_stm32_configure(const struct device *dev, uint32_t dev_config)
{
    const struct i2c_stm32_config *cfg = dev->config;
    struct i2c_stm32_data *data = dev->data;

    // 1. 从设备树获取目标频率
    uint32_t target_freq = cfg->clock_frequency;

    // 2. 计算分频系数（HAL 层宏）
    uint32_t timingr = stm32_i2c_calc_timing(target_freq, 
                                              SystemCoreClock);
    // 3. 写入 TIMINGR 寄存器（HAL 层操作）
    __HAL_I2C_TIMINGR_CONFIG(data->base_addr, timingr);

    // 4. 验证实际频率（调试用）
    uint32_t actual_freq = stm32_i2c_get_actual_freq(timingr);
    if (abs(actual_freq - target_freq) > target_freq / 10) {
        return -EINVAL;  // 频率偏差超过 10%
    }
    return 0;
}

2.4 API 层 (Application Programming Interface)

API 层定义在 include/drivers/i2c.h，提供与硬件无关的标准接口。应用层和子系统（如 sensor、eeprom）通过 API 层调用驱动。

2.4.1 核心 API 函数

2.4.2 API 层消息结构体

struct i2c_msg {
    uint8_t  *buf;      // 数据缓冲区
    uint32_t len;       // 数据长度（字节）
    uint16_t flags;     // 标志位：读/写/停止位/起始位
};

// flags 常用值：
// I2C_MSG_WRITE       = 0x00,  // 写操作
// I2C_MSG_READ        = 0x01,  // 读操作
// I2C_MSG_STOP        = 0x02,  // 传输结束后发送停止位
// I2C_MSG_RESTART     = 0x04,  // 发送重复起始位

2.5 硬件抽象层 (HAL)

HAL 层位于驱动层之下，直接操作硬件寄存器。Zephyr 支持多种 HAL 实现：STM32 HAL、NXP MCUX、Silicon Labs EMLIB 等。

2.5.1 HAL 层核心操作

// STM32 HAL 示例：I2C 寄存器操作宏
#define __HAL_I2C_ENABLE(__HANDLE__) \
    SET_BIT((__HANDLE__)->Instance->CR1, I2C_CR1_PE)

#define __HAL_I2C_GENERATE_START(__HANDLE__) \
    SET_BIT((__HANDLE__)->Instance->CR2, I2C_CR2_START)

#define __HAL_I2C_GENERATE_STOP(__HANDLE__) \
    SET_BIT((__HANDLE__)->Instance->CR2, I2C_CR2_STOP)

// 时序关键寄存器：TIMINGR
#define __HAL_I2C_TIMINGR_CONFIG(__HANDLE__, __TIMINGR__) \
    WRITE_REG((__HANDLE__)->Instance->TIMINGR, (__TIMINGR__))

2.5.2 HAL 层与驱动层的接口

2.6 层次间数据流与故障排查路径

下图展示了 I2C 配置数据从设备树到 HAL 寄存器的完整流动路径：

2.7 层次间常见时序故障对照表