Documentation/admin-guide/sysfs-rules.rst

4 The kernel-exported sysfs exports internal kernel implementation details
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
21 - Do not use libsysfs
23     offer any abstraction, it exposes all the kernel driver-core
31 - sysfs is always at ``/sys``
38 - devices are only "devices"
39     There is no such thing like class-, bus-, physical devices,
41     just simply a "device". Class-, bus-, physical, ... types are just
47     - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
49       - identical to the DEVPATH value in the event sent from the kernel
51       - the unique key to the device at that point in time
52       - the kernel's path to the device directory without the leading
54       - all elements of a devpath must be real directories. Symlinks
59       - using or exposing symlink values as elements in a devpath string
62     - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)
64       - a directory name, identical to the last element of the devpath
65       - applications need to handle spaces and characters like ``!`` in
68     - subsystem (``block``, ``tty``, ``pci``, ...)
70       - simple string, never a path or a link
71       - retrieved by reading the "subsystem"-link and using only the
74     - driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
76       - a simple string, which may contain spaces, never a path or a
78       - it is retrieved by reading the "driver"-link and using only the
80       - devices which do not have "driver"-link just do not have a
84     - attributes
86       - the files in the device directory or files below subdirectories
88       - accessing attributes reached by a symlink pointing to another device,
89         like the "device"-link, is a bug in the application
91     Everything else is just a kernel driver-core implementation detail
94 - Properties of parent devices never belong into a child device.
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
102 - Hierarchy in a single device tree
108 - Classification by subsystem
132 - Block
134     ``/sys/subsystem/block`` will contain the links for disks and partitions
139 - "device"-link and <subsystem>:<kernel name>-links
140     Never depend on the "device"-link. The "device"-link is a workaround
142     ``/sys/devices/`` like the bus devices. If the link-resolving of a
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
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
153     directory does not contain directories for child devices, these links
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
160     It is planned to remove all these links when all class device
163 - Position of devices along device chain can change.
172 - When reading and writing sysfs device attribute files, avoid dependency
180 	``-EIO``: The read or store operation is not supported, typically
184 	``-ENXIO``: The read or store operation failed
187     to error codes result in user-space breakage, it will be fixed, or the