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