Linux I2C核心和设备驱动简要介绍

2019独角兽企业重金招聘Python工程师标准>>>

本章导读

I2C总线仅仅使用SCL、SDA这两根信号线就实现了设备之间的数据交互，极大地简化了对硬件资源和PCB板布线空间的占用。因此，I2C总线非常广泛地应用在EEPROM、实时时钟、小型LCD等设备与CPU的接口中。

Linux系统定义了I2C驱动体系结构。在Linux系统中，I2C驱动由3部分组成，即I2C核心、I2C总线驱动和I2C设备驱动。这3部分相互协作，形成了非常通用、可适应性很强的I2C框架。

Linux I2C体系结构

Linux的I2C体系结构分为3个部分组成。

(1) I2C核心

I2C核心提供了I2C总线驱动和设备驱动的注册、注销方法，I2C通信方法(即Algorithm)上层的与具体设备无关的代码以及探测设备、检测设备地址的上层代码等，如下图所示。

(2) I2C总线驱动

I2C总线驱动是对I2C硬件体系结构中适配器端的实现，适配器可由CPU控制，甚至可以直接集成在CPU内部。

I2C总线驱动主要包含I2C适配器数据结构i2c_adapter、I2C适配器的Algorithm数据结构i2c_algorithm和控制I2C适配器产生通信信号的函数。

 

经由I2C总线驱动的代码，我们可以控制I2C适配器以主控方式产生开始位、停止位、读写周期，以及以从设备方式被读写、产生ACK等。

(3) I2C设备驱动

I2C设备驱动(也称为客户驱动)是对I2C硬件体系结构中设备端的实现，设备一般挂接在受CPU控制的I2C适配器上，通过I2C适配器与CPU交换数据。

I2C设备驱动主要包含数据结构i2c_driver和i2c_client，我们需要根据具体设备实现其中的成员函数。

在Linux内核2.6中，所有的I2C设备都在sysfs文件系统中显示，存于/sys/bus/i2c目录下，以适配器地址和芯片地址的形式列出，例如：

 

在Linux内核源代码中的drivers目录下有一个i2c目录，而在i2c目录下又包含如下文件和文件夹。

(1) i2c-core.c

这个文件实现了I2C核心的功能以及/proc/bus/i2c*接口。

(2) i2c-dev.c

实现了I2C适配器设备文件的功能，每个I2C适配器都被分配一个设备。通过适配器访问设备时的主设备号都为89，次设备号为0-255。应用程序通过i2c-%d文件名并使用文件操作接口open()、write()、read()、ioctl()和close()等来访问这个设备。

i2c-dev.c并不是针对特定的设备而设计的，只是提供了通用的read()、write()和ioctl()等接口，应用层可以借用这些接口访问挂接在适配器上的I2C设备的存储空间或寄存器，并控制I2C设备的工作方式。

(3) busses文件夹

这个文件包含了一些I2C主机控制器的驱动，如i2c-tegra.c、i2c-omap.c等。

(4) algos文件夹

实现了一些I2C总线适配器的通信方法。

此外，内核中的i2c.h头文件对i2c_adapter、i2c_algorithm、i2c_driver和i2c_client这4个数据结构进行了定义。理解这4个数据结构的作用十分重要，它们的定义位于kernel/include/linux/i2c.h文件中，下面的代码清单分别对它们进行了描述。

i2c_adapter结构体：

/*

 * 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 */

  struct rt_mutex bus_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;

};

i2c_algorithm结构体：

/*

 * 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.

 */

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

    
  int (*smbus_xfer) (struct i2c_adapter *adap, u16 addr,

    unsigned short flags, char read_write,

     u8 command, int size, union i2c_smbus_data *data);


  /* To determine what the adapter supports */

   u32 (*functionality) (struct i2c_adapter *);

};

上述master_xfer代码对应为I2C传输函数指针，I2C 主机驱动的大部分工作也聚集在这里。上述smbus_xfer代码对应SMBus传输函数指针，SMBus不需要增加额外引脚，与I2C总线相比，在访问时序上也有一定的差异。

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

 * @remove: Callback for device unbinding

 * @shutdown: Callback for device shutdown

 * @suspend: Callback for device suspend

 * @resume: Callback for device resume

 * @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)

 *

 * 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 *);

   /* driver model interfaces that don't relate to enumeration  */

  void (*shutdown)(struct i2c_client *);

  int (*suspend)(struct i2c_client *, pm_message_t mesg);

  int (*resume)(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").

   */

  void (*alert)(struct i2c_client *, unsigned int data);

  /* 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);

  struct device_driver driver;

  const struct i2c_device_id *id_table;

  /* Device detection callback for automatic device creation */

  int (*detect)(struct i2c_client *, struct i2c_board_info *);

  const unsigned short *address_list;

  struct list_head clients;

};

i2c_client结构体：

/**

 * struct i2c_client - represent an I2C slave device

 * @flags: I2C_CLIENT_TEN indicates the device uses a ten bit chip address;

 * I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking

 * @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

 * @driver: device's driver, hence pointer to access routines

 * @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

 *

 * 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; /* div., see below */

  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 i2c_driver *driver; /* and our access routines */

  struct device dev; /* the device structure */

  int irq; /* irq issued by device */

  struct list_head detected;

};

下面分析i2c_adapter、i2c_algorithm、i2c_driver和i2c_client这4个数据结构的作用以及其盘根错节的关系。

(1) i2c_adapter与i2c_algorithm

i2c_adapter对应于物理上的一个适配器，而i2c_algorithm对应一套通信方法。一个I2C适配器需要i2c_algorithm提供的通信函数来控制适配器产生特定的访问周期。缺少i2c_algorithm的i2c_adapter什么也做不了，因此i2c_adapter中包含所使用的i2c_algorithm指针。

i2c_algorithm中的关键函数master_xfer()用于产生I2C访问周期需要的信号，以i2c_msg为单位。i2c_msg结构体也是非常重要的，它定义于kernel/include/uapi/linux/i2c.h中，下面的代码清单给出了i2c_msg结构体的定义，其主要成员表明了I2C的传输地址、方向、缓冲区、缓冲区长度等信息。

i2c_msg结构体：

/**

 * 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_TEN 0x0010 /* this is a ten bit chip address */

  #define I2C_M_RD 0x0001 /* read data, from slave to master */

  #define I2C_M_STOP 0x8000

  /* if I2C_FUNC_PROTOCOL_MANGLING */

  #define I2C_M_NOSTART 0x4000

  /* if I2C_FUNC_NOSTART */

  #define I2C_M_REV_DIR_ADDR 0x2000

  /* if I2C_FUNC_PROTOCOL_MANGLING */

  #define I2C_M_IGNORE_NAK 0x1000

  /* if I2C_FUNC_PROTOCOL_MANGLING */

  #define I2C_M_NO_RD_ACK 0x0800

  /* if I2C_FUNC_PROTOCOL_MANGLING */

  #define I2C_M_RECV_LEN 0x0400

  /* length will be first received byte */

  __u16 len; /* msg length */

  __u8 *buf; /* pointer to msg data */

};

(2) 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。

i2c_client的信息通常在BSP的板文件中通过i2c_board_info填充，如下面的代码就定义了一个I2C设备的ID为“ad7142_joystick”、地址为0x2C、中断号为IRQ_PF5的i2c_client：

static struct i2c_board_info __initdata xxx_i2c_board_info[] = {
  I2C_BOARD_INFO("ad7142_joystick", 0x2C),
  .irq = IRQ_PF5,
}

在I2C总线驱动i2c_bus_type的match()函数i2c_device_match()中，会调用i2c_match_id()函数匹配在板文件中定义的ID和i2c_driver所支持的ID表。

(3) i2c_adapter与i2c_client

i2c_adapter和i2c_client的关系与I2C硬件体系中适配器和设备的关系一致，即i2c_client依附于i2c_adapter。由于一个适配器可以连接多个I2C设备，所以一个i2c_adapter也可以被多个i2c_client依附，i2c_adapter中包括依附于它的i2c_client的链表。

虽然I2C硬件体系结构比较简单，但是I2C体系结构在Linux中的实现是相当复杂的。当工程师拿到实际的电路板时，面对复杂的Linux I2C子系统，应该如何下手写驱动呢？究竟有那些需要亲自做的，那些是内核已经提供的呢？理清这个问题非常有意义，可以使我们在面对具体问题时迅速抓住重点。

一方面，适配器驱动可能是Linux内核本身还不包含的；另一方面，挂接在适配器上的具体设备驱动可能也是Linux内核还不包含的。因此，工程师要实现的主要工作如下：

l 提供I2C适配器的硬件驱动，探测、初始化I2C适配器、驱动CPU控制的I2C适配器从硬件上产生各种信号以及处理I2C中断等。

l 提供I2C适配器的Algorithm，用具体适配器的xxx_xfer()函数填充i2c_algorithm的master_xfer指针，并把i2c_algorithm指针赋值给i2c_adapter的algo指针。

l 实现I2C设备驱动中的i2c _driver接口，用具体设备yyy的yyy_probe()、yyy_remove()、yyy_suspend()、yyy_resume()函数指针和i2c_device_id设备ID表赋值给i2c_driver的probe、remove、suspend、resume和id_table指针。

l 实现I2C设备所对应类型的具体驱动，i2c_driver只是实现设备与总线的挂接，而挂接在总线上的设备则千差万别。例如，如果是字符设备，就实现文件操作接口，即实现具体设备yyy的yyy_read()、yyy_write()和yyy_ioctl()函数等；如果是声卡，就实现ALSA驱动。

Linux I2C核心：

I2C核心(kernel/drivers/i2c/i2c-core.c)提供了一组不依赖于硬件平台的接口函数，这个文件一般不需要被工程师修改，但是理解其中的主要函数非常关键，因为I2C总线驱动和设备驱动之间以I2C核心作为纽带。I2C核心中的主要函数如下。

(1) 增加/删除i2c_adapter

int i2c_add_adapter(struct i2c_adapter *adapter);
void i2c_del_adapter(struct i2c_adapter *adap);

(2) 增加/删除i2c_driver

int i2c_register_driver(struct module *owner, struct i2c_driver *driver);
void i2c_del_driver(struct i2c_driver *driver);

(3) 传输、发送和接收

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

i2c_transfer()函数用于进行I2C适配器和I2C设备之间的一组消息交互，其中第2个参数是一个指向i2c_msg数组的指针，所以i2c _ transfer()一次可以传输多个i2c_msg(考虑到很多外设的读写波形比较复杂，比如读寄存器可能要先写，所以需要两个以上的消息)。而对于时序比较简单的外设，i2c_master_send()和i2c_master_recv()函数内部会调用i2c_transfer()函数分别完成一条写消息和一条读消息，如下代码清单所示。

I2C核心的i2c_master_send()函数：

/**

 * i2c_master_send - issue a single I2C message in master transmit mode

 * @client: Handle to slave device

 * @buf: Data that will be written to the slave

 * @count: How many bytes to write, must be less than 64k since msg.len is u16

 *

 * Returns negative errno, or else the number of bytes written.

 */

int i2c_master_send(const struct i2c_client *client, const char *buf, int count)
{
  int ret;

  struct i2c_adapter *adap = client->adapter;

  struct i2c_msg msg;

  msg.addr = client->addr;

  msg.flags = client->flags & I2C_M_TEN;

  msg.len = count;

  msg.buf = (char *)buf;

  ret = i2c_transfer(adap, &msg, 1);

  /*
   * If everything went ok (i.e. 1 msg transmitted), return #bytes  
   * transmitted, else error code.  
   */
  return (ret == 1) ? count : ret;

}

I2C核心的i2c_master_recv()函数：

/**

 * i2c_master_recv - issue a single I2C message in master receive mode

 * @client: Handle to slave device

 * @buf: Where to store data read from slave

 * @count: How many bytes to read, must be less than 64k since msg.len is u16

 *

 * Returns negative errno, or else the number of bytes read.

 */

int i2c_master_recv(const struct i2c_client *client, char *buf, int count)
{
  struct i2c_adapter *adap = client->adapter;

  struct i2c_msg msg;

  int ret;

  msg.addr = client->addr;

  msg.flags = client->flags & I2C_M_TEN;

  msg.flags |= I2C_M_RD;

  msg.len = count;

  msg.buf = buf;

  ret = i2c_transfer(adap, &msg, 1);

  /*
   * If everything went ok (i.e. 1 msg received), return #bytes received, 
   * else error code.
   */
  return (ret == 1) ? count : ret;
}

i2c_transfer()函数本身不具备驱动适配器物理硬件以完成消息交互的能力，它只是寻找到与i2c_adapter对应的i2c_algorithm，并使用i2c_algorithm的master_xfer()函数真正驱动硬件流程，代码清单如下所示。

I2C核心的i2c_transfer()函数：

/**

 * i2c_transfer - execute a single or combined I2C message

 * @adap: Handle to I2C bus

 * @msgs: One or more messages to execute before STOP is issued to

 * terminate the operation; each message begins with a START.

 * @num: Number of messages to be executed.

 *

 * Returns negative errno, else the number of messages executed.

 *

 * Note that there is no requirement that each message be sent to

 * the same slave address, although that is the most common model.

 */

int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num)

{

int ret;



/* REVISIT the fault reporting model here is weak:
 *
 *  - When we get an error after receiving N bytes from a slave,
 *    there is no way to report "N".
 *
 *  - When we get a NAK after transmitting N bytes to a slave,
 *    there is no way to report "N" ... or to let the master
 *    continue executing the rest of this combined message, if
 *    that's the appropriate response.
 *
 *  - When for example "num" is two and we successfully complete
 *    the first message but get an error part way through the
 *    second, it's unclear whether that should be reported as
 *    one (discarding status on the second message) or errno
 *    (discarding status on the first one).
 */

if (adap->algo->master_xfer) {
#ifdef DEBUG
for (ret = 0; ret < num; ret++) {

  dev_dbg(&adap->dev, "master_xfer[%d] %c, addr=0x%02x, "

  "len=%d%s\n", ret, (msgs[ret].flags & I2C_M_RD)

  ? 'R' : 'W', msgs[ret].addr, msgs[ret].len,

  (msgs[ret].flags & I2C_M_RECV_LEN) ? "+" : "");
}

#endif

if (in_atomic() || irqs_disabled()) {
    ret = i2c_trylock_adapter(adap);
 if (!ret)
    /* I2C activity is ongoing. */

    return -EAGAIN;
   } else {
     i2c_lock_adapter(adap);
   }
     ret = __i2c_transfer(adap, msgs, num);
     i2c_unlock_adapter(adap);
     return ret;
 } else {
    dev_dbg(&adap->dev, "I2C level transfers not supported\n");
    return -EOPNOTSUPP;
  }
}

Linux I2C设备驱动：

I2C设备驱动要使用i2c_driver和i2c_client数据结构并填充i2c_driver中的成员函数。i2c_client一般被包含在设备的私有信息结构体yyy_data中，而i2c_driver则适合被定义为全局变量并初始化，代码清单如下所示已被初始化的i2c_driver。

被初始化的i2c_driver：

static struct i2c_driver yyy_driver = {
  .driver = {
  .name = "yyy",
},
  .probe = yyy_probe,
  .remove = yyy_remove, 
  .id_table = yyy_id,
};

Linux I2C设备驱动的模块加载和卸载：

I2C设备驱动的模块加载函数通过I2C核心的i2c_add_driver()API函数添加i2c_driver的工作，而模块卸载函数需要做相反的工作；通过I2C核心的i2c_del_driver()函数删除i2c_driver。代码清单如下所示为I2C设备驱动的模块加载和卸载函数模板。

static int __init yyy_init(void)
{
  return i2c_add_driver(&yyy_driver);
}
module_init(yyy_init);

static void __exit yyy_exit(void)
{
  i2c_del_driver(&yyy_driver);
}
module_exit(yyy_exit);

Linux I2C设备驱动的数据传输：

在I2C设备上读写数据的时序且数据通常通过i2c_msg数组进行组织，最后通过i2c_transfer()函数完成，代码清单如下所示为一个读取指定偏移地址offs的寄存器。

I2C设备驱动的数据传输范例：

struct i2c_msg msg[2];

/* 第一条消息是写消息 */
msg[0].addr = client->addr;
msg[0].flags = 0;
msg[0].len = 1;
msg[0].buf = &offs;

/* 第二条消息是读消息 */
msg[1].addr = client->addr;
msg[1].flags = I2C_M_RD;
msg[1].len = sizeof(buf);
msg[1].buf = &buf[0];

i2c_transfer(client->adapter, msg, 2);

此文完结！

转载于:https://my.oschina.net/cht2000/blog/1505715