Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Usually, i2c devices are controlled by a kernel driver. But it is also |
2 | possible to access all devices on an adapter from userspace, through | |
3 | the /dev interface. You need to load module i2c-dev for this. | |
4 | ||
5 | Each registered i2c adapter gets a number, counting from 0. You can | |
6 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. | |
7 | I2C device files are character device files with major device number 89 | |
8 | and a minor device number corresponding to the number assigned as | |
9 | explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., | |
10 | i2c-10, ...). All 256 minor device numbers are reserved for i2c. | |
11 | ||
12 | ||
13 | C example | |
14 | ========= | |
15 | ||
16 | So let's say you want to access an i2c adapter from a C program. The | |
1d772e25 JD |
17 | first thing to do is "#include <linux/i2c-dev.h>". Please note that |
18 | there are two files named "i2c-dev.h" out there, one is distributed | |
19 | with the Linux kernel and is meant to be included from kernel | |
20 | driver code, the other one is distributed with lm_sensors and is | |
21 | meant to be included from user-space programs. You obviously want | |
22 | the second one here. | |
1da177e4 LT |
23 | |
24 | Now, you have to decide which adapter you want to access. You should | |
25 | inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned | |
26 | somewhat dynamically, so you can not even assume /dev/i2c-0 is the | |
27 | first adapter. | |
28 | ||
29 | Next thing, open the device file, as follows: | |
30 | int file; | |
31 | int adapter_nr = 2; /* probably dynamically determined */ | |
32 | char filename[20]; | |
33 | ||
34 | sprintf(filename,"/dev/i2c-%d",adapter_nr); | |
35 | if ((file = open(filename,O_RDWR)) < 0) { | |
36 | /* ERROR HANDLING; you can check errno to see what went wrong */ | |
37 | exit(1); | |
38 | } | |
39 | ||
40 | When you have opened the device, you must specify with what device | |
41 | address you want to communicate: | |
42 | int addr = 0x40; /* The I2C address */ | |
43 | if (ioctl(file,I2C_SLAVE,addr) < 0) { | |
44 | /* ERROR HANDLING; you can check errno to see what went wrong */ | |
45 | exit(1); | |
46 | } | |
47 | ||
48 | Well, you are all set up now. You can now use SMBus commands or plain | |
49 | I2C to communicate with your device. SMBus commands are preferred if | |
50 | the device supports them. Both are illustrated below. | |
51 | __u8 register = 0x10; /* Device register to access */ | |
52 | __s32 res; | |
53 | char buf[10]; | |
54 | /* Using SMBus commands */ | |
55 | res = i2c_smbus_read_word_data(file,register); | |
56 | if (res < 0) { | |
57 | /* ERROR HANDLING: i2c transaction failed */ | |
58 | } else { | |
59 | /* res contains the read word */ | |
60 | } | |
61 | /* Using I2C Write, equivalent of | |
62 | i2c_smbus_write_word_data(file,register,0x6543) */ | |
63 | buf[0] = register; | |
64 | buf[1] = 0x43; | |
65 | buf[2] = 0x65; | |
66 | if ( write(file,buf,3) != 3) { | |
67 | /* ERROR HANDLING: i2c transaction failed */ | |
68 | } | |
69 | /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ | |
70 | if (read(file,buf,1) != 1) { | |
71 | /* ERROR HANDLING: i2c transaction failed */ | |
72 | } else { | |
73 | /* buf[0] contains the read byte */ | |
74 | } | |
75 | ||
76 | IMPORTANT: because of the use of inline functions, you *have* to use | |
77 | '-O' or some variation when you compile your program! | |
78 | ||
79 | ||
80 | Full interface description | |
81 | ========================== | |
82 | ||
83 | The following IOCTLs are defined and fully supported | |
1d772e25 | 84 | (see also i2c-dev.h): |
1da177e4 LT |
85 | |
86 | ioctl(file,I2C_SLAVE,long addr) | |
87 | Change slave address. The address is passed in the 7 lower bits of the | |
88 | argument (except for 10 bit addresses, passed in the 10 lower bits in this | |
89 | case). | |
90 | ||
91 | ioctl(file,I2C_TENBIT,long select) | |
92 | Selects ten bit addresses if select not equals 0, selects normal 7 bit | |
6662cbb9 DB |
93 | addresses if select equals 0. Default 0. This request is only valid |
94 | if the adapter has I2C_FUNC_10BIT_ADDR. | |
1da177e4 LT |
95 | |
96 | ioctl(file,I2C_PEC,long select) | |
97 | Selects SMBus PEC (packet error checking) generation and verification | |
98 | if select not equals 0, disables if select equals 0. Default 0. | |
6662cbb9 DB |
99 | Used only for SMBus transactions. This request only has an effect if the |
100 | the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just | |
101 | doesn't have any effect. | |
1da177e4 LT |
102 | |
103 | ioctl(file,I2C_FUNCS,unsigned long *funcs) | |
104 | Gets the adapter functionality and puts it in *funcs. | |
105 | ||
a68e2f48 | 106 | ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) |
1da177e4 LT |
107 | |
108 | Do combined read/write transaction without stop in between. | |
6662cbb9 DB |
109 | Only valid if the adapter has I2C_FUNC_I2C. The argument is |
110 | a pointer to a | |
1da177e4 | 111 | |
6662cbb9 | 112 | struct i2c_rdwr_ioctl_data { |
1da177e4 LT |
113 | struct i2c_msg *msgs; /* ptr to array of simple messages */ |
114 | int nmsgs; /* number of messages to exchange */ | |
115 | } | |
116 | ||
117 | The msgs[] themselves contain further pointers into data buffers. | |
118 | The function will write or read data to or from that buffers depending | |
119 | on whether the I2C_M_RD flag is set in a particular message or not. | |
120 | The slave address and whether to use ten bit address mode has to be | |
121 | set in each message, overriding the values set with the above ioctl's. | |
122 | ||
123 | ||
124 | Other values are NOT supported at this moment, except for I2C_SMBUS, | |
125 | which you should never directly call; instead, use the access functions | |
126 | below. | |
127 | ||
128 | You can do plain i2c transactions by using read(2) and write(2) calls. | |
129 | You do not need to pass the address byte; instead, set it through | |
130 | ioctl I2C_SLAVE before you try to access the device. | |
131 | ||
132 | You can do SMBus level transactions (see documentation file smbus-protocol | |
133 | for details) through the following functions: | |
134 | __s32 i2c_smbus_write_quick(int file, __u8 value); | |
135 | __s32 i2c_smbus_read_byte(int file); | |
136 | __s32 i2c_smbus_write_byte(int file, __u8 value); | |
137 | __s32 i2c_smbus_read_byte_data(int file, __u8 command); | |
138 | __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); | |
139 | __s32 i2c_smbus_read_word_data(int file, __u8 command); | |
140 | __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); | |
141 | __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); | |
142 | __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); | |
143 | __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, | |
144 | __u8 *values); | |
145 | All these transactions return -1 on failure; you can read errno to see | |
146 | what happened. The 'write' transactions return 0 on success; the | |
147 | 'read' transactions return the read value, except for read_block, which | |
148 | returns the number of values read. The block buffers need not be longer | |
149 | than 32 bytes. | |
150 | ||
151 | The above functions are all macros, that resolve to calls to the | |
152 | i2c_smbus_access function, that on its turn calls a specific ioctl | |
153 | with the data in a specific format. Read the source code if you | |
154 | want to know what happens behind the screens. |