0001 Rules on how to access information in sysfs
0002 ===========================================
0003
0004 The kernel-exported sysfs exports internal kernel implementation details
0005 and depends on internal kernel structures and layout. It is agreed upon
0006 by the kernel developers that the Linux kernel does not provide a stable
0007 internal API. Therefore, there are aspects of the sysfs interface that
0008 may not be stable across kernel releases.
0009
0010 To minimize the risk of breaking users of sysfs, which are in most cases
0011 low-level userspace applications, with a new kernel release, the users
0012 of sysfs must follow some rules to use an as-abstract-as-possible way to
0013 access this filesystem. The current udev and HAL programs already
0014 implement this and users are encouraged to plug, if possible, into the
0015 abstractions these programs provide instead of accessing sysfs directly.
0016
0017 But if you really do want or need to access sysfs directly, please follow
0018 the following rules and then your programs should work with future
0019 versions of the sysfs interface.
0020
0021 - Do not use libsysfs
0022 It makes assumptions about sysfs which are not true. Its API does not
0023 offer any abstraction, it exposes all the kernel driver-core
0024 implementation details in its own API. Therefore it is not better than
0025 reading directories and opening the files yourself.
0026 Also, it is not actively maintained, in the sense of reflecting the
0027 current kernel development. The goal of providing a stable interface
0028 to sysfs has failed; it causes more problems than it solves. It
0029 violates many of the rules in this document.
0030
0031 - sysfs is always at ``/sys``
0032 Parsing ``/proc/mounts`` is a waste of time. Other mount points are a
0033 system configuration bug you should not try to solve. For test cases,
0034 possibly support a ``SYSFS_PATH`` environment variable to overwrite the
0035 application's behavior, but never try to search for sysfs. Never try
0036 to mount it, if you are not an early boot script.
0037
0038 - devices are only "devices"
0039 There is no such thing like class-, bus-, physical devices,
0040 interfaces, and such that you can rely on in userspace. Everything is
0041 just simply a "device". Class-, bus-, physical, ... types are just
0042 kernel implementation details which should not be expected by
0043 applications that look for devices in sysfs.
0044
0045 The properties of a device are:
0046
0047 - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
0048
0049 - identical to the DEVPATH value in the event sent from the kernel
0050 at device creation and removal
0051 - the unique key to the device at that point in time
0052 - the kernel's path to the device directory without the leading
0053 ``/sys``, and always starting with a slash
0054 - all elements of a devpath must be real directories. Symlinks
0055 pointing to /sys/devices must always be resolved to their real
0056 target and the target path must be used to access the device.
0057 That way the devpath to the device matches the devpath of the
0058 kernel used at event time.
0059 - using or exposing symlink values as elements in a devpath string
0060 is a bug in the application
0061
0062 - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)
0063
0064 - a directory name, identical to the last element of the devpath
0065 - applications need to handle spaces and characters like ``!`` in
0066 the name
0067
0068 - subsystem (``block``, ``tty``, ``pci``, ...)
0069
0070 - simple string, never a path or a link
0071 - retrieved by reading the "subsystem"-link and using only the
0072 last element of the target path
0073
0074 - driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
0075
0076 - a simple string, which may contain spaces, never a path or a
0077 link
0078 - it is retrieved by reading the "driver"-link and using only the
0079 last element of the target path
0080 - devices which do not have "driver"-link just do not have a
0081 driver; copying the driver value in a child device context is a
0082 bug in the application
0083
0084 - attributes
0085
0086 - the files in the device directory or files below subdirectories
0087 of the same device directory
0088 - accessing attributes reached by a symlink pointing to another device,
0089 like the "device"-link, is a bug in the application
0090
0091 Everything else is just a kernel driver-core implementation detail
0092 that should not be assumed to be stable across kernel releases.
0093
0094 - Properties of parent devices never belong into a child device.
0095 Always look at the parent devices themselves for determining device
0096 context properties. If the device ``eth0`` or ``sda`` does not have a
0097 "driver"-link, then this device does not have a driver. Its value is empty.
0098 Never copy any property of the parent-device into a child-device. Parent
0099 device properties may change dynamically without any notice to the
0100 child device.
0101
0102 - Hierarchy in a single device tree
0103 There is only one valid place in sysfs where hierarchy can be examined
0104 and this is below: ``/sys/devices.``
0105 It is planned that all device directories will end up in the tree
0106 below this directory.
0107
0108 - Classification by subsystem
0109 There are currently three places for classification of devices:
0110 ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will
0111 not contain any device directories themselves, but only flat lists of
0112 symlinks pointing to the unified ``/sys/devices`` tree.
0113 All three places have completely different rules on how to access
0114 device information. It is planned to merge all three
0115 classification directories into one place at ``/sys/subsystem``,
0116 following the layout of the bus directories. All buses and
0117 classes, including the converted block subsystem, will show up
0118 there.
0119 The devices belonging to a subsystem will create a symlink in the
0120 "devices" directory at ``/sys/subsystem/<name>/devices``,
0121
0122 If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block``
0123 can be ignored. If it does not exist, you always have to scan all three
0124 places, as the kernel is free to move a subsystem from one place to
0125 the other, as long as the devices are still reachable by the same
0126 subsystem name.
0127
0128 Assuming ``/sys/class/<subsystem>`` and ``/sys/bus/<subsystem>``, or
0129 ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in
0130 the application.
0131
0132 - Block
0133 The converted block subsystem at ``/sys/class/block`` or
0134 ``/sys/subsystem/block`` will contain the links for disks and partitions
0135 at the same level, never in a hierarchy. Assuming the block subsystem to
0136 contain only disks and not partition devices in the same flat list is
0137 a bug in the application.
0138
0139 - "device"-link and <subsystem>:<kernel name>-links
0140 Never depend on the "device"-link. The "device"-link is a workaround
0141 for the old layout, where class devices are not created in
0142 ``/sys/devices/`` like the bus devices. If the link-resolving of a
0143 device directory does not end in ``/sys/devices/``, you can use the
0144 "device"-link to find the parent devices in ``/sys/devices/``, That is the
0145 single valid use of the "device"-link; it must never appear in any
0146 path as an element. Assuming the existence of the "device"-link for
0147 a device in ``/sys/devices/`` is a bug in the application.
0148 Accessing ``/sys/class/net/eth0/device`` is a bug in the application.
0149
0150 Never depend on the class-specific links back to the ``/sys/class``
0151 directory. These links are also a workaround for the design mistake
0152 that class devices are not created in ``/sys/devices.`` If a device
0153 directory does not contain directories for child devices, these links
0154 may be used to find the child devices in ``/sys/class.`` That is the single
0155 valid use of these links; they must never appear in any path as an
0156 element. Assuming the existence of these links for devices which are
0157 real child device directories in the ``/sys/devices`` tree is a bug in
0158 the application.
0159
0160 It is planned to remove all these links when all class device
0161 directories live in ``/sys/devices.``
0162
0163 - Position of devices along device chain can change.
0164 Never depend on a specific parent device position in the devpath,
0165 or the chain of parent devices. The kernel is free to insert devices into
0166 the chain. You must always request the parent device you are looking for
0167 by its subsystem value. You need to walk up the chain until you find
0168 the device that matches the expected subsystem. Depending on a specific
0169 position of a parent device or exposing relative paths using ``../`` to
0170 access the chain of parents is a bug in the application.
0171
0172 - When reading and writing sysfs device attribute files, avoid dependency
0173 on specific error codes wherever possible. This minimizes coupling to
0174 the error handling implementation within the kernel.
0175
0176 In general, failures to read or write sysfs device attributes shall
0177 propagate errors wherever possible. Common errors include, but are not
0178 limited to:
0179
0180 ``-EIO``: The read or store operation is not supported, typically
0181 returned by the sysfs system itself if the read or store pointer
0182 is ``NULL``.
0183
0184 ``-ENXIO``: The read or store operation failed
0185
0186 Error codes will not be changed without good reason, and should a change
0187 to error codes result in user-space breakage, it will be fixed, or the
0188 the offending change will be reverted.
0189
0190 Userspace applications can, however, expect the format and contents of
0191 the attribute files to remain consistent in the absence of a version
0192 attribute change in the context of a given attribute.
