章節描述：

核心版本：v4.14

構成

在Linux的I2C架構如圖：

核心空間部分可以分為：i2c裝置驅動、i2c核心以及i2c匯流排驅動。

• i2c核心：框架的實現；提供i2c匯流排驅動和裝置驅動的註冊、登出方法；i2c通訊方法（algorithm）上層的，與具體介面卡無關的程式碼以及探測裝置、檢測裝置地址的上層程式碼等。這一部分的工作由核心開發者完成。
• i2c匯流排驅動：具體控制器的實現；i2c匯流排驅動是對i2c硬體體系結構中介面卡端的實現，說白了，就是怎麼操作i2c模組工作。介面卡可由CPU控制，甚至直接整合到cpu裡面（ algorithm driver
  adapter driver）
• i2c裝置：對i2c硬體體系結構中裝置端的實現，比如說板上的EEPROM裝置等。裝置一般掛接在cpu控制的i2c介面卡上，通過i2c介面卡與cpu交換資料。（ chip drivers, 包括多種型別，如RTC, EEPROM, I/O expander, hardware monitoring, sound, video等）

名詞解釋：

• i2c-adapter（介面卡）：指的是CPU實際的I2C控制器（例如I2C0，I2C1）；
• i2c-device（裝置）：指的是I2C總線上的從裝置（例如某片EEPROM，某個觸控式螢幕）；
• i2c algorithm（演算法、實現方法）：這裡指的是對i2c裝置一套對應的通訊方法。

分層的好處：

• 讓工程師們各司其職，只關心自己應該實現的部分
• 不需要為每一個i2c控制器編寫所有從裝置的控制程式碼，只需要分別完成n個控制器的控制介面，m個從裝置的訪問實現，即可實現任意的控制器訪問任意的從裝置（假設硬體連線支援）

原型

以下原型均定義在 include/linux/i2c.h中，隨著核心版本的不同有差異，但差異不大。

i2c 裝置驅動

i2c_driver：代表一個i2c裝置驅動；

i2c 裝置驅動要使用i2c_driver 和i2c_client資料結構並填充i2c_driver中的成員函式

/**
 * struct i2c_driver - represent an I2C device driver
 * @class: What kind of i2c device we instantiate (for detect)
 * @attach_adapter: Callback for bus addition (deprecated)
 * @probe: Callback for device binding - soon to be deprecated
 * @probe_new: New callback for device binding
 * @remove: Callback for device unbinding
 * @shutdown: Callback for device shutdown
 * @alert: Alert callback, for example for the SMBus alert protocol
 * @command: Callback for bus-wide signaling (optional)
 * @driver: Device driver model driver
 * @id_table: List of I2C devices supported by this driver
 * @detect: Callback for device detection
 * @address_list: The I2C addresses to probe (for detect)
 * @clients: List of detected clients we created (for i2c-core use only)
 * @disable_i2c_core_irq_mapping: Tell the i2c-core to not do irq-mapping
 *
 * The driver.owner field should be set to the module owner of this driver.
 * The driver.name field should be set to the name of this driver.
 *
 * For automatic device detection, both @detect and @address_list must
 * be defined. @class should also be set, otherwise only devices forced
 * with module parameters will be created. The detect function must
 * fill at least the name field of the i2c_board_info structure it is
 * handed upon successful detection, and possibly also the flags field.
 *
 * If @detect is missing, the driver will still work fine for enumerated
 * devices. Detected devices simply won't be supported. This is expected
 * for the many I2C/SMBus devices which can't be detected reliably, and
 * the ones which can always be enumerated in practice.
 *
 * The i2c_client structure which is handed to the @detect callback is
 * not a real i2c_client. It is initialized just enough so that you can
 * call i2c_smbus_read_byte_data and friends on it. Don't do anything
 * else with it. In particular, calling dev_dbg and friends on it is
 * not allowed.
 */

struct i2c_driver {
	unsigned int class; // 表示我們將註冊的是那種裝置（探測時用）

	/* Notifies the driver that a new bus has appeared. You should avoid
	 * using this, it will be removed in a near future.
	 */
	int (*attach_adapter)(struct i2c_adapter *) __deprecated; // 新增匯流排時，告訴驅動的回撥函式（以後可能要棄用）

	/* Standard driver model interfaces */
	int (*probe)(struct i2c_client *, const struct i2c_device_id *); // 繫結裝置時的回撥函式
	int (*remove)(struct i2c_client *); // 解除繫結時呼叫的回撥函式

	/* New driver model interface to aid the seamless removal of the
	 * current probe()'s, more commonly unused than used second parameter.
	 */
	int (*probe_new)(struct i2c_client *); // 新的裝置繫結回撥函式

	/* driver model interfaces that don't relate to enumeration  */
	void (*shutdown)(struct i2c_client *); // 裝置關閉時呼叫的回撥函式

	/* Alert callback, for example for the SMBus alert protocol.
	 * The format and meaning of the data value depends on the protocol.
	 * For the SMBus alert protocol, there is a single bit of data passed
	 * as the alert response's low bit ("event flag").
	 * For the SMBus Host Notify protocol, the data corresponds to the
	 * 16-bit payload data reported by the slave device acting as master.
	 */
	void (*alert)(struct i2c_client *, enum i2c_alert_protocol protocol,
		      unsigned int data); // 警告回撥函式（例如SMBus警報協議）

	/* a ioctl like command that can be used to perform specific functions
	 * with the device.
	 */
	int (*command)(struct i2c_client *client, unsigned int cmd, void *arg); // 類似於ioctl 的命令控制函式

	struct device_driver driver; // 裝置驅動模型中的驅動
	const struct i2c_device_id *id_table; // 這個i2c驅動支援的裝置連結串列

	/* Device detection callback for automatic device creation */
	int (*detect)(struct i2c_client *, struct i2c_board_info *); // 檢測裝置的回撥函式；
	const unsigned short *address_list; // 要探測的I2C地址（用於檢測）
	struct list_head clients; // 我們建立的檢測到的clients（僅供i2c核心使用）

	bool disable_i2c_core_irq_mapping;
};
 

例如：RTC裝置的驅動

/* drivers/rtc/rtc-ds1307.c */
static struct i2c_driver ds1307_driver = {
    .driver = {
        .name   = "rtc-ds1307",
        .of_match_table = of_match_ptr(ds1307_of_match),
        .acpi_match_table = ACPI_PTR(ds1307_acpi_ids),
    },
    .probe      = ds1307_probe,
    .id_table   = ds1307_id,
};

i2c 客戶端

i2c_client：代表一個連線到i2c_bus總線上的從裝置。

/**
 * struct i2c_client - represent an I2C slave device
 * @flags: 
 	- I2C_CLIENT_TEN ： the device uses a ten bit chip address; 表示i2c從裝置使用的晶片地址為10bit
	- I2C_CLIENT_PEC ： it uses SMBus Packet Error Checking；   表示裝置使用SMBus錯誤檢查
 * @addr: Address used on the I2C bus connected to the parent adapter.
 * @name: Indicates the type of the device, usually a chip name that's
 *	generic enough to hide second-sourcing and compatible revisions.
 * @adapter: manages the bus segment hosting this I2C device
 * @dev: Driver model device node for the slave.
 * @irq: indicates the IRQ generated by this device (if any)
 * @detected: member of an i2c_driver.clients list or i2c-core's
 *	userspace_devices list
 * @slave_cb: Callback when I2C slave mode of an adapter is used. The adapter
 *	calls it to pass on slave events to the slave driver.
 *
 * An i2c_client identifies a single device (i.e. chip) connected to an
 * i2c bus. The behaviour exposed to Linux is defined by the driver
 * managing the device.
 */
struct i2c_client {
	unsigned short flags;	 // 一個標示，豐富這個裝置的特殊細節
	unsigned short addr;		/* chip address - NOTE: 7bit；addresses are stored in the _LOWER_ 7 bits	 */ // 從裝置在連線到相應介面卡總線上使用的地址；預設使用低七位。
	char name[I2C_NAME_SIZE]; // 裝置的名字；
	struct i2c_adapter *adapter;	/* the adapter we sit on	*/ // 掛接裝置的介面卡；
	struct device dev;		/* the device structure		*/ // 訪問裝置的驅動；
	int irq;			/* irq issued by device		*/ // 表明由裝置產生的中斷；
	struct list_head detected; // 一個i2c_driver支援的client的數量或i2c-core的使用者空間裝置的連結串列。
#if IS_ENABLED(CONFIG_I2C_SLAVE)
	i2c_slave_cb_t slave_cb;	/* callback for slave mode	*/ // 從模式下的回撥函式
#endif
};

i2c_client的資訊通常在BSP的板檔案中通過i2c_board_info填充， 如下面的程式碼就定義了一個I2C裝置的ID為“wm8580”、 地址為0x1b、 的i2c_client：

static struct i2c_board_info i2c_devs0[] __initdata = {
    {
        I2C_BOARD_INFO("wm8580", 0x1b),
    },
};

struct i2c_board_info {
	char		type[I2C_NAME_SIZE];
	unsigned short	flags;
	unsigned short	addr;
	void		*platform_data;
	struct dev_archdata	*archdata;
#ifdef CONFIG_OF
	struct device_node *of_node;
#endif
	int		irq;
};

i2c介面卡

i2c_adapter：一個用於標識物理匯流排（也就是i2c匯流排）連同訪問它必要的演算法的一個結構

/*
 * i2c_adapter is the structure used to identify a physical i2c bus along
 * with the access algorithms necessary to access it.
 */
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 */

	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;
};

i2c_algorithm中的關鍵函式master_xfer() 用於產生I2C訪問週期需要的訊號， 以i2c_msg（即I2C訊息） 為單位（i2c_msg中的成員表明了I2C的傳輸地址、 方向、 緩衝區、 緩衝區長度等資訊） 。

/**
 * struct i2c_msg - an I2C transaction segment beginning with START
 * @addr: Slave address, either seven or ten bits.  When this is a ten
 *	bit address, I2C_M_TEN must be set in @flags and the adapter
 *	must support I2C_FUNC_10BIT_ADDR.
 * @flags: I2C_M_RD is handled by all adapters.  No other flags may be
 *	provided unless the adapter exported the relevant I2C_FUNC_*
 *	flags through i2c_check_functionality().
 * @len: Number of data bytes in @buf being read from or written to the
 *	I2C slave address.  For read transactions where I2C_M_RECV_LEN
 *	is set, the caller guarantees that this buffer can hold up to
 *	32 bytes in addition to the initial length byte sent by the
 *	slave (plus, if used, the SMBus PEC); and this value will be
 *	incremented by the number of block data bytes received.
 * @buf: The buffer into which data is read, or from which it's written.
 *
 * An i2c_msg is the low level representation of one segment of an I2C
 * transaction.  It is visible to drivers in the @i2c_transfer() procedure,
 * to userspace from i2c-dev, and to I2C adapter drivers through the
 * @i2c_adapter.@master_xfer() method.
 *
 * Except when I2C "protocol mangling" is used, all I2C adapters implement
 * the standard rules for I2C transactions.  Each transaction begins with a
 * START.  That is followed by the slave address, and a bit encoding read
 * versus write.  Then follow all the data bytes, possibly including a byte
 * with SMBus PEC.  The transfer terminates with a NAK, or when all those
 * bytes have been transferred and ACKed.  If this is the last message in a
 * group, it is followed by a STOP.  Otherwise it is followed by the next
 * @i2c_msg transaction segment, beginning with a (repeated) START.
 *
 * Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then
 * passing certain @flags may have changed those standard protocol behaviors.
 * Those flags are only for use with broken/nonconforming slaves, and with
 * adapters which are known to support the specific mangling options they
 * need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR).
 */
struct i2c_msg {
	__u16 addr;	/* slave address			*/
	__u16 flags;
#define I2C_M_RD		0x0001	/* read data, from slave to master */
					/* I2C_M_RD is guaranteed to be 0x0001! */
#define I2C_M_TEN		0x0010	/* this is a ten bit chip address */
#define I2C_M_RECV_LEN		0x0400	/* length will be first received byte */
#define I2C_M_NO_RD_ACK		0x0800	/* if I2C_FUNC_PROTOCOL_MANGLING */
#define I2C_M_IGNORE_NAK	0x1000	/* if I2C_FUNC_PROTOCOL_MANGLING */
#define I2C_M_REV_DIR_ADDR	0x2000	/* if I2C_FUNC_PROTOCOL_MANGLING */
#define I2C_M_NOSTART		0x4000	/* if I2C_FUNC_NOSTART */
#define I2C_M_STOP		0x8000	/* if I2C_FUNC_PROTOCOL_MANGLING */
	__u16 len;		/* msg length				*/
	__u8 *buf;		/* pointer to msg data			*/
};

i2c通訊方法

i2c_algorithm是為一類使用相同匯流排演算法定址的一個介面。

• 當介面卡不能使用i2c訪問裝置時，把master_xfer設定為NULL

• 如果一個介面卡可以做SMBus訪問時，設定smbus_xfer；如果把smbus_xfer設定成NULL，SMBus協議使用通用I2C模擬的訊息。

/**
 * struct i2c_algorithm - represent I2C transfer method
 * @master_xfer: 
     Issue a set of i2c transactions to the given I2C adapter defined by the 
     msgs array, with num messages available to transfer via the adapter 
     specified by adap.
 * @smbus_xfer: 
  	 Issue smbus transactions to the given I2C adapter. If this is not present,
     then the bus layer will try and convert the SMBus calls into I2C transfers
     instead.
 * @functionality: Return the flags that this algorithm/adapter pair supports
 *   from the I2C_FUNC_* flags.
 * @reg_slave: Register given client to I2C slave mode of this adapter
 * @unreg_slave: Unregister given client from I2C slave mode of this adapter
 *
 * The following structs are for those who like to implement new bus drivers:
 * i2c_algorithm is the interface to a class of hardware solutions which can
 * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
 * to name two of the most common.
 *
 * The return codes from the @master_xfer field should indicate the type of
 * error code that occurred during the transfer, as documented in the kernel
 * Documentation file Documentation/i2c/fault-codes.
 */
struct i2c_algorithm {
	/* If an adapter algorithm can't do I2C-level access, set master_xfer
	   to NULL. If an adapter algorithm can do SMBus access, set
	   smbus_xfer. If set to NULL, the SMBus protocol is simulated
	   using common I2C messages */
	/* master_xfer should return the number of messages successfully
	   processed, or a negative value on error */
	int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs,
			   int num); 
    // 向msgs陣列定義的給定i2c介面卡發出一組i2c事務，其中num條訊息可通過adap指定的介面卡傳輸。
	int (*smbus_xfer) (struct i2c_adapter *adap, u16 addr,
			   unsigned short flags, char read_write,
			   u8 command, int size, union i2c_smbus_data *data);
    //  向給定的I2C介面卡發出smbus事務。如果這不存在，那麼匯流排層將嘗試將SMBus呼叫轉換為I2C傳輸。

	/* To determine what the adapter supports */
	u32 (*functionality) (struct i2c_adapter *);

#if IS_ENABLED(CONFIG_I2C_SLAVE)
	int (*reg_slave)(struct i2c_client *client);
	int (*unreg_slave)(struct i2c_client *client);
#endif
};

物件之間的關係

i2c_adapter和i2c_algorithm

由於i2c_adapter對應與物理上的一個介面卡，而i2c_algorithm對應一套通訊方法。

一個i2c介面卡需要i2c_algorithm中提供的通訊函式來控制介面卡上產生特定的訪問週期。

缺少i2c_algorithm的i2c_adapter什麼也做不了，因此i2c_adapter中包含其使用i2c_algorithm的指標。

i2c_driver和i2c_client

i2c_driver對應於一套驅動方法， 其主要成員函式是probe() 、remove()、 suspend() 、resume() 等；

另外， struct i2c_device_id形式的id_table是該驅動所支援的I2C裝置的ID表。 i2c_client對應於真實的物理裝置， 每個I2C裝置都需要一個i2c_client來描述。 i2c_driver與i2c_client的關係是一對多， 一個i2c_driver可以支援多個同類型的i2c_client。

每個探測到的裝置通過在client資料結構中得到自己的資料

在I2C匯流排驅動i2c_bus_type的match() 函式i2c_device_match() 中， 會呼叫i2c_match_id() 函式匹配在板檔案中定義的ID和i2c_driver所支援的ID表。

static int i2c_device_match(struct device *dev, struct device_driver *drv)
{
    struct i2c_client	*client = i2c_verify_client(dev);
    struct i2c_driver	*driver;

    if (!client)
        return 0;

    driver = to_i2c_driver(drv);
    /* match on an id table if there is one */
    if (driver->id_table)
        return i2c_match_id(driver->id_table, client) != NULL;

    return 0;
}

static const struct i2c_device_id *i2c_match_id(const struct i2c_device_id *id,
                                                const struct i2c_client *client)
{
    while (id->name[0]) {
        if (strcmp(client->name, id->name) == 0)
            return id;
        id++;
    }
    return NULL;
}

i2c_adpater與i2c_client

i2c_adpater與i2c_client的關係與I2C硬體體系中介面卡和裝置的關係一致， 即i2c_client依附於i2c_adpater。 由於一個介面卡可以連線多個I2C裝置， 所以一個i2c_adpater也可以被多個i2c_client依附，i2c_adpater中包括依附於它的i2c_client的連結串列。

參考

https://i2c.wiki.kernel.org/index.php/Driver_Architecture
https://blog.csdn.net/xie0812/article/details/22942375