1 |
3 |
xianfeng |
Rules on how to access information in the Linux kernel sysfs
|
2 |
|
|
|
3 |
|
|
The kernel-exported sysfs exports internal kernel implementation details
|
4 |
|
|
and depends on internal kernel structures and layout. It is agreed upon
|
5 |
|
|
by the kernel developers that the Linux kernel does not provide a stable
|
6 |
|
|
internal API. As sysfs is a direct export of kernel internal
|
7 |
|
|
structures, the sysfs interface cannot provide a stable interface either;
|
8 |
|
|
it may always change along with internal kernel changes.
|
9 |
|
|
|
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
|
13 |
|
|
access this filesystem. The current udev and HAL programs already
|
14 |
|
|
implement this and users are encouraged to plug, if possible, into the
|
15 |
|
|
abstractions these programs provide instead of accessing sysfs directly.
|
16 |
|
|
|
17 |
|
|
But if you really do want or need to access sysfs directly, please follow
|
18 |
|
|
the following rules and then your programs should work with future
|
19 |
|
|
versions of the sysfs interface.
|
20 |
|
|
|
21 |
|
|
- 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.
|
30 |
|
|
|
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.
|
37 |
|
|
|
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
|
42 |
|
|
kernel implementation details which should not be expected by
|
43 |
|
|
applications that look for devices in sysfs.
|
44 |
|
|
|
45 |
|
|
The properties of a device are:
|
46 |
|
|
o devpath (/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0)
|
47 |
|
|
- identical to the DEVPATH value in the event sent from the kernel
|
48 |
|
|
at device creation and removal
|
49 |
|
|
- the unique key to the device at that point in time
|
50 |
|
|
- the kernel's path to the device directory without the leading
|
51 |
|
|
/sys, and always starting with with a slash
|
52 |
|
|
- all elements of a devpath must be real directories. Symlinks
|
53 |
|
|
pointing to /sys/devices must always be resolved to their real
|
54 |
|
|
target and the target path must be used to access the device.
|
55 |
|
|
That way the devpath to the device matches the devpath of the
|
56 |
|
|
kernel used at event time.
|
57 |
|
|
- using or exposing symlink values as elements in a devpath string
|
58 |
|
|
is a bug in the application
|
59 |
|
|
|
60 |
|
|
o kernel name (sda, tty, 0000:00:1f.2, ...)
|
61 |
|
|
- a directory name, identical to the last element of the devpath
|
62 |
|
|
- applications need to handle spaces and characters like '!' in
|
63 |
|
|
the name
|
64 |
|
|
|
65 |
|
|
o subsystem (block, tty, pci, ...)
|
66 |
|
|
- simple string, never a path or a link
|
67 |
|
|
- retrieved by reading the "subsystem"-link and using only the
|
68 |
|
|
last element of the target path
|
69 |
|
|
|
70 |
|
|
o driver (tg3, ata_piix, uhci_hcd)
|
71 |
|
|
- a simple string, which may contain spaces, never a path or a
|
72 |
|
|
link
|
73 |
|
|
- it is retrieved by reading the "driver"-link and using only the
|
74 |
|
|
last element of the target path
|
75 |
|
|
- devices which do not have "driver"-link just do not have a
|
76 |
|
|
driver; copying the driver value in a child device context is a
|
77 |
|
|
bug in the application
|
78 |
|
|
|
79 |
|
|
o attributes
|
80 |
|
|
- the files in the device directory or files below subdirectories
|
81 |
|
|
of the same device directory
|
82 |
|
|
- accessing attributes reached by a symlink pointing to another device,
|
83 |
|
|
like the "device"-link, is a bug in the application
|
84 |
|
|
|
85 |
|
|
Everything else is just a kernel driver-core implementation detail
|
86 |
|
|
that should not be assumed to be stable across kernel releases.
|
87 |
|
|
|
88 |
|
|
- Properties of parent devices never belong into a 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.
|
95 |
|
|
|
96 |
|
|
- Hierarchy in a single device tree
|
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.
|
101 |
|
|
|
102 |
|
|
- Classification by subsystem
|
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//devices.
|
115 |
|
|
|
116 |
|
|
If /sys/subsystem exists, /sys/bus, /sys/class and /sys/block can be
|
117 |
|
|
ignored. If it does not exist, you have always 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.
|
121 |
|
|
|
122 |
|
|
Assuming /sys/class/ and /sys/bus/, or
|
123 |
|
|
/sys/block and /sys/class/block are not interchangeable is a bug in
|
124 |
|
|
the application.
|
125 |
|
|
|
126 |
|
|
- Block
|
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 subsytem to
|
130 |
|
|
contain only disks and not partition devices in the same flat list is
|
131 |
|
|
a bug in the application.
|
132 |
|
|
|
133 |
|
|
- "device"-link and :-links
|
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.
|
143 |
|
|
|
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.
|
153 |
|
|
|
154 |
|
|
It is planned to remove all these links when all class device
|
155 |
|
|
directories live in /sys/devices.
|
156 |
|
|
|
157 |
|
|
- Position of devices along device chain can change.
|
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.
|