^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) Rules on how to access information in sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ===========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) The kernel-exported sysfs exports internal kernel implementation details
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) and depends on internal kernel structures and layout. It is agreed upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) by the kernel developers that the Linux kernel does not provide a stable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) internal API. Therefore, there are aspects of the sysfs interface that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) may not be stable across kernel releases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) To minimize the risk of breaking users of sysfs, which are in most cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) low-level userspace applications, with a new kernel release, the users
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) of sysfs must follow some rules to use an as-abstract-as-possible way to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) access this filesystem. The current udev and HAL programs already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) implement this and users are encouraged to plug, if possible, into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) abstractions these programs provide instead of accessing sysfs directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) But if you really do want or need to access sysfs directly, please follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) the following rules and then your programs should work with future
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) versions of the sysfs interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) - Do not use libsysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) It makes assumptions about sysfs which are not true. Its API does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) offer any abstraction, it exposes all the kernel driver-core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) implementation details in its own API. Therefore it is not better than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) reading directories and opening the files yourself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Also, it is not actively maintained, in the sense of reflecting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) current kernel development. The goal of providing a stable interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) to sysfs has failed; it causes more problems than it solves. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) violates many of the rules in this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) - sysfs is always at ``/sys``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Parsing ``/proc/mounts`` is a waste of time. Other mount points are a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) system configuration bug you should not try to solve. For test cases,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) possibly support a ``SYSFS_PATH`` environment variable to overwrite the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) application's behavior, but never try to search for sysfs. Never try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) to mount it, if you are not an early boot script.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) - devices are only "devices"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) There is no such thing like class-, bus-, physical devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) interfaces, and such that you can rely on in userspace. Everything is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) just simply a "device". Class-, bus-, physical, ... types are just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) kernel implementation details which should not be expected by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) applications that look for devices in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The properties of a device are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - identical to the DEVPATH value in the event sent from the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) at device creation and removal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) - the unique key to the device at that point in time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - the kernel's path to the device directory without the leading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) ``/sys``, and always starting with a slash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) - all elements of a devpath must be real directories. Symlinks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) pointing to /sys/devices must always be resolved to their real
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) target and the target path must be used to access the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) That way the devpath to the device matches the devpath of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) kernel used at event time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) - using or exposing symlink values as elements in a devpath string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) is a bug in the application
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - a directory name, identical to the last element of the devpath
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) - applications need to handle spaces and characters like ``!`` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) the name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) - subsystem (``block``, ``tty``, ``pci``, ...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) - simple string, never a path or a link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) - retrieved by reading the "subsystem"-link and using only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) last element of the target path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) - driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) - a simple string, which may contain spaces, never a path or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) - it is retrieved by reading the "driver"-link and using only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) last element of the target path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) - devices which do not have "driver"-link just do not have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) driver; copying the driver value in a child device context is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) bug in the application
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) - attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) - the files in the device directory or files below subdirectories
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) of the same device directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) - accessing attributes reached by a symlink pointing to another device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) like the "device"-link, is a bug in the application
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Everything else is just a kernel driver-core implementation detail
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) that should not be assumed to be stable across kernel releases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) - Properties of parent devices never belong into a child device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) Always look at the parent devices themselves for determining device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) context properties. If the device ``eth0`` or ``sda`` does not have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) "driver"-link, then this device does not have a driver. Its value is empty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Never copy any property of the parent-device into a child-device. Parent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) device properties may change dynamically without any notice to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) child device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - Hierarchy in a single device tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) There is only one valid place in sysfs where hierarchy can be examined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) and this is below: ``/sys/devices.``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) It is planned that all device directories will end up in the tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) below this directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) - Classification by subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) There are currently three places for classification of devices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) not contain any device directories themselves, but only flat lists of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) symlinks pointing to the unified ``/sys/devices`` tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) All three places have completely different rules on how to access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) device information. It is planned to merge all three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) classification directories into one place at ``/sys/subsystem``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) following the layout of the bus directories. All buses and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) classes, including the converted block subsystem, will show up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) The devices belonging to a subsystem will create a symlink in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) "devices" directory at ``/sys/subsystem/<name>/devices``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) can be ignored. If it does not exist, you always have to scan all three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) places, as the kernel is free to move a subsystem from one place to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) the other, as long as the devices are still reachable by the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) subsystem name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Assuming ``/sys/class/<subsystem>`` and ``/sys/bus/<subsystem>``, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) - Block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) The converted block subsystem at ``/sys/class/block`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) ``/sys/subsystem/block`` will contain the links for disks and partitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) at the same level, never in a hierarchy. Assuming the block subsystem to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) contain only disks and not partition devices in the same flat list is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) a bug in the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) - "device"-link and <subsystem>:<kernel name>-links
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Never depend on the "device"-link. The "device"-link is a workaround
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) for the old layout, where class devices are not created in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) ``/sys/devices/`` like the bus devices. If the link-resolving of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) device directory does not end in ``/sys/devices/``, you can use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) "device"-link to find the parent devices in ``/sys/devices/``, That is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) single valid use of the "device"-link; it must never appear in any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) path as an element. Assuming the existence of the "device"-link for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) a device in ``/sys/devices/`` is a bug in the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Accessing ``/sys/class/net/eth0/device`` is a bug in the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Never depend on the class-specific links back to the ``/sys/class``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) directory. These links are also a workaround for the design mistake
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) that class devices are not created in ``/sys/devices.`` If a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) directory does not contain directories for child devices, these links
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) may be used to find the child devices in ``/sys/class.`` That is the single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) valid use of these links; they must never appear in any path as an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) element. Assuming the existence of these links for devices which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) real child device directories in the ``/sys/devices`` tree is a bug in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) It is planned to remove all these links when all class device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) directories live in ``/sys/devices.``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) - Position of devices along device chain can change.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Never depend on a specific parent device position in the devpath,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) or the chain of parent devices. The kernel is free to insert devices into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) the chain. You must always request the parent device you are looking for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) by its subsystem value. You need to walk up the chain until you find
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) the device that matches the expected subsystem. Depending on a specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) position of a parent device or exposing relative paths using ``../`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) access the chain of parents is a bug in the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) - When reading and writing sysfs device attribute files, avoid dependency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) on specific error codes wherever possible. This minimizes coupling to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) the error handling implementation within the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) In general, failures to read or write sysfs device attributes shall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) propagate errors wherever possible. Common errors include, but are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) limited to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ``-EIO``: The read or store operation is not supported, typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) returned by the sysfs system itself if the read or store pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) is ``NULL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ``-ENXIO``: The read or store operation failed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Error codes will not be changed without good reason, and should a change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) to error codes result in user-space breakage, it will be fixed, or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) the offending change will be reverted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Userspace applications can, however, expect the format and contents of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) the attribute files to remain consistent in the absence of a version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) attribute change in the context of a given attribute.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags