| 1 | ============================================
|
| 2 | Implementing I2C device drivers in userspace
|
| 3 | ============================================
|
| 4 |
|
| 5 | Usually, I2C devices are controlled by a kernel driver. But it is also
|
| 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 |
|
| 9 | Each registered I2C adapter gets a number, counting from 0. You can
|
| 10 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
|
| 11 | Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all
|
| 12 | I2C adapters present on your system at a given time. i2cdetect is part of
|
| 13 | the i2c-tools package.
|
| 14 |
|
| 15 | I2C device files are character device files with major device number 89
|
| 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, ...,
|
| 18 | i2c-10, ...). All 256 minor device numbers are reserved for I2C.
|
| 19 |
|
| 20 |
|
| 21 | C example
|
| 22 | =========
|
| 23 |
|
| 24 | So let's say you want to access an I2C adapter from a C program.
|
| 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 to access. You should
|
| 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.
|
| 34 |
|
| 35 | Next thing, open the device file, as follows::
|
| 36 |
|
| 37 | int file;
|
| 38 | int adapter_nr = 2; /* probably dynamically determined */
|
| 39 | char filename[20];
|
| 40 |
|
| 41 | snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
|
| 42 | file = open(filename, O_RDWR);
|
| 43 | if (file < 0) {
|
| 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
|
| 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 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
|
| 60 | the device supports them. Both are illustrated below::
|
| 61 |
|
| 62 | __u8 reg = 0x10; /* Device register to access */
|
| 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, 0x6543)
|
| 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_read_byte(file) */
|
| 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 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 |
|
| 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 |
|
| 105 | The following IOCTLs are defined:
|
| 106 |
|
| 107 | ``ioctl(file, I2C_SLAVE, long addr)``
|
| 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 |
|
| 112 | ``ioctl(file, I2C_TENBIT, long select)``
|
| 113 | Selects ten bit addresses if select not equals 0, selects normal 7 bit
|
| 114 | addresses if select equals 0. Default 0. This request is only valid
|
| 115 | if the adapter has I2C_FUNC_10BIT_ADDR.
|
| 116 |
|
| 117 | ``ioctl(file, I2C_PEC, long select)``
|
| 118 | Selects SMBus PEC (packet error checking) generation and verification
|
| 119 | if select not equals 0, disables if select equals 0. Default 0.
|
| 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.
|
| 123 |
|
| 124 | ``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
|
| 125 | Gets the adapter functionality and puts it in ``*funcs``.
|
| 126 |
|
| 127 | ``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
|
| 128 | Do combined read/write transaction without stop in between.
|
| 129 | Only valid if the adapter has I2C_FUNC_I2C. The argument is
|
| 130 | a pointer to a::
|
| 131 |
|
| 132 | struct i2c_rdwr_ioctl_data {
|
| 133 | struct i2c_msg *msgs; /* ptr to array of simple messages */
|
| 134 | int nmsgs; /* number of messages to exchange */
|
| 135 | }
|
| 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 |
|
| 143 | ``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
|
| 144 | If possible, use the provided ``i2c_smbus_*`` methods described below instead
|
| 145 | of issuing direct ioctls.
|
| 146 |
|
| 147 | You can do plain I2C transactions by using read(2) and write(2) calls.
|
| 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 |
|
| 151 | You can do SMBus level transactions (see documentation file smbus-protocol.rst
|
| 152 | for details) through the following functions::
|
| 153 |
|
| 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);
|
| 162 | __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length,
|
| 163 | __u8 *values);
|
| 164 | __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
|
| 165 | __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
|
| 166 | __u8 *values);
|
| 167 |
|
| 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 |
|
| 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/.
|
| 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 |
|
| 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().
|
| 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.
|