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:    15 July 2010
   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 *, size_t);
 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(obj) container_of(obj, struct device, kobj)
 143 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
 144
 145 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
 146                              char *buf)
 147 {
 148         struct device_attribute *dev_attr = to_dev_attr(attr);
 149         struct device *dev = to_dev(kobj);
 150         ssize_t ret = -EIO;
 151
 152         if (dev_attr->show)
 153                 ret = dev_attr->show(dev, dev_attr, buf);
 154         if (ret >= (ssize_t)PAGE_SIZE) {
 155                 print_symbol("dev_attr_show: %s returned bad count\n",
 156                                 (unsigned long)dev_attr->show);
 157         }
 158         return ret;
 159 }
 160
 161
 162
 163 Reading/Writing Attribute Data
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 165
 166 To read or write attributes, show() or store() methods must be
 167 specified when declaring the attribute. The method types should be as
 168 simple as those defined for device attributes:
 169
 170 ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
 171 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 172                  const char *buf, size_t count);
 173
 174 IOW, they should take only an object, an attribute, and a buffer as parameters.
 175
 176
 177 sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
 178 method. Sysfs will call the method exactly once for each read or
 179 write. This forces the following behavior on the method
 180 implementations:
 181
 182 - On read(2), the show() method should fill the entire buffer.
 183   Recall that an attribute should only be exporting one value, or an
 184   array of similar values, so this shouldn't be that expensive.
 185
 186   This allows userspace to do partial reads and forward seeks
 187   arbitrarily over the entire file at will. If userspace seeks back to
 188   zero or does a pread(2) with an offset of '0' the show() method will
 189   be called again, rearmed, to fill the buffer.
 190
 191 - On write(2), sysfs expects the entire buffer to be passed during the
 192   first write. Sysfs then passes the entire buffer to the store()
 193   method.
 194
 195   When writing sysfs files, userspace processes should first read the
 196   entire file, modify the values it wishes to change, then write the
 197   entire buffer back.
 198
 199   Attribute method implementations should operate on an identical
 200   buffer when reading and writing values.
 201
 202 Other notes:
 203
 204 - Writing causes the show() method to be rearmed regardless of current
 205   file position.
 206
 207 - The buffer will always be PAGE_SIZE bytes in length. On i386, this
 208   is 4096.
 209
 210 - show() methods should return the number of bytes printed into the
 211   buffer. This is the return value of snprintf().
 212
 213 - show() should always use snprintf().
 214
 215 - store() should return the number of bytes used from the buffer. If the
 216   entire buffer has been used, just return the count argument.
 217
 218 - show() or store() can always return errors. If a bad value comes
 219   through, be sure to return an error.
 220
 221 - The object passed to the methods will be pinned in memory via sysfs
 222   referencing counting its embedded object. However, the physical
 223   entity (e.g. device) the object represents may not be present. Be
 224   sure to have a way to check this, if necessary.
 225
 226
 227 A very simple (and naive) implementation of a device attribute is:
 228
 229 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
 230                          char *buf)
 231 {
 232         return snprintf(buf, PAGE_SIZE, "%s\n", dev->name);
 233 }
 234
 235 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
 236                           const char *buf, size_t count)
 237 {
 238         snprintf(dev->name, sizeof(dev->name), "%.*s",
 239                  (int)min(count, sizeof(dev->name) - 1), buf);
 240         return count;
 241 }
 242
 243 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
 244
 245
 246 (Note that the real implementation doesn't allow userspace to set the
 247 name for a device.)
 248
 249
 250 Top Level Directory Layout
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253 The sysfs directory arrangement exposes the relationship of kernel
 254 data structures.
 255
 256 The top level sysfs directory looks like:
 257
 258 block/
 259 bus/
 260 class/
 261 dev/
 262 devices/
 263 firmware/
 264 net/
 265 fs/
 266
 267 devices/ contains a filesystem representation of the device tree. It maps
 268 directly to the internal kernel device tree, which is a hierarchy of
 269 struct device.
 270
 271 bus/ contains flat directory layout of the various bus types in the
 272 kernel. Each bus's directory contains two subdirectories:
 273
 274         devices/
 275         drivers/
 276
 277 devices/ contains symlinks for each device discovered in the system
 278 that point to the device's directory under root/.
 279
 280 drivers/ contains a directory for each device driver that is loaded
 281 for devices on that particular bus (this assumes that drivers do not
 282 span multiple bus types).
 283
 284 fs/ contains a directory for some filesystems.  Currently each
 285 filesystem wanting to export attributes must create its own hierarchy
 286 below fs/ (see ./fuse.txt for an example).
 287
 288 dev/ contains two directories char/ and block/. Inside these two
 289 directories there are symlinks named <major>:<minor>.  These symlinks
 290 point to the sysfs directory for the given device.  /sys/dev provides a
 291 quick way to lookup the sysfs interface for a device from the result of
 292 a stat(2) operation.
 293
 294 More information can driver-model specific features can be found in
 295 Documentation/driver-model/.
 296
 297
 298 TODO: Finish this section.
 299
 300
 301 Current Interfaces
 302 ~~~~~~~~~~~~~~~~~~
 303
 304 The following interface layers currently exist in sysfs:
 305
 306
 307 - devices (include/linux/device.h)
 308 ----------------------------------
 309 Structure:
 310
 311 struct device_attribute {
 312         struct attribute        attr;
 313         ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 314                         char *buf);
 315         ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 316                          const char *buf, size_t count);
 317 };
 318
 319 Declaring:
 320
 321 DEVICE_ATTR(_name, _mode, _show, _store);
 322
 323 Creation/Removal:
 324
 325 int device_create_file(struct device *dev, const struct device_attribute * attr);
 326 void device_remove_file(struct device *dev, const struct device_attribute * attr);
 327
 328
 329 - bus drivers (include/linux/device.h)
 330 --------------------------------------
 331 Structure:
 332
 333 struct bus_attribute {
 334         struct attribute        attr;
 335         ssize_t (*show)(struct bus_type *, char * buf);
 336         ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
 337 };
 338
 339 Declaring:
 340
 341 BUS_ATTR(_name, _mode, _show, _store)
 342
 343 Creation/Removal:
 344
 345 int bus_create_file(struct bus_type *, struct bus_attribute *);
 346 void bus_remove_file(struct bus_type *, struct bus_attribute *);
 347
 348
 349 - device drivers (include/linux/device.h)
 350 -----------------------------------------
 351
 352 Structure:
 353
 354 struct driver_attribute {
 355         struct attribute        attr;
 356         ssize_t (*show)(struct device_driver *, char * buf);
 357         ssize_t (*store)(struct device_driver *, const char * buf,
 358                          size_t count);
 359 };
 360
 361 Declaring:
 362
 363 DRIVER_ATTR(_name, _mode, _show, _store)
 364
 365 Creation/Removal:
 366
 367 int driver_create_file(struct device_driver *, const struct driver_attribute *);
 368 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
 369
 370