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