Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/sysfs-rules.txt: convert it to ReST markup
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+113
-105
+113
-105
Documentation/sysfs-rules.txt
+113
-105
Documentation/sysfs-rules.txt
···
1
1
Rules on how to access information in the Linux kernel sysfs
2
+
============================================================
2
3
3
4
The kernel-exported sysfs exports internal kernel implementation details
4
5
and depends on internal kernel structures and layout. It is agreed upon
···
19
18
versions of the sysfs interface.
20
19
21
20
- Do not use libsysfs
22
-
It makes assumptions about sysfs which are not true. Its API does not
23
-
offer any abstraction, it exposes all the kernel driver-core
24
-
implementation details in its own API. Therefore it is not better than
25
-
reading directories and opening the files yourself.
26
-
Also, it is not actively maintained, in the sense of reflecting the
27
-
current kernel development. The goal of providing a stable interface
28
-
to sysfs has failed; it causes more problems than it solves. It
29
-
violates many of the rules in this document.
21
+
It makes assumptions about sysfs which are not true. Its API does not
22
+
offer any abstraction, it exposes all the kernel driver-core
23
+
implementation details in its own API. Therefore it is not better than
24
+
reading directories and opening the files yourself.
25
+
Also, it is not actively maintained, in the sense of reflecting the
26
+
current kernel development. The goal of providing a stable interface
27
+
to sysfs has failed; it causes more problems than it solves. It
28
+
violates many of the rules in this document.
30
29
31
-
- sysfs is always at /sys
32
-
Parsing /proc/mounts is a waste of time. Other mount points are a
33
-
system configuration bug you should not try to solve. For test cases,
34
-
possibly support a SYSFS_PATH environment variable to overwrite the
35
-
application's behavior, but never try to search for sysfs. Never try
36
-
to mount it, if you are not an early boot script.
30
+
- sysfs is always at ``/sys``
31
+
Parsing ``/proc/mounts`` is a waste of time. Other mount points are a
32
+
system configuration bug you should not try to solve. For test cases,
33
+
possibly support a ``SYSFS_PATH`` environment variable to overwrite the
34
+
application's behavior, but never try to search for sysfs. Never try
35
+
to mount it, if you are not an early boot script.
37
36
38
37
- 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
42
-
kernel implementation details which should not be expected by
43
-
applications that look for devices in sysfs.
38
+
There is no such thing like class-, bus-, physical devices,
39
+
interfaces, and such that you can rely on in userspace. Everything is
40
+
just simply a "device". Class-, bus-, physical, ... types are just
41
+
kernel implementation details which should not be expected by
42
+
applications that look for devices in sysfs.
44
43
45
-
The properties of a device are:
46
-
o devpath (/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0)
44
+
The properties of a device are:
45
+
46
+
- devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
47
+
47
48
- identical to the DEVPATH value in the event sent from the kernel
48
49
at device creation and removal
49
50
- the unique key to the device at that point in time
50
51
- the kernel's path to the device directory without the leading
51
-
/sys, and always starting with a slash
52
+
``/sys``, and always starting with a slash
52
53
- all elements of a devpath must be real directories. Symlinks
53
54
pointing to /sys/devices must always be resolved to their real
54
55
target and the target path must be used to access the device.
···
59
56
- using or exposing symlink values as elements in a devpath string
60
57
is a bug in the application
61
58
62
-
o kernel name (sda, tty, 0000:00:1f.2, ...)
59
+
- kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)
60
+
63
61
- a directory name, identical to the last element of the devpath
64
-
- applications need to handle spaces and characters like '!' in
62
+
- applications need to handle spaces and characters like ``!`` in
65
63
the name
66
64
67
-
o subsystem (block, tty, pci, ...)
65
+
- subsystem (``block``, ``tty``, ``pci``, ...)
66
+
68
67
- simple string, never a path or a link
69
68
- retrieved by reading the "subsystem"-link and using only the
70
69
last element of the target path
71
70
72
-
o driver (tg3, ata_piix, uhci_hcd)
71
+
- driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
72
+
73
73
- a simple string, which may contain spaces, never a path or a
74
74
link
75
75
- it is retrieved by reading the "driver"-link and using only the
···
81
75
driver; copying the driver value in a child device context is a
82
76
bug in the application
83
77
84
-
o attributes
78
+
- attributes
79
+
85
80
- the files in the device directory or files below subdirectories
86
81
of the same device directory
87
82
- accessing attributes reached by a symlink pointing to another device,
88
83
like the "device"-link, is a bug in the application
89
84
90
-
Everything else is just a kernel driver-core implementation detail
91
-
that should not be assumed to be stable across kernel releases.
85
+
Everything else is just a kernel driver-core implementation detail
86
+
that should not be assumed to be stable across kernel releases.
92
87
93
88
- Properties of parent devices never belong into a child device.
94
-
Always look at the parent devices themselves for determining device
95
-
context properties. If the device 'eth0' or 'sda' does not have a
96
-
"driver"-link, then this device does not have a driver. Its value is empty.
97
-
Never copy any property of the parent-device into a child-device. Parent
98
-
device properties may change dynamically without any notice to the
99
-
child device.
89
+
Always look at the parent devices themselves for determining device
90
+
context properties. If the device ``eth0`` or ``sda`` does not have a
91
+
"driver"-link, then this device does not have a driver. Its value is empty.
92
+
Never copy any property of the parent-device into a child-device. Parent
93
+
device properties may change dynamically without any notice to the
94
+
child device.
100
95
101
96
- Hierarchy in a single device tree
102
-
There is only one valid place in sysfs where hierarchy can be examined
103
-
and this is below: /sys/devices.
104
-
It is planned that all device directories will end up in the tree
105
-
below this directory.
97
+
There is only one valid place in sysfs where hierarchy can be examined
98
+
and this is below: ``/sys/devices.``
99
+
It is planned that all device directories will end up in the tree
100
+
below this directory.
106
101
107
102
- Classification by subsystem
108
-
There are currently three places for classification of devices:
109
-
/sys/block, /sys/class and /sys/bus. It is planned that these will
110
-
not contain any device directories themselves, but only flat lists of
111
-
symlinks pointing to the unified /sys/devices tree.
112
-
All three places have completely different rules on how to access
113
-
device information. It is planned to merge all three
114
-
classification directories into one place at /sys/subsystem,
115
-
following the layout of the bus directories. All buses and
116
-
classes, including the converted block subsystem, will show up
117
-
there.
118
-
The devices belonging to a subsystem will create a symlink in the
119
-
"devices" directory at /sys/subsystem/<name>/devices.
103
+
There are currently three places for classification of devices:
104
+
``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will
105
+
not contain any device directories themselves, but only flat lists of
106
+
symlinks pointing to the unified ``/sys/devices`` tree.
107
+
All three places have completely different rules on how to access
108
+
device information. It is planned to merge all three
109
+
classification directories into one place at ``/sys/subsystem``,
110
+
following the layout of the bus directories. All buses and
111
+
classes, including the converted block subsystem, will show up
112
+
there.
113
+
The devices belonging to a subsystem will create a symlink in the
114
+
"devices" directory at ``/sys/subsystem/<name>/devices``,
120
115
121
-
If /sys/subsystem exists, /sys/bus, /sys/class and /sys/block can be
122
-
ignored. If it does not exist, you always have to scan all three
123
-
places, as the kernel is free to move a subsystem from one place to
124
-
the other, as long as the devices are still reachable by the same
125
-
subsystem name.
116
+
If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block``
117
+
can be ignored. If it does not exist, you always have to scan all three
118
+
places, as the kernel is free to move a subsystem from one place to
119
+
the other, as long as the devices are still reachable by the same
120
+
subsystem name.
126
121
127
-
Assuming /sys/class/<subsystem> and /sys/bus/<subsystem>, or
128
-
/sys/block and /sys/class/block are not interchangeable is a bug in
129
-
the application.
122
+
Assuming ``/sys/class/<subsystem>`` and ``/sys/bus/<subsystem>``, or
123
+
``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in
124
+
the application.
130
125
131
126
- Block
132
-
The converted block subsystem at /sys/class/block or
133
-
/sys/subsystem/block will contain the links for disks and partitions
134
-
at the same level, never in a hierarchy. Assuming the block subsystem to
135
-
contain only disks and not partition devices in the same flat list is
136
-
a bug in the application.
127
+
The converted block subsystem at ``/sys/class/block`` or
128
+
``/sys/subsystem/block`` will contain the links for disks and partitions
129
+
at the same level, never in a hierarchy. Assuming the block subsystem to
130
+
contain only disks and not partition devices in the same flat list is
131
+
a bug in the application.
137
132
138
133
- "device"-link and <subsystem>:<kernel name>-links
139
-
Never depend on the "device"-link. The "device"-link is a workaround
140
-
for the old layout, where class devices are not created in
141
-
/sys/devices/ like the bus devices. If the link-resolving of a
142
-
device directory does not end in /sys/devices/, you can use the
143
-
"device"-link to find the parent devices in /sys/devices/. That is the
144
-
single valid use of the "device"-link; it must never appear in any
145
-
path as an element. Assuming the existence of the "device"-link for
146
-
a device in /sys/devices/ is a bug in the application.
147
-
Accessing /sys/class/net/eth0/device is a bug in the application.
134
+
Never depend on the "device"-link. The "device"-link is a workaround
135
+
for the old layout, where class devices are not created in
136
+
``/sys/devices/`` like the bus devices. If the link-resolving of a
137
+
device directory does not end in ``/sys/devices/``, you can use the
138
+
"device"-link to find the parent devices in ``/sys/devices/``, That is the
139
+
single valid use of the "device"-link; it must never appear in any
140
+
path as an element. Assuming the existence of the "device"-link for
141
+
a device in ``/sys/devices/`` is a bug in the application.
142
+
Accessing ``/sys/class/net/eth0/device`` is a bug in the application.
148
143
149
-
Never depend on the class-specific links back to the /sys/class
150
-
directory. These links are also a workaround for the design mistake
151
-
that class devices are not created in /sys/devices. If a device
152
-
directory does not contain directories for child devices, these links
153
-
may be used to find the child devices in /sys/class. That is the single
154
-
valid use of these links; they must never appear in any path as an
155
-
element. Assuming the existence of these links for devices which are
156
-
real child device directories in the /sys/devices tree is a bug in
157
-
the application.
144
+
Never depend on the class-specific links back to the ``/sys/class``
145
+
directory. These links are also a workaround for the design mistake
146
+
that class devices are not created in ``/sys/devices.`` If a device
147
+
directory does not contain directories for child devices, these links
148
+
may be used to find the child devices in ``/sys/class.`` That is the single
149
+
valid use of these links; they must never appear in any path as an
150
+
element. Assuming the existence of these links for devices which are
151
+
real child device directories in the ``/sys/devices`` tree is a bug in
152
+
the application.
158
153
159
-
It is planned to remove all these links when all class device
160
-
directories live in /sys/devices.
154
+
It is planned to remove all these links when all class device
155
+
directories live in ``/sys/devices.``
161
156
162
157
- Position of devices along device chain can change.
163
-
Never depend on a specific parent device position in the devpath,
164
-
or the chain of parent devices. The kernel is free to insert devices into
165
-
the chain. You must always request the parent device you are looking for
166
-
by its subsystem value. You need to walk up the chain until you find
167
-
the device that matches the expected subsystem. Depending on a specific
168
-
position of a parent device or exposing relative paths using "../" to
169
-
access the chain of parents is a bug in the application.
158
+
Never depend on a specific parent device position in the devpath,
159
+
or the chain of parent devices. The kernel is free to insert devices into
160
+
the chain. You must always request the parent device you are looking for
161
+
by its subsystem value. You need to walk up the chain until you find
162
+
the device that matches the expected subsystem. Depending on a specific
163
+
position of a parent device or exposing relative paths using ``../`` to
164
+
access the chain of parents is a bug in the application.
170
165
171
166
- When reading and writing sysfs device attribute files, avoid dependency
172
-
on specific error codes wherever possible. This minimizes coupling to
173
-
the error handling implementation within the kernel.
167
+
on specific error codes wherever possible. This minimizes coupling to
168
+
the error handling implementation within the kernel.
174
169
175
-
In general, failures to read or write sysfs device attributes shall
176
-
propagate errors wherever possible. Common errors include, but are not
177
-
limited to:
170
+
In general, failures to read or write sysfs device attributes shall
171
+
propagate errors wherever possible. Common errors include, but are not
172
+
limited to:
178
173
179
-
-EIO: The read or store operation is not supported, typically returned by
180
-
the sysfs system itself if the read or store pointer is NULL.
174
+
``-EIO``: The read or store operation is not supported, typically
175
+
returned by the sysfs system itself if the read or store pointer
176
+
is ``NULL``.
181
177
182
-
-ENXIO: The read or store operation failed
178
+
``-ENXIO``: The read or store operation failed
183
179
184
-
Error codes will not be changed without good reason, and should a change
185
-
to error codes result in user-space breakage, it will be fixed, or the
186
-
the offending change will be reverted.
180
+
Error codes will not be changed without good reason, and should a change
181
+
to error codes result in user-space breakage, it will be fixed, or the
182
+
the offending change will be reverted.
187
183
188
-
Userspace applications can, however, expect the format and contents of
189
-
the attribute files to remain consistent in the absence of a version
190
-
attribute change in the context of a given attribute.
184
+
Userspace applications can, however, expect the format and contents of
185
+
the attribute files to remain consistent in the absence of a version
186
+
attribute change in the context of a given attribute.