4. Linux I2C 核心框架：数据结构与核心 API

Linux I2C 核心框架是连接 I2C 总线控制器硬件与上层设备驱动的中间层。它通过三个核心数据结构——i2c_adapter、i2c_algorithm 和 i2c_client——实现了硬件无关的抽象。理解这些结构及其 API 是编写正确、高效的 I2C 从设备驱动的基石。

4.1 i2c_adapter：总线适配器

i2c_adapter 是 I2C 总线控制器的内核抽象。每个物理 I2C 控制器（如 SoC 中的 I2C 外设）在系统中对应一个 i2c_adapter 实例。它负责管理总线编号、关联的算法、设备链表以及电源管理。

4.2 i2c_algorithm：通信算法

i2c_algorithm 定义了适配器与 I2C 从设备进行通信的具体方法。它是硬件控制器驱动需要实现的核心接口。该结构体包含两组关键函数指针：主传输函数和从模式函数（较少用）。

struct i2c_algorithm {
    /* 主传输函数：发送 i2c_msg 数组 */
    int (*master_xfer)(struct i2c_adapter *adap,
                       struct i2c_msg *msgs,
                       int num);
    /* 主接收函数（已废弃，使用 master_xfer） */
    int (*master_recv)(struct i2c_adapter *adap,
                       struct i2c_msg *msg);
    /* 从模式传输函数 */
    int (*slave_xfer)(struct i2c_adapter *adap,
                      struct i2c_msg *msgs,
                      int num);
    /* 功能支持查询 */
    u32 (*functionality)(struct i2c_adapter *adap);
};

4.3 i2c_client：从设备客户端

i2c_client 是 I2C 从设备在内核中的代表。每个物理 I2C 从芯片在驱动探测成功后都会生成一个 i2c_client 实例。驱动开发者通过该结构体与设备进行所有交互。

struct i2c_client {
    unsigned short flags;       /* 标志位，如 I2C_CLIENT_TEN */
    unsigned short addr;        /* 从设备地址（7位或10位） */
    char name[I2C_NAME_SIZE];   /* 设备名称 */
    struct i2c_adapter *adapter; /* 所属适配器 */
    struct device dev;          /* 内核设备模型 */
    int irq;                    /* 中断号（若使用中断） */
    struct list_head detected;  /* 检测链表 */
    int (*detect)(struct i2c_client *, struct i2c_board_info *);
};

4.4 核心 API 函数

Linux I2C 核心框架提供了一套丰富的 API，用于设备注册、消息传输和系统级管理。以下是最常用的核心 API：

4.4.1 消息传输 API

/* 核心传输函数：发送一组 I2C 消息 */
int i2c_transfer(struct i2c_adapter *adap,
                 struct i2c_msg *msgs,
                 int num);

/* 便捷函数：发送单条消息 */
int i2c_master_send(const struct i2c_client *client,
                    const char *buf, int count);
int i2c_master_recv(const struct i2c_client *client,
                    char *buf, int count);

/* SMBus 兼容函数 */
s32 i2c_smbus_read_byte_data(const struct i2c_client *client,
                             u8 command);
s32 i2c_smbus_write_byte_data(const struct i2c_client *client,
                              u8 command, u8 value);

4.4.2 设备注册与注销 API

/* 驱动注册/注销 */
int i2c_add_driver(struct i2c_driver *driver);
void i2c_del_driver(struct i2c_driver *driver);

/* 设备节点注册（通常由设备树或板级代码调用） */
struct i2c_client *i2c_new_client_device(struct i2c_adapter *adap,
                                         struct i2c_board_info const *info);
void i2c_unregister_device(struct i2c_client *client);

/* 设备检测与地址扫描 */
int i2c_register_board_info(int busnum,
                            struct i2c_board_info const *info,
                            unsigned len);

4.5 i2c_msg：消息传递单元

i2c_msg 是 I2C 通信的最小数据单元。一次 I2C 事务可以包含多个 i2c_msg，核心框架会按顺序处理它们，并在消息之间自动插入重复起始条件（RESTART）。

struct i2c_msg {
    __u16 addr;    /* 从设备地址 */
    __u16 flags;   /* 标志位：I2C_M_RD 表示读，0 表示写 */
    __u16 len;     /* 消息数据长度 */
    __u8 *buf;     /* 数据缓冲区指针 */
};

/* 示例：读取从设备 0x48 的寄存器 0x05 */
struct i2c_msg msgs[2];
u8 reg_addr = 0x05;
u8 reg_value;

msgs[0].addr = 0x48;
msgs[0].flags = 0;          /* 写 */
msgs[0].len = 1;
msgs[0].buf = ®_addr;

msgs[1].addr = 0x48;
msgs[1].flags = I2C_M_RD;   /* 读 */
msgs[1].len = 1;
msgs[1].buf = ®_value;

ret = i2c_transfer(client->adapter, msgs, 2);
if (ret != 2) {
    dev_err(&client->dev, "I2C read failed: %d\n", ret);
    return -EIO;
}
/* reg_value 现在包含寄存器 0x05 的值 */

4.6 数据结构关系总览

以下表格总结了三个核心数据结构在 I2C 框架中的角色和关系：