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:    22 February 2009
   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 the kobject that owns the directory in the
  43 ->d_fsdata pointer of the directory's dentry. This allows sysfs to do
  44 reference counting directly on the kobject when the file is opened and
  45 closed.
  46
  47
  48 Attributes
  49 ~~~~~~~~~~
  50
  51 Attributes can be exported for kobjects in the form of regular files in
  52 the filesystem. Sysfs forwards file I/O operations to methods defined
  53 for the attributes, providing a means to read and write kernel
  54 attributes.
  55
  56 Attributes should be ASCII text files, preferably with only one value
  57 per file. It is noted that it may not be efficient to contain only one
  58 value per file, so it is socially acceptable to express an array of
  59 values of the same type.
  60
  61 Mixing types, expressing multiple lines of data, and doing fancy
  62 formatting of data is heavily frowned upon. Doing these things may get
  63 you publically humiliated and your code rewritten without notice.
  64
  65
  66 An attribute definition is simply:
  67
  68 struct attribute {
  69         char                    * name;
  70         struct module           *owner;
  71         mode_t                  mode;
  72 };
  73
  74
  75 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
  76 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
  77
  78
  79 A bare attribute contains no means to read or write the value of the
  80 attribute. Subsystems are encouraged to define their own attribute
  81 structure and wrapper functions for adding and removing attributes for
  82 a specific object type.
  83
  84 For example, the driver model defines struct device_attribute like:
  85
  86 struct device_attribute {
  87         struct attribute        attr;
  88         ssize_t (*show)(struct device *dev, struct device_attribute *attr,
  89                         char *buf);
  90         ssize_t (*store)(struct device *dev, struct device_attribute *attr,
  91                          const char *buf, size_t count);
  92 };
  93
  94 int device_create_file(struct device *, const struct device_attribute *);
  95 void device_remove_file(struct device *, const struct device_attribute *);
  96
  97 It also defines this helper for defining device attributes:
  98
  99 #define DEVICE_ATTR(_name, _mode, _show, _store) \
 100 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
 101
 102 For example, declaring
 103
 104 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
 105
 106 is equivalent to doing:
 107
 108 static struct device_attribute dev_attr_foo = {
 109        .attr    = {
 110                 .name = "foo",
 111                 .mode = S_IWUSR | S_IRUGO,
 112                 .show = show_foo,
 113                 .store = store_foo,
 114         },
 115 };
 116
 117
 118 Subsystem-Specific Callbacks
 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 When a subsystem defines a new attribute type, it must implement a
 122 set of sysfs operations for forwarding read and write calls to the
 123 show and store methods of the attribute owners.
 124
 125 struct sysfs_ops {
 126         ssize_t (*show)(struct kobject *, struct attribute *, char *);
 127         ssize_t (*store)(struct kobject *, struct attribute *, const char *);
 128 };
 129
 130 [ Subsystems should have already defined a struct kobj_type as a
 131 descriptor for this type, which is where the sysfs_ops pointer is
 132 stored. See the kobject documentation for more information. ]
 133
 134 When a file is read or written, sysfs calls the appropriate method
 135 for the type. The method then translates the generic struct kobject
 136 and struct attribute pointers to the appropriate pointer types, and
 137 calls the associated methods.
 138
 139
 140 To illustrate:
 141
 142 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
 143 #define to_dev(d) container_of(d, struct device, kobj)
 144
 145 static ssize_t
 146 dev_attr_show(struct kobject * kobj, struct attribute * attr, char * buf)
 147 {
 148         struct device_attribute * dev_attr = to_dev_attr(attr);
 149         struct device * dev = to_dev(kobj);
 150         ssize_t ret = 0;
 151
 152         if (dev_attr->show)
 153                 ret = dev_attr->show(dev, buf);
 154         return ret;
 155 }
 156
 157
 158
 159 Reading/Writing Attribute Data
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 To read or write attributes, show() or store() methods must be
 163 specified when declaring the attribute. The method types should be as
 164 simple as those defined for device attributes:
 165
 166 ssize_t (*show)(struct device * dev, struct device_attribute * attr,
 167                 char * buf);
 168 ssize_t (*store)(struct device * dev, struct device_attribute * attr,
 169                  const char * buf);
 170
 171 IOW, they should take only an object, an attribute, and a buffer as parameters.
 172
 173
 174 sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
 175 method. Sysfs will call the method exactly once for each read or
 176 write. This forces the following behavior on the method
 177 implementations:
 178
 179 - On read(2), the show() method should fill the entire buffer.
 180   Recall that an attribute should only be exporting one value, or an
 181   array of similar values, so this shouldn't be that expensive.
 182
 183   This allows userspace to do partial reads and forward seeks
 184   arbitrarily over the entire file at will. If userspace seeks back to
 185   zero or does a pread(2) with an offset of '0' the show() method will
 186   be called again, rearmed, to fill the buffer.
 187
 188 - On write(2), sysfs expects the entire buffer to be passed during the
 189   first write. Sysfs then passes the entire buffer to the store()
 190   method.
 191
 192   When writing sysfs files, userspace processes should first read the
 193   entire file, modify the values it wishes to change, then write the
 194   entire buffer back.
 195
 196   Attribute method implementations should operate on an identical
 197   buffer when reading and writing values.
 198
 199 Other notes:
 200
 201 - Writing causes the show() method to be rearmed regardless of current
 202   file position.
 203
 204 - The buffer will always be PAGE_SIZE bytes in length. On i386, this
 205   is 4096.
 206
 207 - show() methods should return the number of bytes printed into the
 208   buffer. This is the return value of snprintf().
 209
 210 - show() should always use snprintf().
 211
 212 - store() should return the number of bytes used from the buffer. This
 213   can be done using strlen().
 214
 215 - show() or store() can always return errors. If a bad value comes
 216   through, be sure to return an error.
 217
 218 - The object passed to the methods will be pinned in memory via sysfs
 219   referencing counting its embedded object. However, the physical
 220   entity (e.g. device) the object represents may not be present. Be
 221   sure to have a way to check this, if necessary.
 222
 223
 224 A very simple (and naive) implementation of a device attribute is:
 225
 226 static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf)
 227 {
 228         return snprintf(buf, PAGE_SIZE, "%s\n", dev->name);
 229 }
 230
 231 static ssize_t store_name(struct device * dev, const char * buf)
 232 {
 233         sscanf(buf, "%20s", dev->name);
 234         return strnlen(buf, PAGE_SIZE);
 235 }
 236
 237 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
 238
 239
 240 (Note that the real implementation doesn't allow userspace to set the
 241 name for a device.)
 242
 243
 244 Top Level Directory Layout
 245 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 246
 247 The sysfs directory arrangement exposes the relationship of kernel
 248 data structures.
 249
 250 The top level sysfs directory looks like:
 251
 252 block/
 253 bus/
 254 class/
 255 dev/
 256 devices/
 257 firmware/
 258 net/
 259 fs/
 260
 261 devices/ contains a filesystem representation of the device tree. It maps
 262 directly to the internal kernel device tree, which is a hierarchy of
 263 struct device.
 264
 265 bus/ contains flat directory layout of the various bus types in the
 266 kernel. Each bus's directory contains two subdirectories:
 267
 268         devices/
 269         drivers/
 270
 271 devices/ contains symlinks for each device discovered in the system
 272 that point to the device's directory under root/.
 273
 274 drivers/ contains a directory for each device driver that is loaded
 275 for devices on that particular bus (this assumes that drivers do not
 276 span multiple bus types).
 277
 278 fs/ contains a directory for some filesystems.  Currently each
 279 filesystem wanting to export attributes must create its own hierarchy
 280 below fs/ (see ./fuse.txt for an example).
 281
 282 dev/ contains two directories char/ and block/. Inside these two
 283 directories there are symlinks named <major>:<minor>.  These symlinks
 284 point to the sysfs directory for the given device.  /sys/dev provides a
 285 quick way to lookup the sysfs interface for a device from the result of
 286 a stat(2) operation.
 287
 288 More information can driver-model specific features can be found in
 289 Documentation/driver-model/.
 290
 291
 292 TODO: Finish this section.
 293
 294
 295 Current Interfaces
 296 ~~~~~~~~~~~~~~~~~~
 297
 298 The following interface layers currently exist in sysfs:
 299
 300
 301 - devices (include/linux/device.h)
 302 ----------------------------------
 303 Structure:
 304
 305 struct device_attribute {
 306         struct attribute        attr;
 307         ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 308                         char *buf);
 309         ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 310                          const char *buf, size_t count);
 311 };
 312
 313 Declaring:
 314
 315 DEVICE_ATTR(_name, _mode, _show, _store);
 316
 317 Creation/Removal:
 318
 319 int device_create_file(struct device *dev, const struct device_attribute * attr);
 320 void device_remove_file(struct device *dev, const struct device_attribute * attr);
 321
 322
 323 - bus drivers (include/linux/device.h)
 324 --------------------------------------
 325 Structure:
 326
 327 struct bus_attribute {
 328         struct attribute        attr;
 329         ssize_t (*show)(struct bus_type *, char * buf);
 330         ssize_t (*store)(struct bus_type *, const char * buf);
 331 };
 332
 333 Declaring:
 334
 335 BUS_ATTR(_name, _mode, _show, _store)
 336
 337 Creation/Removal:
 338
 339 int bus_create_file(struct bus_type *, struct bus_attribute *);
 340 void bus_remove_file(struct bus_type *, struct bus_attribute *);
 341
 342
 343 - device drivers (include/linux/device.h)
 344 -----------------------------------------
 345
 346 Structure:
 347
 348 struct driver_attribute {
 349         struct attribute        attr;
 350         ssize_t (*show)(struct device_driver *, char * buf);
 351         ssize_t (*store)(struct device_driver *, const char * buf,
 352                          size_t count);
 353 };
 354
 355 Declaring:
 356
 357 DRIVER_ATTR(_name, _mode, _show, _store)
 358
 359 Creation/Removal:
 360
 361 int driver_create_file(struct device_driver *, const struct driver_attribute *);
 362 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
 363
 364