Commit | Line | Data |
---|---|---|
86beb976 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
1da177e4 | 2 | |
86beb976 MCC |
3 | ===================================================== |
4 | sysfs - _The_ filesystem for exporting kernel objects | |
5 | ===================================================== | |
1da177e4 LT |
6 | |
7 | Patrick Mochel <mochel@osdl.org> | |
86beb976 | 8 | |
f8a1af6b | 9 | Mike Murphy <mamurph@cs.clemson.edu> |
1da177e4 | 10 | |
86beb976 MCC |
11 | :Revised: 16 August 2011 |
12 | :Original: 10 January 2003 | |
1da177e4 LT |
13 | |
14 | ||
15 | What it is: | |
16 | ~~~~~~~~~~~ | |
17 | ||
18 | sysfs is a ram-based filesystem initially based on ramfs. It provides | |
86beb976 MCC |
19 | a means to export kernel data structures, their attributes, and the |
20 | linkages between them to userspace. | |
1da177e4 LT |
21 | |
22 | sysfs is tied inherently to the kobject infrastructure. Please read | |
0c1bc6b8 | 23 | Documentation/core-api/kobject.rst for more information concerning the kobject |
86beb976 | 24 | interface. |
1da177e4 LT |
25 | |
26 | ||
27 | Using sysfs | |
28 | ~~~~~~~~~~~ | |
29 | ||
a39ea210 | 30 | sysfs is always compiled in if CONFIG_SYSFS is defined. You can access |
86beb976 | 31 | it by doing:: |
1da177e4 | 32 | |
86beb976 | 33 | mount -t sysfs sysfs /sys |
1da177e4 LT |
34 | |
35 | ||
36 | Directory Creation | |
37 | ~~~~~~~~~~~~~~~~~~ | |
38 | ||
39 | For every kobject that is registered with the system, a directory is | |
40 | created for it in sysfs. That directory is created as a subdirectory | |
41 | of the kobject's parent, expressing internal object hierarchies to | |
42 | userspace. Top-level directories in sysfs represent the common | |
43 | ancestors of object hierarchies; i.e. the subsystems the objects | |
86beb976 | 44 | belong to. |
1da177e4 | 45 | |
5480bcdd | 46 | Sysfs internally stores a pointer to the kobject that implements a |
390b421c | 47 | directory in the kernfs_node object associated with the directory. In |
5480bcdd BVA |
48 | the past this kobject pointer has been used by sysfs to do reference |
49 | counting directly on the kobject whenever the file is opened or closed. | |
50 | With the current sysfs implementation the kobject reference count is | |
51 | only modified directly by the function sysfs_schedule_callback(). | |
1da177e4 LT |
52 | |
53 | ||
54 | Attributes | |
55 | ~~~~~~~~~~ | |
56 | ||
57 | Attributes can be exported for kobjects in the form of regular files in | |
58 | the filesystem. Sysfs forwards file I/O operations to methods defined | |
59 | for the attributes, providing a means to read and write kernel | |
60 | attributes. | |
61 | ||
62 | Attributes should be ASCII text files, preferably with only one value | |
f8c34f98 | 63 | per file. It is noted that it may not be efficient to contain only one |
1da177e4 | 64 | value per file, so it is socially acceptable to express an array of |
86beb976 | 65 | values of the same type. |
1da177e4 LT |
66 | |
67 | Mixing types, expressing multiple lines of data, and doing fancy | |
68 | formatting of data is heavily frowned upon. Doing these things may get | |
86beb976 | 69 | you publicly humiliated and your code rewritten without notice. |
1da177e4 LT |
70 | |
71 | ||
86beb976 | 72 | An attribute definition is simply:: |
1da177e4 | 73 | |
86beb976 MCC |
74 | struct attribute { |
75 | char * name; | |
76 | struct module *owner; | |
77 | umode_t mode; | |
78 | }; | |
1da177e4 LT |
79 | |
80 | ||
86beb976 MCC |
81 | int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); |
82 | void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); | |
1da177e4 LT |
83 | |
84 | ||
85 | A bare attribute contains no means to read or write the value of the | |
86 | attribute. Subsystems are encouraged to define their own attribute | |
87 | structure and wrapper functions for adding and removing attributes for | |
86beb976 | 88 | a specific object type. |
1da177e4 | 89 | |
86beb976 | 90 | For example, the driver model defines struct device_attribute like:: |
1da177e4 | 91 | |
86beb976 MCC |
92 | struct device_attribute { |
93 | struct attribute attr; | |
94 | ssize_t (*show)(struct device *dev, struct device_attribute *attr, | |
95 | char *buf); | |
96 | ssize_t (*store)(struct device *dev, struct device_attribute *attr, | |
97 | const char *buf, size_t count); | |
98 | }; | |
1da177e4 | 99 | |
86beb976 MCC |
100 | int device_create_file(struct device *, const struct device_attribute *); |
101 | void device_remove_file(struct device *, const struct device_attribute *); | |
1da177e4 | 102 | |
86beb976 | 103 | It also defines this helper for defining device attributes:: |
1da177e4 | 104 | |
86beb976 MCC |
105 | #define DEVICE_ATTR(_name, _mode, _show, _store) \ |
106 | struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) | |
1da177e4 | 107 | |
86beb976 | 108 | For example, declaring:: |
1da177e4 | 109 | |
86beb976 | 110 | static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); |
1da177e4 | 111 | |
86beb976 | 112 | is equivalent to doing:: |
1da177e4 | 113 | |
86beb976 MCC |
114 | static struct device_attribute dev_attr_foo = { |
115 | .attr = { | |
116 | .name = "foo", | |
117 | .mode = S_IWUSR | S_IRUGO, | |
118 | }, | |
119 | .show = show_foo, | |
120 | .store = store_foo, | |
121 | }; | |
1da177e4 | 122 | |
44a47f0e NMG |
123 | Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally |
124 | considered a bad idea." so trying to set a sysfs file writable for | |
125 | everyone will fail reverting to RO mode for "Others". | |
126 | ||
127 | For the common cases sysfs.h provides convenience macros to make | |
128 | defining attributes easier as well as making code more concise and | |
129 | readable. The above case could be shortened to: | |
130 | ||
131 | static struct device_attribute dev_attr_foo = __ATTR_RW(foo); | |
132 | ||
133 | the list of helpers available to define your wrapper function is: | |
86beb976 MCC |
134 | |
135 | __ATTR_RO(name): | |
136 | assumes default name_show and mode 0444 | |
137 | __ATTR_WO(name): | |
138 | assumes a name_store only and is restricted to mode | |
44a47f0e | 139 | 0200 that is root write access only. |
86beb976 MCC |
140 | __ATTR_RO_MODE(name, mode): |
141 | fore more restrictive RO access currently | |
44a47f0e NMG |
142 | only use case is the EFI System Resource Table |
143 | (see drivers/firmware/efi/esrt.c) | |
86beb976 MCC |
144 | __ATTR_RW(name): |
145 | assumes default name_show, name_store and setting | |
44a47f0e | 146 | mode to 0644. |
86beb976 MCC |
147 | __ATTR_NULL: |
148 | which sets the name to NULL and is used as end of list | |
44a47f0e | 149 | indicator (see: kernel/workqueue.c) |
1da177e4 LT |
150 | |
151 | Subsystem-Specific Callbacks | |
152 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
153 | ||
154 | When a subsystem defines a new attribute type, it must implement a | |
155 | set of sysfs operations for forwarding read and write calls to the | |
86beb976 | 156 | show and store methods of the attribute owners:: |
1da177e4 | 157 | |
86beb976 MCC |
158 | struct sysfs_ops { |
159 | ssize_t (*show)(struct kobject *, struct attribute *, char *); | |
160 | ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); | |
161 | }; | |
1da177e4 LT |
162 | |
163 | [ Subsystems should have already defined a struct kobj_type as a | |
164 | descriptor for this type, which is where the sysfs_ops pointer is | |
165 | stored. See the kobject documentation for more information. ] | |
166 | ||
167 | When a file is read or written, sysfs calls the appropriate method | |
168 | for the type. The method then translates the generic struct kobject | |
169 | and struct attribute pointers to the appropriate pointer types, and | |
86beb976 | 170 | calls the associated methods. |
1da177e4 LT |
171 | |
172 | ||
86beb976 | 173 | To illustrate:: |
1da177e4 | 174 | |
86beb976 | 175 | #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) |
1da177e4 | 176 | |
86beb976 MCC |
177 | static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, |
178 | char *buf) | |
179 | { | |
180 | struct device_attribute *dev_attr = to_dev_attr(attr); | |
e046de3d | 181 | struct device *dev = kobj_to_dev(kobj); |
86beb976 | 182 | ssize_t ret = -EIO; |
1da177e4 | 183 | |
86beb976 MCC |
184 | if (dev_attr->show) |
185 | ret = dev_attr->show(dev, dev_attr, buf); | |
186 | if (ret >= (ssize_t)PAGE_SIZE) { | |
187 | printk("dev_attr_show: %pS returned bad count\n", | |
188 | dev_attr->show); | |
189 | } | |
190 | return ret; | |
191 | } | |
1da177e4 LT |
192 | |
193 | ||
194 | ||
195 | Reading/Writing Attribute Data | |
196 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
197 | ||
198 | To read or write attributes, show() or store() methods must be | |
199 | specified when declaring the attribute. The method types should be as | |
86beb976 | 200 | simple as those defined for device attributes:: |
1da177e4 | 201 | |
86beb976 MCC |
202 | ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); |
203 | ssize_t (*store)(struct device *dev, struct device_attribute *attr, | |
204 | const char *buf, size_t count); | |
1da177e4 | 205 | |
f8a1af6b | 206 | IOW, they should take only an object, an attribute, and a buffer as parameters. |
1da177e4 LT |
207 | |
208 | ||
209 | sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the | |
210 | method. Sysfs will call the method exactly once for each read or | |
211 | write. This forces the following behavior on the method | |
86beb976 | 212 | implementations: |
1da177e4 | 213 | |
86beb976 | 214 | - On read(2), the show() method should fill the entire buffer. |
1da177e4 | 215 | Recall that an attribute should only be exporting one value, or an |
86beb976 | 216 | array of similar values, so this shouldn't be that expensive. |
1da177e4 | 217 | |
2424b5dd DW |
218 | This allows userspace to do partial reads and forward seeks |
219 | arbitrarily over the entire file at will. If userspace seeks back to | |
220 | zero or does a pread(2) with an offset of '0' the show() method will | |
221 | be called again, rearmed, to fill the buffer. | |
1da177e4 LT |
222 | |
223 | - On write(2), sysfs expects the entire buffer to be passed during the | |
17666497 UM |
224 | first write. Sysfs then passes the entire buffer to the store() method. |
225 | A terminating null is added after the data on stores. This makes | |
226 | functions like sysfs_streq() safe to use. | |
227 | ||
1da177e4 LT |
228 | When writing sysfs files, userspace processes should first read the |
229 | entire file, modify the values it wishes to change, then write the | |
86beb976 | 230 | entire buffer back. |
1da177e4 LT |
231 | |
232 | Attribute method implementations should operate on an identical | |
86beb976 | 233 | buffer when reading and writing values. |
1da177e4 LT |
234 | |
235 | Other notes: | |
236 | ||
2424b5dd DW |
237 | - Writing causes the show() method to be rearmed regardless of current |
238 | file position. | |
239 | ||
1da177e4 | 240 | - The buffer will always be PAGE_SIZE bytes in length. On i386, this |
86beb976 | 241 | is 4096. |
1da177e4 LT |
242 | |
243 | - show() methods should return the number of bytes printed into the | |
2efc459d | 244 | buffer. |
1da177e4 | 245 | |
2efc459d JP |
246 | - show() should only use sysfs_emit() or sysfs_emit_at() when formatting |
247 | the value to be returned to user space. | |
1da177e4 | 248 | |
30a69000 BVA |
249 | - store() should return the number of bytes used from the buffer. If the |
250 | entire buffer has been used, just return the count argument. | |
1da177e4 LT |
251 | |
252 | - show() or store() can always return errors. If a bad value comes | |
253 | through, be sure to return an error. | |
254 | ||
255 | - The object passed to the methods will be pinned in memory via sysfs | |
86beb976 MCC |
256 | referencing counting its embedded object. However, the physical |
257 | entity (e.g. device) the object represents may not be present. Be | |
258 | sure to have a way to check this, if necessary. | |
1da177e4 LT |
259 | |
260 | ||
86beb976 | 261 | A very simple (and naive) implementation of a device attribute is:: |
1da177e4 | 262 | |
86beb976 MCC |
263 | static ssize_t show_name(struct device *dev, struct device_attribute *attr, |
264 | char *buf) | |
265 | { | |
266 | return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); | |
267 | } | |
1da177e4 | 268 | |
86beb976 MCC |
269 | static ssize_t store_name(struct device *dev, struct device_attribute *attr, |
270 | const char *buf, size_t count) | |
271 | { | |
272 | snprintf(dev->name, sizeof(dev->name), "%.*s", | |
273 | (int)min(count, sizeof(dev->name) - 1), buf); | |
274 | return count; | |
275 | } | |
1da177e4 | 276 | |
86beb976 | 277 | static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); |
1da177e4 LT |
278 | |
279 | ||
86beb976 | 280 | (Note that the real implementation doesn't allow userspace to set the |
1da177e4 LT |
281 | name for a device.) |
282 | ||
283 | ||
284 | Top Level Directory Layout | |
285 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
286 | ||
287 | The sysfs directory arrangement exposes the relationship of kernel | |
86beb976 | 288 | data structures. |
1da177e4 | 289 | |
86beb976 | 290 | The top level sysfs directory looks like:: |
1da177e4 | 291 | |
86beb976 MCC |
292 | block/ |
293 | bus/ | |
294 | class/ | |
295 | dev/ | |
296 | devices/ | |
297 | firmware/ | |
298 | net/ | |
299 | fs/ | |
1da177e4 LT |
300 | |
301 | devices/ contains a filesystem representation of the device tree. It maps | |
302 | directly to the internal kernel device tree, which is a hierarchy of | |
86beb976 | 303 | struct device. |
1da177e4 LT |
304 | |
305 | bus/ contains flat directory layout of the various bus types in the | |
86beb976 | 306 | kernel. Each bus's directory contains two subdirectories:: |
1da177e4 LT |
307 | |
308 | devices/ | |
309 | drivers/ | |
310 | ||
311 | devices/ contains symlinks for each device discovered in the system | |
312 | that point to the device's directory under root/. | |
313 | ||
314 | drivers/ contains a directory for each device driver that is loaded | |
315 | for devices on that particular bus (this assumes that drivers do not | |
316 | span multiple bus types). | |
317 | ||
c86d90df MS |
318 | fs/ contains a directory for some filesystems. Currently each |
319 | filesystem wanting to export attributes must create its own hierarchy | |
320 | below fs/ (see ./fuse.txt for an example). | |
321 | ||
e105b8bf DW |
322 | dev/ contains two directories char/ and block/. Inside these two |
323 | directories there are symlinks named <major>:<minor>. These symlinks | |
324 | point to the sysfs directory for the given device. /sys/dev provides a | |
325 | quick way to lookup the sysfs interface for a device from the result of | |
326 | a stat(2) operation. | |
1da177e4 LT |
327 | |
328 | More information can driver-model specific features can be found in | |
fe34c89d | 329 | Documentation/driver-api/driver-model/. |
1da177e4 LT |
330 | |
331 | ||
332 | TODO: Finish this section. | |
333 | ||
334 | ||
335 | Current Interfaces | |
336 | ~~~~~~~~~~~~~~~~~~ | |
337 | ||
338 | The following interface layers currently exist in sysfs: | |
339 | ||
340 | ||
86beb976 MCC |
341 | devices (include/linux/device.h) |
342 | -------------------------------- | |
343 | Structure:: | |
1da177e4 | 344 | |
86beb976 MCC |
345 | struct device_attribute { |
346 | struct attribute attr; | |
347 | ssize_t (*show)(struct device *dev, struct device_attribute *attr, | |
348 | char *buf); | |
349 | ssize_t (*store)(struct device *dev, struct device_attribute *attr, | |
350 | const char *buf, size_t count); | |
351 | }; | |
1da177e4 | 352 | |
86beb976 | 353 | Declaring:: |
1da177e4 | 354 | |
86beb976 | 355 | DEVICE_ATTR(_name, _mode, _show, _store); |
1da177e4 | 356 | |
86beb976 | 357 | Creation/Removal:: |
1da177e4 | 358 | |
86beb976 MCC |
359 | int device_create_file(struct device *dev, const struct device_attribute * attr); |
360 | void device_remove_file(struct device *dev, const struct device_attribute * attr); | |
1da177e4 LT |
361 | |
362 | ||
86beb976 MCC |
363 | bus drivers (include/linux/device.h) |
364 | ------------------------------------ | |
365 | Structure:: | |
1da177e4 | 366 | |
86beb976 MCC |
367 | struct bus_attribute { |
368 | struct attribute attr; | |
369 | ssize_t (*show)(struct bus_type *, char * buf); | |
370 | ssize_t (*store)(struct bus_type *, const char * buf, size_t count); | |
371 | }; | |
1da177e4 | 372 | |
86beb976 | 373 | Declaring:: |
1da177e4 | 374 | |
86beb976 MCC |
375 | static BUS_ATTR_RW(name); |
376 | static BUS_ATTR_RO(name); | |
377 | static BUS_ATTR_WO(name); | |
1da177e4 | 378 | |
86beb976 | 379 | Creation/Removal:: |
1da177e4 | 380 | |
86beb976 MCC |
381 | int bus_create_file(struct bus_type *, struct bus_attribute *); |
382 | void bus_remove_file(struct bus_type *, struct bus_attribute *); | |
1da177e4 LT |
383 | |
384 | ||
86beb976 MCC |
385 | device drivers (include/linux/device.h) |
386 | --------------------------------------- | |
1da177e4 | 387 | |
86beb976 | 388 | Structure:: |
1da177e4 | 389 | |
86beb976 MCC |
390 | struct driver_attribute { |
391 | struct attribute attr; | |
392 | ssize_t (*show)(struct device_driver *, char * buf); | |
393 | ssize_t (*store)(struct device_driver *, const char * buf, | |
394 | size_t count); | |
395 | }; | |
1da177e4 | 396 | |
86beb976 | 397 | Declaring:: |
1da177e4 | 398 | |
86beb976 MCC |
399 | DRIVER_ATTR_RO(_name) |
400 | DRIVER_ATTR_RW(_name) | |
1da177e4 | 401 | |
86beb976 | 402 | Creation/Removal:: |
1da177e4 | 403 | |
86beb976 MCC |
404 | int driver_create_file(struct device_driver *, const struct driver_attribute *); |
405 | void driver_remove_file(struct device_driver *, const struct driver_attribute *); | |
1da177e4 LT |
406 | |
407 | ||
86028619 BVA |
408 | Documentation |
409 | ~~~~~~~~~~~~~ | |
410 | ||
411 | The sysfs directory structure and the attributes in each directory define an | |
412 | ABI between the kernel and user space. As for any ABI, it is important that | |
413 | this ABI is stable and properly documented. All new sysfs attributes must be | |
414 | documented in Documentation/ABI. See also Documentation/ABI/README for more | |
415 | information. |