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
115     classification directories into one place at ``/sys/subsystem``,
117     classes, including the converted block subsystem, will show up
119     The devices belonging to a subsystem will create a symlink in the
120     "devices" directory at ``/sys/subsystem/<name>/devices``,
122     If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block``
124     places, as the kernel is free to move a subsystem from one place to
126     subsystem name.
128     Assuming ``/sys/class/<subsystem>`` and ``/sys/bus/<subsystem>``, or
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
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``
163 - Position of devices along device chain can change.
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
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