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.
 236
 237 - show() should only use sysfs_emit() or sysfs_emit_at() when formatting
 238   the value to be returned to user space.
 239
 240 - store() should return the number of bytes used from the buffer. If the
 241   entire buffer has been used, just return the count argument.
 242
 243 - show() or store() can always return errors. If a bad value comes
 244   through, be sure to return an error.
 245
 246 - The object passed to the methods will be pinned in memory via sysfs
 247   referencing counting its embedded object. However, the physical
 248   entity (e.g. device) the object represents may not be present. Be
 249   sure to have a way to check this, if necessary.
 250
 251
 252 A very simple (and naive) implementation of a device attribute is:
 253
 254 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
 255                          char *buf)
 256 {
 257         return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
 258 }
 259
 260 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
 261                           const char *buf, size_t count)
 262 {
 263         snprintf(dev->name, sizeof(dev->name), "%.*s",
 264                  (int)min(count, sizeof(dev->name) - 1), buf);
 265         return count;
 266 }
 267
 268 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
 269
 270
 271 (Note that the real implementation doesn't allow userspace to set the
 272 name for a device.)
 273
 274
 275 Top Level Directory Layout
 276 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 277
 278 The sysfs directory arrangement exposes the relationship of kernel
 279 data structures.
 280
 281 The top level sysfs directory looks like:
 282
 283 block/
 284 bus/
 285 class/
 286 dev/
 287 devices/
 288 firmware/
 289 net/
 290 fs/
 291
 292 devices/ contains a filesystem representation of the device tree. It maps
 293 directly to the internal kernel device tree, which is a hierarchy of
 294 struct device.
 295
 296 bus/ contains flat directory layout of the various bus types in the
 297 kernel. Each bus's directory contains two subdirectories:
 298
 299         devices/
 300         drivers/
 301
 302 devices/ contains symlinks for each device discovered in the system
 303 that point to the device's directory under root/.
 304
 305 drivers/ contains a directory for each device driver that is loaded
 306 for devices on that particular bus (this assumes that drivers do not
 307 span multiple bus types).
 308
 309 fs/ contains a directory for some filesystems.  Currently each
 310 filesystem wanting to export attributes must create its own hierarchy
 311 below fs/ (see ./fuse.txt for an example).
 312
 313 dev/ contains two directories char/ and block/. Inside these two
 314 directories there are symlinks named <major>:<minor>.  These symlinks
 315 point to the sysfs directory for the given device.  /sys/dev provides a
 316 quick way to lookup the sysfs interface for a device from the result of
 317 a stat(2) operation.
 318
 319 More information can driver-model specific features can be found in
 320 Documentation/driver-api/driver-model/.
 321
 322
 323 TODO: Finish this section.
 324
 325
 326 Current Interfaces
 327 ~~~~~~~~~~~~~~~~~~
 328
 329 The following interface layers currently exist in sysfs:
 330
 331
 332 - devices (include/linux/device.h)
 333 ----------------------------------
 334 Structure:
 335
 336 struct device_attribute {
 337         struct attribute        attr;
 338         ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 339                         char *buf);
 340         ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 341                          const char *buf, size_t count);
 342 };
 343
 344 Declaring:
 345
 346 DEVICE_ATTR(_name, _mode, _show, _store);
 347
 348 Creation/Removal:
 349
 350 int device_create_file(struct device *dev, const struct device_attribute * attr);
 351 void device_remove_file(struct device *dev, const struct device_attribute * attr);
 352
 353
 354 - bus drivers (include/linux/device.h)
 355 --------------------------------------
 356 Structure:
 357
 358 struct bus_attribute {
 359         struct attribute        attr;
 360         ssize_t (*show)(struct bus_type *, char * buf);
 361         ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
 362 };
 363
 364 Declaring:
 365
 366 static BUS_ATTR_RW(name);
 367 static BUS_ATTR_RO(name);
 368 static BUS_ATTR_WO(name);
 369
 370 Creation/Removal:
 371
 372 int bus_create_file(struct bus_type *, struct bus_attribute *);
 373 void bus_remove_file(struct bus_type *, struct bus_attribute *);
 374
 375
 376 - device drivers (include/linux/device.h)
 377 -----------------------------------------
 378
 379 Structure:
 380
 381 struct driver_attribute {
 382         struct attribute        attr;
 383         ssize_t (*show)(struct device_driver *, char * buf);
 384         ssize_t (*store)(struct device_driver *, const char * buf,
 385                          size_t count);
 386 };
 387
 388 Declaring:
 389
 390 DRIVER_ATTR_RO(_name)
 391 DRIVER_ATTR_RW(_name)
 392
 393 Creation/Removal:
 394
 395 int driver_create_file(struct device_driver *, const struct driver_attribute *);
 396 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
 397
 398
 399 Documentation
 400 ~~~~~~~~~~~~~
 401
 402 The sysfs directory structure and the attributes in each directory define an
 403 ABI between the kernel and user space. As for any ABI, it is important that
 404 this ABI is stable and properly documented. All new sysfs attributes must be
 405 documented in Documentation/ABI. See also Documentation/ABI/README for more
 406 information.