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
119
120Subsystem-Specific Callbacks
121~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122
123When a subsystem defines a new attribute type, it must implement a
124set of sysfs operations for forwarding read and write calls to the
125show and store methods of the attribute owners. 
126
127struct 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
133descriptor for this type, which is where the sysfs_ops pointer is
134stored. See the kobject documentation for more information. ]
135
136When a file is read or written, sysfs calls the appropriate method
137for the type. The method then translates the generic struct kobject
138and struct attribute pointers to the appropriate pointer types, and
139calls the associated methods. 
140
141
142To 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
147static 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
165Reading/Writing Attribute Data
166~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
168To read or write attributes, show() or store() methods must be
169specified when declaring the attribute. The method types should be as
170simple as those defined for device attributes:
171
172ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
173ssize_t (*store)(struct device *dev, struct device_attribute *attr,
174                 const char *buf, size_t count);
175
176IOW, they should take only an object, an attribute, and a buffer as parameters.
177
178
179sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
180method. Sysfs will call the method exactly once for each read or
181write. This forces the following behavior on the method
182implementations: 
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() method.
195  A terminating null is added after the data on stores. This makes
196  functions like sysfs_streq() safe to use.
197
198  When writing sysfs files, userspace processes should first read the
199  entire file, modify the values it wishes to change, then write the
200  entire buffer back. 
201
202  Attribute method implementations should operate on an identical
203  buffer when reading and writing values. 
204
205Other notes:
206
207- Writing causes the show() method to be rearmed regardless of current
208  file position.
209
210- The buffer will always be PAGE_SIZE bytes in length. On i386, this
211  is 4096. 
212
213- show() methods should return the number of bytes printed into the
214  buffer. This is the return value of scnprintf().
215
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
219  scnprintf().
220
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.
223
224- show() or store() can always return errors. If a bad value comes
225  through, be sure to return an error.
226
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. 
231
232
233A very simple (and naive) implementation of a device attribute is:
234
235static ssize_t show_name(struct device *dev, struct device_attribute *attr,
236                         char *buf)
237{
238	return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
239}
240
241static ssize_t store_name(struct device *dev, struct device_attribute *attr,
242                          const char *buf, size_t count)
243{
244        snprintf(dev->name, sizeof(dev->name), "%.*s",
245                 (int)min(count, sizeof(dev->name) - 1), buf);
246	return count;
247}
248
249static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
250
251
252(Note that the real implementation doesn't allow userspace to set the 
253name for a device.)
254
255
256Top Level Directory Layout
257~~~~~~~~~~~~~~~~~~~~~~~~~~
258
259The sysfs directory arrangement exposes the relationship of kernel
260data structures. 
261
262The top level sysfs directory looks like:
263
264block/
265bus/
266class/
267dev/
268devices/
269firmware/
270net/
271fs/
272
273devices/ contains a filesystem representation of the device tree. It maps
274directly to the internal kernel device tree, which is a hierarchy of
275struct device. 
276
277bus/ contains flat directory layout of the various bus types in the
278kernel. Each bus's directory contains two subdirectories:
279
280	devices/
281	drivers/
282
283devices/ contains symlinks for each device discovered in the system
284that point to the device's directory under root/.
285
286drivers/ contains a directory for each device driver that is loaded
287for devices on that particular bus (this assumes that drivers do not
288span multiple bus types).
289
290fs/ contains a directory for some filesystems.  Currently each
291filesystem wanting to export attributes must create its own hierarchy
292below fs/ (see ./fuse.txt for an example).
293
294dev/ contains two directories char/ and block/. Inside these two
295directories there are symlinks named <major>:<minor>.  These symlinks
296point to the sysfs directory for the given device.  /sys/dev provides a
297quick way to lookup the sysfs interface for a device from the result of
298a stat(2) operation.
299
300More information can driver-model specific features can be found in
301Documentation/driver-model/. 
302
303
304TODO: Finish this section.
305
306
307Current Interfaces
308~~~~~~~~~~~~~~~~~~
309
310The following interface layers currently exist in sysfs:
311
312
313- devices (include/linux/device.h)
314----------------------------------
315Structure:
316
317struct device_attribute {
318	struct attribute	attr;
319	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
320			char *buf);
321	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
322			 const char *buf, size_t count);
323};
324
325Declaring:
326
327DEVICE_ATTR(_name, _mode, _show, _store);
328
329Creation/Removal:
330
331int device_create_file(struct device *dev, const struct device_attribute * attr);
332void device_remove_file(struct device *dev, const struct device_attribute * attr);
333
334
335- bus drivers (include/linux/device.h)
336--------------------------------------
337Structure:
338
339struct 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);
343};
344
345Declaring:
346
347BUS_ATTR(_name, _mode, _show, _store)
348
349Creation/Removal:
350
351int bus_create_file(struct bus_type *, struct bus_attribute *);
352void bus_remove_file(struct bus_type *, struct bus_attribute *);
353
354
355- device drivers (include/linux/device.h)
356-----------------------------------------
357
358Structure:
359
360struct driver_attribute {
361        struct attribute        attr;
362        ssize_t (*show)(struct device_driver *, char * buf);
363        ssize_t (*store)(struct device_driver *, const char * buf,
364                         size_t count);
365};
366
367Declaring:
368
369DRIVER_ATTR(_name, _mode, _show, _store)
370
371Creation/Removal:
372
373int driver_create_file(struct device_driver *, const struct driver_attribute *);
374void driver_remove_file(struct device_driver *, const struct driver_attribute *);
375
376
377Documentation
378~~~~~~~~~~~~~
379
380The sysfs directory structure and the attributes in each directory define an
381ABI between the kernel and user space. As for any ABI, it is important that
382this ABI is stable and properly documented. All new sysfs attributes must be
383documented in Documentation/ABI. See also Documentation/ABI/README for more
384information.