Merge tag 'kgdb-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/danielt...
[sfrench/cifs-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:    16 August 2011
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 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().
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 publicly 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         umode_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         },
115         .show = show_foo,
116         .store = store_foo,
117 };
118
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)
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 {
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
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
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
168 static 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
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
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);
196
197 IOW, they should take only an object, an attribute, and a buffer as parameters.
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
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
226 Other 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
254 A very simple (and naive) implementation of a device attribute is:
255
256 static 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
262 static 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
270 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
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
283 The top level sysfs directory looks like:
284
285 block/
286 bus/
287 class/
288 dev/
289 devices/
290 firmware/
291 net/
292 fs/
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
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
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.
320
321 More information can driver-model specific features can be found in
322 Documentation/driver-model/. 
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 {
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
346 Declaring:
347
348 DEVICE_ATTR(_name, _mode, _show, _store);
349
350 Creation/Removal:
351
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);
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);
363         ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
364 };
365
366 Declaring:
367
368 static BUS_ATTR_RW(name);
369 static BUS_ATTR_RO(name);
370 static BUS_ATTR_WO(name);
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);
386         ssize_t (*store)(struct device_driver *, const char * buf,
387                          size_t count);
388 };
389
390 Declaring:
391
392 DRIVER_ATTR_RO(_name)
393 DRIVER_ATTR_RW(_name)
394
395 Creation/Removal:
396
397 int driver_create_file(struct device_driver *, const struct driver_attribute *);
398 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
399
400
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.