blob: a6619b7064b9e679b887d31ec85301d300c088f5 [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
Bart Van Assche86028612011-08-16 18:42:22 +02007Revised: 16 August 2011
Mike Murphyf8a1af62009-02-22 01:19:23 -05008Original: 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
Bart Van Assche5480bcd2010-12-21 13:09:23 +010042Sysfs internally stores a pointer to the kobject that implements a
43directory in the sysfs_dirent object associated with the directory. In
44the past this kobject pointer has been used by sysfs to do reference
45counting directly on the kobject whenever the file is opened or closed.
46With the current sysfs implementation the kobject reference count is
47only modified directly by the function sysfs_schedule_callback().
Linus Torvalds1da177e2005-04-16 15:20:36 -070048
49
50Attributes
51~~~~~~~~~~
52
53Attributes can be exported for kobjects in the form of regular files in
54the filesystem. Sysfs forwards file I/O operations to methods defined
55for the attributes, providing a means to read and write kernel
56attributes.
57
58Attributes should be ASCII text files, preferably with only one value
Shaun Zinckf8c34f92007-10-20 02:39:43 +020059per file. It is noted that it may not be efficient to contain only one
Linus Torvalds1da177e2005-04-16 15:20:36 -070060value per file, so it is socially acceptable to express an array of
61values of the same type.
62
63Mixing types, expressing multiple lines of data, and doing fancy
64formatting of data is heavily frowned upon. Doing these things may get
Lucas De Marchi25985ed2011-03-30 22:57:33 -030065you publicly humiliated and your code rewritten without notice.
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
67
68An attribute definition is simply:
69
70struct attribute {
71 char * name;
Mike Murphyf8a1af62009-02-22 01:19:23 -050072 struct module *owner;
Al Virofaef2b62011-07-24 23:44:53 -040073 umode_t mode;
Linus Torvalds1da177e2005-04-16 15:20:36 -070074};
75
76
Mike Murphyf8a1af62009-02-22 01:19:23 -050077int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
78void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
Linus Torvalds1da177e2005-04-16 15:20:36 -070079
80
81A bare attribute contains no means to read or write the value of the
82attribute. Subsystems are encouraged to define their own attribute
83structure and wrapper functions for adding and removing attributes for
84a specific object type.
85
86For example, the driver model defines struct device_attribute like:
87
88struct device_attribute {
Mike Murphyf8a1af62009-02-22 01:19:23 -050089 struct attribute attr;
90 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
91 char *buf);
92 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
93 const char *buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -070094};
95
Phil Carmody26579ab2009-12-18 15:34:19 +020096int device_create_file(struct device *, const struct device_attribute *);
97void device_remove_file(struct device *, const struct device_attribute *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070098
99It also defines this helper for defining device attributes:
100
Mike Murphyf8a1af62009-02-22 01:19:23 -0500101#define DEVICE_ATTR(_name, _mode, _show, _store) \
102struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700103
104For example, declaring
105
Jan Veldeman91e49002005-07-31 13:12:10 +0200106static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700107
108is equivalent to doing:
109
110static struct device_attribute dev_attr_foo = {
111 .attr = {
112 .name = "foo",
Jan Veldeman91e49002005-07-31 13:12:10 +0200113 .mode = S_IWUSR | S_IRUGO,
Mike Murphyf8a1af62009-02-22 01:19:23 -0500114 .show = show_foo,
115 .store = store_foo,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116 },
Linus Torvalds1da177e2005-04-16 15:20:36 -0700117};
118
119
120Subsystem-Specific Callbacks
121~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122
123When a subsystem defines a new attribute type, it must implement a
124set of sysfs operations for forwarding read and write calls to the
125show and store methods of the attribute owners.
126
127struct sysfs_ops {
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200128 ssize_t (*show)(struct kobject *, struct attribute *, char *);
Bart Van Assche30a69002010-07-20 15:22:05 -0700129 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700130};
131
132[ Subsystems should have already defined a struct kobj_type as a
133descriptor for this type, which is where the sysfs_ops pointer is
134stored. See the kobject documentation for more information. ]
135
136When a file is read or written, sysfs calls the appropriate method
137for the type. The method then translates the generic struct kobject
138and struct attribute pointers to the appropriate pointer types, and
139calls the associated methods.
140
141
142To illustrate:
143
Bart Van Assche30a69002010-07-20 15:22:05 -0700144#define to_dev(obj) container_of(obj, struct device, kobj)
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200145#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700146
Bart Van Assche30a69002010-07-20 15:22:05 -0700147static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
148 char *buf)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149{
Bart Van Assche30a69002010-07-20 15:22:05 -0700150 struct device_attribute *dev_attr = to_dev_attr(attr);
151 struct device *dev = to_dev(kobj);
152 ssize_t ret = -EIO;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153
154 if (dev_attr->show)
Bart Van Assche30a69002010-07-20 15:22:05 -0700155 ret = dev_attr->show(dev, dev_attr, buf);
156 if (ret >= (ssize_t)PAGE_SIZE) {
157 print_symbol("dev_attr_show: %s returned bad count\n",
158 (unsigned long)dev_attr->show);
159 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700160 return ret;
161}
162
163
164
165Reading/Writing Attribute Data
166~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
168To read or write attributes, show() or store() methods must be
169specified when declaring the attribute. The method types should be as
170simple as those defined for device attributes:
171
Bart Van Assche30a69002010-07-20 15:22:05 -0700172ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
173ssize_t (*store)(struct device *dev, struct device_attribute *attr,
174 const char *buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700175
Mike Murphyf8a1af62009-02-22 01:19:23 -0500176IOW, they should take only an object, an attribute, and a buffer as parameters.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700177
178
179sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
180method. Sysfs will call the method exactly once for each read or
181write. This forces the following behavior on the method
182implementations:
183
184- On read(2), the show() method should fill the entire buffer.
185 Recall that an attribute should only be exporting one value, or an
186 array of similar values, so this shouldn't be that expensive.
187
Dan Williams2424b5d2008-04-07 15:35:01 -0700188 This allows userspace to do partial reads and forward seeks
189 arbitrarily over the entire file at will. If userspace seeks back to
190 zero or does a pread(2) with an offset of '0' the show() method will
191 be called again, rearmed, to fill the buffer.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700192
193- On write(2), sysfs expects the entire buffer to be passed during the
194 first write. Sysfs then passes the entire buffer to the store()
195 method.
196
197 When writing sysfs files, userspace processes should first read the
198 entire file, modify the values it wishes to change, then write the
199 entire buffer back.
200
201 Attribute method implementations should operate on an identical
202 buffer when reading and writing values.
203
204Other notes:
205
Dan Williams2424b5d2008-04-07 15:35:01 -0700206- Writing causes the show() method to be rearmed regardless of current
207 file position.
208
Linus Torvalds1da177e2005-04-16 15:20:36 -0700209- The buffer will always be PAGE_SIZE bytes in length. On i386, this
210 is 4096.
211
212- show() methods should return the number of bytes printed into the
Bart Van Assched3f70be2010-12-21 13:09:47 +0100213 buffer. This is the return value of scnprintf().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700214
Bart Van Assched3f70be2010-12-21 13:09:47 +0100215- show() should always use scnprintf().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700216
Bart Van Assche30a69002010-07-20 15:22:05 -0700217- store() should return the number of bytes used from the buffer. If the
218 entire buffer has been used, just return the count argument.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700219
220- show() or store() can always return errors. If a bad value comes
221 through, be sure to return an error.
222
223- The object passed to the methods will be pinned in memory via sysfs
224 referencing counting its embedded object. However, the physical
225 entity (e.g. device) the object represents may not be present. Be
226 sure to have a way to check this, if necessary.
227
228
229A very simple (and naive) implementation of a device attribute is:
230
Bart Van Assche30a69002010-07-20 15:22:05 -0700231static ssize_t show_name(struct device *dev, struct device_attribute *attr,
232 char *buf)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233{
Bart Van Assched3f70be2010-12-21 13:09:47 +0100234 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235}
236
Bart Van Assche30a69002010-07-20 15:22:05 -0700237static ssize_t store_name(struct device *dev, struct device_attribute *attr,
238 const char *buf, size_t count)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700239{
Bart Van Assche30a69002010-07-20 15:22:05 -0700240 snprintf(dev->name, sizeof(dev->name), "%.*s",
241 (int)min(count, sizeof(dev->name) - 1), buf);
242 return count;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700243}
244
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200245static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700246
247
248(Note that the real implementation doesn't allow userspace to set the
249name for a device.)
250
251
252Top Level Directory Layout
253~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255The sysfs directory arrangement exposes the relationship of kernel
256data structures.
257
Matt LaPlantefff92892006-10-03 22:47:42 +0200258The top level sysfs directory looks like:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259
260block/
261bus/
262class/
Dan Williamse105b8b2008-04-21 10:51:07 -0700263dev/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700264devices/
265firmware/
266net/
Miklos Szeredic86d90d2006-04-26 10:49:26 +0200267fs/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700268
269devices/ contains a filesystem representation of the device tree. It maps
270directly to the internal kernel device tree, which is a hierarchy of
271struct device.
272
273bus/ contains flat directory layout of the various bus types in the
274kernel. Each bus's directory contains two subdirectories:
275
276 devices/
277 drivers/
278
279devices/ contains symlinks for each device discovered in the system
280that point to the device's directory under root/.
281
282drivers/ contains a directory for each device driver that is loaded
283for devices on that particular bus (this assumes that drivers do not
284span multiple bus types).
285
Miklos Szeredic86d90d2006-04-26 10:49:26 +0200286fs/ contains a directory for some filesystems. Currently each
287filesystem wanting to export attributes must create its own hierarchy
288below fs/ (see ./fuse.txt for an example).
289
Dan Williamse105b8b2008-04-21 10:51:07 -0700290dev/ contains two directories char/ and block/. Inside these two
291directories there are symlinks named <major>:<minor>. These symlinks
292point to the sysfs directory for the given device. /sys/dev provides a
293quick way to lookup the sysfs interface for a device from the result of
294a stat(2) operation.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700295
296More information can driver-model specific features can be found in
297Documentation/driver-model/.
298
299
300TODO: Finish this section.
301
302
303Current Interfaces
304~~~~~~~~~~~~~~~~~~
305
306The following interface layers currently exist in sysfs:
307
308
309- devices (include/linux/device.h)
310----------------------------------
311Structure:
312
313struct device_attribute {
Mike Murphyf8a1af62009-02-22 01:19:23 -0500314 struct attribute attr;
315 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
316 char *buf);
317 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
318 const char *buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700319};
320
321Declaring:
322
Mike Murphyf8a1af62009-02-22 01:19:23 -0500323DEVICE_ATTR(_name, _mode, _show, _store);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700324
325Creation/Removal:
326
Phil Carmody26579ab2009-12-18 15:34:19 +0200327int device_create_file(struct device *dev, const struct device_attribute * attr);
328void device_remove_file(struct device *dev, const struct device_attribute * attr);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700329
330
331- bus drivers (include/linux/device.h)
332--------------------------------------
333Structure:
334
335struct bus_attribute {
336 struct attribute attr;
337 ssize_t (*show)(struct bus_type *, char * buf);
Ira Weinya5307032010-07-15 11:34:44 -0700338 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700339};
340
341Declaring:
342
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200343BUS_ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700344
345Creation/Removal:
346
347int bus_create_file(struct bus_type *, struct bus_attribute *);
348void bus_remove_file(struct bus_type *, struct bus_attribute *);
349
350
351- device drivers (include/linux/device.h)
352-----------------------------------------
353
354Structure:
355
356struct driver_attribute {
357 struct attribute attr;
358 ssize_t (*show)(struct device_driver *, char * buf);
Mike Murphyf8a1af62009-02-22 01:19:23 -0500359 ssize_t (*store)(struct device_driver *, const char * buf,
360 size_t count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700361};
362
363Declaring:
364
Jan Veldemanf8d825b2005-07-31 13:12:09 +0200365DRIVER_ATTR(_name, _mode, _show, _store)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700366
367Creation/Removal:
368
Phil Carmody099c2f22009-12-18 15:34:21 +0200369int driver_create_file(struct device_driver *, const struct driver_attribute *);
370void driver_remove_file(struct device_driver *, const struct driver_attribute *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700371
372
Bart Van Assche86028612011-08-16 18:42:22 +0200373Documentation
374~~~~~~~~~~~~~
375
376The sysfs directory structure and the attributes in each directory define an
377ABI between the kernel and user space. As for any ABI, it is important that
378this ABI is stable and properly documented. All new sysfs attributes must be
379documented in Documentation/ABI. See also Documentation/ABI/README for more
380information.