Version:  2.0.40 2.2.26 2.4.37 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8

Linux/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 
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() 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 
205 Other 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 
233 A very simple (and naive) implementation of a device attribute is:
234 
235 static 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 
241 static 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 
249 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
250 
251 
252 (Note that the real implementation doesn't allow userspace to set the 
253 name for a device.)
254 
255 
256 Top Level Directory Layout
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~
258 
259 The sysfs directory arrangement exposes the relationship of kernel
260 data structures. 
261 
262 The top level sysfs directory looks like:
263 
264 block/
265 bus/
266 class/
267 dev/
268 devices/
269 firmware/
270 net/
271 fs/
272 
273 devices/ contains a filesystem representation of the device tree. It maps
274 directly to the internal kernel device tree, which is a hierarchy of
275 struct device. 
276 
277 bus/ contains flat directory layout of the various bus types in the
278 kernel. Each bus's directory contains two subdirectories:
279 
280         devices/
281         drivers/
282 
283 devices/ contains symlinks for each device discovered in the system
284 that point to the device's directory under root/.
285 
286 drivers/ contains a directory for each device driver that is loaded
287 for devices on that particular bus (this assumes that drivers do not
288 span multiple bus types).
289 
290 fs/ contains a directory for some filesystems.  Currently each
291 filesystem wanting to export attributes must create its own hierarchy
292 below fs/ (see ./fuse.txt for an example).
293 
294 dev/ contains two directories char/ and block/. Inside these two
295 directories there are symlinks named <major>:<minor>.  These symlinks
296 point to the sysfs directory for the given device.  /sys/dev provides a
297 quick way to lookup the sysfs interface for a device from the result of
298 a stat(2) operation.
299 
300 More information can driver-model specific features can be found in
301 Documentation/driver-model/. 
302 
303 
304 TODO: Finish this section.
305 
306 
307 Current Interfaces
308 ~~~~~~~~~~~~~~~~~~
309 
310 The following interface layers currently exist in sysfs:
311 
312 
313 - devices (include/linux/device.h)
314 ----------------------------------
315 Structure:
316 
317 struct 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 
325 Declaring:
326 
327 DEVICE_ATTR(_name, _mode, _show, _store);
328 
329 Creation/Removal:
330 
331 int device_create_file(struct device *dev, const struct device_attribute * attr);
332 void device_remove_file(struct device *dev, const struct device_attribute * attr);
333 
334 
335 - bus drivers (include/linux/device.h)
336 --------------------------------------
337 Structure:
338 
339 struct 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 
345 Declaring:
346 
347 BUS_ATTR(_name, _mode, _show, _store)
348 
349 Creation/Removal:
350 
351 int bus_create_file(struct bus_type *, struct bus_attribute *);
352 void bus_remove_file(struct bus_type *, struct bus_attribute *);
353 
354 
355 - device drivers (include/linux/device.h)
356 -----------------------------------------
357 
358 Structure:
359 
360 struct 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 
367 Declaring:
368 
369 DRIVER_ATTR(_name, _mode, _show, _store)
370 
371 Creation/Removal:
372 
373 int driver_create_file(struct device_driver *, const struct driver_attribute *);
374 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
375 
376 
377 Documentation
378 ~~~~~~~~~~~~~
379 
380 The sysfs directory structure and the attributes in each directory define an
381 ABI between the kernel and user space. As for any ABI, it is important that
382 this ABI is stable and properly documented. All new sysfs attributes must be
383 documented in Documentation/ABI. See also Documentation/ABI/README for more
384 information.

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us