Lines Matching +full:in +full:- +full:application

1 Rules on how to access information in sysfs
4 The kernel-exported sysfs exports internal kernel implementation details
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
21 - Do not use libsysfs
23 offer any abstraction, it exposes all the kernel driver-core
24 implementation details in its own API. Therefore it is not better than
26 Also, it is not actively maintained, in the sense of reflecting the
29 violates many of the rules in this document.
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,
40 interfaces, and such that you can rely on in userspace. Everything is
41 just simply a "device". Class-, bus-, physical, ... types are just
43 applications that look for devices in sysfs.
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
81 driver; copying the driver value in a child device context is 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
103 There is only one valid place in sysfs where hierarchy can be examined
105 It is planned that all device directories will end up in the tree
108 - Classification by subsystem
119 The devices belonging to a subsystem will create a symlink in the
129 ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in
130 the application.
132 - Block
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.
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.
150 Never depend on the class-specific links back to the ``/sys/class``
152 that class devices are not created in ``/sys/devices.`` If a device
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
157 real child device directories in the ``/sys/devices`` tree is a bug in
158 the application.
161 directories live in ``/sys/devices.``
163 - Position of devices along device chain can change.
164 Never depend on a specific parent device position in the devpath,
170 access the chain of parents is a bug in the application.
172 - When reading and writing sysfs device attribute files, avoid dependency
176 In general, failures to read or write sysfs device attributes shall
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
191 the attribute files to remain consistent in the absence of a version
192 attribute change in the context of a given attribute.