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