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 printk("dev_attr_show: %pS returned bad count\n",
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
214 buffer. This is the return value of scnprintf().
216 - show() must not use snprintf() when formatting the value to be
217 returned to user space. If you can guarantee that an overflow
218 will never happen you can use sprintf() otherwise you must use
221 - store() should return the number of bytes used from the buffer. If the
222 entire buffer has been used, just return the count argument.
224 - show() or store() can always return errors. If a bad value comes
225 through, be sure to return an error.
227 - The object passed to the methods will be pinned in memory via sysfs
228 referencing counting its embedded object. However, the physical
229 entity (e.g. device) the object represents may not be present. Be
230 sure to have a way to check this, if necessary.
233 A very simple (and naive) implementation of a device attribute is:
235 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
238 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
241 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
242 const char *buf, size_t count)
244 snprintf(dev->name, sizeof(dev->name), "%.*s",
245 (int)min(count, sizeof(dev->name) - 1), buf);
249 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
252 (Note that the real implementation doesn't allow userspace to set the
256 Top Level Directory Layout
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~
259 The sysfs directory arrangement exposes the relationship of kernel
262 The top level sysfs directory looks like:
273 devices/ contains a filesystem representation of the device tree. It maps
274 directly to the internal kernel device tree, which is a hierarchy of
277 bus/ contains flat directory layout of the various bus types in the
278 kernel. Each bus's directory contains two subdirectories:
283 devices/ contains symlinks for each device discovered in the system
284 that point to the device's directory under root/.
286 drivers/ contains a directory for each device driver that is loaded
287 for devices on that particular bus (this assumes that drivers do not
288 span multiple bus types).
290 fs/ contains a directory for some filesystems. Currently each
291 filesystem wanting to export attributes must create its own hierarchy
292 below fs/ (see ./fuse.txt for an example).
294 dev/ contains two directories char/ and block/. Inside these two
295 directories there are symlinks named <major>:<minor>. These symlinks
296 point to the sysfs directory for the given device. /sys/dev provides a
297 quick way to lookup the sysfs interface for a device from the result of
300 More information can driver-model specific features can be found in
301 Documentation/driver-model/.
304 TODO: Finish this section.
310 The following interface layers currently exist in sysfs:
313 - devices (include/linux/device.h)
314 ----------------------------------
317 struct device_attribute {
318 struct attribute attr;
319 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
321 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
322 const char *buf, size_t count);
327 DEVICE_ATTR(_name, _mode, _show, _store);
331 int device_create_file(struct device *dev, const struct device_attribute * attr);
332 void device_remove_file(struct device *dev, const struct device_attribute * attr);
335 - bus drivers (include/linux/device.h)
336 --------------------------------------
339 struct bus_attribute {
340 struct attribute attr;
341 ssize_t (*show)(struct bus_type *, char * buf);
342 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
347 static BUS_ATTR_RW(name);
348 static BUS_ATTR_RO(name);
349 static BUS_ATTR_WO(name);
353 int bus_create_file(struct bus_type *, struct bus_attribute *);
354 void bus_remove_file(struct bus_type *, struct bus_attribute *);
357 - device drivers (include/linux/device.h)
358 -----------------------------------------
362 struct driver_attribute {
363 struct attribute attr;
364 ssize_t (*show)(struct device_driver *, char * buf);
365 ssize_t (*store)(struct device_driver *, const char * buf,
371 DRIVER_ATTR_RO(_name)
372 DRIVER_ATTR_RW(_name)
376 int driver_create_file(struct device_driver *, const struct driver_attribute *);
377 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
383 The sysfs directory structure and the attributes in each directory define an
384 ABI between the kernel and user space. As for any ABI, it is important that
385 this ABI is stable and properly documented. All new sysfs attributes must be
386 documented in Documentation/ABI. See also Documentation/ABI/README for more