Documentation/i2c/i2c-sysfs.rst

13 is a gap of knowledge to map from the I2C bus physical number and MUX topology
24 People who need to use Linux shell to interact with I2C subsystem on a system
40 There is a list of symbolic links under that directory. The links that
52 on bus 2 address 0x49 bound with a kernel driver.
73 For each physical I2C bus controller, the system vendor may assign a physical
80 Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a
84 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. In case it is an abstraction of a
86 MUX channel, whenever we access an I2C device via a such logical bus, the kernel
93 If the logical I2C bus is a direct abstraction of a physical I2C bus controller,
94 let us call it a physical I2C bus.
99 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 rename the I2C bus physical number
101 to a different number in logical I2C bus level in Device Tree Source (DTS) under
110 bus has a number same as their I2C bus physical number.
115 For the following content, we will use a more complex I2C topology as an
116 example. Here is a brief graph for the I2C topology. If you do not understand
122   i2c-7 (physical I2C bus controller 7)
123   `-- 7-0071 (4-channel I2C MUX at 0x71)
131       |       `-- i2c-85 (channel-7)
138 One simple way to distinguish between a physical I2C bus and a logical I2C bus,
147 If the symbolic link points to a directory ending with ``.i2c``, it should be a
148 physical I2C bus, directly abstracting a physical I2C bus controller. For
151   $ readlink /sys/bus/i2c/devices/i2c-7/device
153   $ ls /sys/bus/i2c/devices/i2c-7/mux_device
154   ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory
156 In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic
159 mean the physical I2C bus controller 7 of the system.
162 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 either a physical I2C bus or a
170   ../../i2c-7
172   ../7-0071
174 ``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7``
187 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 0x71 on that bus. There is another
193 First of all, let us go to the directory of ``i2c-7``::
195   ~$ cd /sys/bus/i2c/devices/i2c-7
196   /sys/bus/i2c/devices/i2c-7$ ls
197   7-0071         i2c-60         name           subsystem
202 There, we see the 0x71 MUX as ``7-0071``. Go inside it::
204   /sys/bus/i2c/devices/i2c-7$ cd 7-0071/
205   /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l
212   /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1
215 We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned
216 with a logical I2C bus number of 73.
220   /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73
224   /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$ cd ../i2c-73
229   /sys/bus/i2c/devices/i2c-7/i2c-73$
247   channel-3   channel-7   name        uevent
266   i2c-7   i2c             npcm_i2c_7                              I2C adapter
267   i2c-73  i2c             i2c-7-mux (chan_id 1)                   I2C adapter
275   i2c-85  i2c             i2c-73-mux (chan_id 7)                  I2C adapter
281 successfully probed, the kernel will assign the MUX channels with a logical bus
283 example, if the system has ``i2c-15`` as the highest logical bus number, and a
287 The kernel software developer is able to pin the fanout MUX channels to a static
297 Take it further, it is possible to design a logical I2C bus number schema that
299 can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the
301 logical bus number of the channel 7 of the MUX on bus 3.
308 of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus
309 decimal number, while the ``${addr}`` part is a hex number of the I2C address
315 Inside each I2C device directory, there is a file named ``name``.
326 There is a symbolic link named ``driver`` to tell what Linux kernel driver was
362   lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85
367 I2C sensor device is also common to see. If they are bound by a kernel hwmon
368 (Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory