1 ============================================
2 Implementing I2C device drivers in userspace
3 ============================================
4
5 Usually, I2C devices are controlled by a kerne
6 possible to access all devices on an adapter f
7 the /dev interface. You need to load module i2
8
9 Each registered I2C adapter gets a number, cou
10 examine /sys/class/i2c-dev/ to see what number
11 Alternatively, you can run "i2cdetect -l" to o
12 I2C adapters present on your system at a given
13 the i2c-tools package.
14
15 I2C device files are character device files wi
16 and a minor device number corresponding to the
17 explained above. They should be called "i2c-%d
18 i2c-10, ...). All 256 minor device numbers are
19
20
21 C example
22 =========
23
24 So let's say you want to access an I2C adapter
25 First, you need to include these two headers::
26
27 #include <linux/i2c-dev.h>
28 #include <i2c/smbus.h>
29
30 Now, you have to decide which adapter you want
31 inspect /sys/class/i2c-dev/ or run "i2cdetect
32 Adapter numbers are assigned somewhat dynamica
33 assume much about them. They can even change f
34
35 Next thing, open the device file, as follows::
36
37 int file;
38 int adapter_nr = 2; /* probably dynamically
39 char filename[20];
40
41 snprintf(filename, 19, "/dev/i2c-%d", adapte
42 file = open(filename, O_RDWR);
43 if (file < 0) {
44 /* ERROR HANDLING; you can check errno to
45 exit(1);
46 }
47
48 When you have opened the device, you must spec
49 address you want to communicate::
50
51 int addr = 0x40; /* The I2C address */
52
53 if (ioctl(file, I2C_SLAVE, addr) < 0) {
54 /* ERROR HANDLING; you can check errno to
55 exit(1);
56 }
57
58 Well, you are all set up now. You can now use
59 I2C to communicate with your device. SMBus com
60 the device supports them. Both are illustrated
61
62 __u8 reg = 0x10; /* Device register to acces
63 __s32 res;
64 char buf[10];
65
66 /* Using SMBus commands */
67 res = i2c_smbus_read_word_data(file, reg);
68 if (res < 0) {
69 /* ERROR HANDLING: I2C transaction failed
70 } else {
71 /* res contains the read word */
72 }
73
74 /*
75 * Using I2C Write, equivalent of
76 * i2c_smbus_write_word_data(file, reg, 0x65
77 */
78 buf[0] = reg;
79 buf[1] = 0x43;
80 buf[2] = 0x65;
81 if (write(file, buf, 3) != 3) {
82 /* ERROR HANDLING: I2C transaction failed
83 }
84
85 /* Using I2C Read, equivalent of i2c_smbus_r
86 if (read(file, buf, 1) != 1) {
87 /* ERROR HANDLING: I2C transaction failed
88 } else {
89 /* buf[0] contains the read byte */
90 }
91
92 Note that only a subset of the I2C and SMBus p
93 the means of read() and write() calls. In part
94 transactions (mixing read and write messages i
95 aren't supported. For this reason, this interf
96 user-space programs.
97
98 IMPORTANT: because of the use of inline functi
99 '-O' or some variation when you compile your p
100
101
102 Full interface description
103 ==========================
104
105 The following IOCTLs are defined:
106
107 ``ioctl(file, I2C_SLAVE, long addr)``
108 Change slave address. The address is passed
109 argument (except for 10 bit addresses, passe
110 case).
111
112 ``ioctl(file, I2C_TENBIT, long select)``
113 Selects ten bit addresses if select not equa
114 addresses if select equals 0. Default 0. Th
115 if the adapter has I2C_FUNC_10BIT_ADDR.
116
117 ``ioctl(file, I2C_PEC, long select)``
118 Selects SMBus PEC (packet error checking) ge
119 if select not equals 0, disables if select e
120 Used only for SMBus transactions. This requ
121 the adapter has I2C_FUNC_SMBUS_PEC; it is st
122 doesn't have any effect.
123
124 ``ioctl(file, I2C_FUNCS, unsigned long *funcs)
125 Gets the adapter functionality and puts it i
126
127 ``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_
128 Do combined read/write transaction without s
129 Only valid if the adapter has I2C_FUNC_I2C.
130 a pointer to a::
131
132 struct i2c_rdwr_ioctl_data {
133 struct i2c_msg *msgs; /* ptr to array o
134 int nmsgs; /* number of mess
135 }
136
137 The msgs[] themselves contain further pointe
138 The function will write or read data to or f
139 on whether the I2C_M_RD flag is set in a par
140 The slave address and whether to use ten bit
141 set in each message, overriding the values s
142
143 ``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioct
144 If possible, use the provided ``i2c_smbus_*`
145 of issuing direct ioctls.
146
147 You can do plain I2C transactions by using rea
148 You do not need to pass the address byte; inst
149 ioctl I2C_SLAVE before you try to access the d
150
151 You can do SMBus level transactions (see docum
152 for details) through the following functions::
153
154 __s32 i2c_smbus_write_quick(int file, __u8 v
155 __s32 i2c_smbus_read_byte(int file);
156 __s32 i2c_smbus_write_byte(int file, __u8 va
157 __s32 i2c_smbus_read_byte_data(int file, __u
158 __s32 i2c_smbus_write_byte_data(int file, __
159 __s32 i2c_smbus_read_word_data(int file, __u
160 __s32 i2c_smbus_write_word_data(int file, __
161 __s32 i2c_smbus_process_call(int file, __u8
162 __s32 i2c_smbus_block_process_call(int file,
163 __u8 *val
164 __s32 i2c_smbus_read_block_data(int file, __
165 __s32 i2c_smbus_write_block_data(int file, _
166 __u8 *value
167
168 All these transactions return -1 on failure; y
169 what happened. The 'write' transactions return
170 'read' transactions return the read value, exc
171 returns the number of values read. The block b
172 than 32 bytes.
173
174 The above functions are made available by link
175 which is provided by the i2c-tools project. S
176 https://git.kernel.org/pub/scm/utils/i2c-tools
177
178
179 Implementation details
180 ======================
181
182 For the interested, here's the code flow which
183 when you use the /dev interface to I2C:
184
185 1) Your program opens /dev/i2c-N and calls ioc
186 section "C example" above.
187
188 2) These open() and ioctl() calls are handled
189 driver: see i2c-dev.c:i2cdev_open() and i2c
190 respectively. You can think of i2c-dev as a
191 that can be programmed from user-space.
192
193 3) Some ioctl() calls are for administrative t
194 i2c-dev directly. Examples include I2C_SLAV
195 device you want to access) and I2C_PEC (ena
196 checking on future transactions.)
197
198 4) Other ioctl() calls are converted to in-ker
199 i2c-dev. Examples include I2C_FUNCS, which
200 functionality using i2c.h:i2c_get_functiona
201 performs an SMBus transaction using i2c-cor
202
203 The i2c-dev driver is responsible for check
204 come from user-space for validity. After th
205 difference between these calls that came fr
206 and calls that would have been performed by
207 directly. This means that I2C bus drivers d
208 anything special to support access from use
209
210 5) These i2c.h functions are wrappers to the a
211 your I2C bus driver. Each adapter must decl
212 implementing these standard calls. i2c.h:i2
213 i2c_adapter.algo->functionality(), while
214 i2c-core-smbus.c:i2c_smbus_xfer() calls eit
215 adapter.algo->smbus_xfer() if it is impleme
216 i2c-core-smbus.c:i2c_smbus_xfer_emulated()
217 i2c_adapter.algo->master_xfer().
218
219 After your I2C bus driver has processed these
220 up the call chain, with almost no processing d
221 package the returned data, if any, in suitable
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.