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	         fore 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 i386, 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  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.
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    net/
299    fs/
300
301devices/ contains a filesystem representation of the device tree. It maps
302directly to the internal kernel device tree, which is a hierarchy of
303struct device.
304
305bus/ contains flat directory layout of the various bus types in the
306kernel. Each bus's directory contains two subdirectories::
307
308	devices/
309	drivers/
310
311devices/ contains symlinks for each device discovered in the system
312that point to the device's directory under root/.
313
314drivers/ contains a directory for each device driver that is loaded
315for devices on that particular bus (this assumes that drivers do not
316span multiple bus types).
317
318fs/ contains a directory for some filesystems.  Currently each
319filesystem wanting to export attributes must create its own hierarchy
320below fs/ (see ./fuse.txt for an example).
321
322dev/ contains two directories char/ and block/. Inside these two
323directories there are symlinks named <major>:<minor>.  These symlinks
324point to the sysfs directory for the given device.  /sys/dev provides a
325quick way to lookup the sysfs interface for a device from the result of
326a stat(2) operation.
327
328More information can driver-model specific features can be found in
329Documentation/driver-api/driver-model/.
330
331
332TODO: Finish this section.
333
334
335Current Interfaces
336~~~~~~~~~~~~~~~~~~
337
338The following interface layers currently exist in sysfs:
339
340
341devices (include/linux/device.h)
342--------------------------------
343Structure::
344
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    };
352
353Declaring::
354
355    DEVICE_ATTR(_name, _mode, _show, _store);
356
357Creation/Removal::
358
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);
361
362
363bus drivers (include/linux/device.h)
364------------------------------------
365Structure::
366
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    };
372
373Declaring::
374
375    static BUS_ATTR_RW(name);
376    static BUS_ATTR_RO(name);
377    static BUS_ATTR_WO(name);
378
379Creation/Removal::
380
381    int bus_create_file(struct bus_type *, struct bus_attribute *);
382    void bus_remove_file(struct bus_type *, struct bus_attribute *);
383
384
385device drivers (include/linux/device.h)
386---------------------------------------
387
388Structure::
389
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    };
396
397Declaring::
398
399    DRIVER_ATTR_RO(_name)
400    DRIVER_ATTR_RW(_name)
401
402Creation/Removal::
403
404    int driver_create_file(struct device_driver *, const struct driver_attribute *);
405    void driver_remove_file(struct device_driver *, const struct driver_attribute *);
406
407
408Documentation
409~~~~~~~~~~~~~
410
411The sysfs directory structure and the attributes in each directory define an
412ABI between the kernel and user space. As for any ABI, it is important that
413this ABI is stable and properly documented. All new sysfs attributes must be
414documented in Documentation/ABI. See also Documentation/ABI/README for more
415information.
416