/***************************************************I2C设备驱动**********************************************************************/

/*linux的I2C驱动分为3部分：

 *1：I2C核心：

 *I2C核心核心提供了I2C总线驱动和设备驱动的注册、注销方法，I2C通信方法(algorithm(算法))上层的、与具体适配器无关的代码以及探测设备、检测设备地址的上层代码等。

 *

 *2：I2C总线驱动：

 *      I2C总线驱动是对I2C硬件体系结构中适配器(就是i2c控制器)端的实现，适配器可由CPU控制。I2C总线驱动主要包含了I2C适配器数据结构i2c_adapter、I2C适配器的algorithm数据结构

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

 *

 *3：I2C设备驱动：

 *I2C设备驱动(也称客户程序)是对I2C硬件体系结构中设备端的实现，设备一般挂接在I2C适配器上，I2C设备驱动主要包括数据结构i2c_driver和i2c_client，我们需要根据具体设备实现其中的成员函数。

 *

 *在linux2.6内核中，所有的I2C设备都在sysfs文件系统中显示，存于/sys/bus/i2c/目录下。

 *

 *linux内核源代码中的drivers下的i2c目录包含如下文件和目录：

 *1：i2c-core.c    这个文件实现了I2C核心的功能以及/proc/bus/i2c接口

 *

 *2：i2c-dev.c    实现了I2C适配器设备文件的功能，每一个I2C适配器都被分配一个设备。通过适配器访问设备时的主设备号都为89，此设备号为0-255，应用程序通过“i2c-%d”(i2c-0,i2c-1,......)文件名

 *                并使用文件操作接口open()、write()、read()、ioctl()和close()等来访问设备，从而访问挂接在I2C适配器上的I2C设备的存储空间或寄存器，并控制I2C设备的工作方式。

 *               

 *3：chip目录      这个目录包含了一些特定的I2C设备驱动，如 DS1337实时时钟芯片、I2C接口的EEPROM驱动等，在具体的I2C设备驱动中，调用的都是I2C核心提供的接口，因     此，这使得具体的I2C设备驱动不依赖于

 *                 CPU的类型和I2C控制器的硬件特性。

 *

 *4：busses目录    这个文件中包含一些I2C总线的驱动，如针对S3C2410、S3C2440、S3C6410等处理器的I2C控制器驱动为i2c-s3c2410.c。

 *

 *5：algos目录     实现了一些I2C总线适配器的algorithm。

 *

 *此外在i2c.h中对i2c_driver 、i2c_client 、i2c_adapter 、i2c_algorithm这4个数据结构进行了定义，理解这4个结构体非常重要 

 */

 

--------------------------------------------struct i2c_adapter----------------------------------------------------

struct i2c_adapter {      //该结构对应物理上的一个适配器(I2C控制器)，一个I2C适配器需要i2c_algorithm中提供的通信函数来控制适配器上产生特定的访问周期，缺少i2c_algorithm的i2c_adapter什么都做不了，

                          //因此该结构中包含了i2c_algorithm指针

                         

  struct module *owner;   //THIS_MODULE

  unsigned int id;        //algorithms的类型，定义于i2c-id.h，以I2C_ALGO_开始

  unsigned int class;     /* classes to allow probing for */   //允许探测的类

  const struct i2c_algorithm *algo; /* the algorithm to access the bus */   //总线通信方法结构体指针

  void *algo_data;        //algorithm数据，多数I2C总线驱动会定义设备私有结构体，通常用此指针指向它

 

  /* --- administration stuff. */

  int (*client_register)(struct i2c_client *) __deprecated;   //client注册时调用

  int (*client_unregister)(struct i2c_client *) __deprecated; //client注销时调用

 

  /* data fields that are valid for all devices */

  u8 level;       /* nesting level for lockdep */

  struct mutex bus_lock;     //控制并发的信号量

  struct mutex clist_lock;

 

  int timeout;      /* in jiffies */

  int retries;                                     //重试次数

  struct device dev;    /* the adapter device */   //适配器设备

 

  int nr;                                          //适配器的个数，若超过一个则应该调用int i2c_add_numbered_adapter(struct i2c_adapter *adap)函数来添加适配器

  struct list_head clients; /* DEPRECATED */       //client链表头（由于一个适配器上可以连接多个I2C设备，所以一个i2c_adapter可以被多个i2c_client依附，i2c_adapter中包括依附于它的i2c_client的链表）

  char name[48];                                   //适配器名称

  struct completion dev_released;                  //用于同步

}; 

-----------------------------------------------------------------------------------------------------------------

 

--------------------------------------------struct i2c_algorithm-------------------------------------------------

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

//I2C传输函数指针，用于产生I2C访问周期需要的信号，以i2c_msg(I2c消息)为单位，该结构也非常重要，其定义如下：

//struct i2c_msg {   //早期I2C设备上读写数据的时序和数据通常通过该结构体数组来组织，最后通过i2c_transfer发送（实际还是通过master_xfer发送）

//          __u16 addr;      //低7位是设备地址，

//          __u16 flags;     //标志,标志读(flags=1)还是写(flags=0)

//          #define I2C_M_TEN   0x0010  /* this is a ten bit chip address */  //芯片的地址是10位

//          #define I2C_M_RD    0x0001  /* read data, from slave to master */ //从设备读取数据

//          #define I2C_M_NOSTART   0x4000  /* if I2C_FUNC_PROTOCOL_MANGLING */

//          #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;    //消息长度

//          __u8 *buf;    // 指向消息数据的指针

//               };

         int num);

  int (*smbus_xfer) (struct i2c_adapter *adap, u16 addr,                //smbus传输函数指针，SMbus大部分基于I2C总线规范，SMbus不需要增加额外的引脚，与I2C总线相比，

                                                                        //SMbus增加了一些新的功能特性，在访问时序也有一定的差异

         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 *);                         //返回适配器支持的功能

}; 

----------------------------------------------------------------------------------------------------------------

 

--------------------------------------------struct i2c_driver---------------------------------------------------           

struct i2c_driver {    //该结构提供了一套驱动的方法,其主要成员函数probe()、remove()、suspend()、resume()等

  int id;              

  unsigned int class;

 

  /* Notifies the driver that a new bus has appeared. This routine

   * can be used by the driver to test if the bus meets its conditions

   * & seek for the presence of the chip(s) it supports. If found, it

   * registers the client(s) that are on the bus to the i2c admin. via

   * i2c_attach_client.  (LEGACY I2C DRIVERS ONLY)

   */

  int (*attach_adapter)(struct i2c_adapter *);  

  //依附i2c_adapter函数指针,I2C driver在调用I2C_add_driver() 注册时，

  //对发现的每一个I2C adapter都要调用该函数，检查该I2C adapter是否符合I2C driver的特定条件，

  //如果符合条件则连接此I2C adapter，并通过I2C adapter来实现对I2C总线

  //及I2C设备的访问( 直接调用I2C核心的i2c_probe函数)。

                                                

  int (*detach_adapter)(struct i2c_adapter *);  

  //脱离i2c_adapter函数指针,I2C driver在删除一个I2C device时调用该函数，

  //清除描述这个I2C device的数据结构，这样以后就不能访问该设备了

 

  /* tells the driver that a client is about to be deleted & gives it

   * the chance to remove its private data. Also, if the client struct

   * has been dynamically allocated by the driver in the function above,

   * it must be freed here.  (LEGACY I2C DRIVERS ONLY)

   */

  int (*detach_client)(struct i2c_client *) __deprecated;  //i2c_client脱离函数指针

 

  /* Standard driver model interfaces, for "new style" i2c drivers.

   * With the driver model, device enumeration is NEVER done by drivers;

   * it‘s done by infrastructure.  (NEW STYLE DRIVERS ONLY)

   */

  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 *);  //恢复设备

 

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

  //该驱动所支持的设备类型，是该驱动所支持的I2C设备的ID表，在i2c总线驱动i2c_bus_type的mach()函数

  //i2c_device_match()中会调用i2c_match_id()

  //函数比较i2c_client中的name和i2c_driver的id_table->name是否相同，若相同则支持。

  //

  //struct i2c_device_id {

  //                      char name[I2C_NAME_SIZE];

  //                      kernel_ulong_t driver_data  /* Data private to the driver */

  //                      __attribute__((aligned(sizeof(kernel_ulong_t))));

  //                      };

 

  /* Device detection callback for automatic device creation */

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

  const struct i2c_client_address_data *address_data;

  struct list_head clients;

};

----------------------------------------------------------------------------------------------------------------

 

--------------------------------------------struct i2c_client---------------------------------------------------

struct i2c_client { 

//该结构对应于真实的物理设备，每个I2C设备都需要一个i2c_client来描述，i2c_driver与i2c_client的关系是一对多，

//一个i2c_driver上可以支持多个同等类型的i2c_client。由于一个适配器上可以连接多个

//I2C设备，所以一个i2c_adapter可以被多个i2c_client依附，i2c_adapter中包括依附于它的i2c_client的链表。

                    

  unsigned short flags;   /* div., see below    */            //标志

  unsigned short addr;    /* chip address - NOTE: 7bit  */    //低7位为芯片地址

          /* addresses are stored in the  */

          /* _LOWER_ 7 bits   */

  char name[I2C_NAME_SIZE];   //设备名称，在i2c总线驱动i2c_bus_type的mach()函数

  //i2c_device_match()中会调用i2c_match_id()函数比较name和i2c_driver

                              //的id_table->name是否相同，若相同则支持

                                                             

  struct i2c_adapter *adapter;  /* the adapter we sit on  */  //依附的i2c_adapter

  struct i2c_driver *driver;  /* and our access routines  */  //依附的i2c_driver

  struct device dev;    /* the device structure   */          //设备结构体

  int irq;      /* irq issued by device   */                  //使用的中断号

  struct list_head list;    /* DEPRECATED */                  //链表头

  struct list_head detected;

  struct completion released;                                 //用于同步

};

----------------------------------------------------------------------------------------------------------------

/*

 *如何写linux的I2C设备驱动程序：

 *

 *首先适配器可能是linux内核本身还不包含的，其次，挂接在适配器上的具体设备驱动可能也是linux内核还不包含的，

 *因此需要实现的主要工作如下：

 *

 *1：（总线驱动）提供I2C适配器的硬件驱动，探测、初始化I2C适配器(如申请I2C的I/O地址和中断号)、驱动CPU控制的

 *    I2C适配器从硬件上产生各种信号以及处理I2C中断等

 *

 *2：（总线驱动）提供I2C适配器的algorithm，用具体适配器的xxx_xfer()函数填充i2c_algorithm的master_xfer指针，

 *    并把i2c_algorithm指针赋值给i2c_adapter的algo指针

 *

 *3：（设备驱动）实现I2C设备驱动中的i2c_driver接口，用具体设备xxx的xxx_probe() 、xxx_remove() 、xxx_suspend() 、

 *    xxx_resume()函数指针和i2c_device_id设备ID表赋值给i2c_driver的probe、remove、suspend、resume和id_table指针

 *             

 *4：（设备驱动）实现I2C设备所对应类型的具体驱动，i2c_driver只是实现了设备与总线的挂接，而挂接在总线上的设备

 *    则是千差万别。例如，如果是字符设备，就实现文件系统接口(read,write等系统调用的操作函数)如果是声卡，就实现ALSA驱动

 *             

 *I2C核心中提供了一组不依赖于硬件平台的接口函数：

 */

int i2c_add_adapter(struct i2c_adapter *adapter);   //增加i2c_adapter（该函数中注册了i2c_adapter） 

int i2c_del_adapter(struct i2c_adapter *adap);      //删除i2c_adapter（该函数中注销了i2c_adapter）      

 

int i2c_register_driver(struct module *owner, struct i2c_driver *driver);  //注册              

void i2c_del_driver(struct i2c_driver *driver);  //删除i2c_driver（该函数中注销了i2c_driver）

int i2c_add_driver(struct i2c_driver *driver);   //增加i2c_driver（该函数中注册了i2c_driver）

              

int i2c_attach_client(struct i2c_client *client);

//依附i2c_client，当一个具体的client被侦测到被关联的时候，设备和sysfs文件将被注册(device_register(&client->dev))

int i2c_detach_client(struct i2c_client *client);

//脱离i2c_client，当一个具体的client被脱离的时候，sysfs文件和设备被注销(device_unregister(&client->dev))           

              

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

//i2c的传输（该函数用于进行I2C适配器和I2C设备之间的一组消息互传，该函数实际使用了i2c_algorithm的master_xfer函数真正驱动硬件），num为i2c_msg的个数

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

//i2c的发送（该函数会调用i2c_transfer来完成一条消息的写），buf为指向要发送数据的指针，count为要发送的数据的大小（单位为字节）

int i2c_master_recv(struct i2c_client *client, char *buf ,int count);     

//i2c的接收（该函数会调用i2c_transfer来完成一条消息的读）          

              

---------------------------------------------------------------------------------------------------------------

/*              

 *I2C总线驱动：

 *

 *加载模块的任务：

 *1：初始化I2C适配器所使用的硬件资源，如申请I/O地址，中断号等

 *2：初始化i2c_adapter数据结构成员

 *3：通过i2c_add_adapter添加i2c_adapter的数据结构

 *

 *卸载模块：

 *1：释放I2C适配器所使用的硬件资源，如释放I/O地址、中断号等

 *2：通过i2c_del_adapter删除i2c_adapter数据结构

 *

 *另外我们还需要为特定的I2C适配器实现其通信方法，主要实现i2c_algorithm的master_xfer函数和functionality函数：

 *

 *1：functionality函数非常坚持，用于返回algorithm所支持的协议，如I2C_FUNC_I2C、I2C_FUNC_10BIT_ADDR等在i2c.h中定义

 *2：master_xfer函数在i2c适配器上完成传输给它的i2c_msg数组中的每个I2C信息，其模板如下（当然也可以中断方式实现）：

 */

static int i2c_adapter_xxx_master_xfer(struct i2c_adapter *adap, struct i2c_msg *msgs,  int num)

{

   .......

   for(i=0;i<num;i++)

      {

        i2c_adapter_xxx_start();     //产生开始位，需要根据具体硬件实现

        if(msgs[i]->flags&I2C_M_RD)  //判断是如果是读

           {

            i2c_adapter_xxx_setaddr((msgs->addr<<1)|1);   //发送从设备地址，需要根据具体硬件实现

            i2c_adapter_xxx_wait_ack();                   //等待应答信号，需要根据具体硬件实现

            i2c_adapter_xxx_readbytes(msgs[i]->buf,msgs[i]->len);

            //读取长度为msgs[i]->len的数据到msgs[i]->buf，用于从设备接收一串数据，该函数内部也会涉及应答，需要根据具体硬件实现

           }

        else  //否则是写数据

          {

           i2c_adapter_xxx_setaddr(msgs->addr<<1);//发送从设备地址，需要根据具体硬件实现

           i2c_adapter_xxx_wait_ack();            //等待应答信号，需要根据具体硬件实现

           i2c_adapter_xxx_writebytes(msgs[i]->buf,msgs[i]->len);

           //写长度为msgs[i]->len的数据到msgs[i]->buf，用于向设备写入一串数据，该函数内部也会涉及应答，需要根据具体硬件实现

          }

      }

   i2c_adapter_xxx_stop();  //产生停止位，需要根据具体硬件实现

  }

 

//参考总线驱动：i2c-s3c2410.c

 

-------------------------------------------------------------------------------------------------------------

//I2C设备驱动：              

 

//1:I2C设备驱动要使用i2c_driver和i2c_client数据结构并填充i2c_driver中的成员函数，i2c_client一般被包含在设备的私有信息结构体中，

//而i2c_driver则合适被定义为全局变量并初始化，如下：

static struct i2c_driver xxx_driver = {

  .driver = {

    .name = "xxx",

    .owner = THIS_MODULE,

  },

  .probe = xxx_probe,

  .remove = __devexit_p(xxx_remove),

  .id_table = xxx_ids,

  .attach_adapter = xxx_attach_adapter,

  .detach_adapter = xxx_detach_adapter,

};              

//2：定义分配一个i2c_client数据结构并初始化它 ，例如：

  xxx_client = kzalloc(sizeof(struct i2c_client), GFP_KERNEL);

  xxx_client->addr    = address;

  xxx_client->adapter = adapter;

  xxx_client->driver  = &xxx_driver;

  strcpy(xxx_client->name, "xxx");

  i2c_attach_client(xxx_client);

              

//2：通过i2c_add_driver函数添加i2c_driver（也即注册）

 

//3：通过i2c_del_driver函数删除i2c_driver（也即注销）

              

//4：定义和设置i2c_msg数组，最后调用i2c_transfer函数来传输数据，例如：

  msg[0].addr  = xxx_client->addr;  /* 目的 */

  msg[0].buf   = val;                   /* 源 */

  msg[0].len   = 2;                     /* 地址+数据=2 byte */

  msg[0].flags = 0;                     /* 表示写 */

 

  ret = i2c_transfer(xxx_client->adapter, msg, 1);

/*              

 *参考设备驱动：i2c-dev.c

 *关于i2c-dev.c 的说明：该文件可以被看作一个I2C设备驱动，不过，它实现了一个虚拟i2c_client是虚拟、临时的，

 *该文件实现了i2c_driver的成员函数已经文件操作接口，所以该文件的主体是“i2c_driver成员函数+字符设备驱动”

 *但是很遗憾，大多数稍微复杂一点I2C设备的读写并不对应于一条消息，往往需要两条以上的消息来进行一次读写周期，

 *因此该文件下 i2cdev_read和i2cdev_write函数不具备太强的通用性，对于两条以上消息组成的读写，在用户空间

 *需要组织i2c_msg消息数组并调用I2C_RDWRIOCTL命令（ioctl系统调用）            

 *

 *常用的IOCTL包括I2C_SLAVE（设置从设备地址）、I2C_RETRIES（没有收到设备ACK情况下重试次数，默认为1）、

 *I2C_TIMEOU（超时）、I2C_RDWR。

 */                                                                                                                                                                                             

/*********************************************************end*****************************************************************/

#ifndef __PWM_H__

#define __PWM_H__

 

#define BEEP_ON  _IO(‘k‘, 0)

#define BEEP_OFF _IO(‘k‘, 1)

#define SET_CNT  _IO(‘k‘, 2)

#define SET_PRE  _IO(‘k‘, 3)

 

#endif // __PWM_H__