Merge tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi
[linux-block.git] / Documentation / filesystems / sysfs.rst
CommitLineData
86beb976 1.. SPDX-License-Identifier: GPL-2.0
1da177e4 2
86beb976
MCC
3=====================================================
4sysfs - _The_ filesystem for exporting kernel objects
5=====================================================
1da177e4
LT
6
7Patrick Mochel <mochel@osdl.org>
86beb976 8
f8a1af6b 9Mike Murphy <mamurph@cs.clemson.edu>
1da177e4 10
86beb976
MCC
11:Revised: 16 August 2011
12:Original: 10 January 2003
1da177e4
LT
13
14
15What it is:
16~~~~~~~~~~~
17
18sysfs is a ram-based filesystem initially based on ramfs. It provides
86beb976
MCC
19a means to export kernel data structures, their attributes, and the
20linkages between them to userspace.
1da177e4
LT
21
22sysfs is tied inherently to the kobject infrastructure. Please read
0c1bc6b8 23Documentation/core-api/kobject.rst for more information concerning the kobject
86beb976 24interface.
1da177e4
LT
25
26
27Using sysfs
28~~~~~~~~~~~
29
a39ea210 30sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
86beb976 31it by doing::
1da177e4 32
86beb976 33 mount -t sysfs sysfs /sys
1da177e4
LT
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
86beb976 44belong to.
1da177e4 45
5480bcdd 46Sysfs internally stores a pointer to the kobject that implements a
390b421c 47directory in the kernfs_node object associated with the directory. In
5480bcdd
BVA
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().
1da177e4
LT
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
f8c34f98 63per file. It is noted that it may not be efficient to contain only one
1da177e4 64value per file, so it is socially acceptable to express an array of
86beb976 65values of the same type.
1da177e4
LT
66
67Mixing types, expressing multiple lines of data, and doing fancy
68formatting of data is heavily frowned upon. Doing these things may get
86beb976 69you publicly humiliated and your code rewritten without notice.
1da177e4
LT
70
71
86beb976 72An 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
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
86beb976 88a specific object type.
1da177e4 89
86beb976 90For 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 103It 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 108For example, declaring::
1da177e4 109
86beb976 110 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
1da177e4 111
86beb976 112is 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
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:
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
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
86beb976 156show 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
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
86beb976 170calls the associated methods.
1da177e4
LT
171
172
86beb976 173To 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
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
86beb976 200simple 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 206IOW, they should take only an object, an attribute, and a buffer as parameters.
1da177e4
LT
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
86beb976 212implementations:
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
235Other 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 261A 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
281name for a device.)
282
283
284Top Level Directory Layout
285~~~~~~~~~~~~~~~~~~~~~~~~~~
286
287The sysfs directory arrangement exposes the relationship of kernel
86beb976 288data structures.
1da177e4 289
86beb976 290The 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
301devices/ contains a filesystem representation of the device tree. It maps
302directly to the internal kernel device tree, which is a hierarchy of
86beb976 303struct device.
1da177e4
LT
304
305bus/ contains flat directory layout of the various bus types in the
86beb976 306kernel. Each bus's directory contains two subdirectories::
1da177e4
LT
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
c86d90df
MS
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
e105b8bf
DW
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.
1da177e4
LT
327
328More information can driver-model specific features can be found in
fe34c89d 329Documentation/driver-api/driver-model/.
1da177e4
LT
330
331
332TODO: Finish this section.
333
334
335Current Interfaces
336~~~~~~~~~~~~~~~~~~
337
338The following interface layers currently exist in sysfs:
339
340
86beb976
MCC
341devices (include/linux/device.h)
342--------------------------------
343Structure::
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 353Declaring::
1da177e4 354
86beb976 355 DEVICE_ATTR(_name, _mode, _show, _store);
1da177e4 356
86beb976 357Creation/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
363bus drivers (include/linux/device.h)
364------------------------------------
365Structure::
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 373Declaring::
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 379Creation/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
385device drivers (include/linux/device.h)
386---------------------------------------
1da177e4 387
86beb976 388Structure::
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 397Declaring::
1da177e4 398
86beb976
MCC
399 DRIVER_ATTR_RO(_name)
400 DRIVER_ATTR_RW(_name)
1da177e4 401
86beb976 402Creation/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
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.