1.. SPDX-License-Identifier: GPL-2.0
2
3=====================================================
4sysfs - _The_ filesystem for exporting kernel objects
5=====================================================
6
7Patrick Mochel	<mochel@osdl.org>
8
9Mike Murphy <mamurph@cs.clemson.edu>
10
11:Revised:    16 August 2011
12:Original:   10 January 2003
13
14
15What it is
16~~~~~~~~~~
17
18sysfs is a RAM-based filesystem initially based on ramfs. It provides
19a means to export kernel data structures, their attributes, and the
20linkages between them to userspace.
21
22sysfs is tied inherently to the kobject infrastructure. Please read
23Documentation/core-api/kobject.rst for more information concerning the kobject
24interface.
25
26
27Using sysfs
28~~~~~~~~~~~
29
30sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
31it by doing::
32
33    mount -t sysfs sysfs /sys
34
35
36Directory Creation
37~~~~~~~~~~~~~~~~~~
38
39For every kobject that is registered with the system, a directory is
40created for it in sysfs. That directory is created as a subdirectory
41of the kobject's parent, expressing internal object hierarchies to
42userspace. Top-level directories in sysfs represent the common
43ancestors of object hierarchies; i.e. the subsystems the objects
44belong to.
45
46sysfs internally stores a pointer to the kobject that implements a
47directory in the kernfs_node object associated with the directory. In
48the past this kobject pointer has been used by sysfs to do reference
49counting directly on the kobject whenever the file is opened or closed.
50With the current sysfs implementation the kobject reference count is
51only modified directly by the function sysfs_schedule_callback().
52
53
54Attributes
55~~~~~~~~~~
56
57Attributes can be exported for kobjects in the form of regular files in
58the filesystem. sysfs forwards file I/O operations to methods defined
59for the attributes, providing a means to read and write kernel
60attributes.
61
62Attributes should be ASCII text files, preferably with only one value
63per file. It is noted that it may not be efficient to contain only one
64value per file, so it is socially acceptable to express an array of
65values of the same type.
66
67Mixing types, expressing multiple lines of data, and doing fancy
68formatting of data is heavily frowned upon. Doing these things may get
69you publicly humiliated and your code rewritten without notice.
70
71
72An 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
85A bare attribute contains no means to read or write the value of the
86attribute. Subsystems are encouraged to define their own attribute
87structure and wrapper functions for adding and removing attributes for
88a specific object type.
89
90For 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
103It 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
108For example, declaring::
109
110    static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
111
112is 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
123Note as stated in include/linux/kernel.h "OTHER_WRITABLE?  Generally
124considered a bad idea." so trying to set a sysfs file writable for
125everyone will fail reverting to RO mode for "Others".
126
127For the common cases sysfs.h provides convenience macros to make
128defining attributes easier as well as making code more concise and
129readable. The above case could be shortened to:
130
131static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
132
133the 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
151Subsystem-Specific Callbacks
152~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153
154When a subsystem defines a new attribute type, it must implement a
155set of sysfs operations for forwarding read and write calls to the
156show 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
164descriptor for this type, which is where the sysfs_ops pointer is
165stored. See the kobject documentation for more information. ]
166
167When a file is read or written, sysfs calls the appropriate method
168for the type. The method then translates the generic struct kobject
169and struct attribute pointers to the appropriate pointer types, and
170calls the associated methods.
171
172
173To 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
195Reading/Writing Attribute Data
196~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197
198To read or write attributes, show() or store() methods must be
199specified when declaring the attribute. The method types should be as
200simple 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
206IOW, they should take only an object, an attribute, and a buffer as parameters.
207
208
209sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
210method. sysfs will call the method exactly once for each read or
211write. This forces the following behavior on the method
212implementations:
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
235Other 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
261A 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
281name for a device.)
282
283
284Top Level Directory Layout
285~~~~~~~~~~~~~~~~~~~~~~~~~~
286
287The sysfs directory arrangement exposes the relationship of kernel
288data structures.
289
290The 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
305devices/ contains a filesystem representation of the device tree. It maps
306directly to the internal kernel device tree, which is a hierarchy of
307struct device.
308
309bus/ contains flat directory layout of the various bus types in the
310kernel. Each bus's directory contains two subdirectories::
311
312	devices/
313	drivers/
314
315devices/ contains symlinks for each device discovered in the system
316that point to the device's directory under root/.
317
318drivers/ contains a directory for each device driver that is loaded
319for devices on that particular bus (this assumes that drivers do not
320span multiple bus types).
321
322fs/ contains a directory for some filesystems.  Currently each
323filesystem wanting to export attributes must create its own hierarchy
324below fs/ (see ./fuse.rst for an example).
325
326module/ contains parameter values and state information for all
327loaded system modules, for both builtin and loadable modules.
328
329dev/ contains two directories: char/ and block/. Inside these two
330directories there are symlinks named <major>:<minor>.  These symlinks
331point to the sysfs directory for the given device.  /sys/dev provides a
332quick way to lookup the sysfs interface for a device from the result of
333a stat(2) operation.
334
335More information on driver-model specific features can be found in
336Documentation/driver-api/driver-model/.
337
338
339TODO: Finish this section.
340
341
342Current Interfaces
343~~~~~~~~~~~~~~~~~~
344
345The following interface layers currently exist in sysfs.
346
347
348devices (include/linux/device.h)
349--------------------------------
350Structure::
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
360Declaring::
361
362    DEVICE_ATTR(_name, _mode, _show, _store);
363
364Creation/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
370bus drivers (include/linux/device.h)
371------------------------------------
372Structure::
373
374    struct bus_attribute {
375	    struct attribute        attr;
376	    ssize_t (*show)(struct bus_type *, char * buf);
377	    ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
378    };
379
380Declaring::
381
382    static BUS_ATTR_RW(name);
383    static BUS_ATTR_RO(name);
384    static BUS_ATTR_WO(name);
385
386Creation/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
392device drivers (include/linux/device.h)
393---------------------------------------
394
395Structure::
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
404Declaring::
405
406    DRIVER_ATTR_RO(_name)
407    DRIVER_ATTR_RW(_name)
408
409Creation/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
415Documentation
416~~~~~~~~~~~~~
417
418The sysfs directory structure and the attributes in each directory define an
419ABI between the kernel and user space. As for any ABI, it is important that
420this ABI is stable and properly documented. All new sysfs attributes must be
421documented in Documentation/ABI. See also Documentation/ABI/README for more
422information.
423