1libi2c(3) Linux Programmer's Manual libi2c(3)
2
6 libi2c - publicly accessible functions provided by the i2c library
7
10 #include <linux/i2c.h>
11 #include <i2c/smbus.h>
12 /* Universal SMBus transaction */
14 __s32 i2c_smbus_access(int file, char read_write, __u8 command,
15 int size, union i2c_smbus_data *data);
16 /* Simple SMBus transactions */
18 __s32 i2c_smbus_write_quick(int file, __u8 value);
19 __s32 i2c_smbus_read_byte(int file);
20 __s32 i2c_smbus_write_byte(int file, __u8 value);
21 __s32 i2c_smbus_read_byte_data(int file, __u8 command);
22 __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
23 __s32 i2c_smbus_read_word_data(int file, __u8 command);
24 __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
25 __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
26 /* Block SMBus (and non-SMBus) transactions */
28 __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
29 __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
30 const __u8 *values);
31 __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length,
32 __u8 *values);
33 __s32 i2c_smbus_read_i2c_block_data(int file, __u8 command, __u8 length,
34 __u8 *values);
35 __s32 i2c_smbus_write_i2c_block_data(int file, __u8 command, __u8 length,
36 const __u8 *values);
37
40 This library offers to user-space an SMBus-level API similar to the in-
41 kernel one. Each function is a wrapper around the appropriate ioctl
42 call for i2c-dev to process. The i2c-dev kernel driver will convert
43 the ioctl to its in-kernel equivalent function call, and pass the re‐
44 sult back to the user-space caller.
45 i2c_smbus_access() is the universal function to run any SMBus transac‐
47 tion. You have to fill out and link the data structures yourself. It
48 returns 0 on success, or a negative errno value on error. In practice
49 you should never need to call this function directly, instead use one
50 of the specific functions below, which will prepare the data and then
51 call it for you.
52 i2c_smbus_write_quick() runs an SMBus "Quick command" transaction.
54 i2c_smbus_write_byte() runs an SMBus "Send byte" transaction.
56 i2c_smbus_write_byte_data() runs an SMBus "Write byte" transaction.
58 i2c_smbus_write_word_data() runs an SMBus "Write word" transaction.
60 These write transaction functions return 0 on success. On error, a
62 negative errno value is returned.
63 i2c_smbus_read_byte() runs an SMBus "Receive byte" transaction.
65 i2c_smbus_read_byte_data() runs an SMBus "Read byte" transaction.
67 i2c_smbus_read_word_data() runs an SMBus "Read word" transaction.
69 i2c_smbus_process_call() runs an SMBus "Process call" transaction.
71 These read transaction functions return the read byte or word value on
73 success. On error, a negative errno value is returned.
74 i2c_smbus_write_block_data() runs an SMBus "Block write" transaction.
76 i2c_smbus_read_block_data() runs an SMBus "Block read" transaction.
78 i2c_smbus_block_process_call() runs an SMBus "Block write-block read
80 process call" transaction.
81 These block transaction functions return 0 on success. On error, a
83 negative errno value is returned. The block length is limited to 32
84 bytes.
85 i2c_smbus_write_i2c_block_data() runs an "I2C block write" transaction.
87 This is typically used to write to an EEPROM up to 4 kb in size.
88 i2c_smbus_read_i2c_block_data() runs an "I2C block read" transaction.
90 This is typically used to read from an EEPROM up to 4 kb in size.
91 While technically not part of the SMBus specification, these I2C block
93 transactions are supported by many SMBus host controllers. These block
94 transaction functions return 0 on success. On error, a negative errno
95 value is returned. Like their SMBus counterparts, the block length is
96 limited to 32 bytes.
97
100 Structure i2c_smbus_ioctl_data is used to send data to and retrieve
101 data from the kernel through the i2c-dev driver. It will be filled out
102 for you by i2c_smbus_access() so you do not need to care about the de‐
103 tails.
104 Union i2c_smbus_data is used to store all possible SMBus data.
106 union i2c_smbus_data {
108 __u8 byte;
109 __u16 word;
110 __u8 block[I2C_SMBUS_BLOCK_MAX + 2];
111 };
112 block[0] is used for length and the last byte is reserved. If you use
114 the higher-level functions, this structure will be filled out for you
115 so you do not have to care about the details. Only if you call i2c_sm‐
116 bus_access() directly, you need to fill it out yourself.
117
120 To report bugs or send fixes, please write to the Linux I2C mailing
121 list <linux-i2c@vger.kernel.org> with Cc to the current maintainer:
122 Jean Delvare <jdelvare@suse.de>.
123
126 Simon G. Vogl, Frodo Looijaard, Jean Delvare and others
127i2c-tools September 2020 libi2c(3)