4、I2C驱动架构：Zephyr I2C子系统层次、核心API接口与驱动注册机制

Zephyr RTOS 的 I2C 子系统采用分层架构设计，将硬件操作细节与上层应用逻辑解耦。理解这一架构层次、核心 API 以及驱动注册机制，是进行 I2C 从机适配与工程移植的基础。本章将深入剖析这三个关键部分。

4.1 I2C子系统层次结构

Zephyr 的 I2C 驱动栈从上到下分为三个主要层次：应用层、API 层 和 驱动层。这种分层设计使得开发者无需关心底层寄存器细节，即可通过统一的接口操作不同硬件平台上的 I2C 设备。

下图展示了 Zephyr I2C 子系统的完整层次架构与数据流向：

4.2 核心API接口详解

Zephyr 提供了一套完整且统一的 I2C API，用于执行总线事务。最核心的三个函数是 i2c_transfer、i2c_write 和 i2c_read。理解它们的差异与适用场景，是正确使用 I2C 子系统的关键。

以下是一个使用 i2c_transfer 进行组合读写的典型代码示例：

#include <zephyr/drivers/i2c.h>

/* 假设 dev 是已绑定的 I2C 设备，addr 是从机地址 */
int i2c_read_register(const struct device *dev, uint16_t addr,
                      uint8_t reg, uint8_t *data, uint32_t len)
{
    struct i2c_msg msgs[2];
    uint8_t reg_buf = reg;

    /* 消息0：写寄存器地址 */
    msgs[0].buf = &reg_buf;
    msgs[0].len = 1;
    msgs[0].flags = I2C_MSG_WRITE;

    /* 消息1：读数据 */
    msgs[1].buf = data;
    msgs[1].len = len;
    msgs[1].flags = I2C_MSG_READ | I2C_MSG_STOP;

    return i2c_transfer(dev, msgs, 2, addr);
}

4.3 驱动注册机制

Zephyr 使用 设备驱动模型 (Device Driver Model, DDM) 来管理所有外设驱动。I2C 驱动通过 DEVICE_DEFINE 或 I2C_DEVICE_DEFINE 宏进行注册，并填充 struct i2c_driver_api 结构体，将硬件操作函数暴露给上层 API 层。

驱动注册的核心流程如下：

1. 定义驱动 API 结构体：实现 configure、transfer 等回调函数。
2. 定义设备配置与数据：使用 struct i2c_config 和自定义数据结构保存硬件信息。
3. 调用注册宏：使用 I2C_DEVICE_DEFINE 将驱动绑定到设备树节点。
4. 初始化函数：在系统启动时完成硬件复位、时钟使能等操作。

下图展示了 I2C 驱动从注册到调用的完整生命周期：

以下是一个简化的 I2C 从机驱动注册代码示例，展示了 i2c_driver_api 的填充方式：

#include <zephyr/drivers/i2c.h>

/* 驱动私有数据结构 */
struct i2c_my_slave_config {
    uint32_t base_addr;
    uint32_t clock_freq;
};

/* 实现 transfer 回调 */
static int my_i2c_transfer(const struct device *dev,
                           struct i2c_msg *msgs,
                           uint8_t num_msgs,
                           uint16_t addr)
{
    /* 硬件寄存器操作逻辑 */
    return 0;
}

/* 实现 configure 回调 */
static int my_i2c_configure(const struct device *dev,
                            uint32_t config)
{
    /* 配置时钟、模式等 */
    return 0;
}

/* 填充驱动 API 结构体 */
static const struct i2c_driver_api my_i2c_api = {
    .configure = my_i2c_configure,
    .transfer = my_i2c_transfer,
};

/* 使用宏注册驱动 */
#define I2C_MY_SLAVE_INIT(n)                                         \
    static struct i2c_my_slave_config my_i2c_config_##n = {          \
        .base_addr = DT_REG_ADDR(DT_DRV_INST(n)),                    \
        .clock_freq = DT_PROP(DT_DRV_INST(n), clock_frequency),     \
    };                                                               \
    DEVICE_DT_INST_DEFINE(n,                                         \
                          my_i2c_init,                               \
                          NULL,                                      \
                          NULL,                                      \
                          &my_i2c_config_##n,                        \
                          POST_KERNEL,                               \
                          CONFIG_I2C_INIT_PRIORITY,                  \
                          &my_i2c_api);

/* 为每个实例生成驱动 */
DT_INST_FOREACH_STATUS_OKAY(I2C_MY_SLAVE_INIT)

4.4 关键数据结构对比

在 I2C 驱动开发中，理解几个关键数据结构的职责至关重要。下表对比了 i2c_driver_api、i2c_msg 和 i2c_config 的用途：