Commit | Line | Data |
---|---|---|
f6fcefa1 LC |
1 | ============================================ |
2 | Implementing I2C device drivers in userspace | |
3 | ============================================ | |
ccf988b6 | 4 | |
2f07c05f | 5 | Usually, I2C devices are controlled by a kernel driver. But it is also |
1da177e4 LT |
6 | possible to access all devices on an adapter from userspace, through |
7 | the /dev interface. You need to load module i2c-dev for this. | |
8 | ||
2f07c05f | 9 | Each registered I2C adapter gets a number, counting from 0. You can |
1da177e4 | 10 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. |
2e049d61 | 11 | Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all |
2f07c05f | 12 | I2C adapters present on your system at a given time. i2cdetect is part of |
fceb2d06 JD |
13 | the i2c-tools package. |
14 | ||
1da177e4 | 15 | I2C device files are character device files with major device number 89 |
675edea1 SH |
16 | and a minor device number corresponding to the number assigned as |
17 | explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., | |
2f07c05f | 18 | i2c-10, ...). All 256 minor device numbers are reserved for I2C. |
1da177e4 LT |
19 | |
20 | ||
21 | C example | |
22 | ========= | |
23 | ||
2f07c05f | 24 | So let's say you want to access an I2C adapter from a C program. |
ccf988b6 | 25 | First, you need to include these two headers:: |
91b28aeb C |
26 | |
27 | #include <linux/i2c-dev.h> | |
28 | #include <i2c/smbus.h> | |
29 | ||
1da177e4 | 30 | Now, you have to decide which adapter you want to access. You should |
fceb2d06 JD |
31 | inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. |
32 | Adapter numbers are assigned somewhat dynamically, so you can not | |
33 | assume much about them. They can even change from one boot to the next. | |
1da177e4 | 34 | |
ccf988b6 | 35 | Next thing, open the device file, as follows:: |
fceb2d06 | 36 | |
1da177e4 LT |
37 | int file; |
38 | int adapter_nr = 2; /* probably dynamically determined */ | |
39 | char filename[20]; | |
675edea1 | 40 | |
fceb2d06 JD |
41 | snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); |
42 | file = open(filename, O_RDWR); | |
43 | if (file < 0) { | |
1da177e4 LT |
44 | /* ERROR HANDLING; you can check errno to see what went wrong */ |
45 | exit(1); | |
46 | } | |
47 | ||
48 | When you have opened the device, you must specify with what device | |
ccf988b6 | 49 | address you want to communicate:: |
fceb2d06 | 50 | |
1da177e4 | 51 | int addr = 0x40; /* The I2C address */ |
fceb2d06 JD |
52 | |
53 | if (ioctl(file, I2C_SLAVE, addr) < 0) { | |
1da177e4 LT |
54 | /* ERROR HANDLING; you can check errno to see what went wrong */ |
55 | exit(1); | |
56 | } | |
57 | ||
58 | Well, you are all set up now. You can now use SMBus commands or plain | |
59 | I2C to communicate with your device. SMBus commands are preferred if | |
ccf988b6 | 60 | the device supports them. Both are illustrated below:: |
fceb2d06 | 61 | |
257d6ef4 | 62 | __u8 reg = 0x10; /* Device register to access */ |
1da177e4 LT |
63 | __s32 res; |
64 | char buf[10]; | |
fceb2d06 | 65 | |
1da177e4 | 66 | /* Using SMBus commands */ |
257d6ef4 | 67 | res = i2c_smbus_read_word_data(file, reg); |
1da177e4 | 68 | if (res < 0) { |
2f07c05f | 69 | /* ERROR HANDLING: I2C transaction failed */ |
1da177e4 LT |
70 | } else { |
71 | /* res contains the read word */ | |
72 | } | |
fceb2d06 | 73 | |
40d802cb SH |
74 | /* |
75 | * Using I2C Write, equivalent of | |
76 | * i2c_smbus_write_word_data(file, reg, 0x6543) | |
77 | */ | |
257d6ef4 | 78 | buf[0] = reg; |
1da177e4 LT |
79 | buf[1] = 0x43; |
80 | buf[2] = 0x65; | |
257d6ef4 | 81 | if (write(file, buf, 3) != 3) { |
2f07c05f | 82 | /* ERROR HANDLING: I2C transaction failed */ |
1da177e4 | 83 | } |
fceb2d06 | 84 | |
1da177e4 | 85 | /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ |
fceb2d06 | 86 | if (read(file, buf, 1) != 1) { |
2f07c05f | 87 | /* ERROR HANDLING: I2C transaction failed */ |
1da177e4 LT |
88 | } else { |
89 | /* buf[0] contains the read byte */ | |
90 | } | |
91 | ||
fceb2d06 JD |
92 | Note that only a subset of the I2C and SMBus protocols can be achieved by |
93 | the means of read() and write() calls. In particular, so-called combined | |
94 | transactions (mixing read and write messages in the same transaction) | |
95 | aren't supported. For this reason, this interface is almost never used by | |
96 | user-space programs. | |
97 | ||
1da177e4 LT |
98 | IMPORTANT: because of the use of inline functions, you *have* to use |
99 | '-O' or some variation when you compile your program! | |
100 | ||
101 | ||
102 | Full interface description | |
103 | ========================== | |
104 | ||
fceb2d06 | 105 | The following IOCTLs are defined: |
1da177e4 | 106 | |
ccf988b6 | 107 | ``ioctl(file, I2C_SLAVE, long addr)`` |
1da177e4 LT |
108 | Change slave address. The address is passed in the 7 lower bits of the |
109 | argument (except for 10 bit addresses, passed in the 10 lower bits in this | |
110 | case). | |
111 | ||
ccf988b6 | 112 | ``ioctl(file, I2C_TENBIT, long select)`` |
1da177e4 | 113 | Selects ten bit addresses if select not equals 0, selects normal 7 bit |
6662cbb9 DB |
114 | addresses if select equals 0. Default 0. This request is only valid |
115 | if the adapter has I2C_FUNC_10BIT_ADDR. | |
1da177e4 | 116 | |
ccf988b6 | 117 | ``ioctl(file, I2C_PEC, long select)`` |
1da177e4 LT |
118 | Selects SMBus PEC (packet error checking) generation and verification |
119 | if select not equals 0, disables if select equals 0. Default 0. | |
6662cbb9 DB |
120 | Used only for SMBus transactions. This request only has an effect if the |
121 | the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just | |
122 | doesn't have any effect. | |
1da177e4 | 123 | |
ccf988b6 MCC |
124 | ``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` |
125 | Gets the adapter functionality and puts it in ``*funcs``. | |
1da177e4 | 126 | |
ccf988b6 | 127 | ``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` |
1da177e4 | 128 | Do combined read/write transaction without stop in between. |
6662cbb9 | 129 | Only valid if the adapter has I2C_FUNC_I2C. The argument is |
ccf988b6 | 130 | a pointer to a:: |
1da177e4 | 131 | |
ccf988b6 | 132 | struct i2c_rdwr_ioctl_data { |
1da177e4 LT |
133 | struct i2c_msg *msgs; /* ptr to array of simple messages */ |
134 | int nmsgs; /* number of messages to exchange */ | |
ccf988b6 | 135 | } |
1da177e4 LT |
136 | |
137 | The msgs[] themselves contain further pointers into data buffers. | |
138 | The function will write or read data to or from that buffers depending | |
139 | on whether the I2C_M_RD flag is set in a particular message or not. | |
140 | The slave address and whether to use ten bit address mode has to be | |
141 | set in each message, overriding the values set with the above ioctl's. | |
142 | ||
ccf988b6 MCC |
143 | ``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` |
144 | If possible, use the provided ``i2c_smbus_*`` methods described below instead | |
b50cb3ea | 145 | of issuing direct ioctls. |
1da177e4 | 146 | |
2f07c05f | 147 | You can do plain I2C transactions by using read(2) and write(2) calls. |
1da177e4 LT |
148 | You do not need to pass the address byte; instead, set it through |
149 | ioctl I2C_SLAVE before you try to access the device. | |
150 | ||
675edea1 | 151 | You can do SMBus level transactions (see documentation file smbus-protocol |
ccf988b6 MCC |
152 | for details) through the following functions:: |
153 | ||
1da177e4 LT |
154 | __s32 i2c_smbus_write_quick(int file, __u8 value); |
155 | __s32 i2c_smbus_read_byte(int file); | |
156 | __s32 i2c_smbus_write_byte(int file, __u8 value); | |
157 | __s32 i2c_smbus_read_byte_data(int file, __u8 command); | |
158 | __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); | |
159 | __s32 i2c_smbus_read_word_data(int file, __u8 command); | |
160 | __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); | |
161 | __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); | |
cee807cf WS |
162 | __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length, |
163 | __u8 *values); | |
1da177e4 | 164 | __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); |
675edea1 | 165 | __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, |
1da177e4 | 166 | __u8 *values); |
ccf988b6 | 167 | |
1da177e4 LT |
168 | All these transactions return -1 on failure; you can read errno to see |
169 | what happened. The 'write' transactions return 0 on success; the | |
170 | 'read' transactions return the read value, except for read_block, which | |
171 | returns the number of values read. The block buffers need not be longer | |
172 | than 32 bytes. | |
173 | ||
b50cb3ea SH |
174 | The above functions are made available by linking against the libi2c library, |
175 | which is provided by the i2c-tools project. See: | |
176 | https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/. | |
7c15fd12 JD |
177 | |
178 | ||
179 | Implementation details | |
180 | ====================== | |
181 | ||
182 | For the interested, here's the code flow which happens inside the kernel | |
183 | when you use the /dev interface to I2C: | |
184 | ||
ccf988b6 MCC |
185 | 1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in |
186 | section "C example" above. | |
187 | ||
188 | 2) These open() and ioctl() calls are handled by the i2c-dev kernel | |
189 | driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), | |
190 | respectively. You can think of i2c-dev as a generic I2C chip driver | |
191 | that can be programmed from user-space. | |
192 | ||
193 | 3) Some ioctl() calls are for administrative tasks and are handled by | |
194 | i2c-dev directly. Examples include I2C_SLAVE (set the address of the | |
195 | device you want to access) and I2C_PEC (enable or disable SMBus error | |
196 | checking on future transactions.) | |
197 | ||
198 | 4) Other ioctl() calls are converted to in-kernel function calls by | |
199 | i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter | |
200 | functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which | |
201 | performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). | |
202 | ||
203 | The i2c-dev driver is responsible for checking all the parameters that | |
204 | come from user-space for validity. After this point, there is no | |
205 | difference between these calls that came from user-space through i2c-dev | |
206 | and calls that would have been performed by kernel I2C chip drivers | |
207 | directly. This means that I2C bus drivers don't need to implement | |
208 | anything special to support access from user-space. | |
209 | ||
210 | 5) These i2c.h functions are wrappers to the actual implementation of | |
211 | your I2C bus driver. Each adapter must declare callback functions | |
212 | implementing these standard calls. i2c.h:i2c_get_functionality() calls | |
213 | i2c_adapter.algo->functionality(), while | |
214 | i2c-core-smbus.c:i2c_smbus_xfer() calls either | |
215 | adapter.algo->smbus_xfer() if it is implemented, or if not, | |
216 | i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls | |
217 | i2c_adapter.algo->master_xfer(). | |
7c15fd12 JD |
218 | |
219 | After your I2C bus driver has processed these requests, execution runs | |
220 | up the call chain, with almost no processing done, except by i2c-dev to | |
221 | package the returned data, if any, in suitable format for the ioctl. |