1 .. SPDX-License-Identifier: GPL-2.0
2
3 =====================================================
4 sysfs - _The_ filesystem for exporting kernel objects
5 =====================================================
6
7 Patrick Mochel <mochel@osdl.org>
8
9 Mike Murphy <mamurph@cs.clemson.edu>
10
11 :Revised: 16 August 2011
12 :Original: 10 January 2003
13
14
15 What it is
16 ~~~~~~~~~~
17
18 sysfs is a RAM-based filesystem initially based on ramfs. It provides
19 a means to export kernel data structures, their attributes, and the
20 linkages between them to userspace.
21
22 sysfs is tied inherently to the kobject infrastructure. Please read
23 Documentation/core-api/kobject.rst for more information concerning the kobject
24 interface.
25
26
27 Using sysfs
28 ~~~~~~~~~~~
29
30 sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
31 it by doing::
32
33 mount -t sysfs sysfs /sys
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
44 belong to.
45
46 sysfs internally stores a pointer to the kobject that implements a
47 directory in the kernfs_node object associated with the directory. In
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().
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
63 per file. It is noted that it may not be efficient to contain only one
64 value per file, so it is socially acceptable to express an array of
65 values of the same type.
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
69 you publicly humiliated and your code rewritten without notice.
70
71
72 An attribute definition is simply::
73
74 struct attribute {
75 char *name;
76 struct module *owner;
77 umode_t mode;
78 };
79
80
81 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
82 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
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
88 a specific object type.
89
90 For example, the driver model defines struct device_attribute like::
91
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 };
99
100 int device_create_file(struct device *, const struct device_attribute *);
101 void device_remove_file(struct device *, const struct device_attribute *);
102
103 It also defines this helper for defining device attributes::
104
105 #define DEVICE_ATTR(_name, _mode, _show, _store) \
106 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
107
108 For example, declaring::
109
110 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
111
112 is equivalent to doing::
113
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 };
122
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:
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
139 0200 that is root write access only.
140 __ATTR_RO_MODE(name, mode):
141 for more restrictive RO access; currently
142 only use case is the EFI System Resource Table
143 (see drivers/firmware/efi/esrt.c)
144 __ATTR_RW(name):
145 assumes default name_show, name_store and setting
146 mode to 0644.
147 __ATTR_NULL:
148 which sets the name to NULL and is used as end of list
149 indicator (see: kernel/workqueue.c)
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
156 show and store methods of the attribute owners::
157
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 };
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
170 calls the associated methods.
171
172
173 To illustrate::
174
175 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
176
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);
181 struct device *dev = kobj_to_dev(kobj);
182 ssize_t ret = -EIO;
183
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 }
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
200 simple as those defined for device attributes::
201
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);
205
206 IOW, they should take only an object, an attribute, and a buffer as parameters.
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
212 implementations:
213
214 - On read(2), the show() method should fill the entire buffer.
215 Recall that an attribute should only be exporting one value, or an
216 array of similar values, so this shouldn't be that expensive.
217
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.
222
223 - On write(2), sysfs expects the entire buffer to be passed during the
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
228 When writing sysfs files, userspace processes should first read the
229 entire file, modify the values it wishes to change, then write the
230 entire buffer back.
231
232 Attribute method implementations should operate on an identical
233 buffer when reading and writing values.
234
235 Other notes:
236
237 - Writing causes the show() method to be rearmed regardless of current
238 file position.
239
240 - The buffer will always be PAGE_SIZE bytes in length. On x86, this
241 is 4096.
242
243 - show() methods should return the number of bytes printed into the
244 buffer.
245
246 - show() should only use sysfs_emit() or sysfs_emit_at() when formatting
247 the value to be returned to user space.
248
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.
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
256 reference 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.
259
260
261 A very simple (and naive) implementation of a device attribute is::
262
263 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
264 char *buf)
265 {
266 return sysfs_emit(buf, "%s\n", dev->name);
267 }
268
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 }
276
277 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
278
279
280 (Note that the real implementation doesn't allow userspace to set the
281 name for a device.)
282
283
284 Top Level Directory Layout
285 ~~~~~~~~~~~~~~~~~~~~~~~~~~
286
287 The sysfs directory arrangement exposes the relationship of kernel
288 data structures.
289
290 The top level sysfs directory looks like::
291
292 block/
293 bus/
294 class/
295 dev/
296 devices/
297 firmware/
298 fs/
299 hypervisor/
300 kernel/
301 module/
302 net/
303 power/
304
305 devices/ contains a filesystem representation of the device tree. It maps
306 directly to the internal kernel device tree, which is a hierarchy of
307 struct device.
308
309 bus/ contains flat directory layout of the various bus types in the
310 kernel. Each bus's directory contains two subdirectories::
311
312 devices/
313 drivers/
314
315 devices/ contains symlinks for each device discovered in the system
316 that point to the device's directory under root/.
317
318 drivers/ contains a directory for each device driver that is loaded
319 for devices on that particular bus (this assumes that drivers do not
320 span multiple bus types).
321
322 fs/ contains a directory for some filesystems. Currently each
323 filesystem wanting to export attributes must create its own hierarchy
324 below fs/ (see ./fuse.rst for an example).
325
326 module/ contains parameter values and state information for all
327 loaded system modules, for both builtin and loadable modules.
328
329 dev/ contains two directories: char/ and block/. Inside these two
330 directories there are symlinks named <major>:<minor>. These symlinks
331 point to the sysfs directory for the given device. /sys/dev provides a
332 quick way to lookup the sysfs interface for a device from the result of
333 a stat(2) operation.
334
335 More information on driver-model specific features can be found in
336 Documentation/driver-api/driver-model/.
337
338
339 TODO: Finish this section.
340
341
342 Current Interfaces
343 ~~~~~~~~~~~~~~~~~~
344
345 The following interface layers currently exist in sysfs.
346
347
348 devices (include/linux/device.h)
349 --------------------------------
350 Structure::
351
352 struct device_attribute {
353 struct attribute attr;
354 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
355 char *buf);
356 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
357 const char *buf, size_t count);
358 };
359
360 Declaring::
361
362 DEVICE_ATTR(_name, _mode, _show, _store);
363
364 Creation/Removal::
365
366 int device_create_file(struct device *dev, const struct device_attribute * attr);
367 void device_remove_file(struct device *dev, const struct device_attribute * attr);
368
369
370 bus drivers (include/linux/device.h)
371 ------------------------------------
372 Structure::
373
374 struct bus_attribute {
375 struct attribute attr;
376 ssize_t (*show)(const struct bus_type *, char * buf);
377 ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);
378 };
379
380 Declaring::
381
382 static BUS_ATTR_RW(name);
383 static BUS_ATTR_RO(name);
384 static BUS_ATTR_WO(name);
385
386 Creation/Removal::
387
388 int bus_create_file(struct bus_type *, struct bus_attribute *);
389 void bus_remove_file(struct bus_type *, struct bus_attribute *);
390
391
392 device drivers (include/linux/device.h)
393 ---------------------------------------
394
395 Structure::
396
397 struct driver_attribute {
398 struct attribute attr;
399 ssize_t (*show)(struct device_driver *, char * buf);
400 ssize_t (*store)(struct device_driver *, const char * buf,
401 size_t count);
402 };
403
404 Declaring::
405
406 DRIVER_ATTR_RO(_name)
407 DRIVER_ATTR_RW(_name)
408
409 Creation/Removal::
410
411 int driver_create_file(struct device_driver *, const struct driver_attribute *);
412 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
413
414
415 Documentation
416 ~~~~~~~~~~~~~
417
418 The sysfs directory structure and the attributes in each directory define an
419 ABI between the kernel and user space. As for any ABI, it is important that
420 this ABI is stable and properly documented. All new sysfs attributes must be
421 documented in Documentation/ABI. See also Documentation/ABI/README for more
422 information.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.