Linux内核之I2C协议

Linux内核之I2C协议
I2C协议标准文档

THE I2C-BUS SPECIFICATION VERSION 2.1 JANUARY 2000: https://www.csd.uoc.gr/~hy428/reading/i2c_spec.pdf
I2C全称Inter-IC，又写作IIC，有些又归类为TWI(Two-Wire Interface).

电路原理

IIC仅由SDA数据线、SCL时钟线构成。并且两根线都需要接上拉电阻，原因是采用了OD门。

OD门(Open Drain漏极开路)的作用：
适用于输出\输入
单独使用时，可独立输出或输入低电平和高阻态（可理解为开路）
- 我们只需要给一个上拉电阻产生高电平，在高阻态/开路的作用下，线路电平就会等同于上拉电阻的高电平；
- 在低电平的作用下，线路电平仍然是低电平；
  所以接上拉电阻，可以让OD门有输入\输出高低电平的功能，可以使用半双工，这就是通信的物理电路基础。
高电平一般有1.8V 3.3V 5V 三种。
上拉电阻阻值(3.3K~10K)与速度和容性负载相关，可以决定稳定性。

而且标准文档还提供了不同电平之间的电路兼容方案

连接方式

所有从机SDA都并联到主机上，所有从机SCK线都并联到主机SCL上。

时序图

关键点：
空闲状态：SCL/SDA都是高电平。
工作状态：SCL脉冲在高电平状态下指示SDA有效。

经典的开始和结束信号

SDA下降沿表示开始，上升沿表示结束

多机冲突与通讯
有低电平的话，同一线上的都会被拉低。
接到同一SCL线的都会被同步
对端SDA的可判断电平不一致而打断操作。

如果需要FPGA实现，还需要留意标准文档里的Table5和Fig.31的时间间隔要求。

主要传输形式

速度： 0_100KHz400KHz~3.4MHz
不同速度模式的设备混合接入总线系统，速度如表:

速度是需要“协商”的，如启用 High Speed Mode

保留地址作为管理码(master code)，详见标准手册 10.1 Definition of bits in the first byte

开始条件S 8位管理码(00001xxx) 一位NACK

普通速率下传输数据（7地址模式）

其数据可抽象简化为
DEV_ADDR BYTE_DATA [..BYTE_DATA]

发送设备地址(7位+R/W标识位) 另外也有10位地址的，就是两个地址字而已，用得少可以看标准文档。
发送数据(8位一次)
可选继续发送数据(每次也都是8位)

每8位都需要从机回复一个A/A应答位。
也就说，它是基于字节传输的超短距简单低速协议。

一般来说，I2C最适合用于读写寄存器，其数据形态与可以现有计算
机/微机体系匹配，符合8/16/32/64位等以字节整倍数的寄存器。
一个写入寄存器的例子(16位寄存器地址,32位寄存器数据)： DEV_ADDR REG_ADDR0 REG_ADDR1 REG_DATA0 REG_DATA1 REG_DATA2 REG_DATA3
Tips: 基于字节传输的协议都可以替代串口协议的部分应用场景。

测试工具

Linux上一般使用i2c-tools这个包的工具
i2cdetect 用于扫描总线上挂接的从机设备地址。注意：非标设备不回复，则扫描不到。i2cdetect -y -r 0代表确认并以Read扫描一次IIC总线0下的所有非保留地址。把-r换成-q则表示以QUICK写模式扫描。
i2cdump 用于读取某个i2c从机设备的所有寄存器数据。
小技巧：当i2cdetect扫描不到的时候，可以用循环i2cdump抓出所有的从机设备数据，只要有数据的，说明该地址就有设备。

关于i2cdetect不回复的问题排查，可以查看i2ctools源码: https://github.com/mozilla-b2g/i2c-tools/blob/master/tools/i2cdetect.c#L50

其实就是从机要支持主机发送的 SMBUG_READ 指令

有个案例：https://bbs.aw-ol.com/topic/2304/分析笔记-linux-i2c-tools-使用踩坑笔记/2

变种

I2C的变种有 SMBUS MDIO I3C MIPI系等等协议。
本质上都是1时钟线+1数据线，OD门实现双向高低电平。可并联。

Linux内核I2C&SMBUS子系统 API文档

see: https://www.kernel.org/doc/html/v5.14/driver-api/i2c.html
文档路径 » The Linux driver implementer’s API guide » I2C and SMBus Subsystem
SMBUS是I2C的兄弟协议，大部分SMBUS也是I2C，并且电气规定上比I2C更严格。

(SoC)I2C控制器收发的内核API
```
// 普通版本
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)
// 带DMA控制器的版本
int i2c_master_send_dmasafe(const struct i2c_client *client, const char *buf, int count)
int i2c_master_recv_dmasafe(const struct i2c_client *client, char *buf, int count)
```
一些重要的结构体

架构分层

贴张经典老图，出处找不到了，侵权请联系

APP
/dev/i2c-x (device文件节点)
设备驱动driver

i2c-Core I2C_Adapter （控制器）
控制器一般是这样的：一般由I2C控制器的IP设计服务商给到SoC厂商，SoC厂商在处理器微电路设计适配后，仅放出寄存器给用户。所以我们用户只需要根据SoC数据手册对SoC寄存器操作即可。SoC会根据寄存器内容对控制器进行微电路操作的。

SOC厂家的对接代码

硬件上对应:
n个SOC片上控制器 - Adapter
n个从机硬件设备 - 一个Driver+多个同系列型号Device

Adapter结构体里还包含了传输算法algo、独占操作lock_ops、适配器对应的device及其name、下挂的userspace_clients，总线恢复操作bus_rec、特性quirks、中断irq_domain等等。
传输算法algo里面其实就是i2c和smbus的传输函数指针而已。
```
//设备识别
struct i2c_device_identity {
  u16 manufacturer_id; //0 - 4095, database maintained by NXP
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS                0;
//...
#define I2C_DEVICE_ID_ATMEL                            13;
#define I2C_DEVICE_ID_NONE                         0xffff;
  u16 part_id;
  u8 die_revision;
};


//板载设备信息模板 template for device creation
struct i2c_board_info {
  char type[I2C_NAME_SIZE];
  unsigned short  flags;
  unsigned short  addr;
  const char      *dev_name;
  void *platform_data;
  struct device_node *of_node;
  struct fwnode_handle *fwnode;
  const struct software_node *swnode;
  const struct resource *resources;
  unsigned int    num_resources;
  int irq;
};


//时序控制
struct i2c_timings {
  u32 bus_freq_hz;
  u32 scl_rise_ns;
  u32 scl_fall_ns;
  u32 scl_int_delay_ns;
  u32 sda_fall_ns;
  u32 sda_hold_ns;
  u32 digital_filter_width_ns;
  u32 analog_filter_cutoff_freq_hz;
};
```
总线API
```
//锁，实现独占操作
void i2c_lock_bus(struct i2c_adapter *adapter, unsigned int flags)
int i2c_trylock_bus(struct i2c_adapter *adapter, unsigned int flags)
void i2c_unlock_bus(struct i2c_adapter *adapter, unsigned int flags)
```
电源操作
```
void i2c_mark_adapter_suspended(struct i2c_adapter *adap)
void i2c_mark_adapter_resumed(struct i2c_adapter *adap)
```
特性检测
```
bool i2c_check_quirks(struct i2c_adapter *adap, u64 quirks)
```
初始化/卸载操作
```
int i2c_register_board_info(int busnum, struct i2c_board_info const *info, unsigned len)
struct i2c_client * i2c_verify_client(struct device *dev)
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)
//dummy是虚拟设备
struct i2c_client * i2c_new_dummy_device(struct i2c_adapter *adapter, u16 address)
struct i2c_client * devm_i2c_new_dummy_device(struct device *dev, struct i2c_adapter *adapter, u16 address)

struct i2c_client * i2c_new_ancillary_device(struct i2c_client *client, const char *name, u16 default_addr)
struct i2c_adapter * i2c_verify_adapter(struct device *dev)
int i2c_handle_smbus_host_notify(struct i2c_adapter *adap, unsigned short addr)
int i2c_add_adapter(struct i2c_adapter *adapter)
void i2c_del_adapter(struct i2c_adapter *adap)
int i2c_add_numbered_adapter(struct i2c_adapter *adap)
int devm_i2c_add_adapter(struct device *dev, struct i2c_adapter *adapter)
void i2c_parse_fw_timings(struct device *dev, struct i2c_timings *t, bool use_defaults)
void i2c_del_driver(struct i2c_driver *driver)
```
向从机读写数据
```
int __i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num)
int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num)
int i2c_transfer_buffer_flags(const struct i2c_client *client, char *buf, int count, u16 flags)
int i2c_get_device_id(const struct i2c_client *client, struct i2c_device_identity *id)
u8* i2c_get_dma_safe_msg_buf(struct i2c_msg *msg, unsigned int threshold)
void i2c_put_dma_safe_msg_buf(u8 *buf, struct i2c_msg *msg, bool xferred)

u8 i2c_smbus_pec(u8 crc, u8 *p, size_t count)
s32 i2c_smbus_read_byte(const struct i2c_client *client)
s32 i2c_smbus_write_byte(const struct i2c_client *client, u8 value)
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)
s32 i2c_smbus_read_word_data(const struct i2c_client *client, u8 command)
s32 i2c_smbus_write_word_data(const struct i2c_client *client, u8 command, u16 value)
s32 i2c_smbus_read_block_data(const struct i2c_client *client, u8 command, u8 *values)
s32 i2c_smbus_write_block_data(const struct i2c_client *client, u8 command, u8 length, const u8 *values)
s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, unsigned short flags, char read_write, u8 command, int protocol, union i2c_smbus_data *data)
s32 i2c_smbus_read_i2c_block_data_or_emulated(const struct i2c_client *client, u8 command, u8 length, u8 *values)
struct i2c_client * i2c_new_smbus_alert_device(struct i2c_adapter *adapter, struct i2c_smbus_alert_setup *setup)
```
Linux内核I2C&SMBUS子系统架构

从机设备驱动部分

设备驱动编写：https://docs.kernel.org/i2c/writing-clients.html (较简单)

I2C SysFs的：https://docs.kernel.org/i2c/i2c-sysfs.html
用法：https://docs.kernel.org/i2c/instantiating-devices.html
有以下几种为Linux内核创建I2C设备的方法（任选其一即可）：
- 结构信息
  - 设备树
  - ACPI（可以理解为X86的设备树）
- 代码调用
  - 填充 struct i2c_board_info 结构体并使用i2c_new_client_device()创建
  - 调用i2c_new_scanned_device() 等API函数
- 驱动里写
  - probe（比较常见）见：lm90_driver and lm90_detect() in drivers/hwmon/lm90.c
- 用户空间使用sysfs接口
  - 例子echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device 或者delete_device
核心 I2C-Core

总线部分 BUS主控/片上外设驱动 Adapter

这部分一般是原厂在弄
```
//i2c.h里的适配器结构体
struct i2c_adapter {
	struct module *owner;
	unsigned int class;		  /* classes to allow probing for */
	const struct i2c_algorithm *algo; /* the algorithm to access the bus */
	void *algo_data;

	/* data fields that are valid for all devices	*/
	const struct i2c_lock_operations *lock_ops;
	struct rt_mutex bus_lock;
	struct rt_mutex mux_lock;

	int timeout;			/* in jiffies */
	int retries;
	struct device dev;		/* the adapter device */
	unsigned long locked_flags;	/* owned by the I2C core */
#define I2C_ALF_IS_SUSPENDED		0
#define I2C_ALF_SUSPEND_REPORTED	1

	int nr;
	char name[48];
	struct completion dev_released;

	struct mutex userspace_clients_lock;
	struct list_head userspace_clients;

	struct i2c_bus_recovery_info *bus_recovery_info;
	const struct i2c_adapter_quirks *quirks;

	struct irq_domain *host_notify_domain;
	struct regulator *bus_regulator;

	struct dentry *debugfs;
};

//设备器成员函数-收发接口
struct i2c_algorithm {
  int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
  int (*master_xfer_atomic)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
  int (*smbus_xfer)(struct i2c_adapter *adap, u16 addr,unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data);
  int (*smbus_xfer_atomic)(struct i2c_adapter *adap, u16 addr,unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data);
  u32 (*functionality)(struct i2c_adapter *adap);
#if IS_ENABLED(CONFIG_I2C_SLAVE);
  int (*reg_slave)(struct i2c_client *client);
  int (*unreg_slave)(struct i2c_client *client);
#endif;
};

//适配器成员函数-锁定解锁操作
struct i2c_lock_operations {
  void (*lock_bus)(struct i2c_adapter *adapter, unsigned int flags);
  int (*trylock_bus)(struct i2c_adapter *adapter, unsigned int flags);
  void (*unlock_bus)(struct i2c_adapter *adapter, unsigned int flags);
};

//适配器成员-特性结构体
struct i2c_adapter_quirks {
  u64 flags;
  int max_num_msgs;
  u16 max_write_len;
  u16 max_read_len;
  u16 max_comb_1st_msg_len;
  u16 max_comb_2nd_msg_len;
};

//适配器成员函数-操作两根线
struct i2c_bus_recovery_info {
  int (*recover_bus)(struct i2c_adapter *adap);
  int (*get_scl)(struct i2c_adapter *adap);
  void (*set_scl)(struct i2c_adapter *adap, int val);
  int (*get_sda)(struct i2c_adapter *adap);
  void (*set_sda)(struct i2c_adapter *adap, int val);
  int (*get_bus_free)(struct i2c_adapter *adap);
  void (*prepare_recovery)(struct i2c_adapter *adap);
  void (*unprepare_recovery)(struct i2c_adapter *adap);
  struct gpio_desc *scl_gpiod;
  struct gpio_desc *sda_gpiod;
  struct pinctrl *pinctrl;
  struct pinctrl_state *pins_default;
  struct pinctrl_state *pins_gpio;
};
```
从机设备节点
```
//从机设备结构体
struct i2c_client {
  unsigned short flags;
#define I2C_CLIENT_PEC          0x04    ;
#define I2C_CLIENT_TEN          0x10    ;
#define I2C_CLIENT_SLAVE        0x20    ;
#define I2C_CLIENT_HOST_NOTIFY  0x40    ;
#define I2C_CLIENT_WAKE         0x80    ;
#define I2C_CLIENT_SCCB         0x9000  ;
  unsigned short addr;
  char name[I2C_NAME_SIZE];
  struct i2c_adapter *adapter;
  struct device dev;
  int init_irq;
  int irq;
  struct list_head detected;
#if IS_ENABLED(CONFIG_I2C_SLAVE);
  i2c_slave_cb_t slave_cb;
#endif;
  void *devres_group_id;
};
```
从机设备驱动/板上外设驱动

拿到新的IIC从机设备，首先就是根据其数据手册适配该外设的驱动
```
//从机设备驱动接口
struct i2c_driver {
  unsigned int class;
  int (*probe)(struct i2c_client *client, const struct i2c_device_id *id);
  int (*remove)(struct i2c_client *client);
  int (*probe_new)(struct i2c_client *client);
  void (*shutdown)(struct i2c_client *client);
  void (*alert)(struct i2c_client *client, enum i2c_alert_protocol protocol, unsigned int data);
  int (*command)(struct i2c_client *client, unsigned int cmd, void *arg);
  struct device_driver driver;
  const struct i2c_device_id *id_table;
  int (*detect)(struct i2c_client *client, struct i2c_board_info *info);
  const unsigned short *address_list;
  struct list_head clients;
};
```
我们要实现i2c_algorithm的transfer接口，才能完成对I2C主控/Soc的驱动适配。

drivers/i2c

除了一些 include/linux/i2c.h之类相关的头文件，剩下的实现都在 drivers/i2c

i2c-core.h头文件主要是一个i2c_devinfo结构体和一些static inline静态内联函数定义
```
struct i2c_devinfo {
	struct list_head	list;
	int			busnum;
	struct i2c_board_info	board_info;
};
```
i2c-core-base.ccore层的实现，支撑了i2c-core-xxx.c的功能。
i2c-core-of.c 是设备树的实现，主要是match、设备树sysfs导出、设备树属性reg host-notify wakeup-source 等支持，注册/反注册设备。
i2c-core-acpi.c是X86特有的ACPI表（ACPI比ARM设备树更高级强大）
i2c-core-slave.c是从机设备的核心支持，主要是从机模式选择、事件、注册/反注册的支持。
i2c-core-smbus.c是SMBus支持。其读写最终会调用__i2c_smbus_xfer到adapter->algo->smbus_xfer()

xxx有acpi表、base、of设备树、从机slave、SMBUS等类型的注册/反注册。

i2c-atr.c是I2C Address Translator地址翻译器的缩写，

i2c-boardinfo.c 用于静态声明板载从机I2C设备。这个源码很少，仅有一个函数（加锁，然后把填充i2c_devinfo并加到i2c_board链表）。

i2c-dev.c主要是SoC片上i2c总线控制器的驱动实现，即I2C主机设备字符驱动，代表了一个 i2c_adapter
```
struct i2c_dev {
	struct list_head list;
	struct i2c_adapter *adap;
	struct device dev;
	struct cdev cdev;
};
```
i2c-mux.c是I2C多路总线驱动(Multiplexed I2C bus driver)，用于支持控制器的多路通道设计。

i2c-smbus.c是其SMBus驱动实现，几乎所有的I2C主控都是同时支持SMBus的。

i2c-stub.c是I2C/SMBus芯片模拟器

剩下的两个i2c-slave-eeprom.c和i2c-slave-testuint.c都是I2C从机模拟器

目录 drivers/i2c/algos下面是一些通用控制器的algo实现，比较古老了一般用不到，现在都是高度集成到SoC里了。目前实现了移位寄存器类型/PCF8584/PCA9564这几类拓展的适配器。放张PCF8584的框图欣赏一下，FPGA要实现也可以参考这种。

目录drivers/i2c/busses则较为庞大，是各厂家提供的总线驱动，遵守内核的i2c_adapter模型。SoC厂家可能会使用不同的IP定制，使得自家SoC能采用不同的I2C控制器，但是他们一般对片上外设的控制器是一致的，这个叫做总线控制。例如博通的[drivers/i2c/busses/i2c-bcm2835.c](struct bcm2835_i2c_dev {)
和赛灵思的 drivers/i2c/busses/i2c-xiic.c ，虽然看起来复杂，但里面也基本都是ARM核通过寄存器配置片上外设(I2C控制器)，比单片机裸机寄存器编程难，但也不会太难。
这部分只有需要定制自己的SoC时才需要，一般能做SoC的都是原厂。

目录drivers/i2c/muxes是一些板上外设的分线器/拓展器驱动，例如你SoC线不够用了，可以通过在板子上加个外设如PCA9544来拓展I2C的，让你1路变4路，多爽啊。

总结
- i2c-core是内核对I2c的核心支持，最主要的就是提供了适配器模型，
- 厂家提供的总线驱动drivers/i2c/busses都需要遵循这个适配器模型，而里面的操作基本都是写处理器的寄存器，由处理器最后去操作对应的控制器IP
- 板载外设IIC设备的驱动编写则使用内核提供的Client API，见 https://docs.kernel.org/i2c/writing-clients.html
- 板载外设IIC拓展器使用的是 drivers/i2c/muxes
- SMBUS有自己的读写概念，所以额外实现。
I2C例子：

原厂写总线驱动

SoC数据手册：https://docs.amd.com/r/en-US/ug1085-zynq-ultrascale-trm/I2C-Controllers
代码：drivers/i2c/busses/i2c-xiic.c

编写外设设备驱动

基于I2C通信的DAC外设，数据手册：https://www.ti.com/lit/ds/symlink/dac7571.pdf?ts=1714157964385
drivers/iio/dac/ti-dac5571.c

__EOF__
本文作者： YuCloud
本文链接： https://www.cnblogs.com/yucloud/p/18157014/linux_kernel_i2c
关于博主： love to create
版权声明： 本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
声援博主： Click【推荐】if the article helpful, and Welcome to discuss

I2C协议标准文档

电路原理

连接方式

时序图

主要传输形式

普通速率下传输数据（7地址模式）

测试工具

变种

Linux内核I2C&SMBUS子系统 API文档

架构分层

Linux内核I2C&SMBUS子系统架构

从机设备驱动部分

核心 I2C-Core

总线部分 BUS主控/片上外设驱动 Adapter

从机设备节点

从机设备驱动/板上外设驱动

drivers/i2c

总结

I2C例子：

原厂写总线驱动

编写外设设备驱动