]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | sysfs - _The_ filesystem for exporting kernel objects. | |
3 | ||
4 | Patrick Mochel <mochel@osdl.org> | |
f8a1af6b | 5 | Mike Murphy <mamurph@cs.clemson.edu> |
1da177e4 | 6 | |
86028619 | 7 | Revised: 16 August 2011 |
f8a1af6b | 8 | Original: 10 January 2003 |
1da177e4 LT |
9 | |
10 | ||
11 | What it is: | |
12 | ~~~~~~~~~~~ | |
13 | ||
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. | |
17 | ||
18 | sysfs is tied inherently to the kobject infrastructure. Please read | |
19 | Documentation/kobject.txt for more information concerning the kobject | |
20 | interface. | |
21 | ||
22 | ||
23 | Using sysfs | |
24 | ~~~~~~~~~~~ | |
25 | ||
a39ea210 LAG |
26 | sysfs is always compiled in if CONFIG_SYSFS is defined. You can access |
27 | it by doing: | |
1da177e4 LT |
28 | |
29 | mount -t sysfs sysfs /sys | |
30 | ||
31 | ||
32 | Directory Creation | |
33 | ~~~~~~~~~~~~~~~~~~ | |
34 | ||
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 | |
40 | belong to. | |
41 | ||
5480bcdd | 42 | Sysfs internally stores a pointer to the kobject that implements a |
390b421c | 43 | directory in the kernfs_node object associated with the directory. In |
5480bcdd BVA |
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(). | |
1da177e4 LT |
48 | |
49 | ||
50 | Attributes | |
51 | ~~~~~~~~~~ | |
52 | ||
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 | |
56 | attributes. | |
57 | ||
58 | Attributes should be ASCII text files, preferably with only one value | |
f8c34f98 | 59 | per file. It is noted that it may not be efficient to contain only one |
1da177e4 LT |
60 | value per file, so it is socially acceptable to express an array of |
61 | values of the same type. | |
62 | ||
63 | Mixing types, expressing multiple lines of data, and doing fancy | |
64 | formatting of data is heavily frowned upon. Doing these things may get | |
25985edc | 65 | you publicly humiliated and your code rewritten without notice. |
1da177e4 LT |
66 | |
67 | ||
68 | An attribute definition is simply: | |
69 | ||
70 | struct attribute { | |
71 | char * name; | |
f8a1af6b | 72 | struct module *owner; |
faef2b6c | 73 | umode_t mode; |
1da177e4 LT |
74 | }; |
75 | ||
76 | ||
f8a1af6b MM |
77 | int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); |
78 | void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); | |
1da177e4 LT |
79 | |
80 | ||
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. | |
85 | ||
86 | For example, the driver model defines struct device_attribute like: | |
87 | ||
88 | struct device_attribute { | |
f8a1af6b MM |
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); | |
1da177e4 LT |
94 | }; |
95 | ||
26579ab7 PC |
96 | int device_create_file(struct device *, const struct device_attribute *); |
97 | void device_remove_file(struct device *, const struct device_attribute *); | |
1da177e4 LT |
98 | |
99 | It also defines this helper for defining device attributes: | |
100 | ||
f8a1af6b MM |
101 | #define DEVICE_ATTR(_name, _mode, _show, _store) \ |
102 | struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) | |
1da177e4 LT |
103 | |
104 | For example, declaring | |
105 | ||
91e49001 | 106 | static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); |
1da177e4 LT |
107 | |
108 | is equivalent to doing: | |
109 | ||
110 | static struct device_attribute dev_attr_foo = { | |
c1083732 | 111 | .attr = { |
1da177e4 | 112 | .name = "foo", |
91e49001 | 113 | .mode = S_IWUSR | S_IRUGO, |
1da177e4 | 114 | }, |
c1083732 AR |
115 | .show = show_foo, |
116 | .store = store_foo, | |
1da177e4 LT |
117 | }; |
118 | ||
44a47f0e NMG |
119 | Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally |
120 | considered a bad idea." so trying to set a sysfs file writable for | |
121 | everyone will fail reverting to RO mode for "Others". | |
122 | ||
123 | For the common cases sysfs.h provides convenience macros to make | |
124 | defining attributes easier as well as making code more concise and | |
125 | readable. The above case could be shortened to: | |
126 | ||
127 | static struct device_attribute dev_attr_foo = __ATTR_RW(foo); | |
128 | ||
129 | the 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) | |
1da177e4 LT |
140 | |
141 | Subsystem-Specific Callbacks | |
142 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
143 | ||
144 | When a subsystem defines a new attribute type, it must implement a | |
145 | set of sysfs operations for forwarding read and write calls to the | |
146 | show and store methods of the attribute owners. | |
147 | ||
148 | struct sysfs_ops { | |
f8d825bf | 149 | ssize_t (*show)(struct kobject *, struct attribute *, char *); |
30a69000 | 150 | ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); |
1da177e4 LT |
151 | }; |
152 | ||
153 | [ Subsystems should have already defined a struct kobj_type as a | |
154 | descriptor for this type, which is where the sysfs_ops pointer is | |
155 | stored. See the kobject documentation for more information. ] | |
156 | ||
157 | When a file is read or written, sysfs calls the appropriate method | |
158 | for the type. The method then translates the generic struct kobject | |
159 | and struct attribute pointers to the appropriate pointer types, and | |
160 | calls the associated methods. | |
161 | ||
162 | ||
163 | To illustrate: | |
164 | ||
30a69000 | 165 | #define to_dev(obj) container_of(obj, struct device, kobj) |
f8d825bf | 166 | #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) |
1da177e4 | 167 | |
30a69000 BVA |
168 | static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, |
169 | char *buf) | |
1da177e4 | 170 | { |
30a69000 BVA |
171 | struct device_attribute *dev_attr = to_dev_attr(attr); |
172 | struct device *dev = to_dev(kobj); | |
173 | ssize_t ret = -EIO; | |
1da177e4 LT |
174 | |
175 | if (dev_attr->show) | |
30a69000 BVA |
176 | ret = dev_attr->show(dev, dev_attr, buf); |
177 | if (ret >= (ssize_t)PAGE_SIZE) { | |
d2279c9d SS |
178 | printk("dev_attr_show: %pS returned bad count\n", |
179 | dev_attr->show); | |
30a69000 | 180 | } |
1da177e4 LT |
181 | return ret; |
182 | } | |
183 | ||
184 | ||
185 | ||
186 | Reading/Writing Attribute Data | |
187 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
188 | ||
189 | To read or write attributes, show() or store() methods must be | |
190 | specified when declaring the attribute. The method types should be as | |
191 | simple as those defined for device attributes: | |
192 | ||
30a69000 BVA |
193 | ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); |
194 | ssize_t (*store)(struct device *dev, struct device_attribute *attr, | |
195 | const char *buf, size_t count); | |
1da177e4 | 196 | |
f8a1af6b | 197 | IOW, they should take only an object, an attribute, and a buffer as parameters. |
1da177e4 LT |
198 | |
199 | ||
200 | sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the | |
201 | method. Sysfs will call the method exactly once for each read or | |
202 | write. This forces the following behavior on the method | |
203 | implementations: | |
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 | ||
2424b5dd DW |
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. | |
1da177e4 LT |
213 | |
214 | - On write(2), sysfs expects the entire buffer to be passed during the | |
17666497 UM |
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 | ||
1da177e4 LT |
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 | ||
226 | Other notes: | |
227 | ||
2424b5dd DW |
228 | - Writing causes the show() method to be rearmed regardless of current |
229 | file position. | |
230 | ||
1da177e4 LT |
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 | |
d3f70bef | 235 | buffer. This is the return value of scnprintf(). |
1da177e4 | 236 | |
223e8f01 SS |
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(). | |
1da177e4 | 241 | |
30a69000 BVA |
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. | |
1da177e4 LT |
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 | ||
254 | A very simple (and naive) implementation of a device attribute is: | |
255 | ||
30a69000 BVA |
256 | static ssize_t show_name(struct device *dev, struct device_attribute *attr, |
257 | char *buf) | |
1da177e4 | 258 | { |
d3f70bef | 259 | return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); |
1da177e4 LT |
260 | } |
261 | ||
30a69000 BVA |
262 | static ssize_t store_name(struct device *dev, struct device_attribute *attr, |
263 | const char *buf, size_t count) | |
1da177e4 | 264 | { |
30a69000 BVA |
265 | snprintf(dev->name, sizeof(dev->name), "%.*s", |
266 | (int)min(count, sizeof(dev->name) - 1), buf); | |
267 | return count; | |
1da177e4 LT |
268 | } |
269 | ||
f8d825bf | 270 | static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); |
1da177e4 LT |
271 | |
272 | ||
273 | (Note that the real implementation doesn't allow userspace to set the | |
274 | name for a device.) | |
275 | ||
276 | ||
277 | Top Level Directory Layout | |
278 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
279 | ||
280 | The sysfs directory arrangement exposes the relationship of kernel | |
281 | data structures. | |
282 | ||
fff9289b | 283 | The top level sysfs directory looks like: |
1da177e4 LT |
284 | |
285 | block/ | |
286 | bus/ | |
287 | class/ | |
e105b8bf | 288 | dev/ |
1da177e4 LT |
289 | devices/ |
290 | firmware/ | |
291 | net/ | |
c86d90df | 292 | fs/ |
1da177e4 LT |
293 | |
294 | devices/ contains a filesystem representation of the device tree. It maps | |
295 | directly to the internal kernel device tree, which is a hierarchy of | |
296 | struct device. | |
297 | ||
298 | bus/ contains flat directory layout of the various bus types in the | |
299 | kernel. Each bus's directory contains two subdirectories: | |
300 | ||
301 | devices/ | |
302 | drivers/ | |
303 | ||
304 | devices/ contains symlinks for each device discovered in the system | |
305 | that point to the device's directory under root/. | |
306 | ||
307 | drivers/ contains a directory for each device driver that is loaded | |
308 | for devices on that particular bus (this assumes that drivers do not | |
309 | span multiple bus types). | |
310 | ||
c86d90df MS |
311 | fs/ contains a directory for some filesystems. Currently each |
312 | filesystem wanting to export attributes must create its own hierarchy | |
313 | below fs/ (see ./fuse.txt for an example). | |
314 | ||
e105b8bf DW |
315 | dev/ contains two directories char/ and block/. Inside these two |
316 | directories there are symlinks named <major>:<minor>. These symlinks | |
317 | point to the sysfs directory for the given device. /sys/dev provides a | |
318 | quick way to lookup the sysfs interface for a device from the result of | |
319 | a stat(2) operation. | |
1da177e4 LT |
320 | |
321 | More information can driver-model specific features can be found in | |
fe34c89d | 322 | Documentation/driver-api/driver-model/. |
1da177e4 LT |
323 | |
324 | ||
325 | TODO: Finish this section. | |
326 | ||
327 | ||
328 | Current Interfaces | |
329 | ~~~~~~~~~~~~~~~~~~ | |
330 | ||
331 | The following interface layers currently exist in sysfs: | |
332 | ||
333 | ||
334 | - devices (include/linux/device.h) | |
335 | ---------------------------------- | |
336 | Structure: | |
337 | ||
338 | struct device_attribute { | |
f8a1af6b MM |
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); | |
1da177e4 LT |
344 | }; |
345 | ||
346 | Declaring: | |
347 | ||
f8a1af6b | 348 | DEVICE_ATTR(_name, _mode, _show, _store); |
1da177e4 LT |
349 | |
350 | Creation/Removal: | |
351 | ||
26579ab7 PC |
352 | int device_create_file(struct device *dev, const struct device_attribute * attr); |
353 | void device_remove_file(struct device *dev, const struct device_attribute * attr); | |
1da177e4 LT |
354 | |
355 | ||
356 | - bus drivers (include/linux/device.h) | |
357 | -------------------------------------- | |
358 | Structure: | |
359 | ||
360 | struct bus_attribute { | |
361 | struct attribute attr; | |
362 | ssize_t (*show)(struct bus_type *, char * buf); | |
a5307032 | 363 | ssize_t (*store)(struct bus_type *, const char * buf, size_t count); |
1da177e4 LT |
364 | }; |
365 | ||
366 | Declaring: | |
367 | ||
735df0ff GKH |
368 | static BUS_ATTR_RW(name); |
369 | static BUS_ATTR_RO(name); | |
370 | static BUS_ATTR_WO(name); | |
1da177e4 LT |
371 | |
372 | Creation/Removal: | |
373 | ||
374 | int bus_create_file(struct bus_type *, struct bus_attribute *); | |
375 | void bus_remove_file(struct bus_type *, struct bus_attribute *); | |
376 | ||
377 | ||
378 | - device drivers (include/linux/device.h) | |
379 | ----------------------------------------- | |
380 | ||
381 | Structure: | |
382 | ||
383 | struct driver_attribute { | |
384 | struct attribute attr; | |
385 | ssize_t (*show)(struct device_driver *, char * buf); | |
f8a1af6b MM |
386 | ssize_t (*store)(struct device_driver *, const char * buf, |
387 | size_t count); | |
1da177e4 LT |
388 | }; |
389 | ||
390 | Declaring: | |
391 | ||
850fdec8 GKH |
392 | DRIVER_ATTR_RO(_name) |
393 | DRIVER_ATTR_RW(_name) | |
1da177e4 LT |
394 | |
395 | Creation/Removal: | |
396 | ||
099c2f21 PC |
397 | int driver_create_file(struct device_driver *, const struct driver_attribute *); |
398 | void driver_remove_file(struct device_driver *, const struct driver_attribute *); | |
1da177e4 LT |
399 | |
400 | ||
86028619 BVA |
401 | Documentation |
402 | ~~~~~~~~~~~~~ | |
403 | ||
404 | The sysfs directory structure and the attributes in each directory define an | |
405 | ABI between the kernel and user space. As for any ABI, it is important that | |
406 | this ABI is stable and properly documented. All new sysfs attributes must be | |
407 | documented in Documentation/ABI. See also Documentation/ABI/README for more | |
408 | information. |