388 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===============4Linux I2C Sysfs5===============6 7Overview8========9 10I2C topology can be complex because of the existence of I2C MUX11(I2C Multiplexer). The Linux12kernel abstracts the MUX channels into logical I2C bus numbers. However, there13is a gap of knowledge to map from the I2C bus physical number and MUX topology14to logical I2C bus number. This doc is aimed to fill in this gap, so the15audience (hardware engineers and new software developers for example) can learn16the concept of logical I2C buses in the kernel, by knowing the physical I2C17topology and navigating through the I2C sysfs in Linux shell. This knowledge is18useful and essential to use ``i2c-tools`` for the purpose of development and19debugging.20 21Target audience22---------------23 24People who need to use Linux shell to interact with I2C subsystem on a system25which the Linux is running on.26 27Prerequisites28-------------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 Sysfs35=====================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 that41start with ``i2c-`` are I2C buses, which may be either physical or logical. The42other links that begin with numbers and end with numbers are I2C devices, where43the 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 $ ls48 0-0008 0-0061 1-0028 3-0043 4-0036 4-0041 i2c-1 i2c-349 0-000c 0-0066 2-0049 4-000b 4-0040 i2c-0 i2c-2 i2c-450 51``i2c-2`` is an I2C bus whose number is 2, and ``2-0049`` is an I2C device52on bus 2 address 0x49 bound with a kernel driver.53 54Terminology55===========56 57First, let us define some terms to avoid confusion in later sections.58 59(Physical) I2C Bus Controller60-----------------------------61 62The hardware system that the Linux kernel is running on may have multiple63physical I2C bus controllers. The controllers are hardware and physical, and the64system may define multiple registers in the memory space to manipulate the65controllers. Linux kernel has I2C bus drivers under source directory66``drivers/i2c/busses`` to translate kernel I2C API into register67operations for different systems. This terminology is not limited to Linux68kernel only.69 70I2C Bus Physical Number71-----------------------72 73For each physical I2C bus controller, the system vendor may assign a physical74number to each controller. For example, the first I2C bus controller which has75the lowest register addresses may be called ``I2C-0``.76 77Logical I2C Bus78---------------79 80Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a81number assigned. This is similar to the fact that software code is usually82written upon virtual memory space, instead of physical memory space.83 84Each logical I2C bus may be an abstraction of a physical I2C bus controller, or85an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a86MUX channel, whenever we access an I2C device via a such logical bus, the kernel87will switch the I2C MUX for you to the proper channel as part of the88abstraction.89 90Physical I2C Bus91----------------92 93If the logical I2C bus is a direct abstraction of a physical I2C bus controller,94let us call it a physical I2C bus.95 96Caveat97------98 99This may be a confusing part for people who only know about the physical I2C100design of a board. It is actually possible to rename the I2C bus physical number101to a different number in logical I2C bus level in Device Tree Source (DTS) under102section ``aliases``. See ``arch/arm/boot/dts/nuvoton-npcm730-gsj.dts``103for an example of DTS file.104 105Best Practice: **(To kernel software developers)** It is better to keep the I2C106bus physical number the same as their corresponding logical I2C bus number,107instead of renaming or mapping them, so that it may be less confusing to other108users. These physical I2C buses can be served as good starting points for I2C109MUX fanouts. For the following examples, we will assume that the physical I2C110bus has a number same as their I2C bus physical number.111 112Walk through Logical I2C Bus113============================114 115For the following content, we will use a more complex I2C topology as an116example. Here is a brief graph for the I2C topology. If you do not understand117this graph at first glance, do not be afraid to continue reading this doc118and 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 hwmon directory)127 | |-- 73-0070 (I2C MUX at 0x70, exists in DTS, but failed to probe)128 | `-- 73-0072 (8-channel I2C MUX at 0x72)129 | |-- i2c-78 (channel-0)130 | |-- ... (channel-1...6, i2c-79...i2c-84)131 | `-- i2c-85 (channel-7)132 |-- i2c-86 (channel-2)133 `-- i2c-203 (channel-3)134 135Distinguish Physical and Logical I2C Bus136----------------------------------------137 138One simple way to distinguish between a physical I2C bus and a logical I2C bus,139is to read the symbolic link ``device`` under the I2C bus directory by using140command ``ls -l`` or ``readlink``.141 142An alternative symbolic link to check is ``mux_device``. This link only exists143in logical I2C bus directory which is fanned out from another I2C bus.144Reading this link will also tell you which I2C MUX device created145this logical I2C bus.146 147If the symbolic link points to a directory ending with ``.i2c``, it should be a148physical I2C bus, directly abstracting a physical I2C bus controller. For149example::150 151 $ readlink /sys/bus/i2c/devices/i2c-7/device152 ../../f0087000.i2c153 $ ls /sys/bus/i2c/devices/i2c-7/mux_device154 ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory155 156In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic157link ``mux_device`` under its directory. And if the kernel software developer158follows the common practice by not renaming physical I2C buses, this should also159mean the physical I2C bus controller 7 of the system.160 161On the other hand, if the symbolic link points to another I2C bus, the I2C bus162presented by the current directory has to be a logical bus. The I2C bus pointed163by the link is the parent bus which may be either a physical I2C bus or a164logical one. In this case, the I2C bus presented by the current directory165abstracts an I2C MUX channel under the parent bus.166 167For example::168 169 $ readlink /sys/bus/i2c/devices/i2c-73/device170 ../../i2c-7171 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device172 ../7-0071173 174``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7``175whose I2C address is 0x71.176Whenever we access an I2C device with bus 73, the kernel will always177switch the I2C MUX addressed 0x71 to the proper channel for you as part of the178abstraction.179 180Finding out Logical I2C Bus Number181----------------------------------182 183In this section, we will describe how to find out the logical I2C bus number184representing certain I2C MUX channels based on the knowledge of physical185hardware I2C topology.186 187In this example, we have a system which has a physical I2C bus 7 and not renamed188in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another1898-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us190navigate through Sysfs and find out the logical I2C bus number of the channel 3191of the 0x72 MUX.192 193First of all, let us go to the directory of ``i2c-7``::194 195 ~$ cd /sys/bus/i2c/devices/i2c-7196 /sys/bus/i2c/devices/i2c-7$ ls197 7-0071 i2c-60 name subsystem198 delete_device i2c-73 new_device uevent199 device i2c-86 of_node200 i2c-203 i2c-dev power201 202There, we see the 0x71 MUX as ``7-0071``. Go inside it::203 204 /sys/bus/i2c/devices/i2c-7$ cd 7-0071/205 /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l206 channel-0 channel-3 modalias power207 channel-1 driver name subsystem208 channel-2 idle_state of_node uevent209 210Read the link ``channel-1`` using ``readlink`` or ``ls -l``::211 212 /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1213 ../i2c-73214 215We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned216with a logical I2C bus number of 73.217Let us continue the journey to directory ``i2c-73`` in either ways::218 219 # cd to i2c-73 under I2C Sysfs root220 /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73221 /sys/bus/i2c/devices/i2c-73$222 223 # cd the channel symbolic link224 /sys/bus/i2c/devices/i2c-7/7-0071$ cd channel-1225 /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$226 227 # cd the link content228 /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c-73229 /sys/bus/i2c/devices/i2c-7/i2c-73$230 231Either ways, you will end up in the directory of ``i2c-73``. Similar to above,232we can now find the 0x72 MUX and what logical I2C bus numbers233that its channels are assigned::234 235 /sys/bus/i2c/devices/i2c-73$ ls236 73-0040 device i2c-83 new_device237 73-004e i2c-78 i2c-84 of_node238 73-0050 i2c-79 i2c-85 power239 73-0070 i2c-80 i2c-dev subsystem240 73-0072 i2c-81 mux_device uevent241 delete_device i2c-82 name242 /sys/bus/i2c/devices/i2c-73$ cd 73-0072243 /sys/bus/i2c/devices/i2c-73/73-0072$ ls244 channel-0 channel-4 driver of_node245 channel-1 channel-5 idle_state power246 channel-2 channel-6 modalias subsystem247 channel-3 channel-7 name uevent248 /sys/bus/i2c/devices/i2c-73/73-0072$ readlink channel-3249 ../i2c-81250 251There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX252is 81. We can later use this number to switch to its own I2C Sysfs directory or253issue ``i2c-tools`` commands.254 255Tip: Once you understand the I2C topology with MUX, command256`i2cdetect -l257<https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_258in259`I2C Tools260<https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_261can give you262an overview of the I2C topology easily, if it is available on your system. For263example::264 265 $ i2cdetect -l | grep -e '\-73' -e _7 | sort -V266 i2c-7 i2c npcm_i2c_7 I2C adapter267 i2c-73 i2c i2c-7-mux (chan_id 1) I2C adapter268 i2c-78 i2c i2c-73-mux (chan_id 0) I2C adapter269 i2c-79 i2c i2c-73-mux (chan_id 1) I2C adapter270 i2c-80 i2c i2c-73-mux (chan_id 2) I2C adapter271 i2c-81 i2c i2c-73-mux (chan_id 3) I2C adapter272 i2c-82 i2c i2c-73-mux (chan_id 4) I2C adapter273 i2c-83 i2c i2c-73-mux (chan_id 5) I2C adapter274 i2c-84 i2c i2c-73-mux (chan_id 6) I2C adapter275 i2c-85 i2c i2c-73-mux (chan_id 7) I2C adapter276 277Pinned Logical I2C Bus Number278-----------------------------279 280If not specified in DTS, when an I2C MUX driver is applied and the MUX device is281successfully probed, the kernel will assign the MUX channels with a logical bus282number based on the current biggest logical bus number incrementally. For283example, if the system has ``i2c-15`` as the highest logical bus number, and a2844-channel MUX is applied successfully, we will have ``i2c-16`` for the285MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3.286 287The kernel software developer is able to pin the fanout MUX channels to a static288logical I2C bus number in the DTS. This doc will not go through the details on289how to implement this in DTS, but we can see an example in:290``arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts``291 292In the above example, there is an 8-channel I2C MUX at address 0x70 on physical293I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS,294and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;``295in section ``aliases``.296 297Take it further, it is possible to design a logical I2C bus number schema that298can be easily remembered by humans or calculated arithmetically. For example, we299can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the300logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the301logical bus number of the channel 7 of the MUX on bus 3.302 303I2C Devices304===========305 306In previous sections, we mostly covered the I2C bus. In this section, let us see307what we can learn from the I2C device directory whose link name is in the format308of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus309decimal number, while the ``${addr}`` part is a hex number of the I2C address310of each device.311 312I2C Device Directory Content313----------------------------314 315Inside each I2C device directory, there is a file named ``name``.316This file tells what device name it was used for the kernel driver to317probe this device. Use command ``cat`` to read its content. For example::318 319 /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name320 ina230321 /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name322 pca9546323 /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name324 pca9547325 326There is a symbolic link named ``driver`` to tell what Linux kernel driver was327used to probe this device::328 329 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0040/driver330 /sys/bus/i2c/drivers/ina2xx331 /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0072/driver332 /sys/bus/i2c/drivers/pca954x333 334But if the link ``driver`` does not exist at the first place,335it may mean that the kernel driver failed to probe this device due to336some errors. The error may be found in ``dmesg``::337 338 /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driver339 ls: 73-0070/driver: No such file or directory340 /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73-0070341 pca954x 73-0070: probe failed342 pca954x 73-0070: probe failed343 344Depending on what the I2C device is and what kernel driver was used to probe the345device, we may have different content in the device directory.346 347I2C MUX Device348--------------349 350While you may be already aware of this in previous sections, an I2C MUX device351will have symbolic link ``channel-*`` inside its device directory.352These symbolic links point to their logical I2C bus directories::353 354 /sys/bus/i2c/devices/i2c-73$ ls -l 73-0072/channel-*355 lrwxrwxrwx ... 73-0072/channel-0 -> ../i2c-78356 lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-79357 lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-80358 lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-81359 lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-82360 lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-83361 lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-84362 lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85363 364I2C Sensor Device / Hwmon365-------------------------366 367I2C sensor device is also common to see. If they are bound by a kernel hwmon368(Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory369inside the I2C device directory. Keep digging into it, you will find the Hwmon370Sysfs for the I2C sensor device::371 372 /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hwmon17$ ls373 curr1_input in0_lcrit_alarm name subsystem374 device in1_crit power uevent375 in0_crit in1_crit_alarm power1_crit update_interval376 in0_crit_alarm in1_input power1_crit_alarm377 in0_input in1_lcrit power1_input378 in0_lcrit in1_lcrit_alarm shunt_resistor379 380For more info on the Hwmon Sysfs, refer to the doc:381 382../hwmon/sysfs-interface.rst383 384Instantiate I2C Devices in I2C Sysfs385------------------------------------386 387Refer to section "Method 4: Instantiate from user-space" of instantiating-devices.rst388