Documentation/admin-guide/sysfs-rules.rst

   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.