blob: 931c806642c5939a61c5f6ad01c7b9fedbd4a0a9 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2sysfs - _The_ filesystem for exporting kernel objects.
3
4Patrick Mochel <mochel@osdl.org>
Mike Murphyf8a1af62009-02-22 01:19:23 -05005Mike Murphy <mamurph@cs.clemson.edu>
Linus Torvalds1da177e2005-04-16 15:20:36 -07006
Mike Murphyf8a1af62009-02-22 01:19:23 -05007Revised: 22 February 2009
8Original: 10 January 2003
Linus Torvalds1da177e2005-04-16 15:20:36 -07009
10
11What it is:
12~~~~~~~~~~~
13
14sysfs is a ram-based filesystem initially based on ramfs. It provides
15a means to export kernel data structures, their attributes, and the
16linkages between them to userspace.
17
18sysfs is tied inherently to the kobject infrastructure. Please read
19Documentation/kobject.txt for more information concerning the kobject
20interface.
21
22
23Using sysfs
24~~~~~~~~~~~
25
Lucian Adrian Grijincua39ea212009-07-27 09:06:42 -070026sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
27it by doing:
Linus Torvalds1da177e2005-04-16 15:20:36 -070028
29 mount -t sysfs sysfs /sys
30
31
32Directory Creation
33~~~~~~~~~~~~~~~~~~
34
35For every kobject that is registered with the system, a directory is
36created for it in sysfs. That directory is created as a subdirectory
37of the kobject's parent, expressing internal object hierarchies to
38userspace. Top-level directories in sysfs represent the common
39ancestors of object hierarchies; i.e. the subsystems the objects
40belong to.
41
42Sysfs internally stores the kobject that owns the directory in the
43->d_fsdata pointer of the directory's dentry. This allows sysfs to do
44reference counting directly on the kobject when the file is opened and
45closed.
46
47
48Attributes
49~~~~~~~~~~
50
51Attributes can be exported for kobjects in the form of regular files in
52the filesystem. Sysfs forwards file I/O operations to methods defined
53for the attributes, providing a means to read and write kernel
54attributes.
55
56Attributes should be ASCII text files, preferably with only one value
Shaun Zinckf8c34f92007-10-20 02:39:43 +020057per file. It is noted that it may not be efficient to contain only one
Linus Torvalds1da177e2005-04-16 15:20:36 -070058value per file, so it is socially acceptable to express an array of
59values of the same type.
60
61Mixing types, expressing multiple lines of data, and doing fancy
62formatting of data is heavily frowned upon. Doing these things may get
63you publically humiliated and your code rewritten without notice.
64
65
66An attribute definition is simply:
67
68struct attribute {
69 char * name;
Mike Murphyf8a1af62009-02-22 01:19:23 -050070 struct module *owner;
Linus Torvalds1da177e2005-04-16 15:20:36 -070071 mode_t mode;
72};
73
74
Mike Murphyf8a1af62009-02-22 01:19:23 -050075int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
76void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
Linus Torvalds1da177e2005-04-16 15:20:36 -070077
78
79A bare attribute contains no means to read or write the value of the
80attribute. Subsystems are encouraged to define their own attribute
81structure and wrapper functions for adding and removing attributes for
82a specific object type.
83
84For example, the driver model defines struct device_attribute like:
85
86struct device_attribute {
Mike Murphyf8a1af62009-02-22 01:19:23 -050087 struct attribute attr;
88 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
89 char *buf);
90 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
91 const char *buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -070092};
93
Phil Carmody26579ab2009-12-18 15:34:19 +020094int device_create_file(struct device *, const struct device_attribute *);
95void device_remove_file(struct device *, const struct device_attribute *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070096
97It also defines this helper for defining device attributes:
98
Mike Murphyf8a1af62009-02-22 01:19:23 -050099#define DEVICE_ATTR(_name, _mode, _show, _store) \
100struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101
102For example, declaring
103
Jan Veldeman91e49002005-07-31 13:12:10 +0200104static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700105
106is equivalent to doing:
107
108static struct device_attribute dev_attr_foo = {
109 .attr = {
110 .name = "foo",
Jan Veldeman91e49002005-07-31 13:12:10 +0200111 .mode = S_IWUSR | S_IRUGO,
Mike Murphyf8a1af62009-02-22 01:19:23 -0500112 .show = show_foo,
113 .store = store_foo,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700114 },
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115};
116
117
118Subsystem-Specific Callbacks
119~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120
121When a subsystem defines a new attribute type, it must implement a
122set of sysfs operations for forwarding read and write calls to the
123show and store methods of the attribute owners.
124
125struct sysfs_ops {
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200126 ssize_t (*show)(struct kobject *, struct attribute *, char *);
127 ssize_t (*store)(struct kobject *, struct attribute *, const char *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700128};
129
130[ Subsystems should have already defined a struct kobj_type as a
131descriptor for this type, which is where the sysfs_ops pointer is
132stored. See the kobject documentation for more information. ]
133
134When a file is read or written, sysfs calls the appropriate method
135for the type. The method then translates the generic struct kobject
136and struct attribute pointers to the appropriate pointer types, and
137calls the associated methods.
138
139
140To illustrate:
141
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200142#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143#define to_dev(d) container_of(d, struct device, kobj)
144
145static ssize_t
146dev_attr_show(struct kobject * kobj, struct attribute * attr, char * buf)
147{
148 struct device_attribute * dev_attr = to_dev_attr(attr);
149 struct device * dev = to_dev(kobj);
150 ssize_t ret = 0;
151
152 if (dev_attr->show)
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200153 ret = dev_attr->show(dev, buf);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700154 return ret;
155}
156
157
158
159Reading/Writing Attribute Data
160~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161
162To read or write attributes, show() or store() methods must be
163specified when declaring the attribute. The method types should be as
164simple as those defined for device attributes:
165
Mike Murphyf8a1af62009-02-22 01:19:23 -0500166ssize_t (*show)(struct device * dev, struct device_attribute * attr,
167 char * buf);
168ssize_t (*store)(struct device * dev, struct device_attribute * attr,
169 const char * buf);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170
Mike Murphyf8a1af62009-02-22 01:19:23 -0500171IOW, they should take only an object, an attribute, and a buffer as parameters.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172
173
174sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
175method. Sysfs will call the method exactly once for each read or
176write. This forces the following behavior on the method
177implementations:
178
179- On read(2), the show() method should fill the entire buffer.
180 Recall that an attribute should only be exporting one value, or an
181 array of similar values, so this shouldn't be that expensive.
182
Dan Williams2424b5d2008-04-07 15:35:01 -0700183 This allows userspace to do partial reads and forward seeks
184 arbitrarily over the entire file at will. If userspace seeks back to
185 zero or does a pread(2) with an offset of '0' the show() method will
186 be called again, rearmed, to fill the buffer.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700187
188- On write(2), sysfs expects the entire buffer to be passed during the
189 first write. Sysfs then passes the entire buffer to the store()
190 method.
191
192 When writing sysfs files, userspace processes should first read the
193 entire file, modify the values it wishes to change, then write the
194 entire buffer back.
195
196 Attribute method implementations should operate on an identical
197 buffer when reading and writing values.
198
199Other notes:
200
Dan Williams2424b5d2008-04-07 15:35:01 -0700201- Writing causes the show() method to be rearmed regardless of current
202 file position.
203
Linus Torvalds1da177e2005-04-16 15:20:36 -0700204- The buffer will always be PAGE_SIZE bytes in length. On i386, this
205 is 4096.
206
207- show() methods should return the number of bytes printed into the
208 buffer. This is the return value of snprintf().
209
210- show() should always use snprintf().
211
212- store() should return the number of bytes used from the buffer. This
213 can be done using strlen().
214
215- show() or store() can always return errors. If a bad value comes
216 through, be sure to return an error.
217
218- The object passed to the methods will be pinned in memory via sysfs
219 referencing counting its embedded object. However, the physical
220 entity (e.g. device) the object represents may not be present. Be
221 sure to have a way to check this, if necessary.
222
223
224A very simple (and naive) implementation of a device attribute is:
225
Yani Ioannou3eb8c782005-05-17 06:40:28 -0400226static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700227{
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200228 return snprintf(buf, PAGE_SIZE, "%s\n", dev->name);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700229}
230
231static ssize_t store_name(struct device * dev, const char * buf)
232{
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200233 sscanf(buf, "%20s", dev->name);
234 return strnlen(buf, PAGE_SIZE);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235}
236
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200237static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238
239
240(Note that the real implementation doesn't allow userspace to set the
241name for a device.)
242
243
244Top Level Directory Layout
245~~~~~~~~~~~~~~~~~~~~~~~~~~
246
247The sysfs directory arrangement exposes the relationship of kernel
248data structures.
249
Matt LaPlantefff92892006-10-03 22:47:42 +0200250The top level sysfs directory looks like:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700251
252block/
253bus/
254class/
Dan Williamse105b8b2008-04-21 10:51:07 -0700255dev/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700256devices/
257firmware/
258net/
Miklos Szeredic86d90d2006-04-26 10:49:26 +0200259fs/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700260
261devices/ contains a filesystem representation of the device tree. It maps
262directly to the internal kernel device tree, which is a hierarchy of
263struct device.
264
265bus/ contains flat directory layout of the various bus types in the
266kernel. Each bus's directory contains two subdirectories:
267
268 devices/
269 drivers/
270
271devices/ contains symlinks for each device discovered in the system
272that point to the device's directory under root/.
273
274drivers/ contains a directory for each device driver that is loaded
275for devices on that particular bus (this assumes that drivers do not
276span multiple bus types).
277
Miklos Szeredic86d90d2006-04-26 10:49:26 +0200278fs/ contains a directory for some filesystems. Currently each
279filesystem wanting to export attributes must create its own hierarchy
280below fs/ (see ./fuse.txt for an example).
281
Dan Williamse105b8b2008-04-21 10:51:07 -0700282dev/ contains two directories char/ and block/. Inside these two
283directories there are symlinks named <major>:<minor>. These symlinks
284point to the sysfs directory for the given device. /sys/dev provides a
285quick way to lookup the sysfs interface for a device from the result of
286a stat(2) operation.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700287
288More information can driver-model specific features can be found in
289Documentation/driver-model/.
290
291
292TODO: Finish this section.
293
294
295Current Interfaces
296~~~~~~~~~~~~~~~~~~
297
298The following interface layers currently exist in sysfs:
299
300
301- devices (include/linux/device.h)
302----------------------------------
303Structure:
304
305struct device_attribute {
Mike Murphyf8a1af62009-02-22 01:19:23 -0500306 struct attribute attr;
307 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
308 char *buf);
309 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
310 const char *buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700311};
312
313Declaring:
314
Mike Murphyf8a1af62009-02-22 01:19:23 -0500315DEVICE_ATTR(_name, _mode, _show, _store);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700316
317Creation/Removal:
318
Phil Carmody26579ab2009-12-18 15:34:19 +0200319int device_create_file(struct device *dev, const struct device_attribute * attr);
320void device_remove_file(struct device *dev, const struct device_attribute * attr);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700321
322
323- bus drivers (include/linux/device.h)
324--------------------------------------
325Structure:
326
327struct bus_attribute {
328 struct attribute attr;
329 ssize_t (*show)(struct bus_type *, char * buf);
330 ssize_t (*store)(struct bus_type *, const char * buf);
331};
332
333Declaring:
334
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200335BUS_ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700336
337Creation/Removal:
338
339int bus_create_file(struct bus_type *, struct bus_attribute *);
340void bus_remove_file(struct bus_type *, struct bus_attribute *);
341
342
343- device drivers (include/linux/device.h)
344-----------------------------------------
345
346Structure:
347
348struct driver_attribute {
349 struct attribute attr;
350 ssize_t (*show)(struct device_driver *, char * buf);
Mike Murphyf8a1af62009-02-22 01:19:23 -0500351 ssize_t (*store)(struct device_driver *, const char * buf,
352 size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700353};
354
355Declaring:
356
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200357DRIVER_ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700358
359Creation/Removal:
360
Phil Carmody099c2f22009-12-18 15:34:21 +0200361int driver_create_file(struct device_driver *, const struct driver_attribute *);
362void driver_remove_file(struct device_driver *, const struct driver_attribute *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700363
364