423 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=====================================================4sysfs - _The_ filesystem for exporting kernel objects5=====================================================6 7Patrick Mochel <mochel@osdl.org>8 9Mike Murphy <mamurph@cs.clemson.edu>10 11:Revised: 16 August 201112:Original: 10 January 200313 14 15What it is16~~~~~~~~~~17 18sysfs is a RAM-based filesystem initially based on ramfs. It provides19a means to export kernel data structures, their attributes, and the20linkages between them to userspace.21 22sysfs is tied inherently to the kobject infrastructure. Please read23Documentation/core-api/kobject.rst for more information concerning the kobject24interface.25 26 27Using sysfs28~~~~~~~~~~~29 30sysfs is always compiled in if CONFIG_SYSFS is defined. You can access31it by doing::32 33 mount -t sysfs sysfs /sys34 35 36Directory Creation37~~~~~~~~~~~~~~~~~~38 39For every kobject that is registered with the system, a directory is40created for it in sysfs. That directory is created as a subdirectory41of the kobject's parent, expressing internal object hierarchies to42userspace. Top-level directories in sysfs represent the common43ancestors of object hierarchies; i.e. the subsystems the objects44belong to.45 46sysfs internally stores a pointer to the kobject that implements a47directory in the kernfs_node object associated with the directory. In48the past this kobject pointer has been used by sysfs to do reference49counting directly on the kobject whenever the file is opened or closed.50With the current sysfs implementation the kobject reference count is51only modified directly by the function sysfs_schedule_callback().52 53 54Attributes55~~~~~~~~~~56 57Attributes can be exported for kobjects in the form of regular files in58the filesystem. sysfs forwards file I/O operations to methods defined59for the attributes, providing a means to read and write kernel60attributes.61 62Attributes should be ASCII text files, preferably with only one value63per file. It is noted that it may not be efficient to contain only one64value per file, so it is socially acceptable to express an array of65values of the same type.66 67Mixing types, expressing multiple lines of data, and doing fancy68formatting of data is heavily frowned upon. Doing these things may get69you publicly humiliated and your code rewritten without notice.70 71 72An 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 85A bare attribute contains no means to read or write the value of the86attribute. Subsystems are encouraged to define their own attribute87structure and wrapper functions for adding and removing attributes for88a specific object type.89 90For 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 103It 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 108For example, declaring::109 110 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);111 112is 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 123Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally124considered a bad idea." so trying to set a sysfs file writable for125everyone will fail reverting to RO mode for "Others".126 127For the common cases sysfs.h provides convenience macros to make128defining attributes easier as well as making code more concise and129readable. The above case could be shortened to:130 131static struct device_attribute dev_attr_foo = __ATTR_RW(foo);132 133the list of helpers available to define your wrapper function is:134 135__ATTR_RO(name):136 assumes default name_show and mode 0444137__ATTR_WO(name):138 assumes a name_store only and is restricted to mode139 0200 that is root write access only.140__ATTR_RO_MODE(name, mode):141 for more restrictive RO access; currently142 only use case is the EFI System Resource Table143 (see drivers/firmware/efi/esrt.c)144__ATTR_RW(name):145 assumes default name_show, name_store and setting146 mode to 0644.147__ATTR_NULL:148 which sets the name to NULL and is used as end of list149 indicator (see: kernel/workqueue.c)150 151Subsystem-Specific Callbacks152~~~~~~~~~~~~~~~~~~~~~~~~~~~~153 154When a subsystem defines a new attribute type, it must implement a155set of sysfs operations for forwarding read and write calls to the156show 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 a164descriptor for this type, which is where the sysfs_ops pointer is165stored. See the kobject documentation for more information. ]166 167When a file is read or written, sysfs calls the appropriate method168for the type. The method then translates the generic struct kobject169and struct attribute pointers to the appropriate pointer types, and170calls the associated methods.171 172 173To 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 195Reading/Writing Attribute Data196~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~197 198To read or write attributes, show() or store() methods must be199specified when declaring the attribute. The method types should be as200simple 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 206IOW, they should take only an object, an attribute, and a buffer as parameters.207 208 209sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the210method. sysfs will call the method exactly once for each read or211write. This forces the following behavior on the method212implementations: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 an216 array of similar values, so this shouldn't be that expensive.217 218 This allows userspace to do partial reads and forward seeks219 arbitrarily over the entire file at will. If userspace seeks back to220 zero or does a pread(2) with an offset of '0' the show() method will221 be called again, rearmed, to fill the buffer.222 223- On write(2), sysfs expects the entire buffer to be passed during the224 first write. sysfs then passes the entire buffer to the store() method.225 A terminating null is added after the data on stores. This makes226 functions like sysfs_streq() safe to use.227 228 When writing sysfs files, userspace processes should first read the229 entire file, modify the values it wishes to change, then write the230 entire buffer back.231 232 Attribute method implementations should operate on an identical233 buffer when reading and writing values.234 235Other notes:236 237- Writing causes the show() method to be rearmed regardless of current238 file position.239 240- The buffer will always be PAGE_SIZE bytes in length. On x86, this241 is 4096.242 243- show() methods should return the number of bytes printed into the244 buffer.245 246- show() should only use sysfs_emit() or sysfs_emit_at() when formatting247 the value to be returned to user space.248 249- store() should return the number of bytes used from the buffer. If the250 entire buffer has been used, just return the count argument.251 252- show() or store() can always return errors. If a bad value comes253 through, be sure to return an error.254 255- The object passed to the methods will be pinned in memory via sysfs256 reference counting its embedded object. However, the physical257 entity (e.g. device) the object represents may not be present. Be258 sure to have a way to check this, if necessary.259 260 261A 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 the281name for a device.)282 283 284Top Level Directory Layout285~~~~~~~~~~~~~~~~~~~~~~~~~~286 287The sysfs directory arrangement exposes the relationship of kernel288data structures.289 290The 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 net/303 power/304 305devices/ contains a filesystem representation of the device tree. It maps306directly to the internal kernel device tree, which is a hierarchy of307struct device.308 309bus/ contains flat directory layout of the various bus types in the310kernel. Each bus's directory contains two subdirectories::311 312 devices/313 drivers/314 315devices/ contains symlinks for each device discovered in the system316that point to the device's directory under root/.317 318drivers/ contains a directory for each device driver that is loaded319for devices on that particular bus (this assumes that drivers do not320span multiple bus types).321 322fs/ contains a directory for some filesystems. Currently each323filesystem wanting to export attributes must create its own hierarchy324below fs/ (see ./fuse.rst for an example).325 326module/ contains parameter values and state information for all327loaded system modules, for both builtin and loadable modules.328 329dev/ contains two directories: char/ and block/. Inside these two330directories there are symlinks named <major>:<minor>. These symlinks331point to the sysfs directory for the given device. /sys/dev provides a332quick way to lookup the sysfs interface for a device from the result of333a stat(2) operation.334 335More information on driver-model specific features can be found in336Documentation/driver-api/driver-model/.337 338 339TODO: Finish this section.340 341 342Current Interfaces343~~~~~~~~~~~~~~~~~~344 345The following interface layers currently exist in sysfs.346 347 348devices (include/linux/device.h)349--------------------------------350Structure::351 352 struct device_attribute {353 struct attribute attr;354 ssize_t (*show)(struct device *dev, struct device_attribute *attr,355 char *buf);356 ssize_t (*store)(struct device *dev, struct device_attribute *attr,357 const char *buf, size_t count);358 };359 360Declaring::361 362 DEVICE_ATTR(_name, _mode, _show, _store);363 364Creation/Removal::365 366 int device_create_file(struct device *dev, const struct device_attribute * attr);367 void device_remove_file(struct device *dev, const struct device_attribute * attr);368 369 370bus drivers (include/linux/device.h)371------------------------------------372Structure::373 374 struct bus_attribute {375 struct attribute attr;376 ssize_t (*show)(const struct bus_type *, char * buf);377 ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);378 };379 380Declaring::381 382 static BUS_ATTR_RW(name);383 static BUS_ATTR_RO(name);384 static BUS_ATTR_WO(name);385 386Creation/Removal::387 388 int bus_create_file(struct bus_type *, struct bus_attribute *);389 void bus_remove_file(struct bus_type *, struct bus_attribute *);390 391 392device drivers (include/linux/device.h)393---------------------------------------394 395Structure::396 397 struct driver_attribute {398 struct attribute attr;399 ssize_t (*show)(struct device_driver *, char * buf);400 ssize_t (*store)(struct device_driver *, const char * buf,401 size_t count);402 };403 404Declaring::405 406 DRIVER_ATTR_RO(_name)407 DRIVER_ATTR_RW(_name)408 409Creation/Removal::410 411 int driver_create_file(struct device_driver *, const struct driver_attribute *);412 void driver_remove_file(struct device_driver *, const struct driver_attribute *);413 414 415Documentation416~~~~~~~~~~~~~417 418The sysfs directory structure and the attributes in each directory define an419ABI between the kernel and user space. As for any ABI, it is important that420this ABI is stable and properly documented. All new sysfs attributes must be421documented in Documentation/ABI. See also Documentation/ABI/README for more422information.423