sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget!/translations/zh_CN/i2c/i2c-sysfsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/zh_TW/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/it_IT/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/ja_JP/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/ko_KR/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/pt_BR/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget!/translations/sp_SP/i2c/i2c-sysfsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh;/var/lib/git/docbuild/linux/Documentation/i2c/i2c-sysfs.rsthKubhsection)}(hhh](htitle)}(hLinux I2C Sysfsh]hLinux I2C Sysfs}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hOverviewh]hOverview}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXI2C 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.h](hXLI2C 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 }(hhhhhNhNubhliteral)}(h ``i2c-tools``h]h i2c-tools}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh. for the purpose of development and debugging.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hhh](h)}(hTarget audienceh]hTarget audience}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hlPeople who need to use Linux shell to interact with I2C subsystem on a system which the Linux is running on.h]hlPeople who need to use Linux shell to interact with I2C subsystem on a system which the Linux is running on.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]target-audienceah ]h"]target audienceah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Prerequisitesh]h Prerequisites}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj9hhhhhKubhenumerated_list)}(hhh](h list_item)}(hFKnowledge of general Linux shell file system commands and operations. h]h)}(hEKnowledge of general Linux shell file system commands and operations.h]hEKnowledge of general Linux shell file system commands and operations.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQubah}(h]h ]h"]h$]h&]uh1jOhjLhhhhhNubjP)}(h4General knowledge of I2C, I2C MUX and I2C topology. h]h)}(h3General knowledge of I2C, I2C MUX and I2C topology.h]h3General knowledge of I2C, I2C MUX and I2C topology.}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjiubah}(h]h ]h"]h$]h&]uh1jOhjLhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jJhj9hhhhhKubeh}(h] prerequisitesah ]h"] prerequisitesah$]h&]uh1hhhhhhhhKubeh}(h]overviewah ]h"]overviewah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hLocation of I2C Sysfsh]hLocation of I2C Sysfs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK#ubh)}(hXTypically, 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.h](h8Typically, the Linux Sysfs filesystem is mounted at the }(hjhhhNhNubh)}(h``/sys``h]h/sys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh0 directory, so you can find the I2C Sysfs under }(hjhhhNhNubh)}(h``/sys/bus/i2c/devices``h]h/sys/bus/i2c/devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh where you can directly }(hjhhhNhNubh)}(h``cd``h]hcd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhZ to it. There is a list of symbolic links under that directory. The links that start with }(hjhhhNhNubh)}(h``i2c-``h]hi2c-}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK%hjhhubh)}(h"Google Pixel 3 phone for example::h]h!Google Pixel 3 phone for example:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hjhhubh literal_block)}(hblueline:/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-4h]hblueline:/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}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhK/hjhhubh)}(h|``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.h](h)}(h ``i2c-2``h]hi2c-2}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh& is an I2C bus whose number is 2, and }(hj!hhhNhNubh)}(h ``2-0049``h]h2-0049}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubhC is an I2C device on bus 2 address 0x49 bound with a kernel driver.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubeh}(h]location-of-i2c-sysfsah ]h"]location of i2c sysfsah$]h&]uh1hhhhhhhhK#ubh)}(hhh](h)}(h Terminologyh]h Terminology}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWhhhhhK7ubh)}(hEFirst, let us define some terms to avoid confusion in later sections.h]hEFirst, let us define some terms to avoid confusion in later sections.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjWhhubh)}(hhh](h)}(h(Physical) I2C Bus Controllerh]h(Physical) I2C Bus Controller}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjvhhhhhKhjvhhubeh}(h]physical-i2c-bus-controllerah ]h"](physical) i2c bus controllerah$]h&]uh1hhjWhhhhhK is a physical I2C bus, so it does not have the symbolic link }(hjhhhNhNubh)}(h``mux_device``h]h mux_device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXeOn 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.h]hXeOn 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h For example::h]h For example:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hu$ readlink /sys/bus/i2c/devices/i2c-73/device ../../i2c-7 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device ../7-0071h]hu$ readlink /sys/bus/i2c/devices/i2c-73/device ../../i2c-7 $ readlink /sys/bus/i2c/devices/i2c-73/mux_device ../7-0071}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(h``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.h](h)}(h ``i2c-73``h]hi2c-73}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh- is a logical bus fanout by an I2C MUX under }(hjhhhNhNubh)}(h ``i2c-7``h]hi2c-7}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h](distinguish-physical-and-logical-i2c-busah ]h"](distinguish physical and logical i2c busah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h"Finding out Logical I2C Bus Numberh]h"Finding out Logical I2C Bus Number}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hIn 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.h]hIn 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.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXKIn 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.h]hXKIn 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.}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h7First of all, let us go to the directory of ``i2c-7``::h](h,First of all, let us go to the directory of }(hjHhhhNhNubh)}(h ``i2c-7``h]hi2c-7}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHubh:}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h~$ 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 powerh]h~$ 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}hjhsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(h8There, we see the 0x71 MUX as ``7-0071``. Go inside it::h](hThere, we see the 0x71 MUX as }(hjvhhhNhNubh)}(h ``7-0071``h]h7-0071}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjvubh. Go inside it:}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h/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 ueventh]h/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}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(h=Read the link ``channel-1`` using ``readlink`` or ``ls -l``::h](hRead the link }(hjhhhNhNubh)}(h ``channel-1``h]h channel-1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh using }(hjhhhNhNubh)}(h ``readlink``h]hreadlink}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or }(hjhhhNhNubh)}(h ``ls -l``h]hls -l}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h?/sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1 ../i2c-73h]h?/sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1 ../i2c-73}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hWe 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::h](h.We find out that the channel 1 of 0x71 MUX on }(hjhhhNhNubh)}(h ``i2c-7``h]hi2c-7}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh[ is assigned with a logical I2C bus number of 73. Let us continue the journey to directory }(hjhhhNhNubh)}(h ``i2c-73``h]hi2c-73}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh in either ways:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hXi# 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$h]hXi# 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$}hj(sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hEither 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::h](h1Either ways, you will end up in the directory of }(hj6hhhNhNubh)}(h ``i2c-73``h]hi2c-73}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubhq. Similar to above, we can now find the 0x72 MUX and what logical I2C bus numbers that its channels are assigned:}(hj6hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX/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-81h]hX/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}hjVsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hThere, 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.h](hThere, 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 }(hjdhhhNhNubh)}(h ``i2c-tools``h]h i2c-tools}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdubh commands.}(hjdhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX8Tip: Once you understand the I2C topology with MUX, command `i2cdetect -l `_ in `I2C Tools `_ can give you an overview of the I2C topology easily, if it is available on your system. For example::h](h`_h]h i2cdetect -l}(hjhhhNhNubah}(h]h ]h"]h$]h&]name i2cdetect -lrefuriBhttps://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.htmluh1jhjubhtarget)}(hE h]h}(h] i2cdetect-lah ]h"] i2cdetect -lah$]h&]refurijuh1j referencedKhjubh in }(hjhhhNhNubj)}(h>`I2C Tools `_h]h I2C Tools}(hjhhhNhNubah}(h]h ]h"]h$]h&]name I2C Toolsj/https://i2c.wiki.kernel.org/index.php/I2C_Toolsuh1jhjubj)}(h2 h]h}(h] i2c-toolsah ]h"] i2c toolsah$]h&]refurijuh1jjKhjubhe can give you an overview of the I2C topology easily, if it is available on your system. For example:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX'$ 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 adapterh]hX'$ 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}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhM hjhhubeh}(h]"finding-out-logical-i2c-bus-numberah ]h"]"finding out logical i2c bus numberah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hPinned Logical I2C Bus Numberh]hPinned Logical I2C Bus Number}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXIf 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.h](hXIf 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 }(hjhhhNhNubh)}(h ``i2c-15``h]hi2c-15}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh^ as the highest logical bus number, and a 4-channel MUX is applied successfully, we will have }(hjhhhNhNubh)}(h ``i2c-16``h]hi2c-16}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh+ for the MUX channel 0, and all the way to }(hjhhhNhNubh)}(h ``i2c-19``h]hi2c-19}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh for the MUX channel 3.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXThe 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``h](hThe 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: }(hjGhhhNhNubh)}(h6``arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts``h]h2arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIn 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``.h](hIn 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 }(hjchhhNhNubh)}(h ``imux18``h]himux18}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjcubhB in DTS, and pinned to logical I2C bus number 18 with the line of }(hjchhhNhNubh)}(h``i2c18 = &imux18;``h]hi2c18 = &imux18;}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjcubh in section }(hjchhhNhNubh)}(h ``aliases``h]haliases}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjcubh.}(hjchhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM$hjhhubh)}(hXtTake 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.h]hXtTake 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hjhhubeh}(h]pinned-logical-i2c-bus-numberah ]h"]pinned logical i2c bus numberah$]h&]uh1hhjhhhhhMubeh}(h]walk-through-logical-i2c-busah ]h"]walk through logical i2c busah$]h&]uh1hhhhhhhhKqubh)}(hhh](h)}(h I2C Devicesh]h I2C Devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM0ubh)}(hXKIn 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.h](hIn 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 }(hjhhhNhNubh)}(h``${bus}-${addr}``h]h${bus}-${addr}}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. The }(hjhhhNhNubh)}(h ``${bus}``h]h${bus}}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhA part in the name is a logical I2C bus decimal number, while the }(hjhhhNhNubh)}(h ``${addr}``h]h${addr}}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh8 part is a hex number of the I2C address of each device.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM2hjhhubh)}(hhh](h)}(hI2C Device Directory Contenth]hI2C Device Directory Content}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM9ubh)}(hInside 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::h](h8Inside each I2C device directory, there is a file named }(hj+hhhNhNubh)}(h``name``h]hname}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+ubhg. This file tells what device name it was used for the kernel driver to probe this device. Use command }(hj+hhhNhNubh)}(h``cat``h]hcat}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+ubh" to read its content. For example:}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM;hjhhubj)}(h/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 pca9547h]h/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}hj]sbah}(h]h ]h"]h$]h&]hhuh1jhhhM?hjhhubh)}(hjThere is a symbolic link named ``driver`` to tell what Linux kernel driver was used to probe this device::h](hThere is a symbolic link named }(hjkhhhNhNubh)}(h ``driver``h]hdriver}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhjkubh@ to tell what Linux kernel driver was used to probe this device:}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMFhjhhubj)}(h/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/pca954xh]h/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}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMIhjhhubh)}(hBut 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``::h](hBut if the link }(hjhhhNhNubh)}(h ``driver``h]hdriver}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh 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 }(hjhhhNhNubh)}(h ``dmesg``h]hdmesg}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMNhjhhubj)}(h/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 failedh]h/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}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMRhjhhubh)}(hDepending 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.h]hDepending 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjhhubeh}(h]i2c-device-directory-contentah ]h"]i2c device directory contentah$]h&]uh1hhjhhhhhM9ubh)}(hhh](h)}(hI2C MUX Deviceh]hI2C MUX Device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM\ubh)}(hWhile 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::h](hgWhile you may be already aware of this in previous sections, an I2C MUX device will have symbolic link }(hj hhhNhNubh)}(h ``channel-*``h]h channel-*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh^ inside its device directory. These symbolic links point to their logical I2C bus directories:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM^hjhhubj)}(hX/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-85h]hX/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}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMbhjhhubeh}(h]i2c-mux-deviceah ]h"]i2c mux deviceah$]h&]uh1hhjhhhhhM\ubh)}(hhh](h)}(hI2C Sensor Device / Hwmonh]hI2C Sensor Device / Hwmon}(hj9 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6 hhhhhMmubh)}(hX 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::h](hI2C sensor device is also common to see. If they are bound by a kernel hwmon (Hardware Monitoring) driver successfully, you will see a }(hjG hhhNhNubh)}(h ``hwmon``h]hhwmon}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjG ubhz directory inside the I2C device directory. Keep digging into it, you will find the Hwmon Sysfs for the I2C sensor device:}(hjG hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMohj6 hhubj)}(hX/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_resistorh]hX/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}hjg sbah}(h]h ]h"]h$]h&]hhuh1jhhhMthj6 hhubh)}(h3For more info on the Hwmon Sysfs, refer to the doc:h]h3For more info on the Hwmon Sysfs, refer to the doc:}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hj6 hhubh)}(h../hwmon/sysfs-interface.rsth]h../hwmon/sysfs-interface.rst}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM~hj6 hhubeh}(h]i2c-sensor-device-hwmonah ]h"]i2c sensor device / hwmonah$]h&]uh1hhjhhhhhMmubh)}(hhh](h)}(h$Instantiate I2C Devices in I2C Sysfsh]h$Instantiate I2C Devices in I2C Sysfs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hURefer to section "Method 4: Instantiate from user-space" of instantiating-devices.rsth]hYRefer to section “Method 4: Instantiate from user-space” of instantiating-devices.rst}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]$instantiate-i2c-devices-in-i2c-sysfsah ]h"]$instantiate i2c devices in i2c sysfsah$]h&]uh1hhjhhhhhMubeh}(h] i2c-devicesah ]h"] i2c devicesah$]h&]uh1hhhhhhhhM0ubeh}(h]linux-i2c-sysfsah ]h"]linux i2c sysfsah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jjj6j3jjjTjQjjjjjjjjjAj>jjjjjjjjjjjjjjj j jjj3 j0 j j j j u nametypes}(j jj6jjTjjjjjAjjjjjjjj jj3 j j uh}(j hjhj3jjj9jQjjjWjjvjjjjj>jjjDjjjjjjjjjjjjj jjjj0 jj j6 j j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.