Documentation/filesystems/sysfs.txt

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