2 sysfs - _The_ filesystem for exporting kernel objects.
4 Patrick Mochel <mochel@osdl.org>
5 Mike Murphy <mamurph@cs.clemson.edu>
7 Revised: 16 August 2011
8 Original: 10 January 2003
14 sysfs is a ram-based filesystem initially based on ramfs. It provides
15 a means to export kernel data structures, their attributes, and the
16 linkages between them to userspace.
18 sysfs is tied inherently to the kobject infrastructure. Please read
19 Documentation/kobject.txt for more information concerning the kobject
26 sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
29 mount -t sysfs sysfs /sys
35 For every kobject that is registered with the system, a directory is
36 created for it in sysfs. That directory is created as a subdirectory
37 of the kobject's parent, expressing internal object hierarchies to
38 userspace. Top-level directories in sysfs represent the common
39 ancestors of object hierarchies; i.e. the subsystems the objects
42 Sysfs internally stores a pointer to the kobject that implements a
43 directory in the kernfs_node object associated with the directory. In
44 the past this kobject pointer has been used by sysfs to do reference
45 counting directly on the kobject whenever the file is opened or closed.
46 With the current sysfs implementation the kobject reference count is
47 only modified directly by the function sysfs_schedule_callback().
53 Attributes can be exported for kobjects in the form of regular files in
54 the filesystem. Sysfs forwards file I/O operations to methods defined
55 for the attributes, providing a means to read and write kernel
58 Attributes should be ASCII text files, preferably with only one value
59 per file. It is noted that it may not be efficient to contain only one
60 value per file, so it is socially acceptable to express an array of
61 values of the same type.
63 Mixing types, expressing multiple lines of data, and doing fancy
64 formatting of data is heavily frowned upon. Doing these things may get
65 you publicly humiliated and your code rewritten without notice.
68 An attribute definition is simply:
77 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
78 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
81 A bare attribute contains no means to read or write the value of the
82 attribute. Subsystems are encouraged to define their own attribute
83 structure and wrapper functions for adding and removing attributes for
84 a specific object type.
86 For example, the driver model defines struct device_attribute like:
88 struct device_attribute {
89 struct attribute attr;
90 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
92 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
93 const char *buf, size_t count);
96 int device_create_file(struct device *, const struct device_attribute *);
97 void device_remove_file(struct device *, const struct device_attribute *);
99 It also defines this helper for defining device attributes:
101 #define DEVICE_ATTR(_name, _mode, _show, _store) \
102 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
104 For example, declaring
106 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
108 is equivalent to doing:
110 static struct device_attribute dev_attr_foo = {
113 .mode = S_IWUSR | S_IRUGO,
120 Subsystem-Specific Callbacks
121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123 When a subsystem defines a new attribute type, it must implement a
124 set of sysfs operations for forwarding read and write calls to the
125 show and store methods of the attribute owners.
128 ssize_t (*show)(struct kobject *, struct attribute *, char *);
129 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
132 [ Subsystems should have already defined a struct kobj_type as a
133 descriptor for this type, which is where the sysfs_ops pointer is
134 stored. See the kobject documentation for more information. ]
136 When a file is read or written, sysfs calls the appropriate method
137 for the type. The method then translates the generic struct kobject
138 and struct attribute pointers to the appropriate pointer types, and
139 calls the associated methods.
144 #define to_dev(obj) container_of(obj, struct device, kobj)
145 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
147 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
150 struct device_attribute *dev_attr = to_dev_attr(attr);
151 struct device *dev = to_dev(kobj);
155 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);
165 Reading/Writing Attribute Data
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168 To read or write attributes, show() or store() methods must be
169 specified when declaring the attribute. The method types should be as
170 simple as those defined for device attributes:
172 ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
173 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
174 const char *buf, size_t count);
176 IOW, they should take only an object, an attribute, and a buffer as parameters.
179 sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
180 method. Sysfs will call the method exactly once for each read or
181 write. This forces the following behavior on the method
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.
188 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.
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() method.
195 A terminating null is added after the data on stores. This makes
196 functions like sysfs_streq() safe to use.
198 When writing sysfs files, userspace processes should first read the
199 entire file, modify the values it wishes to change, then write the
202 Attribute method implementations should operate on an identical
203 buffer when reading and writing values.
207 - Writing causes the show() method to be rearmed regardless of current
210 - The buffer will always be PAGE_SIZE bytes in length. On i386, this
213 - show() methods should return the number of bytes printed into the
216 - show() should only use sysfs_emit() or sysfs_emit_at() when formatting
217 the value to be returned to user space.
219 - store() should return the number of bytes used from the buffer. If the
220 entire buffer has been used, just return the count argument.
222 - show() or store() can always return errors. If a bad value comes
223 through, be sure to return an error.
225 - The object passed to the methods will be pinned in memory via sysfs
226 referencing counting its embedded object. However, the physical
227 entity (e.g. device) the object represents may not be present. Be
228 sure to have a way to check this, if necessary.
231 A very simple (and naive) implementation of a device attribute is:
233 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
236 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
239 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
240 const char *buf, size_t count)
242 snprintf(dev->name, sizeof(dev->name), "%.*s",
243 (int)min(count, sizeof(dev->name) - 1), buf);
247 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
250 (Note that the real implementation doesn't allow userspace to set the
254 Top Level Directory Layout
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~
257 The sysfs directory arrangement exposes the relationship of kernel
260 The top level sysfs directory looks like:
271 devices/ contains a filesystem representation of the device tree. It maps
272 directly to the internal kernel device tree, which is a hierarchy of
275 bus/ contains flat directory layout of the various bus types in the
276 kernel. Each bus's directory contains two subdirectories:
281 devices/ contains symlinks for each device discovered in the system
282 that point to the device's directory under root/.
284 drivers/ contains a directory for each device driver that is loaded
285 for devices on that particular bus (this assumes that drivers do not
286 span multiple bus types).
288 fs/ contains a directory for some filesystems. Currently each
289 filesystem wanting to export attributes must create its own hierarchy
290 below fs/ (see ./fuse.txt for an example).
292 dev/ contains two directories char/ and block/. Inside these two
293 directories there are symlinks named <major>:<minor>. These symlinks
294 point to the sysfs directory for the given device. /sys/dev provides a
295 quick way to lookup the sysfs interface for a device from the result of
298 More information can driver-model specific features can be found in
299 Documentation/driver-model/.
302 TODO: Finish this section.
308 The following interface layers currently exist in sysfs:
311 - devices (include/linux/device.h)
312 ----------------------------------
315 struct device_attribute {
316 struct attribute attr;
317 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
319 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
320 const char *buf, size_t count);
325 DEVICE_ATTR(_name, _mode, _show, _store);
329 int device_create_file(struct device *dev, const struct device_attribute * attr);
330 void device_remove_file(struct device *dev, const struct device_attribute * attr);
333 - bus drivers (include/linux/device.h)
334 --------------------------------------
337 struct bus_attribute {
338 struct attribute attr;
339 ssize_t (*show)(struct bus_type *, char * buf);
340 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
345 BUS_ATTR(_name, _mode, _show, _store)
349 int bus_create_file(struct bus_type *, struct bus_attribute *);
350 void bus_remove_file(struct bus_type *, struct bus_attribute *);
353 - device drivers (include/linux/device.h)
354 -----------------------------------------
358 struct driver_attribute {
359 struct attribute attr;
360 ssize_t (*show)(struct device_driver *, char * buf);
361 ssize_t (*store)(struct device_driver *, const char * buf,
367 DRIVER_ATTR(_name, _mode, _show, _store)
371 int driver_create_file(struct device_driver *, const struct driver_attribute *);
372 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
378 The sysfs directory structure and the attributes in each directory define an
379 ABI between the kernel and user space. As for any ABI, it is important that
380 this ABI is stable and properly documented. All new sysfs attributes must be
381 documented in Documentation/ABI. See also Documentation/ABI/README for more