Loading...
Note: File does not exist in v6.13.7.
1
2sysfs - _The_ filesystem for exporting kernel objects.
3
4Patrick Mochel <mochel@osdl.org>
5Mike Murphy <mamurph@cs.clemson.edu>
6
7Revised: 16 August 2011
8Original: 10 January 2003
9
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
26sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
27it by doing:
28
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 a pointer to the kobject that implements a
43directory in the kernfs_node 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().
48
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
59per file. It is noted that it may not be efficient to contain only one
60value 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
65you publicly humiliated and your code rewritten without notice.
66
67
68An attribute definition is simply:
69
70struct attribute {
71 char * name;
72 struct module *owner;
73 umode_t mode;
74};
75
76
77int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
78void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
79
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 {
89 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);
94};
95
96int device_create_file(struct device *, const struct device_attribute *);
97void device_remove_file(struct device *, const struct device_attribute *);
98
99It also defines this helper for defining device attributes:
100
101#define DEVICE_ATTR(_name, _mode, _show, _store) \
102struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
103
104For example, declaring
105
106static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
107
108is equivalent to doing:
109
110static struct device_attribute dev_attr_foo = {
111 .attr = {
112 .name = "foo",
113 .mode = S_IWUSR | S_IRUGO,
114 },
115 .show = show_foo,
116 .store = store_foo,
117};
118
119Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally
120considered a bad idea." so trying to set a sysfs file writable for
121everyone will fail reverting to RO mode for "Others".
122
123For the common cases sysfs.h provides convenience macros to make
124defining attributes easier as well as making code more concise and
125readable. The above case could be shortened to:
126
127static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
128
129the list of helpers available to define your wrapper function is:
130__ATTR_RO(name): assumes default name_show and mode 0444
131__ATTR_WO(name): assumes a name_store only and is restricted to mode
132 0200 that is root write access only.
133__ATTR_RO_MODE(name, mode): fore more restrictive RO access currently
134 only use case is the EFI System Resource Table
135 (see drivers/firmware/efi/esrt.c)
136__ATTR_RW(name): assumes default name_show, name_store and setting
137 mode to 0644.
138__ATTR_NULL: which sets the name to NULL and is used as end of list
139 indicator (see: kernel/workqueue.c)
140
141Subsystem-Specific Callbacks
142~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143
144When a subsystem defines a new attribute type, it must implement a
145set of sysfs operations for forwarding read and write calls to the
146show and store methods of the attribute owners.
147
148struct sysfs_ops {
149 ssize_t (*show)(struct kobject *, struct attribute *, char *);
150 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
151};
152
153[ Subsystems should have already defined a struct kobj_type as a
154descriptor for this type, which is where the sysfs_ops pointer is
155stored. See the kobject documentation for more information. ]
156
157When a file is read or written, sysfs calls the appropriate method
158for the type. The method then translates the generic struct kobject
159and struct attribute pointers to the appropriate pointer types, and
160calls the associated methods.
161
162
163To illustrate:
164
165#define to_dev(obj) container_of(obj, struct device, kobj)
166#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
167
168static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
169 char *buf)
170{
171 struct device_attribute *dev_attr = to_dev_attr(attr);
172 struct device *dev = to_dev(kobj);
173 ssize_t ret = -EIO;
174
175 if (dev_attr->show)
176 ret = dev_attr->show(dev, dev_attr, buf);
177 if (ret >= (ssize_t)PAGE_SIZE) {
178 printk("dev_attr_show: %pS returned bad count\n",
179 dev_attr->show);
180 }
181 return ret;
182}
183
184
185
186Reading/Writing Attribute Data
187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189To read or write attributes, show() or store() methods must be
190specified when declaring the attribute. The method types should be as
191simple as those defined for device attributes:
192
193ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
194ssize_t (*store)(struct device *dev, struct device_attribute *attr,
195 const char *buf, size_t count);
196
197IOW, they should take only an object, an attribute, and a buffer as parameters.
198
199
200sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
201method. Sysfs will call the method exactly once for each read or
202write. This forces the following behavior on the method
203implementations:
204
205- On read(2), the show() method should fill the entire buffer.
206 Recall that an attribute should only be exporting one value, or an
207 array of similar values, so this shouldn't be that expensive.
208
209 This allows userspace to do partial reads and forward seeks
210 arbitrarily over the entire file at will. If userspace seeks back to
211 zero or does a pread(2) with an offset of '0' the show() method will
212 be called again, rearmed, to fill the buffer.
213
214- On write(2), sysfs expects the entire buffer to be passed during the
215 first write. Sysfs then passes the entire buffer to the store() method.
216 A terminating null is added after the data on stores. This makes
217 functions like sysfs_streq() safe to use.
218
219 When writing sysfs files, userspace processes should first read the
220 entire file, modify the values it wishes to change, then write the
221 entire buffer back.
222
223 Attribute method implementations should operate on an identical
224 buffer when reading and writing values.
225
226Other notes:
227
228- Writing causes the show() method to be rearmed regardless of current
229 file position.
230
231- The buffer will always be PAGE_SIZE bytes in length. On i386, this
232 is 4096.
233
234- show() methods should return the number of bytes printed into the
235 buffer. This is the return value of scnprintf().
236
237- show() must not use snprintf() when formatting the value to be
238 returned to user space. If you can guarantee that an overflow
239 will never happen you can use sprintf() otherwise you must use
240 scnprintf().
241
242- store() should return the number of bytes used from the buffer. If the
243 entire buffer has been used, just return the count argument.
244
245- show() or store() can always return errors. If a bad value comes
246 through, be sure to return an error.
247
248- The object passed to the methods will be pinned in memory via sysfs
249 referencing counting its embedded object. However, the physical
250 entity (e.g. device) the object represents may not be present. Be
251 sure to have a way to check this, if necessary.
252
253
254A very simple (and naive) implementation of a device attribute is:
255
256static ssize_t show_name(struct device *dev, struct device_attribute *attr,
257 char *buf)
258{
259 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
260}
261
262static ssize_t store_name(struct device *dev, struct device_attribute *attr,
263 const char *buf, size_t count)
264{
265 snprintf(dev->name, sizeof(dev->name), "%.*s",
266 (int)min(count, sizeof(dev->name) - 1), buf);
267 return count;
268}
269
270static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
271
272
273(Note that the real implementation doesn't allow userspace to set the
274name for a device.)
275
276
277Top Level Directory Layout
278~~~~~~~~~~~~~~~~~~~~~~~~~~
279
280The sysfs directory arrangement exposes the relationship of kernel
281data structures.
282
283The top level sysfs directory looks like:
284
285block/
286bus/
287class/
288dev/
289devices/
290firmware/
291net/
292fs/
293
294devices/ contains a filesystem representation of the device tree. It maps
295directly to the internal kernel device tree, which is a hierarchy of
296struct device.
297
298bus/ contains flat directory layout of the various bus types in the
299kernel. Each bus's directory contains two subdirectories:
300
301 devices/
302 drivers/
303
304devices/ contains symlinks for each device discovered in the system
305that point to the device's directory under root/.
306
307drivers/ contains a directory for each device driver that is loaded
308for devices on that particular bus (this assumes that drivers do not
309span multiple bus types).
310
311fs/ contains a directory for some filesystems. Currently each
312filesystem wanting to export attributes must create its own hierarchy
313below fs/ (see ./fuse.txt for an example).
314
315dev/ contains two directories char/ and block/. Inside these two
316directories there are symlinks named <major>:<minor>. These symlinks
317point to the sysfs directory for the given device. /sys/dev provides a
318quick way to lookup the sysfs interface for a device from the result of
319a stat(2) operation.
320
321More information can driver-model specific features can be found in
322Documentation/driver-api/driver-model/.
323
324
325TODO: Finish this section.
326
327
328Current Interfaces
329~~~~~~~~~~~~~~~~~~
330
331The following interface layers currently exist in sysfs:
332
333
334- devices (include/linux/device.h)
335----------------------------------
336Structure:
337
338struct device_attribute {
339 struct attribute attr;
340 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
341 char *buf);
342 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
343 const char *buf, size_t count);
344};
345
346Declaring:
347
348DEVICE_ATTR(_name, _mode, _show, _store);
349
350Creation/Removal:
351
352int device_create_file(struct device *dev, const struct device_attribute * attr);
353void device_remove_file(struct device *dev, const struct device_attribute * attr);
354
355
356- bus drivers (include/linux/device.h)
357--------------------------------------
358Structure:
359
360struct bus_attribute {
361 struct attribute attr;
362 ssize_t (*show)(struct bus_type *, char * buf);
363 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
364};
365
366Declaring:
367
368static BUS_ATTR_RW(name);
369static BUS_ATTR_RO(name);
370static BUS_ATTR_WO(name);
371
372Creation/Removal:
373
374int bus_create_file(struct bus_type *, struct bus_attribute *);
375void bus_remove_file(struct bus_type *, struct bus_attribute *);
376
377
378- device drivers (include/linux/device.h)
379-----------------------------------------
380
381Structure:
382
383struct driver_attribute {
384 struct attribute attr;
385 ssize_t (*show)(struct device_driver *, char * buf);
386 ssize_t (*store)(struct device_driver *, const char * buf,
387 size_t count);
388};
389
390Declaring:
391
392DRIVER_ATTR_RO(_name)
393DRIVER_ATTR_RW(_name)
394
395Creation/Removal:
396
397int driver_create_file(struct device_driver *, const struct driver_attribute *);
398void driver_remove_file(struct device_driver *, const struct driver_attribute *);
399
400
401Documentation
402~~~~~~~~~~~~~
403
404The sysfs directory structure and the attributes in each directory define an
405ABI between the kernel and user space. As for any ABI, it is important that
406this ABI is stable and properly documented. All new sysfs attributes must be
407documented in Documentation/ABI. See also Documentation/ABI/README for more
408information.