1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Linux I2C Sysfs 5=============== 6 7Overview 8======== 9 10I2C topology can be complex because of the existence of I2C MUX 11(I2C Multiplexer). The Linux 12kernel abstracts the MUX channels into logical I2C bus numbers. However, there 13is a gap of knowledge to map from the I2C bus physical number and MUX topology 14to logical I2C bus number. This doc is aimed to fill in this gap, so the 15audience (hardware engineers and new software developers for example) can learn 16the concept of logical I2C buses in the kernel, by knowing the physical I2C 17topology and navigating through the I2C sysfs in Linux shell. This knowledge is 18useful and essential to use ``i2c-tools`` for the purpose of development and 19debugging. 20 21Target audience 22--------------- 23 24People who need to use Linux shell to interact with I2C subsystem on a system 25which the Linux is running on. 26 27Prerequisites 28------------- 29 301. Knowledge of general Linux shell file system commands and operations. 31 322. General knowledge of I2C, I2C MUX and I2C topology. 33 34Location of I2C Sysfs 35===================== 36 37Typically, the Linux Sysfs filesystem is mounted at the ``/sys`` directory, 38so you can find the I2C Sysfs under ``/sys/bus/i2c/devices`` 39where you can directly ``cd`` to it. 40There is a list of symbolic links under that directory. The links that 41start with ``i2c-`` are I2C buses, which may be either physical or logical. The 42other links that begin with numbers and end with numbers are I2C devices, where 43the first number is I2C bus number, and the second number is I2C address. 44 45Google 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-0041 i2c-1 i2c-3 49 0-000c 0-0066 2-0049 4-000b 4-0040 i2c-0 i2c-2 i2c-4 50 51``i2c-2`` is an I2C bus whose number is 2, and ``2-0049`` is an I2C device 52on bus 2 address 0x49 bound with a kernel driver. 53 54Terminologies 55============= 56 57First, let us define a couple of terminologies to avoid confusions in the later 58sections. 59 60(Physical) I2C Bus Controller 61----------------------------- 62 63The hardware system that the Linux kernel is running on may have multiple 64physical I2C bus controllers. The controllers are hardware and physical, and the 65system may define multiple registers in the memory space to manipulate the 66controllers. Linux kernel has I2C bus drivers under source directory 67``drivers/i2c/busses`` to translate kernel I2C API into register 68operations for different systems. This terminology is not limited to Linux 69kernel only. 70 71I2C Bus Physical Number 72----------------------- 73 74For each physical I2C bus controller, the system vendor may assign a physical 75number to each controller. For example, the first I2C bus controller which has 76the lowest register addresses may be called ``I2C-0``. 77 78Logical I2C Bus 79--------------- 80 81Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a 82number assigned. This is similar to the fact that software code is usually 83written upon virtual memory space, instead of physical memory space. 84 85Each logical I2C bus may be an abstraction of a physical I2C bus controller, or 86an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a 87MUX channel, whenever we access an I2C device via a such logical bus, the kernel 88will switch the I2C MUX for you to the proper channel as part of the 89abstraction. 90 91Physical I2C Bus 92---------------- 93 94If the logical I2C bus is a direct abstraction of a physical I2C bus controller, 95let us call it a physical I2C bus. 96 97Caveat 98------ 99 100This may be a confusing part for people who only know about the physical I2C 101design of a board. It is actually possible to rename the I2C bus physical number 102to a different number in logical I2C bus level in Device Tree Source (DTS) under 103section ``aliases``. See 104`arch/arm/boot/dts/nuvoton-npcm730-gsj.dts 105<../../arch/arm/boot/dts/nuvoton-npcm730-gsj.dts>`_ 106for an example of DTS file. 107 108Best Practice: **(To kernel software developers)** It is better to keep the I2C 109bus physical number the same as their corresponding logical I2C bus number, 110instead of renaming or mapping them, so that it may be less confusing to other 111users. These physical I2C buses can be served as good starting points for I2C 112MUX fanouts. For the following examples, we will assume that the physical I2C 113bus has a number same as their I2C bus physical number. 114 115Walk through Logical I2C Bus 116============================ 117 118For the following content, we will use a more complex I2C topology as an 119example. Here is a brief graph for the I2C topology. If you do not understand 120this graph at the first glance, do not be afraid to continue reading this doc 121and review it when you finish reading. 122 123:: 124 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) 137 138Distinguish Physical and Logical I2C Bus 139---------------------------------------- 140 141One simple way to distinguish between a physical I2C bus and a logical I2C bus, 142is to read the symbolic link ``device`` under the I2C bus directory by using 143command ``ls -l`` or ``readlink``. 144 145An alternative symbolic link to check is ``mux_device``. This link only exists 146in logical I2C bus directory which is fanned out from another I2C bus. 147Reading this link will also tell you which I2C MUX device created 148this logical I2C bus. 149 150If the symbolic link points to a directory ending with ``.i2c``, it should be a 151physical I2C bus, directly abstracting a physical I2C bus controller. For 152example:: 153 154 $ readlink /sys/bus/i2c/devices/i2c-7/device 155 ../../f0087000.i2c 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 158 159In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic 160link ``mux_device`` under its directory. And if the kernel software developer 161follows the common practice by not renaming physical I2C buses, this should also 162mean the physical I2C bus controller 7 of the system. 163 164On the other hand, if the symbolic link points to another I2C bus, the I2C bus 165presented by the current directory has to be a logical bus. The I2C bus pointed 166by the link is the parent bus which may be either a physical I2C bus or a 167logical one. In this case, the I2C bus presented by the current directory 168abstracts an I2C MUX channel under the parent bus. 169 170For example:: 171 172 $ readlink /sys/bus/i2c/devices/i2c-73/device 173 ../../i2c-7 174 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device 175 ../7-0071 176 177``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7`` 178whose I2C address is 0x71. 179Whenever we access an I2C device with bus 73, the kernel will always 180switch the I2C MUX addressed 0x71 to the proper channel for you as part of the 181abstraction. 182 183Finding out Logical I2C Bus Number 184---------------------------------- 185 186In this section, we will describe how to find out the logical I2C bus number 187representing certain I2C MUX channels based on the knowledge of physical 188hardware I2C topology. 189 190In this example, we have a system which has a physical I2C bus 7 and not renamed 191in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another 1928-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us 193navigate through Sysfs and find out the logical I2C bus number of the channel 3 194of the 0x72 MUX. 195 196First of all, let us go to the directory of ``i2c-7``:: 197 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 204 205There, we see the 0x71 MUX as ``7-0071``. Go inside it:: 206 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 212 213Read the link ``channel-1`` using ``readlink`` or ``ls -l``:: 214 215 /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1 216 ../i2c-73 217 218We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned 219with a logical I2C bus number of 73. 220Let us continue the journey to directory ``i2c-73`` in either ways:: 221 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$ 225 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$ 229 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$ 233 234Either ways, you will end up in the directory of ``i2c-73``. Similar to above, 235we can now find the 0x72 MUX and what logical I2C bus numbers 236that its channels are assigned:: 237 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 252 ../i2c-81 253 254There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX 255is 81. We can later use this number to switch to its own I2C Sysfs directory or 256issue ``i2c-tools`` commands. 257 258Tip: Once you understand the I2C topology with MUX, command 259`i2cdetect -l 260<https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_ 261in 262`I2C Tools 263<https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_ 264can give you 265an overview of the I2C topology easily, if it is available on your system. For 266example:: 267 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 279 280Pinned Logical I2C Bus Number 281----------------------------- 282 283If not specified in DTS, when an I2C MUX driver is applied and the MUX device is 284successfully probed, the kernel will assign the MUX channels with a logical bus 285number based on the current biggest logical bus number incrementally. For 286example, if the system has ``i2c-15`` as the highest logical bus number, and a 2874-channel MUX is applied successfully, we will have ``i2c-16`` for the 288MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3. 289 290The kernel software developer is able to pin the fanout MUX channels to a static 291logical I2C bus number in the DTS. This doc will not go through the details on 292how 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>`_ 295 296In the above example, there is an 8-channel I2C MUX at address 0x70 on physical 297I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS, 298and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;`` 299in section ``aliases``. 300 301Take it further, it is possible to design a logical I2C bus number schema that 302can be easily remembered by humans or calculated arithmetically. For example, we 303can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the 304logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the 305logical bus number of the channel 7 of the MUX on bus 3. 306 307I2C Devices 308=========== 309 310In previous sections, we mostly covered the I2C bus. In this section, let us see 311what we can learn from the I2C device directory whose link name is in the format 312of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus 313decimal number, while the ``${addr}`` part is a hex number of the I2C address 314of each device. 315 316I2C Device Directory Content 317---------------------------- 318 319Inside each I2C device directory, there is a file named ``name``. 320This file tells what device name it was used for the kernel driver to 321probe this device. Use command ``cat`` to read its content. For example:: 322 323 /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name 324 ina230 325 /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name 326 pca9546 327 /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name 328 pca9547 329 330There is a symbolic link named ``driver`` to tell what Linux kernel driver was 331used to probe this device:: 332 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 337 338But if the link ``driver`` does not exist at the first place, 339it may mean that the kernel driver failed to probe this device due to 340some errors. The error may be found in ``dmesg``:: 341 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 347 348Depending on what the I2C device is and what kernel driver was used to probe the 349device, we may have different content in the device directory. 350 351I2C MUX Device 352-------------- 353 354While you may be already aware of this in previous sections, an I2C MUX device 355will have symbolic link ``channel-*`` inside its device directory. 356These symbolic links point to their logical I2C bus directories:: 357 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 367 368I2C Sensor Device / Hwmon 369------------------------- 370 371I2C 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 373inside the I2C device directory. Keep digging into it, you will find the Hwmon 374Sysfs for the I2C sensor device:: 375 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 383 384For more info on the Hwmon Sysfs, refer to the doc: 385 386`Naming and data format standards for sysfs files 387<../hwmon/sysfs-interface.rst>`_ 388 389Instantiate I2C Devices in I2C Sysfs 390------------------------------------ 391 392Refer 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>`_ 396