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``
35     application's behavior, but never try to search for sysfs. Never try
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
60         is a bug in the application
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
82         bug in the application
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
130     the application.
132 - Block
137     a bug in the application.
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
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.
150     Never depend on the class-specific links back to the ``/sys/class``
158     the application.
163 - Position of devices along device chain can change.
164     Never depend on a specific parent device position in the devpath,
168     the device that matches the expected subsystem. Depending on a specific
170     access the chain of parents is a bug in the application.
172 - When reading and writing sysfs device attribute files, avoid dependency
173     on specific error codes wherever possible. This minimizes coupling to
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