Documentation/i2c/i2c-sysfs.rst

   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
  54 Terminology
  55 ===========
  56
  57 First, let us define some terms to avoid confusion in later sections.
  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
 102 section ``aliases``. See ``arch/arm/boot/dts/nuvoton-npcm730-gsj.dts``
 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
 117 this graph at first glance, do not be afraid to continue reading this doc
 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:
 290 ``arch/arm/boot/dts/aspeed-bmc-facebook-wedge400.dts``
 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
 382 ../hwmon/sysfs-interface.rst
 383
 384 Instantiate I2C Devices in I2C Sysfs
 385 ------------------------------------
 386
 387 Refer to section "Method 4: Instantiate from user-space" of instantiating-devices.rst