1 .. SPDX-License-Identifier: GPL-2.0
10 I2C topology can be complex because of the existence of I2C MUX
11 (I2C Multiplexer). The Linux
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 physical number and MUX topology
14 to logical I2C bus number. This doc is aimed to fill in this gap, so the
15 audience (hardware engineers and new software developers for example) can learn
16 the concept of logical I2C buses in the kernel, by knowing the physical I2C
17 topology and navigating through the I2C sysfs in Linux shell. This knowledge is
18 useful and essential to use ``i2c-tools`` for the purpose of development and
24 People who need to use Linux shell to interact with I2C subsystem on a system
25 which the Linux is running on.
30 1. Knowledge of general Linux shell file system commands and operations.
32 2. General knowledge of I2C, I2C MUX and I2C topology.
37 Typically, the Linux Sysfs filesystem is mounted at the ``/sys`` directory,
38 so you can find the I2C Sysfs under ``/sys/bus/i2c/devices``
39 where you can directly ``cd`` to it.
40 There is a list of symbolic links under that directory. The links that
41 start with ``i2c-`` are I2C buses, which may be either physical or logical. The
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 second number is I2C address.
45 Google Pixel 3 phone for example::
47 blueline:/sys/bus/i2c/devices $ ls
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-0 i2c-2 i2c-4
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 driver.
57 First, let us define a couple of terminologies to avoid confusions in the later
60 (Physical) I2C Bus Controller
61 -----------------------------
63 The hardware system that the Linux kernel is running on may have multiple
64 physical I2C bus controllers. The controllers are hardware and physical, and the
65 system may define multiple registers in the memory space to manipulate the
66 controllers. Linux kernel has I2C bus drivers under source directory
67 ``drivers/i2c/busses`` to translate kernel I2C API into register
68 operations for different systems. This terminology is not limited to Linux
71 I2C Bus Physical Number
72 -----------------------
74 For each physical I2C bus controller, the system vendor may assign a physical
75 number to each controller. For example, the first I2C bus controller which has
76 the lowest register addresses may be called ``I2C-0``.
81 Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a
82 number assigned. This is similar to the fact that software code is usually
83 written upon virtual memory space, instead of physical memory space.
85 Each logical I2C bus may be an abstraction of a physical I2C bus controller, or
86 an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a
87 MUX channel, whenever we access an I2C device via a such logical bus, the kernel
88 will switch the I2C MUX for you to the proper channel as part of the
94 If the logical I2C bus is a direct abstraction of a physical I2C bus controller,
95 let us call it a physical I2C bus.
100 This may be a confusing part for people who only know about the physical I2C
101 design of a board. It is actually possible to rename the I2C bus physical number
102 to a different number in logical I2C bus level in Device Tree Source (DTS) under
103 section ``aliases``. See
104 `arch/arm/boot/dts/nuvoton-npcm730-gsj.dts
105 <../../arch/arm/boot/dts/nuvoton-npcm730-gsj.dts>`_
106 for an example of DTS file.
108 Best Practice: **(To kernel software developers)** It is better to keep the I2C
109 bus physical number the same as their corresponding logical I2C bus number,
110 instead of renaming or mapping them, so that it may be less confusing to other
111 users. These physical I2C buses can be served as good starting points for I2C
112 MUX fanouts. For the following examples, we will assume that the physical I2C
113 bus has a number same as their I2C bus physical number.
115 Walk through Logical I2C Bus
116 ============================
118 For the following content, we will use a more complex I2C topology as an
119 example. Here is a brief graph for the I2C topology. If you do not understand
120 this graph at the first glance, do not be afraid to continue reading this doc
121 and review it when you finish reading.
125 i2c-7 (physical I2C bus controller 7)
126 `-- 7-0071 (4-channel I2C MUX at 0x71)
127 |-- i2c-60 (channel-0)
128 |-- i2c-73 (channel-1)
129 | |-- 73-0040 (I2C sensor device with hwmon directory)
130 | |-- 73-0070 (I2C MUX at 0x70, exists in DTS, but failed to probe)
131 | `-- 73-0072 (8-channel I2C MUX at 0x72)
132 | |-- i2c-78 (channel-0)
133 | |-- ... (channel-1...6, i2c-79...i2c-84)
134 | `-- i2c-85 (channel-7)
135 |-- i2c-86 (channel-2)
136 `-- i2c-203 (channel-3)
138 Distinguish Physical and Logical I2C Bus
139 ----------------------------------------
141 One simple way to distinguish between a physical I2C bus and a logical I2C bus,
142 is to read the symbolic link ``device`` under the I2C bus directory by using
143 command ``ls -l`` or ``readlink``.
145 An alternative symbolic link to check is ``mux_device``. This link only exists
146 in logical I2C bus directory which is fanned out from another I2C bus.
147 Reading this link will also tell you which I2C MUX device created
148 this logical I2C bus.
150 If the symbolic link points to a directory ending with ``.i2c``, it should be a
151 physical I2C bus, directly abstracting a physical I2C bus controller. For
154 $ readlink /sys/bus/i2c/devices/i2c-7/device
156 $ ls /sys/bus/i2c/devices/i2c-7/mux_device
157 ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory
159 In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic
160 link ``mux_device`` under its directory. And if the kernel software developer
161 follows the common practice by not renaming physical I2C buses, this should also
162 mean the physical I2C bus controller 7 of the system.
164 On the other hand, if the symbolic link points to another I2C bus, the I2C bus
165 presented by the current directory has to be a logical bus. The I2C bus pointed
166 by the link is the parent bus which may be either a physical I2C bus or a
167 logical one. In this case, the I2C bus presented by the current directory
168 abstracts an I2C MUX channel under the parent bus.
172 $ readlink /sys/bus/i2c/devices/i2c-73/device
174 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device
177 ``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7``
178 whose I2C address is 0x71.
179 Whenever we access an I2C device with bus 73, the kernel will always
180 switch the I2C MUX addressed 0x71 to the proper channel for you as part of the
183 Finding out Logical I2C Bus Number
184 ----------------------------------
186 In this section, we will describe how to find out the logical I2C bus number
187 representing certain I2C MUX channels based on the knowledge of physical
188 hardware I2C topology.
190 In this example, we have a system which has a physical I2C bus 7 and not renamed
191 in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another
192 8-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us
193 navigate through Sysfs and find out the logical I2C bus number of the channel 3
196 First of all, let us go to the directory of ``i2c-7``::
198 ~$ cd /sys/bus/i2c/devices/i2c-7
199 /sys/bus/i2c/devices/i2c-7$ ls
200 7-0071 i2c-60 name subsystem
201 delete_device i2c-73 new_device uevent
202 device i2c-86 of_node
203 i2c-203 i2c-dev power
205 There, we see the 0x71 MUX as ``7-0071``. Go inside it::
207 /sys/bus/i2c/devices/i2c-7$ cd 7-0071/
208 /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l
209 channel-0 channel-3 modalias power
210 channel-1 driver name subsystem
211 channel-2 idle_state of_node uevent
213 Read the link ``channel-1`` using ``readlink`` or ``ls -l``::
215 /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1
218 We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned
219 with a logical I2C bus number of 73.
220 Let us continue the journey to directory ``i2c-73`` in either ways::
222 # cd to i2c-73 under I2C Sysfs root
223 /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73
224 /sys/bus/i2c/devices/i2c-73$
226 # cd the channel symbolic link
227 /sys/bus/i2c/devices/i2c-7/7-0071$ cd channel-1
228 /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$
230 # cd the link content
231 /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c-73
232 /sys/bus/i2c/devices/i2c-7/i2c-73$
234 Either ways, you will end up in the directory of ``i2c-73``. Similar to above,
235 we can now find the 0x72 MUX and what logical I2C bus numbers
236 that its channels are assigned::
238 /sys/bus/i2c/devices/i2c-73$ ls
239 73-0040 device i2c-83 new_device
240 73-004e i2c-78 i2c-84 of_node
241 73-0050 i2c-79 i2c-85 power
242 73-0070 i2c-80 i2c-dev subsystem
243 73-0072 i2c-81 mux_device uevent
244 delete_device i2c-82 name
245 /sys/bus/i2c/devices/i2c-73$ cd 73-0072
246 /sys/bus/i2c/devices/i2c-73/73-0072$ ls
247 channel-0 channel-4 driver of_node
248 channel-1 channel-5 idle_state power
249 channel-2 channel-6 modalias subsystem
250 channel-3 channel-7 name uevent
251 /sys/bus/i2c/devices/i2c-73/73-0072$ readlink channel-3
254 There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX
255 is 81. We can later use this number to switch to its own I2C Sysfs directory or
256 issue ``i2c-tools`` commands.
258 Tip: Once you understand the I2C topology with MUX, command
260 <https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_
263 <https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_
265 an overview of the I2C topology easily, if it is available on your system. For
268 $ i2cdetect -l | grep -e '\-73' -e _7 | sort -V
269 i2c-7 i2c npcm_i2c_7 I2C adapter
270 i2c-73 i2c i2c-7-mux (chan_id 1) I2C adapter
271 i2c-78 i2c i2c-73-mux (chan_id 0) I2C adapter
272 i2c-79 i2c i2c-73-mux (chan_id 1) I2C adapter
273 i2c-80 i2c i2c-73-mux (chan_id 2) I2C adapter
274 i2c-81 i2c i2c-73-mux (chan_id 3) I2C adapter
275 i2c-82 i2c i2c-73-mux (chan_id 4) I2C adapter
276 i2c-83 i2c i2c-73-mux (chan_id 5) I2C adapter
277 i2c-84 i2c i2c-73-mux (chan_id 6) I2C adapter
278 i2c-85 i2c i2c-73-mux (chan_id 7) I2C adapter
280 Pinned Logical I2C Bus Number
281 -----------------------------
283 If not specified in DTS, when an I2C MUX driver is applied and the MUX device is
284 successfully probed, the kernel will assign the MUX channels with a logical bus
285 number based on the current biggest logical bus number incrementally. For
286 example, if the system has ``i2c-15`` as the highest logical bus number, and a
287 4-channel MUX is applied successfully, we will have ``i2c-16`` for the
288 MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3.
290 The kernel software developer is able to pin the fanout MUX channels to a static
291 logical I2C bus number in the DTS. This doc will not go through the details on
292 how to implement this in DTS, but we can see an example in:
293 `arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts
294 <../../arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts>`_
296 In the above example, there is an 8-channel I2C MUX at address 0x70 on physical
297 I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS,
298 and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;``
299 in section ``aliases``.
301 Take it further, it is possible to design a logical I2C bus number schema that
302 can be easily remembered by humans or calculated arithmetically. For example, we
303 can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the
304 logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the
305 logical bus number of the channel 7 of the MUX on bus 3.
310 In previous sections, we mostly covered the I2C bus. In this section, let us see
311 what we can learn from the I2C device directory whose link name is in the format
312 of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus
313 decimal number, while the ``${addr}`` part is a hex number of the I2C address
316 I2C Device Directory Content
317 ----------------------------
319 Inside each I2C device directory, there is a file named ``name``.
320 This file tells what device name it was used for the kernel driver to
321 probe this device. Use command ``cat`` to read its content. For example::
323 /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name
325 /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name
327 /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name
330 There is a symbolic link named ``driver`` to tell what Linux kernel driver was
331 used to probe this device::
333 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0040/driver
334 /sys/bus/i2c/drivers/ina2xx
335 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0072/driver
336 /sys/bus/i2c/drivers/pca954x
338 But if the link ``driver`` does not exist at the first place,
339 it may mean that the kernel driver failed to probe this device due to
340 some errors. The error may be found in ``dmesg``::
342 /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driver
343 ls: 73-0070/driver: No such file or directory
344 /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73-0070
345 pca954x 73-0070: probe failed
346 pca954x 73-0070: probe failed
348 Depending on what the I2C device is and what kernel driver was used to probe the
349 device, we may have different content in the device directory.
354 While you may be already aware of this in previous sections, an I2C MUX device
355 will have symbolic link ``channel-*`` inside its device directory.
356 These symbolic links point to their logical I2C bus directories::
358 /sys/bus/i2c/devices/i2c-73$ ls -l 73-0072/channel-*
359 lrwxrwxrwx ... 73-0072/channel-0 -> ../i2c-78
360 lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-79
361 lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-80
362 lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-81
363 lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-82
364 lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-83
365 lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-84
366 lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85
368 I2C Sensor Device / Hwmon
369 -------------------------
371 I2C sensor device is also common to see. If they are bound by a kernel hwmon
372 (Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory
373 inside the I2C device directory. Keep digging into it, you will find the Hwmon
374 Sysfs for the I2C sensor device::
376 /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hwmon17$ ls
377 curr1_input in0_lcrit_alarm name subsystem
378 device in1_crit power uevent
379 in0_crit in1_crit_alarm power1_crit update_interval
380 in0_crit_alarm in1_input power1_crit_alarm
381 in0_input in1_lcrit power1_input
382 in0_lcrit in1_lcrit_alarm shunt_resistor
384 For more info on the Hwmon Sysfs, refer to the doc:
386 `Naming and data format standards for sysfs files
387 <../hwmon/sysfs-interface.rst>`_
389 Instantiate I2C Devices in I2C Sysfs
390 ------------------------------------
394 `How to instantiate I2C devices, Method 4: Instantiate from user-space
395 <instantiating-devices.rst#method-4-instantiate-from-user-space>`_