About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / admin-guide / sysfs-rules.rst




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

1	Rules on how to access information in sysfs
2	===========================================
3	
4	The kernel-exported sysfs exports internal kernel implementation details
5	and depends on internal kernel structures and layout. It is agreed upon
6	by the kernel developers that the Linux kernel does not provide a stable
7	internal API. Therefore, there are aspects of the sysfs interface that
8	may not be stable across kernel releases.
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	
47	    - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
48	
49	      - identical to the DEVPATH value in the event sent from the kernel
50	        at device creation and removal
51	      - the unique key to the device at that point in time
52	      - the kernel's path to the device directory without the leading
53	        ``/sys``, and always starting with a slash
54	      - all elements of a devpath must be real directories. Symlinks
55	        pointing to /sys/devices must always be resolved to their real
56	        target and the target path must be used to access the device.
57	        That way the devpath to the device matches the devpath of the
58	        kernel used at event time.
59	      - using or exposing symlink values as elements in a devpath string
60	        is a bug in the application
61	
62	    - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...)
63	
64	      - a directory name, identical to the last element of the devpath
65	      - applications need to handle spaces and characters like ``!`` in
66	        the name
67	
68	    - subsystem (``block``, ``tty``, ``pci``, ...)
69	
70	      - simple string, never a path or a link
71	      - retrieved by reading the "subsystem"-link and using only the
72	        last element of the target path
73	
74	    - driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
75	
76	      - a simple string, which may contain spaces, never a path or a
77	        link
78	      - it is retrieved by reading the "driver"-link and using only the
79	        last element of the target path
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
83	
84	    - attributes
85	
86	      - the files in the device directory or files below subdirectories
87	        of the same device directory
88	      - accessing attributes reached by a symlink pointing to another device,
89	        like the "device"-link, is a bug in the application
90	
91	    Everything else is just a kernel driver-core implementation detail
92	    that should not be assumed to be stable across kernel releases.
93	
94	- Properties of parent devices never belong into a child device.
95	    Always look at the parent devices themselves for determining device
96	    context properties. If the device ``eth0`` or ``sda`` does not have a
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
99	    device properties may change dynamically without any notice to the
100	    child device.
101	
102	- Hierarchy in a single device tree
103	    There is only one valid place in sysfs where hierarchy can be examined
104	    and this is below: ``/sys/devices.``
105	    It is planned that all device directories will end up in the tree
106	    below this directory.
107	
108	- Classification by subsystem
109	    There are currently three places for classification of devices:
110	    ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will
111	    not contain any device directories themselves, but only flat lists of
112	    symlinks pointing to the unified ``/sys/devices`` tree.
113	    All three places have completely different rules on how to access
114	    device information. It is planned to merge all three
115	    classification directories into one place at ``/sys/subsystem``,
116	    following the layout of the bus directories. All buses and
117	    classes, including the converted block subsystem, will show up
118	    there.
119	    The devices belonging to a subsystem will create a symlink in the
120	    "devices" directory at ``/sys/subsystem/<name>/devices``,
121	
122	    If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block``
123	    can be ignored. If it does not exist, you always have to scan all three
124	    places, as the kernel is free to move a subsystem from one place to
125	    the other, as long as the devices are still reachable by the same
126	    subsystem name.
127	
128	    Assuming ``/sys/class/<subsystem>`` and ``/sys/bus/<subsystem>``, or
129	    ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in
130	    the application.
131	
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
136	    contain only disks and not partition devices in the same flat list is
137	    a bug in the application.
138	
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.
149	
150	    Never depend on the class-specific links back to the ``/sys/class``
151	    directory.  These links are also a workaround for the design mistake
152	    that class devices are not created in ``/sys/devices.`` If a device
153	    directory does not contain directories for child devices, these links
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
156	    element. Assuming the existence of these links for devices which are
157	    real child device directories in the ``/sys/devices`` tree is a bug in
158	    the application.
159	
160	    It is planned to remove all these links when all class device
161	    directories live in ``/sys/devices.``
162	
163	- Position of devices along device chain can change.
164	    Never depend on a specific parent device position in the devpath,
165	    or the chain of parent devices. The kernel is free to insert devices into
166	    the chain. You must always request the parent device you are looking for
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
169	    position of a parent device or exposing relative paths using ``../`` to
170	    access the chain of parents is a bug in the application.
171	
172	- When reading and writing sysfs device attribute files, avoid dependency
173	    on specific error codes wherever possible. This minimizes coupling to
174	    the error handling implementation within the kernel.
175	
176	    In general, failures to read or write sysfs device attributes shall
177	    propagate errors wherever possible. Common errors include, but are not
178	    limited to:
179	
180		``-EIO``: The read or store operation is not supported, typically
181		returned by the sysfs system itself if the read or store pointer
182		is ``NULL``.
183	
184		``-ENXIO``: The read or store operation failed
185	
186	    Error codes will not be changed without good reason, and should a change
187	    to error codes result in user-space breakage, it will be fixed, or the
188	    the offending change will be reverted.
189	
190	    Userspace applications can, however, expect the format and contents of
191	    the attribute files to remain consistent in the absence of a version
192	    attribute change in the context of a given attribute.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.