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