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
77         link
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
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``
154     may be used to find the child devices in ``/sys/class.`` That is the single
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