| 1 | |
| 2 |
|
| 3 | =====================================================
|
| 4 | sysfs - _The_ filesystem for exporting kernel objects
|
| 5 | =====================================================
|
| 6 |
|
| 7 | Patrick Mochel <[email protected]>
|
| 8 |
|
| 9 | Mike Murphy <[email protected]>
|
| 10 |
|
| 11 | :Revised: 16 August 2011
|
| 12 | :Original: 10 January 2003
|
| 13 |
|
| 14 |
|
| 15 | What it is
|
| 16 | ~~~~~~~~~~
|
| 17 |
|
| 18 | sysfs is a RAM-based filesystem initially based on ramfs. It provides
|
| 19 | a means to export kernel data structures, their attributes, and the
|
| 20 | linkages between them to userspace.
|
| 21 |
|
| 22 | sysfs is tied inherently to the kobject infrastructure. Please read
|
| 23 | Documentation/core-api/kobject.rst for more information concerning the kobject
|
| 24 | interface.
|
| 25 |
|
| 26 |
|
| 27 | Using sysfs
|
| 28 | ~~~~~~~~~~~
|
| 29 |
|
| 30 | sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
|
| 31 | it by doing::
|
| 32 |
|
| 33 | mount -t sysfs sysfs /sys
|
| 34 |
|
| 35 |
|
| 36 | Directory Creation
|
| 37 | ~~~~~~~~~~~~~~~~~~
|
| 38 |
|
| 39 | For every kobject that is registered with the system, a directory is
|
| 40 | created for it in sysfs. That directory is created as a subdirectory
|
| 41 | of the kobject's parent, expressing internal object hierarchies to
|
| 42 | userspace. Top-level directories in sysfs represent the common
|
| 43 | ancestors of object hierarchies; i.e. the subsystems the objects
|
| 44 | belong to.
|
| 45 |
|
| 46 | sysfs internally stores a pointer to the kobject that implements a
|
| 47 | directory in the kernfs_node object associated with the directory. In
|
| 48 | the past this kobject pointer has been used by sysfs to do reference
|
| 49 | counting directly on the kobject whenever the file is opened or closed.
|
| 50 | With the current sysfs implementation the kobject reference count is
|
| 51 | only modified directly by the function sysfs_schedule_callback().
|
| 52 |
|
| 53 |
|
| 54 | Attributes
|
| 55 | ~~~~~~~~~~
|
| 56 |
|
| 57 | Attributes can be exported for kobjects in the form of regular files in
|
| 58 | the filesystem. sysfs forwards file I/O operations to methods defined
|
| 59 | for the attributes, providing a means to read and write kernel
|
| 60 | attributes.
|
| 61 |
|
| 62 | Attributes should be ASCII text files, preferably with only one value
|
| 63 | per file. It is noted that it may not be efficient to contain only one
|
| 64 | value per file, so it is socially acceptable to express an array of
|
| 65 | values of the same type.
|
| 66 |
|
| 67 | Mixing types, expressing multiple lines of data, and doing fancy
|
| 68 | formatting of data is heavily frowned upon. Doing these things may get
|
| 69 | you publicly humiliated and your code rewritten without notice.
|
| 70 |
|
| 71 |
|
| 72 | An attribute definition is simply::
|
| 73 |
|
| 74 | struct attribute {
|
| 75 | char *name;
|
| 76 | struct module *owner;
|
| 77 | umode_t mode;
|
| 78 | };
|
| 79 |
|
| 80 |
|
| 81 | int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
|
| 82 | void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
|
| 83 |
|
| 84 |
|
| 85 | A bare attribute contains no means to read or write the value of the
|
| 86 | attribute. Subsystems are encouraged to define their own attribute
|
| 87 | structure and wrapper functions for adding and removing attributes for
|
| 88 | a specific object type.
|
| 89 |
|
| 90 | For example, the driver model defines struct device_attribute like::
|
| 91 |
|
| 92 | struct device_attribute {
|
| 93 | struct attribute attr;
|
| 94 | ssize_t (*show)(struct device *dev, struct device_attribute *attr,
|
| 95 | char *buf);
|
| 96 | ssize_t (*store)(struct device *dev, struct device_attribute *attr,
|
| 97 | const char *buf, size_t count);
|
| 98 | };
|
| 99 |
|
| 100 | int device_create_file(struct device *, const struct device_attribute *);
|
| 101 | void device_remove_file(struct device *, const struct device_attribute *);
|
| 102 |
|
| 103 | It also defines this helper for defining device attributes::
|
| 104 |
|
| 105 | #define DEVICE_ATTR(_name, _mode, _show, _store) \
|
| 106 | struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
|
| 107 |
|
| 108 | For example, declaring::
|
| 109 |
|
| 110 | static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
|
| 111 |
|
| 112 | is equivalent to doing::
|
| 113 |
|
| 114 | static struct device_attribute dev_attr_foo = {
|
| 115 | .attr = {
|
| 116 | .name = "foo",
|
| 117 | .mode = S_IWUSR | S_IRUGO,
|
| 118 | },
|
| 119 | .show = show_foo,
|
| 120 | .store = store_foo,
|
| 121 | };
|
| 122 |
|
| 123 | Note as stated in include/linux/sysfs.h "OTHER_WRITABLE? Generally
|
| 124 | considered a bad idea." so trying to set a sysfs file writable for
|
| 125 | everyone will fail reverting to RO mode for "Others".
|
| 126 |
|
| 127 | For the common cases sysfs.h provides convenience macros to make
|
| 128 | defining attributes easier as well as making code more concise and
|
| 129 | readable. The above case could be shortened to:
|
| 130 |
|
| 131 | static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
|
| 132 |
|
| 133 | the list of helpers available to define your wrapper function is:
|
| 134 |
|
| 135 | __ATTR_RO(name):
|
| 136 | assumes default name_show and mode 0444
|
| 137 | __ATTR_WO(name):
|
| 138 | assumes a name_store only and is restricted to mode
|
| 139 | 0200 that is root write access only.
|
| 140 | __ATTR_RO_MODE(name, mode):
|
| 141 | for more restrictive RO access; currently
|
| 142 | only use case is the EFI System Resource Table
|
| 143 | (see drivers/firmware/efi/esrt.c)
|
| 144 | __ATTR_RW(name):
|
| 145 | assumes default name_show, name_store and setting
|
| 146 | mode to 0644.
|
| 147 | __ATTR_NULL:
|
| 148 | which sets the name to NULL and is used as end of list
|
| 149 | indicator (see: kernel/workqueue.c)
|
| 150 |
|
| 151 | Subsystem-Specific Callbacks
|
| 152 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 153 |
|
| 154 | When a subsystem defines a new attribute type, it must implement a
|
| 155 | set of sysfs operations for forwarding read and write calls to the
|
| 156 | show and store methods of the attribute owners::
|
| 157 |
|
| 158 | struct sysfs_ops {
|
| 159 | ssize_t (*show)(struct kobject *, struct attribute *, char *);
|
| 160 | ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
|
| 161 | };
|
| 162 |
|
| 163 | [ Subsystems should have already defined a struct kobj_type as a
|
| 164 | descriptor for this type, which is where the sysfs_ops pointer is
|
| 165 | stored. See the kobject documentation for more information. ]
|
| 166 |
|
| 167 | When a file is read or written, sysfs calls the appropriate method
|
| 168 | for the type. The method then translates the generic struct kobject
|
| 169 | and struct attribute pointers to the appropriate pointer types, and
|
| 170 | calls the associated methods.
|
| 171 |
|
| 172 |
|
| 173 | To illustrate::
|
| 174 |
|
| 175 | #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
|
| 176 |
|
| 177 | static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
|
| 178 | char *buf)
|
| 179 | {
|
| 180 | struct device_attribute *dev_attr = to_dev_attr(attr);
|
| 181 | struct device *dev = kobj_to_dev(kobj);
|
| 182 | ssize_t ret = -EIO;
|
| 183 |
|
| 184 | if (dev_attr->show)
|
| 185 | ret = dev_attr->show(dev, dev_attr, buf);
|
| 186 | if (ret >= (ssize_t)PAGE_SIZE) {
|
| 187 | printk("dev_attr_show: %pS returned bad count\n",
|
| 188 | dev_attr->show);
|
| 189 | }
|
| 190 | return ret;
|
| 191 | }
|
| 192 |
|
| 193 |
|
| 194 |
|
| 195 | Reading/Writing Attribute Data
|
| 196 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 197 |
|
| 198 | To read or write attributes, show() or store() methods must be
|
| 199 | specified when declaring the attribute. The method types should be as
|
| 200 | simple as those defined for device attributes::
|
| 201 |
|
| 202 | ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
|
| 203 | ssize_t (*store)(struct device *dev, struct device_attribute *attr,
|
| 204 | const char *buf, size_t count);
|
| 205 |
|
| 206 | IOW, they should take only an object, an attribute, and a buffer as parameters.
|
| 207 |
|
| 208 |
|
| 209 | sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
|
| 210 | method. sysfs will call the method exactly once for each read or
|
| 211 | write. This forces the following behavior on the method
|
| 212 | implementations:
|
| 213 |
|
| 214 | - On read(2), the show() method should fill the entire buffer.
|
| 215 | Recall that an attribute should only be exporting one value, or an
|
| 216 | array of similar values, so this shouldn't be that expensive.
|
| 217 |
|
| 218 | This allows userspace to do partial reads and forward seeks
|
| 219 | arbitrarily over the entire file at will. If userspace seeks back to
|
| 220 | zero or does a pread(2) with an offset of '0' the show() method will
|
| 221 | be called again, rearmed, to fill the buffer.
|
| 222 |
|
| 223 | - On write(2), sysfs expects the entire buffer to be passed during the
|
| 224 | first write. sysfs then passes the entire buffer to the store() method.
|
| 225 | A terminating null is added after the data on stores. This makes
|
| 226 | functions like sysfs_streq() safe to use.
|
| 227 |
|
| 228 | When writing sysfs files, userspace processes should first read the
|
| 229 | entire file, modify the values it wishes to change, then write the
|
| 230 | entire buffer back.
|
| 231 |
|
| 232 | Attribute method implementations should operate on an identical
|
| 233 | buffer when reading and writing values.
|
| 234 |
|
| 235 | Other notes:
|
| 236 |
|
| 237 | - Writing causes the show() method to be rearmed regardless of current
|
| 238 | file position.
|
| 239 |
|
| 240 | - The buffer will always be PAGE_SIZE bytes in length. On x86, this
|
| 241 | is 4096.
|
| 242 |
|
| 243 | - show() methods should return the number of bytes printed into the
|
| 244 | buffer.
|
| 245 |
|
| 246 | - New implementations of show() methods should only use sysfs_emit() or
|
| 247 | sysfs_emit_at() when formatting the value to be returned to user space.
|
| 248 |
|
| 249 | - store() should return the number of bytes used from the buffer. If the
|
| 250 | entire buffer has been used, just return the count argument.
|
| 251 |
|
| 252 | - show() or store() can always return errors. If a bad value comes
|
| 253 | through, be sure to return an error.
|
| 254 |
|
| 255 | - The object passed to the methods will be pinned in memory via sysfs
|
| 256 | reference counting its embedded object. However, the physical
|
| 257 | entity (e.g. device) the object represents may not be present. Be
|
| 258 | sure to have a way to check this, if necessary.
|
| 259 |
|
| 260 |
|
| 261 | A very simple (and naive) implementation of a device attribute is::
|
| 262 |
|
| 263 | static ssize_t show_name(struct device *dev, struct device_attribute *attr,
|
| 264 | char *buf)
|
| 265 | {
|
| 266 | return sysfs_emit(buf, "%s\n", dev->name);
|
| 267 | }
|
| 268 |
|
| 269 | static ssize_t store_name(struct device *dev, struct device_attribute *attr,
|
| 270 | const char *buf, size_t count)
|
| 271 | {
|
| 272 | snprintf(dev->name, sizeof(dev->name), "%.*s",
|
| 273 | (int)min(count, sizeof(dev->name) - 1), buf);
|
| 274 | return count;
|
| 275 | }
|
| 276 |
|
| 277 | static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
|
| 278 |
|
| 279 |
|
| 280 | (Note that the real implementation doesn't allow userspace to set the
|
| 281 | name for a device.)
|
| 282 |
|
| 283 |
|
| 284 | Top Level Directory Layout
|
| 285 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 286 |
|
| 287 | The sysfs directory arrangement exposes the relationship of kernel
|
| 288 | data structures.
|
| 289 |
|
| 290 | The top level sysfs directory looks like::
|
| 291 |
|
| 292 | block/
|
| 293 | bus/
|
| 294 | class/
|
| 295 | dev/
|
| 296 | devices/
|
| 297 | firmware/
|
| 298 | fs/
|
| 299 | hypervisor/
|
| 300 | kernel/
|
| 301 | module/
|
| 302 | power/
|
| 303 |
|
| 304 | devices/ contains a filesystem representation of the device tree. It maps
|
| 305 | directly to the internal kernel device tree, which is a hierarchy of
|
| 306 | struct device.
|
| 307 |
|
| 308 | bus/ contains flat directory layout of the various bus types in the
|
| 309 | kernel. Each bus's directory contains two subdirectories::
|
| 310 |
|
| 311 | devices/
|
| 312 | drivers/
|
| 313 |
|
| 314 | devices/ contains symlinks for each device discovered in the system
|
| 315 | that point to the device's directory under /sys/devices.
|
| 316 |
|
| 317 | drivers/ contains a directory for each device driver that is loaded
|
| 318 | for devices on that particular bus (this assumes that drivers do not
|
| 319 | span multiple bus types).
|
| 320 |
|
| 321 | fs/ contains a directory for some filesystems. Currently each
|
| 322 | filesystem wanting to export attributes must create its own hierarchy
|
| 323 | below fs/ (see fuse/fuse.rst for an example).
|
| 324 |
|
| 325 | module/ contains parameter values and state information for all
|
| 326 | loaded system modules, for both builtin and loadable modules.
|
| 327 |
|
| 328 | dev/ contains two directories: char/ and block/. Inside these two
|
| 329 | directories there are symlinks named <major>:<minor>. These symlinks
|
| 330 | point to the directories under /sys/devices for each device. /sys/dev provides a
|
| 331 | quick way to lookup the sysfs interface for a device from the result of
|
| 332 | a stat(2) operation.
|
| 333 |
|
| 334 | More information on driver-model specific features can be found in
|
| 335 | Documentation/driver-api/driver-model/.
|
| 336 |
|
| 337 | block/ contains symlinks to all the block devices discovered on the system.
|
| 338 | These symlinks point to directories under /sys/devices.
|
| 339 |
|
| 340 | class/ contains a directory for each device class, grouped by functional type.
|
| 341 | Each directory in class/ contains symlinks to devices in the /sys/devices directory.
|
| 342 |
|
| 343 | firmware/ contains system firmware data and configuration such as firmware tables,
|
| 344 | ACPI information, and device tree data.
|
| 345 |
|
| 346 | hypervisor/ contains virtualization platform information and provides an interface to
|
| 347 | the underlying hypervisor. It is only present when running on a virtual machine.
|
| 348 |
|
| 349 | kernel/ contains runtime kernel parameters, configuration settings, and status.
|
| 350 |
|
| 351 | power/ contains power management subsystem information including
|
| 352 | sleep states, suspend/resume capabilities, and policies.
|
| 353 |
|
| 354 |
|
| 355 | Current Interfaces
|
| 356 | ~~~~~~~~~~~~~~~~~~
|
| 357 |
|
| 358 | The following interface layers currently exist in sysfs.
|
| 359 |
|
| 360 |
|
| 361 | devices (include/linux/device.h)
|
| 362 | --------------------------------
|
| 363 | Structure::
|
| 364 |
|
| 365 | struct device_attribute {
|
| 366 | struct attribute attr;
|
| 367 | ssize_t (*show)(struct device *dev, struct device_attribute *attr,
|
| 368 | char *buf);
|
| 369 | ssize_t (*store)(struct device *dev, struct device_attribute *attr,
|
| 370 | const char *buf, size_t count);
|
| 371 | };
|
| 372 |
|
| 373 | Declaring::
|
| 374 |
|
| 375 | DEVICE_ATTR(_name, _mode, _show, _store);
|
| 376 |
|
| 377 | Creation/Removal::
|
| 378 |
|
| 379 | int device_create_file(struct device *dev, const struct device_attribute * attr);
|
| 380 | void device_remove_file(struct device *dev, const struct device_attribute * attr);
|
| 381 |
|
| 382 |
|
| 383 | bus drivers (include/linux/device.h)
|
| 384 | ------------------------------------
|
| 385 | Structure::
|
| 386 |
|
| 387 | struct bus_attribute {
|
| 388 | struct attribute attr;
|
| 389 | ssize_t (*show)(const struct bus_type *, char * buf);
|
| 390 | ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);
|
| 391 | };
|
| 392 |
|
| 393 | Declaring::
|
| 394 |
|
| 395 | static BUS_ATTR_RW(name);
|
| 396 | static BUS_ATTR_RO(name);
|
| 397 | static BUS_ATTR_WO(name);
|
| 398 |
|
| 399 | Creation/Removal::
|
| 400 |
|
| 401 | int bus_create_file(struct bus_type *, struct bus_attribute *);
|
| 402 | void bus_remove_file(struct bus_type *, struct bus_attribute *);
|
| 403 |
|
| 404 |
|
| 405 | device drivers (include/linux/device.h)
|
| 406 | ---------------------------------------
|
| 407 |
|
| 408 | Structure::
|
| 409 |
|
| 410 | struct driver_attribute {
|
| 411 | struct attribute attr;
|
| 412 | ssize_t (*show)(struct device_driver *, char * buf);
|
| 413 | ssize_t (*store)(struct device_driver *, const char * buf,
|
| 414 | size_t count);
|
| 415 | };
|
| 416 |
|
| 417 | Declaring::
|
| 418 |
|
| 419 | DRIVER_ATTR_RO(_name)
|
| 420 | DRIVER_ATTR_RW(_name)
|
| 421 |
|
| 422 | Creation/Removal::
|
| 423 |
|
| 424 | int driver_create_file(struct device_driver *, const struct driver_attribute *);
|
| 425 | void driver_remove_file(struct device_driver *, const struct driver_attribute *);
|
| 426 |
|
| 427 |
|
| 428 | Documentation
|
| 429 | ~~~~~~~~~~~~~
|
| 430 |
|
| 431 | The sysfs directory structure and the attributes in each directory define an
|
| 432 | ABI between the kernel and user space. As for any ABI, it is important that
|
| 433 | this ABI is stable and properly documented. All new sysfs attributes must be
|
| 434 | documented in Documentation/ABI. See also Documentation/ABI/README for more
|
| 435 | information.
|