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 sysfs_dirent 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()
 195   method.
 196
 197   When writing sysfs files, userspace processes should first read the
 198   entire file, modify the values it wishes to change, then write the
 199   entire buffer back.
 200
 201   Attribute method implementations should operate on an identical
 202   buffer when reading and writing values.
 203
 204 Other notes:
 205
 206 - Writing causes the show() method to be rearmed regardless of current
 207   file position.
 208
 209 - The buffer will always be PAGE_SIZE bytes in length. On i386, this
 210   is 4096.
 211
 212 - show() methods should return the number of bytes printed into the
 213   buffer. This is the return value of scnprintf().
 214
 215 - show() must not use snprintf() when formatting the value to be
 216   returned to user space. If you can guarantee that an overflow
 217   will never happen you can use sprintf() otherwise you must use
 218   scnprintf().
 219
 220 - store() should return the number of bytes used from the buffer. If the
 221   entire buffer has been used, just return the count argument.
 222
 223 - show() or store() can always return errors. If a bad value comes
 224   through, be sure to return an error.
 225
 226 - The object passed to the methods will be pinned in memory via sysfs
 227   referencing counting its embedded object. However, the physical
 228   entity (e.g. device) the object represents may not be present. Be
 229   sure to have a way to check this, if necessary.
 230
 231
 232 A very simple (and naive) implementation of a device attribute is:
 233
 234 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
 235                          char *buf)
 236 {
 237         return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
 238 }
 239
 240 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
 241                           const char *buf, size_t count)
 242 {
 243         snprintf(dev->name, sizeof(dev->name), "%.*s",
 244                  (int)min(count, sizeof(dev->name) - 1), buf);
 245         return count;
 246 }
 247
 248 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
 249
 250
 251 (Note that the real implementation doesn't allow userspace to set the
 252 name for a device.)
 253
 254
 255 Top Level Directory Layout
 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 257
 258 The sysfs directory arrangement exposes the relationship of kernel
 259 data structures.
 260
 261 The top level sysfs directory looks like:
 262
 263 block/
 264 bus/
 265 class/
 266 dev/
 267 devices/
 268 firmware/
 269 net/
 270 fs/
 271
 272 devices/ contains a filesystem representation of the device tree. It maps
 273 directly to the internal kernel device tree, which is a hierarchy of
 274 struct device.
 275
 276 bus/ contains flat directory layout of the various bus types in the
 277 kernel. Each bus's directory contains two subdirectories:
 278
 279         devices/
 280         drivers/
 281
 282 devices/ contains symlinks for each device discovered in the system
 283 that point to the device's directory under root/.
 284
 285 drivers/ contains a directory for each device driver that is loaded
 286 for devices on that particular bus (this assumes that drivers do not
 287 span multiple bus types).
 288
 289 fs/ contains a directory for some filesystems.  Currently each
 290 filesystem wanting to export attributes must create its own hierarchy
 291 below fs/ (see ./fuse.txt for an example).
 292
 293 dev/ contains two directories char/ and block/. Inside these two
 294 directories there are symlinks named <major>:<minor>.  These symlinks
 295 point to the sysfs directory for the given device.  /sys/dev provides a
 296 quick way to lookup the sysfs interface for a device from the result of
 297 a stat(2) operation.
 298
 299 More information can driver-model specific features can be found in
 300 Documentation/driver-model/.
 301
 302
 303 TODO: Finish this section.
 304
 305
 306 Current Interfaces
 307 ~~~~~~~~~~~~~~~~~~
 308
 309 The following interface layers currently exist in sysfs:
 310
 311
 312 - devices (include/linux/device.h)
 313 ----------------------------------
 314 Structure:
 315
 316 struct device_attribute {
 317         struct attribute        attr;
 318         ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 319                         char *buf);
 320         ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 321                          const char *buf, size_t count);
 322 };
 323
 324 Declaring:
 325
 326 DEVICE_ATTR(_name, _mode, _show, _store);
 327
 328 Creation/Removal:
 329
 330 int device_create_file(struct device *dev, const struct device_attribute * attr);
 331 void device_remove_file(struct device *dev, const struct device_attribute * attr);
 332
 333
 334 - bus drivers (include/linux/device.h)
 335 --------------------------------------
 336 Structure:
 337
 338 struct bus_attribute {
 339         struct attribute        attr;
 340         ssize_t (*show)(struct bus_type *, char * buf);
 341         ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
 342 };
 343
 344 Declaring:
 345
 346 BUS_ATTR(_name, _mode, _show, _store)
 347
 348 Creation/Removal:
 349
 350 int bus_create_file(struct bus_type *, struct bus_attribute *);
 351 void bus_remove_file(struct bus_type *, struct bus_attribute *);
 352
 353
 354 - device drivers (include/linux/device.h)
 355 -----------------------------------------
 356
 357 Structure:
 358
 359 struct driver_attribute {
 360         struct attribute        attr;
 361         ssize_t (*show)(struct device_driver *, char * buf);
 362         ssize_t (*store)(struct device_driver *, const char * buf,
 363                          size_t count);
 364 };
 365
 366 Declaring:
 367
 368 DRIVER_ATTR(_name, _mode, _show, _store)
 369
 370 Creation/Removal:
 371
 372 int driver_create_file(struct device_driver *, const struct driver_attribute *);
 373 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
 374
 375
 376 Documentation
 377 ~~~~~~~~~~~~~
 378
 379 The sysfs directory structure and the attributes in each directory define an
 380 ABI between the kernel and user space. As for any ABI, it is important that
 381 this ABI is stable and properly documented. All new sysfs attributes must be
 382 documented in Documentation/ABI. See also Documentation/ABI/README for more
 383 information.