Commit | Line | Data |
---|---|---|
31df7195 AQ |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | =============== | |
4 | Linux I2C Sysfs | |
5 | =============== | |
6 | ||
7 | Overview | |
8 | ======== | |
9 | ||
10 | I2C topology can be complex because of the existence of I2C MUX | |
11 | (I2C Multiplexer). The Linux | |
12 | kernel abstracts the MUX channels into logical I2C bus numbers. However, there | |
13 | is a gap of knowledge to map from the I2C bus physical number and MUX topology | |
14 | to logical I2C bus number. This doc is aimed to fill in this gap, so the | |
15 | audience (hardware engineers and new software developers for example) can learn | |
16 | the concept of logical I2C buses in the kernel, by knowing the physical I2C | |
17 | topology and navigating through the I2C sysfs in Linux shell. This knowledge is | |
18 | useful and essential to use ``i2c-tools`` for the purpose of development and | |
19 | debugging. | |
20 | ||
21 | Target audience | |
22 | --------------- | |
23 | ||
24 | People who need to use Linux shell to interact with I2C subsystem on a system | |
25 | which the Linux is running on. | |
26 | ||
27 | Prerequisites | |
28 | ------------- | |
29 | ||
30 | 1. Knowledge of general Linux shell file system commands and operations. | |
31 | ||
32 | 2. General knowledge of I2C, I2C MUX and I2C topology. | |
33 | ||
34 | Location of I2C Sysfs | |
35 | ===================== | |
36 | ||
37 | Typically, the Linux Sysfs filesystem is mounted at the ``/sys`` directory, | |
38 | so you can find the I2C Sysfs under ``/sys/bus/i2c/devices`` | |
39 | where you can directly ``cd`` to it. | |
40 | There is a list of symbolic links under that directory. The links that | |
41 | start with ``i2c-`` are I2C buses, which may be either physical or logical. The | |
42 | other links that begin with numbers and end with numbers are I2C devices, where | |
43 | the first number is I2C bus number, and the second number is I2C address. | |
44 | ||
45 | Google 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 | |
52 | on bus 2 address 0x49 bound with a kernel driver. | |
53 | ||
55bdfb8b LC |
54 | Terminology |
55 | =========== | |
31df7195 | 56 | |
55bdfb8b | 57 | First, let us define some terms to avoid confusion in later sections. |
31df7195 AQ |
58 | |
59 | (Physical) I2C Bus Controller | |
60 | ----------------------------- | |
61 | ||
62 | The hardware system that the Linux kernel is running on may have multiple | |
63 | physical I2C bus controllers. The controllers are hardware and physical, and the | |
64 | system may define multiple registers in the memory space to manipulate the | |
65 | controllers. Linux kernel has I2C bus drivers under source directory | |
66 | ``drivers/i2c/busses`` to translate kernel I2C API into register | |
67 | operations for different systems. This terminology is not limited to Linux | |
68 | kernel only. | |
69 | ||
70 | I2C Bus Physical Number | |
71 | ----------------------- | |
72 | ||
73 | For each physical I2C bus controller, the system vendor may assign a physical | |
74 | number to each controller. For example, the first I2C bus controller which has | |
75 | the lowest register addresses may be called ``I2C-0``. | |
76 | ||
77 | Logical I2C Bus | |
78 | --------------- | |
79 | ||
80 | Every I2C bus number you see in Linux I2C Sysfs is a logical I2C bus with a | |
81 | number assigned. This is similar to the fact that software code is usually | |
82 | written upon virtual memory space, instead of physical memory space. | |
83 | ||
84 | Each logical I2C bus may be an abstraction of a physical I2C bus controller, or | |
85 | an abstraction of a channel behind an I2C MUX. In case it is an abstraction of a | |
86 | MUX channel, whenever we access an I2C device via a such logical bus, the kernel | |
87 | will switch the I2C MUX for you to the proper channel as part of the | |
88 | abstraction. | |
89 | ||
90 | Physical I2C Bus | |
91 | ---------------- | |
92 | ||
93 | If the logical I2C bus is a direct abstraction of a physical I2C bus controller, | |
94 | let us call it a physical I2C bus. | |
95 | ||
96 | Caveat | |
97 | ------ | |
98 | ||
99 | This may be a confusing part for people who only know about the physical I2C | |
100 | design of a board. It is actually possible to rename the I2C bus physical number | |
101 | to a different number in logical I2C bus level in Device Tree Source (DTS) under | |
fe99b819 | 102 | section ``aliases``. See ``arch/arm/boot/dts/nuvoton-npcm730-gsj.dts`` |
31df7195 AQ |
103 | for an example of DTS file. |
104 | ||
105 | Best Practice: **(To kernel software developers)** It is better to keep the I2C | |
106 | bus physical number the same as their corresponding logical I2C bus number, | |
107 | instead of renaming or mapping them, so that it may be less confusing to other | |
108 | users. These physical I2C buses can be served as good starting points for I2C | |
109 | MUX fanouts. For the following examples, we will assume that the physical I2C | |
110 | bus has a number same as their I2C bus physical number. | |
111 | ||
112 | Walk through Logical I2C Bus | |
113 | ============================ | |
114 | ||
115 | For the following content, we will use a more complex I2C topology as an | |
116 | example. Here is a brief graph for the I2C topology. If you do not understand | |
55bdfb8b | 117 | this graph at first glance, do not be afraid to continue reading this doc |
31df7195 AQ |
118 | and 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 | ||
135 | Distinguish Physical and Logical I2C Bus | |
136 | ---------------------------------------- | |
137 | ||
138 | One simple way to distinguish between a physical I2C bus and a logical I2C bus, | |
139 | is to read the symbolic link ``device`` under the I2C bus directory by using | |
140 | command ``ls -l`` or ``readlink``. | |
141 | ||
142 | An alternative symbolic link to check is ``mux_device``. This link only exists | |
143 | in logical I2C bus directory which is fanned out from another I2C bus. | |
144 | Reading this link will also tell you which I2C MUX device created | |
145 | this logical I2C bus. | |
146 | ||
147 | If the symbolic link points to a directory ending with ``.i2c``, it should be a | |
148 | physical I2C bus, directly abstracting a physical I2C bus controller. For | |
149 | example:: | |
150 | ||
151 | $ readlink /sys/bus/i2c/devices/i2c-7/device | |
152 | ../../f0087000.i2c | |
153 | $ ls /sys/bus/i2c/devices/i2c-7/mux_device | |
154 | ls: /sys/bus/i2c/devices/i2c-7/mux_device: No such file or directory | |
155 | ||
156 | In this case, ``i2c-7`` is a physical I2C bus, so it does not have the symbolic | |
157 | link ``mux_device`` under its directory. And if the kernel software developer | |
158 | follows the common practice by not renaming physical I2C buses, this should also | |
159 | mean the physical I2C bus controller 7 of the system. | |
160 | ||
161 | On the other hand, if the symbolic link points to another I2C bus, the I2C bus | |
162 | presented by the current directory has to be a logical bus. The I2C bus pointed | |
163 | by the link is the parent bus which may be either a physical I2C bus or a | |
164 | logical one. In this case, the I2C bus presented by the current directory | |
165 | abstracts an I2C MUX channel under the parent bus. | |
166 | ||
167 | For example:: | |
168 | ||
169 | $ readlink /sys/bus/i2c/devices/i2c-73/device | |
170 | ../../i2c-7 | |
171 | $ readlink /sys/bus/i2c/devices/i2c-73/mux_device | |
172 | ../7-0071 | |
173 | ||
174 | ``i2c-73`` is a logical bus fanout by an I2C MUX under ``i2c-7`` | |
175 | whose I2C address is 0x71. | |
176 | Whenever we access an I2C device with bus 73, the kernel will always | |
177 | switch the I2C MUX addressed 0x71 to the proper channel for you as part of the | |
178 | abstraction. | |
179 | ||
180 | Finding out Logical I2C Bus Number | |
181 | ---------------------------------- | |
182 | ||
183 | In this section, we will describe how to find out the logical I2C bus number | |
184 | representing certain I2C MUX channels based on the knowledge of physical | |
185 | hardware I2C topology. | |
186 | ||
187 | In this example, we have a system which has a physical I2C bus 7 and not renamed | |
188 | in DTS. There is a 4-channel MUX at address 0x71 on that bus. There is another | |
189 | 8-channel MUX at address 0x72 behind the channel 1 of the 0x71 MUX. Let us | |
190 | navigate through Sysfs and find out the logical I2C bus number of the channel 3 | |
191 | of the 0x72 MUX. | |
192 | ||
193 | First of all, let us go to the directory of ``i2c-7``:: | |
194 | ||
195 | ~$ cd /sys/bus/i2c/devices/i2c-7 | |
196 | /sys/bus/i2c/devices/i2c-7$ ls | |
197 | 7-0071 i2c-60 name subsystem | |
198 | delete_device i2c-73 new_device uevent | |
199 | device i2c-86 of_node | |
200 | i2c-203 i2c-dev power | |
201 | ||
202 | There, 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 -l | |
206 | channel-0 channel-3 modalias power | |
207 | channel-1 driver name subsystem | |
208 | channel-2 idle_state of_node uevent | |
209 | ||
210 | Read the link ``channel-1`` using ``readlink`` or ``ls -l``:: | |
211 | ||
212 | /sys/bus/i2c/devices/i2c-7/7-0071$ readlink channel-1 | |
213 | ../i2c-73 | |
214 | ||
215 | We find out that the channel 1 of 0x71 MUX on ``i2c-7`` is assigned | |
216 | with a logical I2C bus number of 73. | |
217 | Let us continue the journey to directory ``i2c-73`` in either ways:: | |
218 | ||
219 | # cd to i2c-73 under I2C Sysfs root | |
220 | /sys/bus/i2c/devices/i2c-7/7-0071$ cd /sys/bus/i2c/devices/i2c-73 | |
221 | /sys/bus/i2c/devices/i2c-73$ | |
222 | ||
223 | # cd the channel symbolic link | |
224 | /sys/bus/i2c/devices/i2c-7/7-0071$ cd channel-1 | |
225 | /sys/bus/i2c/devices/i2c-7/7-0071/channel-1$ | |
226 | ||
227 | # cd the link content | |
228 | /sys/bus/i2c/devices/i2c-7/7-0071$ cd ../i2c-73 | |
229 | /sys/bus/i2c/devices/i2c-7/i2c-73$ | |
230 | ||
231 | Either ways, you will end up in the directory of ``i2c-73``. Similar to above, | |
232 | we can now find the 0x72 MUX and what logical I2C bus numbers | |
233 | that its channels are assigned:: | |
234 | ||
235 | /sys/bus/i2c/devices/i2c-73$ ls | |
236 | 73-0040 device i2c-83 new_device | |
237 | 73-004e i2c-78 i2c-84 of_node | |
238 | 73-0050 i2c-79 i2c-85 power | |
239 | 73-0070 i2c-80 i2c-dev subsystem | |
240 | 73-0072 i2c-81 mux_device uevent | |
241 | delete_device i2c-82 name | |
242 | /sys/bus/i2c/devices/i2c-73$ cd 73-0072 | |
243 | /sys/bus/i2c/devices/i2c-73/73-0072$ ls | |
244 | channel-0 channel-4 driver of_node | |
245 | channel-1 channel-5 idle_state power | |
246 | channel-2 channel-6 modalias subsystem | |
247 | channel-3 channel-7 name uevent | |
248 | /sys/bus/i2c/devices/i2c-73/73-0072$ readlink channel-3 | |
249 | ../i2c-81 | |
250 | ||
251 | There, we find out the logical I2C bus number of the channel 3 of the 0x72 MUX | |
252 | is 81. We can later use this number to switch to its own I2C Sysfs directory or | |
253 | issue ``i2c-tools`` commands. | |
254 | ||
255 | Tip: Once you understand the I2C topology with MUX, command | |
256 | `i2cdetect -l | |
257 | <https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html>`_ | |
258 | in | |
259 | `I2C Tools | |
260 | <https://i2c.wiki.kernel.org/index.php/I2C_Tools>`_ | |
261 | can give you | |
262 | an overview of the I2C topology easily, if it is available on your system. For | |
263 | example:: | |
264 | ||
265 | $ i2cdetect -l | grep -e '\-73' -e _7 | sort -V | |
266 | i2c-7 i2c npcm_i2c_7 I2C adapter | |
267 | i2c-73 i2c i2c-7-mux (chan_id 1) I2C adapter | |
268 | i2c-78 i2c i2c-73-mux (chan_id 0) I2C adapter | |
269 | i2c-79 i2c i2c-73-mux (chan_id 1) I2C adapter | |
270 | i2c-80 i2c i2c-73-mux (chan_id 2) I2C adapter | |
271 | i2c-81 i2c i2c-73-mux (chan_id 3) I2C adapter | |
272 | i2c-82 i2c i2c-73-mux (chan_id 4) I2C adapter | |
273 | i2c-83 i2c i2c-73-mux (chan_id 5) I2C adapter | |
274 | i2c-84 i2c i2c-73-mux (chan_id 6) I2C adapter | |
275 | i2c-85 i2c i2c-73-mux (chan_id 7) I2C adapter | |
276 | ||
277 | Pinned Logical I2C Bus Number | |
278 | ----------------------------- | |
279 | ||
280 | If not specified in DTS, when an I2C MUX driver is applied and the MUX device is | |
281 | successfully probed, the kernel will assign the MUX channels with a logical bus | |
282 | number based on the current biggest logical bus number incrementally. For | |
283 | example, if the system has ``i2c-15`` as the highest logical bus number, and a | |
284 | 4-channel MUX is applied successfully, we will have ``i2c-16`` for the | |
285 | MUX channel 0, and all the way to ``i2c-19`` for the MUX channel 3. | |
286 | ||
287 | The kernel software developer is able to pin the fanout MUX channels to a static | |
288 | logical I2C bus number in the DTS. This doc will not go through the details on | |
289 | how to implement this in DTS, but we can see an example in: | |
fe99b819 | 290 | ``arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts`` |
31df7195 AQ |
291 | |
292 | In the above example, there is an 8-channel I2C MUX at address 0x70 on physical | |
293 | I2C bus 2. The channel 2 of the MUX is defined as ``imux18`` in DTS, | |
294 | and pinned to logical I2C bus number 18 with the line of ``i2c18 = &imux18;`` | |
295 | in section ``aliases``. | |
296 | ||
297 | Take it further, it is possible to design a logical I2C bus number schema that | |
298 | can be easily remembered by humans or calculated arithmetically. For example, we | |
299 | can pin the fanout channels of a MUX on bus 3 to start at 30. So 30 will be the | |
300 | logical bus number of the channel 0 of the MUX on bus 3, and 37 will be the | |
301 | logical bus number of the channel 7 of the MUX on bus 3. | |
302 | ||
303 | I2C Devices | |
304 | =========== | |
305 | ||
306 | In previous sections, we mostly covered the I2C bus. In this section, let us see | |
307 | what we can learn from the I2C device directory whose link name is in the format | |
308 | of ``${bus}-${addr}``. The ``${bus}`` part in the name is a logical I2C bus | |
309 | decimal number, while the ``${addr}`` part is a hex number of the I2C address | |
310 | of each device. | |
311 | ||
312 | I2C Device Directory Content | |
313 | ---------------------------- | |
314 | ||
315 | Inside each I2C device directory, there is a file named ``name``. | |
316 | This file tells what device name it was used for the kernel driver to | |
317 | probe this device. Use command ``cat`` to read its content. For example:: | |
318 | ||
319 | /sys/bus/i2c/devices/i2c-73$ cat 73-0040/name | |
320 | ina230 | |
321 | /sys/bus/i2c/devices/i2c-73$ cat 73-0070/name | |
322 | pca9546 | |
323 | /sys/bus/i2c/devices/i2c-73$ cat 73-0072/name | |
324 | pca9547 | |
325 | ||
326 | There is a symbolic link named ``driver`` to tell what Linux kernel driver was | |
327 | used to probe this device:: | |
328 | ||
329 | /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0040/driver | |
330 | /sys/bus/i2c/drivers/ina2xx | |
331 | /sys/bus/i2c/devices/i2c-73$ readlink -f 73-0072/driver | |
332 | /sys/bus/i2c/drivers/pca954x | |
333 | ||
334 | But if the link ``driver`` does not exist at the first place, | |
335 | it may mean that the kernel driver failed to probe this device due to | |
336 | some errors. The error may be found in ``dmesg``:: | |
337 | ||
338 | /sys/bus/i2c/devices/i2c-73$ ls 73-0070/driver | |
339 | ls: 73-0070/driver: No such file or directory | |
340 | /sys/bus/i2c/devices/i2c-73$ dmesg | grep 73-0070 | |
341 | pca954x 73-0070: probe failed | |
342 | pca954x 73-0070: probe failed | |
343 | ||
344 | Depending on what the I2C device is and what kernel driver was used to probe the | |
345 | device, we may have different content in the device directory. | |
346 | ||
347 | I2C MUX Device | |
348 | -------------- | |
349 | ||
350 | While you may be already aware of this in previous sections, an I2C MUX device | |
351 | will have symbolic link ``channel-*`` inside its device directory. | |
352 | These 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-78 | |
356 | lrwxrwxrwx ... 73-0072/channel-1 -> ../i2c-79 | |
357 | lrwxrwxrwx ... 73-0072/channel-2 -> ../i2c-80 | |
358 | lrwxrwxrwx ... 73-0072/channel-3 -> ../i2c-81 | |
359 | lrwxrwxrwx ... 73-0072/channel-4 -> ../i2c-82 | |
360 | lrwxrwxrwx ... 73-0072/channel-5 -> ../i2c-83 | |
361 | lrwxrwxrwx ... 73-0072/channel-6 -> ../i2c-84 | |
362 | lrwxrwxrwx ... 73-0072/channel-7 -> ../i2c-85 | |
363 | ||
364 | I2C Sensor Device / Hwmon | |
365 | ------------------------- | |
366 | ||
367 | I2C sensor device is also common to see. If they are bound by a kernel hwmon | |
368 | (Hardware Monitoring) driver successfully, you will see a ``hwmon`` directory | |
369 | inside the I2C device directory. Keep digging into it, you will find the Hwmon | |
370 | Sysfs for the I2C sensor device:: | |
371 | ||
372 | /sys/bus/i2c/devices/i2c-73/73-0040/hwmon/hwmon17$ ls | |
373 | curr1_input in0_lcrit_alarm name subsystem | |
374 | device in1_crit power uevent | |
375 | in0_crit in1_crit_alarm power1_crit update_interval | |
376 | in0_crit_alarm in1_input power1_crit_alarm | |
377 | in0_input in1_lcrit power1_input | |
378 | in0_lcrit in1_lcrit_alarm shunt_resistor | |
379 | ||
380 | For more info on the Hwmon Sysfs, refer to the doc: | |
381 | ||
fe99b819 | 382 | ../hwmon/sysfs-interface.rst |
31df7195 AQ |
383 | |
384 | Instantiate I2C Devices in I2C Sysfs | |
385 | ------------------------------------ | |
386 | ||
fe99b819 | 387 | Refer to section "Method 4: Instantiate from user-space" of instantiating-devices.rst |