diff options
author | Jean Delvare <khali@linux-fr.org> | 2008-10-14 11:30:05 -0400 |
---|---|---|
committer | Jean Delvare <khali@mahadeva.delvare> | 2008-10-14 11:30:05 -0400 |
commit | fceb2d06800ddae53095f63843d85fcff4f701ac (patch) | |
tree | f5a298b152c54bff38f0941da90ca8e4dc239f6e /Documentation/i2c/dev-interface | |
parent | 9def255631bb742264d334d77819e1ae5278a515 (diff) |
i2c: Improve dev-interface documentation
* Clarify some points.
* Point developers to i2c-tools instead of lm_sensors.
* Fix coding style in code examples.
Signed-off-by: Jean Delvare <khali@linux-fr.org>
Diffstat (limited to 'Documentation/i2c/dev-interface')
-rw-r--r-- | Documentation/i2c/dev-interface | 65 |
1 files changed, 40 insertions, 25 deletions
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 9dd79123ddd9..689a79ea5ce7 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface | |||
@@ -4,6 +4,10 @@ the /dev interface. You need to load module i2c-dev for this. | |||
4 | 4 | ||
5 | Each registered i2c adapter gets a number, counting from 0. You can | 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. | 6 | examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. |
7 | Alternatively, you can run "i2cdetect -l" to obtain a formated list of all | ||
8 | i2c adapters present on your system at a given time. i2cdetect is part of | ||
9 | the i2c-tools package. | ||
10 | |||
7 | I2C device files are character device files with major device number 89 | 11 | I2C device files are character device files with major device number 89 |
8 | and a minor device number corresponding to the number assigned as | 12 | and a minor device number corresponding to the number assigned as |
9 | explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., | 13 | explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., |
@@ -17,30 +21,34 @@ So let's say you want to access an i2c adapter from a C program. The | |||
17 | first thing to do is "#include <linux/i2c-dev.h>". Please note that | 21 | 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 | 22 | 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 | 23 | 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 | 24 | driver code, the other one is distributed with i2c-tools and is |
21 | meant to be included from user-space programs. You obviously want | 25 | meant to be included from user-space programs. You obviously want |
22 | the second one here. | 26 | the second one here. |
23 | 27 | ||
24 | Now, you have to decide which adapter you want to access. You should | 28 | 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 | 29 | inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. |
26 | somewhat dynamically, so you can not even assume /dev/i2c-0 is the | 30 | Adapter numbers are assigned somewhat dynamically, so you can not |
27 | first adapter. | 31 | assume much about them. They can even change from one boot to the next. |
28 | 32 | ||
29 | Next thing, open the device file, as follows: | 33 | Next thing, open the device file, as follows: |
34 | |||
30 | int file; | 35 | int file; |
31 | int adapter_nr = 2; /* probably dynamically determined */ | 36 | int adapter_nr = 2; /* probably dynamically determined */ |
32 | char filename[20]; | 37 | char filename[20]; |
33 | 38 | ||
34 | sprintf(filename,"/dev/i2c-%d",adapter_nr); | 39 | snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); |
35 | if ((file = open(filename,O_RDWR)) < 0) { | 40 | file = open(filename, O_RDWR); |
41 | if (file < 0) { | ||
36 | /* ERROR HANDLING; you can check errno to see what went wrong */ | 42 | /* ERROR HANDLING; you can check errno to see what went wrong */ |
37 | exit(1); | 43 | exit(1); |
38 | } | 44 | } |
39 | 45 | ||
40 | When you have opened the device, you must specify with what device | 46 | When you have opened the device, you must specify with what device |
41 | address you want to communicate: | 47 | address you want to communicate: |
48 | |||
42 | int addr = 0x40; /* The I2C address */ | 49 | int addr = 0x40; /* The I2C address */ |
43 | if (ioctl(file,I2C_SLAVE,addr) < 0) { | 50 | |
51 | if (ioctl(file, I2C_SLAVE, addr) < 0) { | ||
44 | /* ERROR HANDLING; you can check errno to see what went wrong */ | 52 | /* ERROR HANDLING; you can check errno to see what went wrong */ |
45 | exit(1); | 53 | exit(1); |
46 | } | 54 | } |
@@ -48,31 +56,41 @@ address you want to communicate: | |||
48 | Well, you are all set up now. You can now use SMBus commands or plain | 56 | 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 | 57 | I2C to communicate with your device. SMBus commands are preferred if |
50 | the device supports them. Both are illustrated below. | 58 | the device supports them. Both are illustrated below. |
59 | |||
51 | __u8 register = 0x10; /* Device register to access */ | 60 | __u8 register = 0x10; /* Device register to access */ |
52 | __s32 res; | 61 | __s32 res; |
53 | char buf[10]; | 62 | char buf[10]; |
63 | |||
54 | /* Using SMBus commands */ | 64 | /* Using SMBus commands */ |
55 | res = i2c_smbus_read_word_data(file,register); | 65 | res = i2c_smbus_read_word_data(file, register); |
56 | if (res < 0) { | 66 | if (res < 0) { |
57 | /* ERROR HANDLING: i2c transaction failed */ | 67 | /* ERROR HANDLING: i2c transaction failed */ |
58 | } else { | 68 | } else { |
59 | /* res contains the read word */ | 69 | /* res contains the read word */ |
60 | } | 70 | } |
71 | |||
61 | /* Using I2C Write, equivalent of | 72 | /* Using I2C Write, equivalent of |
62 | i2c_smbus_write_word_data(file,register,0x6543) */ | 73 | i2c_smbus_write_word_data(file, register, 0x6543) */ |
63 | buf[0] = register; | 74 | buf[0] = register; |
64 | buf[1] = 0x43; | 75 | buf[1] = 0x43; |
65 | buf[2] = 0x65; | 76 | buf[2] = 0x65; |
66 | if ( write(file,buf,3) != 3) { | 77 | if (write(file, buf, 3) ! =3) { |
67 | /* ERROR HANDLING: i2c transaction failed */ | 78 | /* ERROR HANDLING: i2c transaction failed */ |
68 | } | 79 | } |
80 | |||
69 | /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ | 81 | /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ |
70 | if (read(file,buf,1) != 1) { | 82 | if (read(file, buf, 1) != 1) { |
71 | /* ERROR HANDLING: i2c transaction failed */ | 83 | /* ERROR HANDLING: i2c transaction failed */ |
72 | } else { | 84 | } else { |
73 | /* buf[0] contains the read byte */ | 85 | /* buf[0] contains the read byte */ |
74 | } | 86 | } |
75 | 87 | ||
88 | Note that only a subset of the I2C and SMBus protocols can be achieved by | ||
89 | the means of read() and write() calls. In particular, so-called combined | ||
90 | transactions (mixing read and write messages in the same transaction) | ||
91 | aren't supported. For this reason, this interface is almost never used by | ||
92 | user-space programs. | ||
93 | |||
76 | IMPORTANT: because of the use of inline functions, you *have* to use | 94 | IMPORTANT: because of the use of inline functions, you *have* to use |
77 | '-O' or some variation when you compile your program! | 95 | '-O' or some variation when you compile your program! |
78 | 96 | ||
@@ -80,31 +98,29 @@ IMPORTANT: because of the use of inline functions, you *have* to use | |||
80 | Full interface description | 98 | Full interface description |
81 | ========================== | 99 | ========================== |
82 | 100 | ||
83 | The following IOCTLs are defined and fully supported | 101 | The following IOCTLs are defined: |
84 | (see also i2c-dev.h): | ||
85 | 102 | ||
86 | ioctl(file,I2C_SLAVE,long addr) | 103 | ioctl(file, I2C_SLAVE, long addr) |
87 | Change slave address. The address is passed in the 7 lower bits of the | 104 | 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 | 105 | argument (except for 10 bit addresses, passed in the 10 lower bits in this |
89 | case). | 106 | case). |
90 | 107 | ||
91 | ioctl(file,I2C_TENBIT,long select) | 108 | ioctl(file, I2C_TENBIT, long select) |
92 | Selects ten bit addresses if select not equals 0, selects normal 7 bit | 109 | Selects ten bit addresses if select not equals 0, selects normal 7 bit |
93 | addresses if select equals 0. Default 0. This request is only valid | 110 | addresses if select equals 0. Default 0. This request is only valid |
94 | if the adapter has I2C_FUNC_10BIT_ADDR. | 111 | if the adapter has I2C_FUNC_10BIT_ADDR. |
95 | 112 | ||
96 | ioctl(file,I2C_PEC,long select) | 113 | ioctl(file, I2C_PEC, long select) |
97 | Selects SMBus PEC (packet error checking) generation and verification | 114 | Selects SMBus PEC (packet error checking) generation and verification |
98 | if select not equals 0, disables if select equals 0. Default 0. | 115 | if select not equals 0, disables if select equals 0. Default 0. |
99 | Used only for SMBus transactions. This request only has an effect if the | 116 | 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 | 117 | the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just |
101 | doesn't have any effect. | 118 | doesn't have any effect. |
102 | 119 | ||
103 | ioctl(file,I2C_FUNCS,unsigned long *funcs) | 120 | ioctl(file, I2C_FUNCS, unsigned long *funcs) |
104 | Gets the adapter functionality and puts it in *funcs. | 121 | Gets the adapter functionality and puts it in *funcs. |
105 | 122 | ||
106 | ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) | 123 | ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) |
107 | |||
108 | Do combined read/write transaction without stop in between. | 124 | Do combined read/write transaction without stop in between. |
109 | Only valid if the adapter has I2C_FUNC_I2C. The argument is | 125 | Only valid if the adapter has I2C_FUNC_I2C. The argument is |
110 | a pointer to a | 126 | a pointer to a |
@@ -120,10 +136,9 @@ ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) | |||
120 | The slave address and whether to use ten bit address mode has to be | 136 | 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. | 137 | set in each message, overriding the values set with the above ioctl's. |
122 | 138 | ||
123 | 139 | ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) | |
124 | Other values are NOT supported at this moment, except for I2C_SMBUS, | 140 | Not meant to be called directly; instead, use the access functions |
125 | which you should never directly call; instead, use the access functions | 141 | below. |
126 | below. | ||
127 | 142 | ||
128 | You can do plain i2c transactions by using read(2) and write(2) calls. | 143 | 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 | 144 | You do not need to pass the address byte; instead, set it through |
@@ -148,7 +163,7 @@ what happened. The 'write' transactions return 0 on success; the | |||
148 | returns the number of values read. The block buffers need not be longer | 163 | returns the number of values read. The block buffers need not be longer |
149 | than 32 bytes. | 164 | than 32 bytes. |
150 | 165 | ||
151 | The above functions are all macros, that resolve to calls to the | 166 | The above functions are all inline functions, that resolve to calls to |
152 | i2c_smbus_access function, that on its turn calls a specific ioctl | 167 | the 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 | 168 | with the data in a specific format. Read the source code if you |
154 | want to know what happens behind the screens. | 169 | want to know what happens behind the screens. |