1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =============== 3 ===============
4 Linux I2C Sysfs 4 Linux I2C Sysfs
5 =============== 5 ===============
6 6
7 Overview 7 Overview
8 ======== 8 ========
9 9
10 I2C topology can be complex because of the exi 10 I2C topology can be complex because of the existence of I2C MUX
11 (I2C Multiplexer). The Linux 11 (I2C Multiplexer). The Linux
12 kernel abstracts the MUX channels into logical 12 kernel abstracts the MUX channels into logical I2C bus numbers. However, there
13 is a gap of knowledge to map from the I2C bus 13 is a gap of knowledge to map from the I2C bus physical number and MUX topology
14 to logical I2C bus number. This doc is aimed t 14 to logical I2C bus number. This doc is aimed to fill in this gap, so the
15 audience (hardware engineers and new software 15 audience (hardware engineers and new software developers for example) can learn
16 the concept of logical I2C buses in the kernel 16 the concept of logical I2C buses in the kernel, by knowing the physical I2C
17 topology and navigating through the I2C sysfs 17 topology and navigating through the I2C sysfs in Linux shell. This knowledge is
18 useful and essential to use ``i2c-tools`` for 18 useful and essential to use ``i2c-tools`` for the purpose of development and
19 debugging. 19 debugging.
20 20
21 Target audience 21 Target audience
22 --------------- 22 ---------------
23 23
24 People who need to use Linux shell to interact 24 People who need to use Linux shell to interact with I2C subsystem on a system
25 which the Linux is running on. 25 which the Linux is running on.
26 26
27 Prerequisites 27 Prerequisites
28 ------------- 28 -------------
29 29
30 1. Knowledge of general Linux shell file syst 30 1. Knowledge of general Linux shell file system commands and operations.
31 31
32 2. General knowledge of I2C, I2C MUX and I2C 32 2. General knowledge of I2C, I2C MUX and I2C topology.
33 33
34 Location of I2C Sysfs 34 Location of I2C Sysfs
35 ===================== 35 =====================
36 36
37 Typically, the Linux Sysfs filesystem is mount 37 Typically, the Linux Sysfs filesystem is mounted at the ``/sys`` directory,
38 so you can find the I2C Sysfs under ``/sys/bus 38 so you can find the I2C Sysfs under ``/sys/bus/i2c/devices``
39 where you can directly ``cd`` to it. 39 where you can directly ``cd`` to it.
40 There is a list of symbolic links under that d 40 There is a list of symbolic links under that directory. The links that
41 start with ``i2c-`` are I2C buses, which may b 41 start with ``i2c-`` are I2C buses, which may be either physical or logical. The
42 other links that begin with numbers and end wi 42 other links that begin with numbers and end with numbers are I2C devices, where
43 the first number is I2C bus number, and the se 43 the first number is I2C bus number, and the second number is I2C address.
44 44
45 Google Pixel 3 phone for example:: 45 Google Pixel 3 phone for example::
46 46
47 blueline:/sys/bus/i2c/devices $ ls 47 blueline:/sys/bus/i2c/devices $ ls
48 0-0008 0-0061 1-0028 3-0043 4-0036 4-00 48 0-0008 0-0061 1-0028 3-0043 4-0036 4-0041 i2c-1 i2c-3
49 0-000c 0-0066 2-0049 4-000b 4-0040 i2c- 49 0-000c 0-0066 2-0049 4-000b 4-0040 i2c-0 i2c-2 i2c-4
50 50
51 ``i2c-2`` is an I2C bus whose number is 2, and 51 ``i2c-2`` is an I2C bus whose number is 2, and ``2-0049`` is an I2C device
52 on bus 2 address 0x49 bound with a kernel driv 52 on bus 2 address 0x49 bound with a kernel driver.
53 53
54 Terminology !! 54 Terminologies
55 =========== !! 55 =============
56 56
57 First, let us define some terms to avoid confu !! 57 First, let us define a couple of terminologies to avoid confusions in the later
>> 58 sections.
58 59
59 (Physical) I2C Bus Controller 60 (Physical) I2C Bus Controller
60 ----------------------------- 61 -----------------------------
61 62
62 The hardware system that the Linux kernel is r 63 The hardware system that the Linux kernel is running on may have multiple
63 physical I2C bus controllers. The controllers 64 physical I2C bus controllers. The controllers are hardware and physical, and the
64 system may define multiple registers in the me 65 system may define multiple registers in the memory space to manipulate the
65 controllers. Linux kernel has I2C bus drivers 66 controllers. Linux kernel has I2C bus drivers under source directory
66 ``drivers/i2c/busses`` to translate kernel I2C 67 ``drivers/i2c/busses`` to translate kernel I2C API into register
67 operations for different systems. This termino 68 operations for different systems. This terminology is not limited to Linux
68 kernel only. 69 kernel only.
69 70
70 I2C Bus Physical Number 71 I2C Bus Physical Number
71 ----------------------- 72 -----------------------
72 73
73 For each physical I2C bus controller, the syst 74 For each physical I2C bus controller, the system vendor may assign a physical
74 number to each controller. For example, the fi 75 number to each controller. For example, the first I2C bus controller which has
75 the lowest register addresses may be called `` 76 the lowest register addresses may be called ``I2C-0``.
76 77
77 Logical I2C Bus 78 Logical I2C Bus
78 --------------- 79 ---------------
79 80
80 Every I2C bus number you see in Linux I2C Sysf 81 Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a
81 number assigned. This is similar to the fact t 82 number assigned. This is similar to the fact that software code is usually
82 written upon virtual memory space, instead of 83 written upon virtual memory space, instead of physical memory space.
83 84
84 Each logical I2C bus may be an abstraction of 85 Each logical I2C bus may be an abstraction of a physical I2C bus controller, or
85 an abstraction of a channel behind an I2C MUX. 86 an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a
86 MUX channel, whenever we access an I2C device 87 MUX channel, whenever we access an I2C device via a such logical bus, the kernel
87 will switch the I2C MUX for you to the proper 88 will switch the I2C MUX for you to the proper channel as part of the
88 abstraction. 89 abstraction.
89 90
90 Physical I2C Bus 91 Physical I2C Bus
91 ---------------- 92 ----------------
92 93
93 If the logical I2C bus is a direct abstraction 94 If the logical I2C bus is a direct abstraction of a physical I2C bus controller,
94 let us call it a physical I2C bus. 95 let us call it a physical I2C bus.
95 96
96 Caveat 97 Caveat
97 ------ 98 ------
98 99
99 This may be a confusing part for people who on 100 This may be a confusing part for people who only know about the physical I2C
100 design of a board. It is actually possible to 101 design of a board. It is actually possible to rename the I2C bus physical number
101 to a different number in logical I2C bus level 102 to a different number in logical I2C bus level in Device Tree Source (DTS) under
102 section ``aliases``. See ``arch/arm/boot/dts/n !! 103 section ``aliases``. See
>> 104 `arch/arm/boot/dts/nuvoton-npcm730-gsj.dts
>> 105 <../../arch/arm/boot/dts/nuvoton-npcm730-gsj.dts>`_
103 for an example of DTS file. 106 for an example of DTS file.
104 107
105 Best Practice: **(To kernel software developer 108 Best Practice: **(To kernel software developers)** It is better to keep the I2C
106 bus physical number the same as their correspo 109 bus physical number the same as their corresponding logical I2C bus number,
107 instead of renaming or mapping them, so that i 110 instead of renaming or mapping them, so that it may be less confusing to other
108 users. These physical I2C buses can be served 111 users. These physical I2C buses can be served as good starting points for I2C
109 MUX fanouts. For the following examples, we wi 112 MUX fanouts. For the following examples, we will assume that the physical I2C
110 bus has a number same as their I2C bus physica 113 bus has a number same as their I2C bus physical number.
111 114
112 Walk through Logical I2C Bus 115 Walk through Logical I2C Bus
113 ============================ 116 ============================
114 117
115 For the following content, we will use a more 118 For the following content, we will use a more complex I2C topology as an
116 example. Here is a brief graph for the I2C top 119 example. Here is a brief graph for the I2C topology. If you do not understand
117 this graph at first glance, do not be afraid t !! 120 this graph at the first glance, do not be afraid to continue reading this doc
118 and review it when you finish reading. 121 and review it when you finish reading.
119 122
120 :: 123 ::
121 124
122 i2c-7 (physical I2C bus controller 7) 125 i2c-7 (physical I2C bus controller 7)
123 `-- 7-0071 (4-channel I2C MUX at 0x71) 126 `-- 7-0071 (4-channel I2C MUX at 0x71)
124 |-- i2c-60 (channel-0) 127 |-- i2c-60 (channel-0)
125 |-- i2c-73 (channel-1) 128 |-- i2c-73 (channel-1)
126 | |-- 73-0040 (I2C sensor device with 129 | |-- 73-0040 (I2C sensor device with hwmon directory)
127 | |-- 73-0070 (I2C MUX at 0x70, exists 130 | |-- 73-0070 (I2C MUX at 0x70, exists in DTS, but failed to probe)
128 | `-- 73-0072 (8-channel I2C MUX at 0x 131 | `-- 73-0072 (8-channel I2C MUX at 0x72)
129 | |-- i2c-78 (channel-0) 132 | |-- i2c-78 (channel-0)
130 | |-- ... (channel-1...6, i2c-79.. 133 | |-- ... (channel-1...6, i2c-79...i2c-84)
131 | `-- i2c-85 (channel-7) 134 | `-- i2c-85 (channel-7)
132 |-- i2c-86 (channel-2) 135 |-- i2c-86 (channel-2)
133 `-- i2c-203 (channel-3) 136 `-- i2c-203 (channel-3)
134 137
135 Distinguish Physical and Logical I2C Bus 138 Distinguish Physical and Logical I2C Bus
136 ---------------------------------------- 139 ----------------------------------------
137 140
138 One simple way to distinguish between a physic 141 One simple way to distinguish between a physical I2C bus and a logical I2C bus,
139 is to read the symbolic link ``device`` under 142 is to read the symbolic link ``device`` under the I2C bus directory by using
140 command ``ls -l`` or ``readlink``. 143 command ``ls -l`` or ``readlink``.
141 144
142 An alternative symbolic link to check is ``mux 145 An alternative symbolic link to check is ``mux_device``. This link only exists
143 in logical I2C bus directory which is fanned o 146 in logical I2C bus directory which is fanned out from another I2C bus.
144 Reading this link will also tell you which I2C 147 Reading this link will also tell you which I2C MUX device created
145 this logical I2C bus. 148 this logical I2C bus.
146 149
147 If the symbolic link points to a directory end 150 If the symbolic link points to a directory ending with ``.i2c``, it should be a
148 physical I2C bus, directly abstracting a physi 151 physical I2C bus, directly abstracting a physical I2C bus controller. For
149 example:: 152 example::
150 153
151 $ readlink /sys/bus/i2c/devices/i2c-7/device 154 $ readlink /sys/bus/i2c/devices/i2c-7/device
152 ../../f0087000.i2c 155 ../../f0087000.i2c
153 $ ls /sys/bus/i2c/devices/i2c-7/mux_device 156 $ ls /sys/bus/i2c/devices/i2c-7/mux_device
154 ls: /sys/bus/i2c/devices/i2c-7/mux_device: N 157 ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory
155 158
156 In this case, ``i2c-7`` is a physical I2C bus, 159 In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic
157 link ``mux_device`` under its directory. And i 160 link ``mux_device`` under its directory. And if the kernel software developer
158 follows the common practice by not renaming ph 161 follows the common practice by not renaming physical I2C buses, this should also
159 mean the physical I2C bus controller 7 of the 162 mean the physical I2C bus controller 7 of the system.
160 163
161 On the other hand, if the symbolic link points 164 On the other hand, if the symbolic link points to another I2C bus, the I2C bus
162 presented by the current directory has to be a 165 presented by the current directory has to be a logical bus. The I2C bus pointed
163 by the link is the parent bus which may be eit 166 by the link is the parent bus which may be either a physical I2C bus or a
164 logical one. In this case, the I2C bus present 167 logical one. In this case, the I2C bus presented by the current directory
165 abstracts an I2C MUX channel under the parent 168 abstracts an I2C MUX channel under the parent bus.
166 169
167 For example:: 170 For example::
168 171
169 $ readlink /sys/bus/i2c/devices/i2c-73/devic 172 $ readlink /sys/bus/i2c/devices/i2c-73/device
170 ../../i2c-7 173 ../../i2c-7
171 $ readlink /sys/bus/i2c/devices/i2c-73/mux_d 174 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device
172 ../7-0071 175 ../7-0071
173 176
174 ``i2c-73`` is a logical bus fanout by an I2C M 177 ``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7``
175 whose I2C address is 0x71. 178 whose I2C address is 0x71.
176 Whenever we access an I2C device with bus 73, 179 Whenever we access an I2C device with bus 73, the kernel will always
177 switch the I2C MUX addressed 0x71 to the prope 180 switch the I2C MUX addressed 0x71 to the proper channel for you as part of the
178 abstraction. 181 abstraction.
179 182
180 Finding out Logical I2C Bus Number 183 Finding out Logical I2C Bus Number
181 ---------------------------------- 184 ----------------------------------
182 185
183 In this section, we will describe how to find 186 In this section, we will describe how to find out the logical I2C bus number
184 representing certain I2C MUX channels based on 187 representing certain I2C MUX channels based on the knowledge of physical
185 hardware I2C topology. 188 hardware I2C topology.
186 189
187 In this example, we have a system which has a 190 In this example, we have a system which has a physical I2C bus 7 and not renamed
188 in DTS. There is a 4-channel MUX at address 0x 191 in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another
189 8-channel MUX at address 0x72 behind the chann 192 8-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us
190 navigate through Sysfs and find out the logica 193 navigate through Sysfs and find out the logical I2C bus number of the channel 3
191 of the 0x72 MUX. 194 of the 0x72 MUX.
192 195
193 First of all, let us go to the directory of `` 196 First of all, let us go to the directory of ``i2c-7``::
194 197
195 ~$ cd /sys/bus/i2c/devices/i2c-7 198 ~$ cd /sys/bus/i2c/devices/i2c-7
196 /sys/bus/i2c/devices/i2c-7$ ls 199 /sys/bus/i2c/devices/i2c-7$ ls
197 7-0071 i2c-60 name 200 7-0071 i2c-60 name subsystem
198 delete_device i2c-73 new_device 201 delete_device i2c-73 new_device uevent
199 device i2c-86 of_node 202 device i2c-86 of_node
200 i2c-203 i2c-dev power 203 i2c-203 i2c-dev power
201 204
202 There, we see the 0x71 MUX as ``7-0071``. Go i 205 There, we see the 0x71 MUX as ``7-0071``. Go inside it::
203 206
204 /sys/bus/i2c/devices/i2c-7$ cd 7-0071/ 207 /sys/bus/i2c/devices/i2c-7$ cd 7-0071/
205 /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l 208 /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l
206 channel-0 channel-3 modalias power 209 channel-0 channel-3 modalias power
207 channel-1 driver name subsyste 210 channel-1 driver name subsystem
208 channel-2 idle_state of_node uevent 211 channel-2 idle_state of_node uevent
209 212
210 Read the link ``channel-1`` using ``readlink`` 213 Read the link ``channel-1`` using ``readlink`` or ``ls -l``::
211 214
212 /sys/bus/i2c/devices/i2c-7/7-0071$ readlink 215 /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1
213 ../i2c-73 216 ../i2c-73
214 217
215 We find out that the channel 1 of 0x71 MUX on 218 We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned
216 with a logical I2C bus number of 73. 219 with a logical I2C bus number of 73.
217 Let us continue the journey to directory ``i2c 220 Let us continue the journey to directory ``i2c-73`` in either ways::
218 221
219 # cd to i2c-73 under I2C Sysfs root 222 # cd to i2c-73 under I2C Sysfs root
220 /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/b 223 /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73
221 /sys/bus/i2c/devices/i2c-73$ 224 /sys/bus/i2c/devices/i2c-73$
222 225
223 # cd the channel symbolic link 226 # cd the channel symbolic link
224 /sys/bus/i2c/devices/i2c-7/7-0071$ cd channe 227 /sys/bus/i2c/devices/i2c-7/7-0071$ cd channel-1
225 /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$ 228 /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$
226 229
227 # cd the link content 230 # cd the link content
228 /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c 231 /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c-73
229 /sys/bus/i2c/devices/i2c-7/i2c-73$ 232 /sys/bus/i2c/devices/i2c-7/i2c-73$
230 233
231 Either ways, you will end up in the directory 234 Either ways, you will end up in the directory of ``i2c-73``. Similar to above,
232 we can now find the 0x72 MUX and what logical 235 we can now find the 0x72 MUX and what logical I2C bus numbers
233 that its channels are assigned:: 236 that its channels are assigned::
234 237
235 /sys/bus/i2c/devices/i2c-73$ ls 238 /sys/bus/i2c/devices/i2c-73$ ls
236 73-0040 device i2c-83 239 73-0040 device i2c-83 new_device
237 73-004e i2c-78 i2c-84 240 73-004e i2c-78 i2c-84 of_node
238 73-0050 i2c-79 i2c-85 241 73-0050 i2c-79 i2c-85 power
239 73-0070 i2c-80 i2c-dev 242 73-0070 i2c-80 i2c-dev subsystem
240 73-0072 i2c-81 mux_device 243 73-0072 i2c-81 mux_device uevent
241 delete_device i2c-82 name 244 delete_device i2c-82 name
242 /sys/bus/i2c/devices/i2c-73$ cd 73-0072 245 /sys/bus/i2c/devices/i2c-73$ cd 73-0072
243 /sys/bus/i2c/devices/i2c-73/73-0072$ ls 246 /sys/bus/i2c/devices/i2c-73/73-0072$ ls
244 channel-0 channel-4 driver of_node 247 channel-0 channel-4 driver of_node
245 channel-1 channel-5 idle_state power 248 channel-1 channel-5 idle_state power
246 channel-2 channel-6 modalias subsyste 249 channel-2 channel-6 modalias subsystem
247 channel-3 channel-7 name uevent 250 channel-3 channel-7 name uevent
248 /sys/bus/i2c/devices/i2c-73/73-0072$ readlin 251 /sys/bus/i2c/devices/i2c-73/73-0072$ readlink channel-3
249 ../i2c-81 252 ../i2c-81
250 253
251 There, we find out the logical I2C bus number 254 There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX
252 is 81. We can later use this number to switch 255 is 81. We can later use this number to switch to its own I2C Sysfs directory or
253 issue ``i2c-tools`` commands. 256 issue ``i2c-tools`` commands.
254 257
255 Tip: Once you understand the I2C topology with 258 Tip: Once you understand the I2C topology with MUX, command
256 `i2cdetect -l 259 `i2cdetect -l
257 <https://manpages.debian.org/unstable/i2c-tool 260 <https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_
258 in 261 in
259 `I2C Tools 262 `I2C Tools
260 <https://i2c.wiki.kernel.org/index.php/I2C_Too 263 <https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_
261 can give you 264 can give you
262 an overview of the I2C topology easily, if it 265 an overview of the I2C topology easily, if it is available on your system. For
263 example:: 266 example::
264 267
265 $ i2cdetect -l | grep -e '\-73' -e _7 | sort 268 $ i2cdetect -l | grep -e '\-73' -e _7 | sort -V
266 i2c-7 i2c npcm_i2c_7 269 i2c-7 i2c npcm_i2c_7 I2C adapter
267 i2c-73 i2c i2c-7-mux (chan_id 1 270 i2c-73 i2c i2c-7-mux (chan_id 1) I2C adapter
268 i2c-78 i2c i2c-73-mux (chan_id 271 i2c-78 i2c i2c-73-mux (chan_id 0) I2C adapter
269 i2c-79 i2c i2c-73-mux (chan_id 272 i2c-79 i2c i2c-73-mux (chan_id 1) I2C adapter
270 i2c-80 i2c i2c-73-mux (chan_id 273 i2c-80 i2c i2c-73-mux (chan_id 2) I2C adapter
271 i2c-81 i2c i2c-73-mux (chan_id 274 i2c-81 i2c i2c-73-mux (chan_id 3) I2C adapter
272 i2c-82 i2c i2c-73-mux (chan_id 275 i2c-82 i2c i2c-73-mux (chan_id 4) I2C adapter
273 i2c-83 i2c i2c-73-mux (chan_id 276 i2c-83 i2c i2c-73-mux (chan_id 5) I2C adapter
274 i2c-84 i2c i2c-73-mux (chan_id 277 i2c-84 i2c i2c-73-mux (chan_id 6) I2C adapter
275 i2c-85 i2c i2c-73-mux (chan_id 278 i2c-85 i2c i2c-73-mux (chan_id 7) I2C adapter
276 279
277 Pinned Logical I2C Bus Number 280 Pinned Logical I2C Bus Number
278 ----------------------------- 281 -----------------------------
279 282
280 If not specified in DTS, when an I2C MUX drive 283 If not specified in DTS, when an I2C MUX driver is applied and the MUX device is
281 successfully probed, the kernel will assign th 284 successfully probed, the kernel will assign the MUX channels with a logical bus
282 number based on the current biggest logical bu 285 number based on the current biggest logical bus number incrementally. For
283 example, if the system has ``i2c-15`` as the h 286 example, if the system has ``i2c-15`` as the highest logical bus number, and a
284 4-channel MUX is applied successfully, we will 287 4-channel MUX is applied successfully, we will have ``i2c-16`` for the
285 MUX channel 0, and all the way to ``i2c-19`` f 288 MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3.
286 289
287 The kernel software developer is able to pin t 290 The kernel software developer is able to pin the fanout MUX channels to a static
288 logical I2C bus number in the DTS. This doc wi 291 logical I2C bus number in the DTS. This doc will not go through the details on
289 how to implement this in DTS, but we can see a 292 how to implement this in DTS, but we can see an example in:
290 ``arch/arm/boot/dts/aspeed-bmc-facebook-wedge4 !! 293 `arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts
>> 294 <../../arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts>`_
291 295
292 In the above example, there is an 8-channel I2 296 In the above example, there is an 8-channel I2C MUX at address 0x70 on physical
293 I2C bus 2. The channel 2 of the MUX is defined 297 I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS,
294 and pinned to logical I2C bus number 18 with t 298 and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;``
295 in section ``aliases``. 299 in section ``aliases``.
296 300
297 Take it further, it is possible to design a lo 301 Take it further, it is possible to design a logical I2C bus number schema that
298 can be easily remembered by humans or calculat 302 can be easily remembered by humans or calculated arithmetically. For example, we
299 can pin the fanout channels of a MUX on bus 3 303 can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the
300 logical bus number of the channel 0 of the MUX 304 logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the
301 logical bus number of the channel 7 of the MUX 305 logical bus number of the channel 7 of the MUX on bus 3.
302 306
303 I2C Devices 307 I2C Devices
304 =========== 308 ===========
305 309
306 In previous sections, we mostly covered the I2 310 In previous sections, we mostly covered the I2C bus. In this section, let us see
307 what we can learn from the I2C device director 311 what we can learn from the I2C device directory whose link name is in the format
308 of ``${bus}-${addr}``. The ``${bus}`` part in 312 of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus
309 decimal number, while the ``${addr}`` part is 313 decimal number, while the ``${addr}`` part is a hex number of the I2C address
310 of each device. 314 of each device.
311 315
312 I2C Device Directory Content 316 I2C Device Directory Content
313 ---------------------------- 317 ----------------------------
314 318
315 Inside each I2C device directory, there is a f 319 Inside each I2C device directory, there is a file named ``name``.
316 This file tells what device name it was used f 320 This file tells what device name it was used for the kernel driver to
317 probe this device. Use command ``cat`` to read 321 probe this device. Use command ``cat`` to read its content. For example::
318 322
319 /sys/bus/i2c/devices/i2c-73$ cat 73-0040/nam 323 /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name
320 ina230 324 ina230
321 /sys/bus/i2c/devices/i2c-73$ cat 73-0070/nam 325 /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name
322 pca9546 326 pca9546
323 /sys/bus/i2c/devices/i2c-73$ cat 73-0072/nam 327 /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name
324 pca9547 328 pca9547
325 329
326 There is a symbolic link named ``driver`` to t 330 There is a symbolic link named ``driver`` to tell what Linux kernel driver was
327 used to probe this device:: 331 used to probe this device::
328 332
329 /sys/bus/i2c/devices/i2c-73$ readlink -f 73- 333 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0040/driver
330 /sys/bus/i2c/drivers/ina2xx 334 /sys/bus/i2c/drivers/ina2xx
331 /sys/bus/i2c/devices/i2c-73$ readlink -f 73- 335 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0072/driver
332 /sys/bus/i2c/drivers/pca954x 336 /sys/bus/i2c/drivers/pca954x
333 337
334 But if the link ``driver`` does not exist at t 338 But if the link ``driver`` does not exist at the first place,
335 it may mean that the kernel driver failed to p 339 it may mean that the kernel driver failed to probe this device due to
336 some errors. The error may be found in ``dmesg 340 some errors. The error may be found in ``dmesg``::
337 341
338 /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driv 342 /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driver
339 ls: 73-0070/driver: No such file or director 343 ls: 73-0070/driver: No such file or directory
340 /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73 344 /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73-0070
341 pca954x 73-0070: probe failed 345 pca954x 73-0070: probe failed
342 pca954x 73-0070: probe failed 346 pca954x 73-0070: probe failed
343 347
344 Depending on what the I2C device is and what k 348 Depending on what the I2C device is and what kernel driver was used to probe the
345 device, we may have different content in the d 349 device, we may have different content in the device directory.
346 350
347 I2C MUX Device 351 I2C MUX Device
348 -------------- 352 --------------
349 353
350 While you may be already aware of this in prev 354 While you may be already aware of this in previous sections, an I2C MUX device
351 will have symbolic link ``channel-*`` inside i 355 will have symbolic link ``channel-*`` inside its device directory.
352 These symbolic links point to their logical I2 356 These symbolic links point to their logical I2C bus directories::
353 357
354 /sys/bus/i2c/devices/i2c-73$ ls -l 73-0072/c 358 /sys/bus/i2c/devices/i2c-73$ ls -l 73-0072/channel-*
355 lrwxrwxrwx ... 73-0072/channel-0 -> ../i2c-7 359 lrwxrwxrwx ... 73-0072/channel-0 -> ../i2c-78
356 lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-7 360 lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-79
357 lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-8 361 lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-80
358 lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-8 362 lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-81
359 lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-8 363 lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-82
360 lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-8 364 lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-83
361 lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-8 365 lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-84
362 lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-8 366 lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85
363 367
364 I2C Sensor Device / Hwmon 368 I2C Sensor Device / Hwmon
365 ------------------------- 369 -------------------------
366 370
367 I2C sensor device is also common to see. If th 371 I2C sensor device is also common to see. If they are bound by a kernel hwmon
368 (Hardware Monitoring) driver successfully, you 372 (Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory
369 inside the I2C device directory. Keep digging 373 inside the I2C device directory. Keep digging into it, you will find the Hwmon
370 Sysfs for the I2C sensor device:: 374 Sysfs for the I2C sensor device::
371 375
372 /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hw 376 /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hwmon17$ ls
373 curr1_input in0_lcrit_alarm name 377 curr1_input in0_lcrit_alarm name subsystem
374 device in1_crit power 378 device in1_crit power uevent
375 in0_crit in1_crit_alarm power1 379 in0_crit in1_crit_alarm power1_crit update_interval
376 in0_crit_alarm in1_input power1 380 in0_crit_alarm in1_input power1_crit_alarm
377 in0_input in1_lcrit power1 381 in0_input in1_lcrit power1_input
378 in0_lcrit in1_lcrit_alarm shunt_ 382 in0_lcrit in1_lcrit_alarm shunt_resistor
379 383
380 For more info on the Hwmon Sysfs, refer to the 384 For more info on the Hwmon Sysfs, refer to the doc:
381 385
382 ../hwmon/sysfs-interface.rst !! 386 `Naming and data format standards for sysfs files
>> 387 <../hwmon/sysfs-interface.rst>`_
383 388
384 Instantiate I2C Devices in I2C Sysfs 389 Instantiate I2C Devices in I2C Sysfs
385 ------------------------------------ 390 ------------------------------------
386 391
387 Refer to section "Method 4: Instantiate from u !! 392 Refer to the doc:
>> 393
>> 394 `How to instantiate I2C devices, Method 4: Instantiate from user-space
>> 395 <instantiating-devices.rst#method-4-instantiate-from-user-space>`_
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.