| .. SPDX-License-Identifier: GPL-2.0 |
| |
| =============== |
| Linux I2C Sysfs |
| =============== |
| |
| Overview |
| ======== |
| |
| I2C topology can be complex because of the existence of I2C MUX |
| (I2C Multiplexer). The Linux |
| kernel abstracts the MUX channels into logical I2C bus numbers. However, there |
| is a gap of knowledge to map from the I2C bus physical number and MUX topology |
| to logical I2C bus number. This doc is aimed to fill in this gap, so the |
| audience (hardware engineers and new software developers for example) can learn |
| the concept of logical I2C buses in the kernel, by knowing the physical I2C |
| topology and navigating through the I2C sysfs in Linux shell. This knowledge is |
| useful and essential to use ``i2c-tools`` for the purpose of development and |
| debugging. |
| |
| Target audience |
| --------------- |
| |
| People who need to use Linux shell to interact with I2C subsystem on a system |
| which the Linux is running on. |
| |
| Prerequisites |
| ------------- |
| |
| 1. Knowledge of general Linux shell file system commands and operations. |
| |
| 2. General knowledge of I2C, I2C MUX and I2C topology. |
| |
| Location of I2C Sysfs |
| ===================== |
| |
| Typically, the Linux Sysfs filesystem is mounted at the ``/sys`` directory, |
| so you can find the I2C Sysfs under ``/sys/bus/i2c/devices`` |
| where you can directly ``cd`` to it. |
| There is a list of symbolic links under that directory. The links that |
| start with ``i2c-`` are I2C buses, which may be either physical or logical. The |
| other links that begin with numbers and end with numbers are I2C devices, where |
| the first number is I2C bus number, and the second number is I2C address. |
| |
| Google Pixel 3 phone for example:: |
| |
| blueline:/sys/bus/i2c/devices $ ls |
| 0-0008 0-0061 1-0028 3-0043 4-0036 4-0041 i2c-1 i2c-3 |
| 0-000c 0-0066 2-0049 4-000b 4-0040 i2c-0 i2c-2 i2c-4 |
| |
| ``i2c-2`` is an I2C bus whose number is 2, and ``2-0049`` is an I2C device |
| on bus 2 address 0x49 bound with a kernel driver. |
| |
| Terminologies |
| ============= |
| |
| First, let us define a couple of terminologies to avoid confusions in the later |
| sections. |
| |
| (Physical) I2C Bus Controller |
| ----------------------------- |
| |
| The hardware system that the Linux kernel is running on may have multiple |
| physical I2C bus controllers. The controllers are hardware and physical, and the |
| system may define multiple registers in the memory space to manipulate the |
| controllers. Linux kernel has I2C bus drivers under source directory |
| ``drivers/i2c/busses`` to translate kernel I2C API into register |
| operations for different systems. This terminology is not limited to Linux |
| kernel only. |
| |
| I2C Bus Physical Number |
| ----------------------- |
| |
| For each physical I2C bus controller, the system vendor may assign a physical |
| number to each controller. For example, the first I2C bus controller which has |
| the lowest register addresses may be called ``I2C-0``. |
| |
| Logical I2C Bus |
| --------------- |
| |
| Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a |
| number assigned. This is similar to the fact that software code is usually |
| written upon virtual memory space, instead of physical memory space. |
| |
| Each logical I2C bus may be an abstraction of a physical I2C bus controller, or |
| an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a |
| MUX channel, whenever we access an I2C device via a such logical bus, the kernel |
| will switch the I2C MUX for you to the proper channel as part of the |
| abstraction. |
| |
| Physical I2C Bus |
| ---------------- |
| |
| If the logical I2C bus is a direct abstraction of a physical I2C bus controller, |
| let us call it a physical I2C bus. |
| |
| Caveat |
| ------ |
| |
| This may be a confusing part for people who only know about the physical I2C |
| design of a board. It is actually possible to rename the I2C bus physical number |
| to a different number in logical I2C bus level in Device Tree Source (DTS) under |
| section ``aliases``. See |
| `arch/arm/boot/dts/nuvoton-npcm730-gsj.dts |
| <../../arch/arm/boot/dts/nuvoton-npcm730-gsj.dts>`_ |
| for an example of DTS file. |
| |
| Best Practice: **(To kernel software developers)** It is better to keep the I2C |
| bus physical number the same as their corresponding logical I2C bus number, |
| instead of renaming or mapping them, so that it may be less confusing to other |
| users. These physical I2C buses can be served as good starting points for I2C |
| MUX fanouts. For the following examples, we will assume that the physical I2C |
| bus has a number same as their I2C bus physical number. |
| |
| Walk through Logical I2C Bus |
| ============================ |
| |
| For the following content, we will use a more complex I2C topology as an |
| example. Here is a brief graph for the I2C topology. If you do not understand |
| this graph at the first glance, do not be afraid to continue reading this doc |
| and review it when you finish reading. |
| |
| :: |
| |
| i2c-7 (physical I2C bus controller 7) |
| `-- 7-0071 (4-channel I2C MUX at 0x71) |
| |-- i2c-60 (channel-0) |
| |-- i2c-73 (channel-1) |
| | |-- 73-0040 (I2C sensor device with hwmon directory) |
| | |-- 73-0070 (I2C MUX at 0x70, exists in DTS, but failed to probe) |
| | `-- 73-0072 (8-channel I2C MUX at 0x72) |
| | |-- i2c-78 (channel-0) |
| | |-- ... (channel-1...6, i2c-79...i2c-84) |
| | `-- i2c-85 (channel-7) |
| |-- i2c-86 (channel-2) |
| `-- i2c-203 (channel-3) |
| |
| Distinguish Physical and Logical I2C Bus |
| ---------------------------------------- |
| |
| One simple way to distinguish between a physical I2C bus and a logical I2C bus, |
| is to read the symbolic link ``device`` under the I2C bus directory by using |
| command ``ls -l`` or ``readlink``. |
| |
| An alternative symbolic link to check is ``mux_device``. This link only exists |
| in logical I2C bus directory which is fanned out from another I2C bus. |
| Reading this link will also tell you which I2C MUX device created |
| this logical I2C bus. |
| |
| If the symbolic link points to a directory ending with ``.i2c``, it should be a |
| physical I2C bus, directly abstracting a physical I2C bus controller. For |
| example:: |
| |
| $ readlink /sys/bus/i2c/devices/i2c-7/device |
| ../../f0087000.i2c |
| $ ls /sys/bus/i2c/devices/i2c-7/mux_device |
| ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory |
| |
| In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic |
| link ``mux_device`` under its directory. And if the kernel software developer |
| follows the common practice by not renaming physical I2C buses, this should also |
| mean the physical I2C bus controller 7 of the system. |
| |
| On the other hand, if the symbolic link points to another I2C bus, the I2C bus |
| presented by the current directory has to be a logical bus. The I2C bus pointed |
| by the link is the parent bus which may be either a physical I2C bus or a |
| logical one. In this case, the I2C bus presented by the current directory |
| abstracts an I2C MUX channel under the parent bus. |
| |
| For example:: |
| |
| $ readlink /sys/bus/i2c/devices/i2c-73/device |
| ../../i2c-7 |
| $ readlink /sys/bus/i2c/devices/i2c-73/mux_device |
| ../7-0071 |
| |
| ``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7`` |
| whose I2C address is 0x71. |
| Whenever we access an I2C device with bus 73, the kernel will always |
| switch the I2C MUX addressed 0x71 to the proper channel for you as part of the |
| abstraction. |
| |
| Finding out Logical I2C Bus Number |
| ---------------------------------- |
| |
| In this section, we will describe how to find out the logical I2C bus number |
| representing certain I2C MUX channels based on the knowledge of physical |
| hardware I2C topology. |
| |
| In this example, we have a system which has a physical I2C bus 7 and not renamed |
| in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another |
| 8-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us |
| navigate through Sysfs and find out the logical I2C bus number of the channel 3 |
| of the 0x72 MUX. |
| |
| First of all, let us go to the directory of ``i2c-7``:: |
| |
| ~$ cd /sys/bus/i2c/devices/i2c-7 |
| /sys/bus/i2c/devices/i2c-7$ ls |
| 7-0071 i2c-60 name subsystem |
| delete_device i2c-73 new_device uevent |
| device i2c-86 of_node |
| i2c-203 i2c-dev power |
| |
| There, we see the 0x71 MUX as ``7-0071``. Go inside it:: |
| |
| /sys/bus/i2c/devices/i2c-7$ cd 7-0071/ |
| /sys/bus/i2c/devices/i2c-7/7-0071$ ls -l |
| channel-0 channel-3 modalias power |
| channel-1 driver name subsystem |
| channel-2 idle_state of_node uevent |
| |
| Read the link ``channel-1`` using ``readlink`` or ``ls -l``:: |
| |
| /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1 |
| ../i2c-73 |
| |
| We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned |
| with a logical I2C bus number of 73. |
| Let us continue the journey to directory ``i2c-73`` in either ways:: |
| |
| # cd to i2c-73 under I2C Sysfs root |
| /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73 |
| /sys/bus/i2c/devices/i2c-73$ |
| |
| # cd the channel symbolic link |
| /sys/bus/i2c/devices/i2c-7/7-0071$ cd channel-1 |
| /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$ |
| |
| # cd the link content |
| /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c-73 |
| /sys/bus/i2c/devices/i2c-7/i2c-73$ |
| |
| Either ways, you will end up in the directory of ``i2c-73``. Similar to above, |
| we can now find the 0x72 MUX and what logical I2C bus numbers |
| that its channels are assigned:: |
| |
| /sys/bus/i2c/devices/i2c-73$ ls |
| 73-0040 device i2c-83 new_device |
| 73-004e i2c-78 i2c-84 of_node |
| 73-0050 i2c-79 i2c-85 power |
| 73-0070 i2c-80 i2c-dev subsystem |
| 73-0072 i2c-81 mux_device uevent |
| delete_device i2c-82 name |
| /sys/bus/i2c/devices/i2c-73$ cd 73-0072 |
| /sys/bus/i2c/devices/i2c-73/73-0072$ ls |
| channel-0 channel-4 driver of_node |
| channel-1 channel-5 idle_state power |
| channel-2 channel-6 modalias subsystem |
| channel-3 channel-7 name uevent |
| /sys/bus/i2c/devices/i2c-73/73-0072$ readlink channel-3 |
| ../i2c-81 |
| |
| There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX |
| is 81. We can later use this number to switch to its own I2C Sysfs directory or |
| issue ``i2c-tools`` commands. |
| |
| Tip: Once you understand the I2C topology with MUX, command |
| `i2cdetect -l |
| <https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_ |
| in |
| `I2C Tools |
| <https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_ |
| can give you |
| an overview of the I2C topology easily, if it is available on your system. For |
| example:: |
| |
| $ i2cdetect -l | grep -e '\-73' -e _7 | sort -V |
| i2c-7 i2c npcm_i2c_7 I2C adapter |
| i2c-73 i2c i2c-7-mux (chan_id 1) I2C adapter |
| i2c-78 i2c i2c-73-mux (chan_id 0) I2C adapter |
| i2c-79 i2c i2c-73-mux (chan_id 1) I2C adapter |
| i2c-80 i2c i2c-73-mux (chan_id 2) I2C adapter |
| i2c-81 i2c i2c-73-mux (chan_id 3) I2C adapter |
| i2c-82 i2c i2c-73-mux (chan_id 4) I2C adapter |
| i2c-83 i2c i2c-73-mux (chan_id 5) I2C adapter |
| i2c-84 i2c i2c-73-mux (chan_id 6) I2C adapter |
| i2c-85 i2c i2c-73-mux (chan_id 7) I2C adapter |
| |
| Pinned Logical I2C Bus Number |
| ----------------------------- |
| |
| If not specified in DTS, when an I2C MUX driver is applied and the MUX device is |
| successfully probed, the kernel will assign the MUX channels with a logical bus |
| number based on the current biggest logical bus number incrementally. For |
| example, if the system has ``i2c-15`` as the highest logical bus number, and a |
| 4-channel MUX is applied successfully, we will have ``i2c-16`` for the |
| MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3. |
| |
| The kernel software developer is able to pin the fanout MUX channels to a static |
| logical I2C bus number in the DTS. This doc will not go through the details on |
| how to implement this in DTS, but we can see an example in: |
| `arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts |
| <../../arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts>`_ |
| |
| In the above example, there is an 8-channel I2C MUX at address 0x70 on physical |
| I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS, |
| and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;`` |
| in section ``aliases``. |
| |
| Take it further, it is possible to design a logical I2C bus number schema that |
| can be easily remembered by humans or calculated arithmetically. For example, we |
| can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the |
| logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the |
| logical bus number of the channel 7 of the MUX on bus 3. |
| |
| I2C Devices |
| =========== |
| |
| In previous sections, we mostly covered the I2C bus. In this section, let us see |
| what we can learn from the I2C device directory whose link name is in the format |
| of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus |
| decimal number, while the ``${addr}`` part is a hex number of the I2C address |
| of each device. |
| |
| I2C Device Directory Content |
| ---------------------------- |
| |
| Inside each I2C device directory, there is a file named ``name``. |
| This file tells what device name it was used for the kernel driver to |
| probe this device. Use command ``cat`` to read its content. For example:: |
| |
| /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name |
| ina230 |
| /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name |
| pca9546 |
| /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name |
| pca9547 |
| |
| There is a symbolic link named ``driver`` to tell what Linux kernel driver was |
| used to probe this device:: |
| |
| /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0040/driver |
| /sys/bus/i2c/drivers/ina2xx |
| /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0072/driver |
| /sys/bus/i2c/drivers/pca954x |
| |
| But if the link ``driver`` does not exist at the first place, |
| it may mean that the kernel driver failed to probe this device due to |
| some errors. The error may be found in ``dmesg``:: |
| |
| /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driver |
| ls: 73-0070/driver: No such file or directory |
| /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73-0070 |
| pca954x 73-0070: probe failed |
| pca954x 73-0070: probe failed |
| |
| Depending on what the I2C device is and what kernel driver was used to probe the |
| device, we may have different content in the device directory. |
| |
| I2C MUX Device |
| -------------- |
| |
| While you may be already aware of this in previous sections, an I2C MUX device |
| will have symbolic link ``channel-*`` inside its device directory. |
| These symbolic links point to their logical I2C bus directories:: |
| |
| /sys/bus/i2c/devices/i2c-73$ ls -l 73-0072/channel-* |
| lrwxrwxrwx ... 73-0072/channel-0 -> ../i2c-78 |
| lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-79 |
| lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-80 |
| lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-81 |
| lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-82 |
| lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-83 |
| lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-84 |
| lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85 |
| |
| I2C Sensor Device / Hwmon |
| ------------------------- |
| |
| I2C sensor device is also common to see. If they are bound by a kernel hwmon |
| (Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory |
| inside the I2C device directory. Keep digging into it, you will find the Hwmon |
| Sysfs for the I2C sensor device:: |
| |
| /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hwmon17$ ls |
| curr1_input in0_lcrit_alarm name subsystem |
| device in1_crit power uevent |
| in0_crit in1_crit_alarm power1_crit update_interval |
| in0_crit_alarm in1_input power1_crit_alarm |
| in0_input in1_lcrit power1_input |
| in0_lcrit in1_lcrit_alarm shunt_resistor |
| |
| For more info on the Hwmon Sysfs, refer to the doc: |
| |
| `Naming and data format standards for sysfs files |
| <../hwmon/sysfs-interface.rst>`_ |
| |
| Instantiate I2C Devices in I2C Sysfs |
| ------------------------------------ |
| |
| Refer to the doc: |
| |
| `How to instantiate I2C devices, Method 4: Instantiate from user-space |
| <instantiating-devices.rst#method-4-instantiate-from-user-space>`_ |
