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.