Merge branch 'nfs-for-2.6.39' of git://git.linux-nfs.org/projects/trondmy/nfs-2.6
[linux-2.6.git] / Documentation / filesystems / sysfs.txt
1
2 sysfs - _The_ filesystem for exporting kernel objects. 
3
4 Patrick Mochel  <mochel@osdl.org>
5 Mike Murphy <mamurph@cs.clemson.edu>
6
7 Revised:    15 July 2010
8 Original:   10 January 2003
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
26 sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
27 it by doing:
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
42 Sysfs internally stores a pointer to the kobject that implements a
43 directory in the sysfs_dirent 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().
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
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. 
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
65 you publically humiliated and your code rewritten without notice. 
66
67
68 An attribute definition is simply:
69
70 struct attribute {
71         char                    * name;
72         struct module           *owner;
73         mode_t                  mode;
74 };
75
76
77 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
78 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
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 {
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
96 int device_create_file(struct device *, const struct device_attribute *);
97 void device_remove_file(struct device *, const struct device_attribute *);
98
99 It also defines this helper for defining device attributes: 
100
101 #define DEVICE_ATTR(_name, _mode, _show, _store) \
102 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
103
104 For example, declaring
105
106 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
107
108 is equivalent to doing:
109
110 static struct device_attribute dev_attr_foo = {
111        .attr    = {
112                 .name = "foo",
113                 .mode = S_IWUSR | S_IRUGO,
114                 .show = show_foo,
115                 .store = store_foo,
116         },
117 };
118
119
120 Subsystem-Specific Callbacks
121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122
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. 
126
127 struct sysfs_ops {
128         ssize_t (*show)(struct kobject *, struct attribute *, char *);
129         ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
130 };
131
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. ]
135
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. 
140
141
142 To illustrate:
143
144 #define to_dev(obj) container_of(obj, struct device, kobj)
145 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
146
147 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
148                              char *buf)
149 {
150         struct device_attribute *dev_attr = to_dev_attr(attr);
151         struct device *dev = to_dev(kobj);
152         ssize_t ret = -EIO;
153
154         if (dev_attr->show)
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);
159         }
160         return ret;
161 }
162
163
164
165 Reading/Writing Attribute Data
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
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:
171
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);
175
176 IOW, they should take only an object, an attribute, and a buffer as parameters.
177
178
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
182 implementations: 
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
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.
192
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
204 Other notes:
205
206 - Writing causes the show() method to be rearmed regardless of current
207   file position.
208
209 - 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
213   buffer. This is the return value of scnprintf().
214
215 - show() should always use scnprintf().
216
217 - store() should return the number of bytes used from the buffer. If the
218   entire buffer has been used, just return the count argument.
219
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
229 A very simple (and naive) implementation of a device attribute is:
230
231 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
232                          char *buf)
233 {
234         return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
235 }
236
237 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
238                           const char *buf, size_t count)
239 {
240         snprintf(dev->name, sizeof(dev->name), "%.*s",
241                  (int)min(count, sizeof(dev->name) - 1), buf);
242         return count;
243 }
244
245 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
246
247
248 (Note that the real implementation doesn't allow userspace to set the 
249 name for a device.)
250
251
252 Top Level Directory Layout
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255 The sysfs directory arrangement exposes the relationship of kernel
256 data structures. 
257
258 The top level sysfs directory looks like:
259
260 block/
261 bus/
262 class/
263 dev/
264 devices/
265 firmware/
266 net/
267 fs/
268
269 devices/ contains a filesystem representation of the device tree. It maps
270 directly to the internal kernel device tree, which is a hierarchy of
271 struct device. 
272
273 bus/ contains flat directory layout of the various bus types in the
274 kernel. Each bus's directory contains two subdirectories:
275
276         devices/
277         drivers/
278
279 devices/ contains symlinks for each device discovered in the system
280 that point to the device's directory under root/.
281
282 drivers/ contains a directory for each device driver that is loaded
283 for devices on that particular bus (this assumes that drivers do not
284 span multiple bus types).
285
286 fs/ contains a directory for some filesystems.  Currently each
287 filesystem wanting to export attributes must create its own hierarchy
288 below fs/ (see ./fuse.txt for an example).
289
290 dev/ contains two directories char/ and block/. Inside these two
291 directories there are symlinks named <major>:<minor>.  These symlinks
292 point to the sysfs directory for the given device.  /sys/dev provides a
293 quick way to lookup the sysfs interface for a device from the result of
294 a stat(2) operation.
295
296 More information can driver-model specific features can be found in
297 Documentation/driver-model/. 
298
299
300 TODO: Finish this section.
301
302
303 Current Interfaces
304 ~~~~~~~~~~~~~~~~~~
305
306 The following interface layers currently exist in sysfs:
307
308
309 - devices (include/linux/device.h)
310 ----------------------------------
311 Structure:
312
313 struct device_attribute {
314         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);
319 };
320
321 Declaring:
322
323 DEVICE_ATTR(_name, _mode, _show, _store);
324
325 Creation/Removal:
326
327 int device_create_file(struct device *dev, const struct device_attribute * attr);
328 void device_remove_file(struct device *dev, const struct device_attribute * attr);
329
330
331 - bus drivers (include/linux/device.h)
332 --------------------------------------
333 Structure:
334
335 struct bus_attribute {
336         struct attribute        attr;
337         ssize_t (*show)(struct bus_type *, char * buf);
338         ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
339 };
340
341 Declaring:
342
343 BUS_ATTR(_name, _mode, _show, _store)
344
345 Creation/Removal:
346
347 int bus_create_file(struct bus_type *, struct bus_attribute *);
348 void bus_remove_file(struct bus_type *, struct bus_attribute *);
349
350
351 - device drivers (include/linux/device.h)
352 -----------------------------------------
353
354 Structure:
355
356 struct driver_attribute {
357         struct attribute        attr;
358         ssize_t (*show)(struct device_driver *, char * buf);
359         ssize_t (*store)(struct device_driver *, const char * buf,
360                          size_t count);
361 };
362
363 Declaring:
364
365 DRIVER_ATTR(_name, _mode, _show, _store)
366
367 Creation/Removal:
368
369 int driver_create_file(struct device_driver *, const struct driver_attribute *);
370 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
371
372