patch-2.3.34 linux/Documentation/i2c/dev-interface

• Lines: 125
• Date: Thu Dec 16 13:59:38 1999
• Orig file: v2.3.33/linux/Documentation/i2c/dev-interface
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.3.33/linux/Documentation/i2c/dev-interface linux/Documentation/i2c/dev-interface
@@ -0,0 +1,124 @@
+Usually, i2c devices are controlled by a kernel driver. But it is also
+possible to access all devices on an adapter from userspace, through
+the /dev interface. You need to load module i2c-dev for this.
+
+Each registered i2c adapter gets a number, counting from 0. You can
+examine /proc/bus/i2c to see what number corresponds to which adapter.
+I2C device files are character device files with major device number 89
+and a minor device number corresponding to the number assigned as 
+explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., 
+i2c-10, ...). All 256 minor device numbers are reserved for i2c.
+
+
+C example
+=========
+
+So let's say you want to access an i2c adapter from a C program. The
+first thing to do is `#include <linux/i2c.h>" and "#include <linux/i2c-dev.h>. 
+Yes, I know, you should never include kernel header files, but until glibc 
+knows about i2c, there is not much choice.
+
+Now, you have to decide which adapter you want to access. You should
+inspect /proc/bus/i2c to decide this. Adapter numbers are assigned
+somewhat dynamically, so you can not even assume /dev/i2c-0 is the
+first adapter.
+
+Next thing, open the device file, as follows:
+  int file;
+  int adapter_nr = 2; /* probably dynamically determined */
+  char filename[20];
+  
+  sprintf(filename,"/dev/i2c-%d",adapter_nr);
+  if ((file = open(filename,O_RDWR)) < 0) {
+    /* ERROR HANDLING; you can check errno to see what went wrong */
+    exit(1);
+  }
+
+When you have opened the device, you must specify with what device
+address you want to communicate:
+  int addr = 0x40; /* The I2C address */
+  if (ioctl(file,I2C_SLAVE,addr) < 0) {
+    /* ERROR HANDLING; you can check errno to see what went wrong */
+    exit(1);
+  }
+
+Well, you are all set up now. You can now use SMBus commands or plain
+I2C to communicate with your device. SMBus commands are preferred if
+the device supports them. Both are illustrated below.
+  __u8 register = 0x10; /* Device register to access */
+  __s32 res;
+  char buf[10];
+  /* Using SMBus commands */
+  res = i2c_smbus_read_word_data(file,register);
+  if (res < 0) {
+    /* ERROR HANDLING: i2c transaction failed */
+  } else {
+    /* res contains the read word */
+  }
+  /* Using I2C Write, equivalent of 
+           i2c_smbus_write_word_data(file,register,0x6543) */
+  buf[0] = register;
+  buf[1] = 0x43;
+  buf[2] = 0x65;
+  if ( write(file,buf,3) != 3) {
+    /* ERROR HANDLING: i2c transaction failed */
+  }
+  /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
+  if (read(file,buf,1) != 1) {
+    /* ERROR HANDLING: i2c transaction failed */
+  } else {
+    /* buf[0] contains the read byte */
+  }
+
+
+Full interface description
+==========================
+
+The following IOCTLs are defined and fully supported 
+(see also i2c-dev.h and i2c.h):
+
+ioctl(file,I2C_SLAVE,long addr)
+  Change slave address. The address is passed in the 7 lower bits of the
+  argument (except for 10 bit addresses, passed in the 10 lower bits in this
+  case).
+
+ioctl(file,I2C_TENBIT,long select)
+  Selects ten bit addresses if select not equals 0, selects normal 7 bit
+  addresses if select equals 0.
+
+ioctl(file,I2C_FUNCS,unsigned long *funcs)
+  Gets the adapter functionality and puts it in *funcs.
+
+Other values are NOT supported at this moment, except for I2C_SMBUS,
+which you should never directly call; instead, use the access functions
+below.
+
+You can do plain i2c transactions by using read(2) and write(2) calls.
+Combined read/write transactions are not yet supported (they will in
+the future, through an ioctl). You do not need to pass the address
+byte; instead, set it through ioctl I2C_SLAVE before you try to 
+access the device.
+
+You can do SMBus level transactions (see documentation file smbus-protocol 
+for details) through the following functions:
+  __s32 i2c_smbus_write_quick(int file, __u8 value);
+  __s32 i2c_smbus_read_byte(int file);
+  __s32 i2c_smbus_write_byte(int file, __u8 value);
+  __s32 i2c_smbus_read_byte_data(int file, __u8 command);
+  __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
+  __s32 i2c_smbus_read_word_data(int file, __u8 command);
+  __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
+  __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
+  __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
+  __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, 
+                                   __u8 *values);
+All these tranactions return -1 on failure; you can read errno to see
+what happened. The 'write' transactions return 0 on success; the
+'read' transactions return the read value, except for read_block, which
+returns the number of values read. The block buffers need not be longer
+than 32 bytes.
+
+The above functions are all macros, that resolve to calls to the
+i2c_smbus_access function, that on its turn calls a specific ioctl
+with the data in a specific format. Read the source code if you
+want to know what happens behind the screens.