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