sysfs.rst (13290B)
1.. SPDX-License-Identifier: GPL-2.0 2 3===================================================== 4sysfs - _The_ filesystem for exporting kernel objects 5===================================================== 6 7Patrick Mochel <mochel@osdl.org> 8 9Mike Murphy <mamurph@cs.clemson.edu> 10 11:Revised: 16 August 2011 12:Original: 10 January 2003 13 14 15What it is: 16~~~~~~~~~~~ 17 18sysfs is a ram-based filesystem initially based on ramfs. It provides 19a means to export kernel data structures, their attributes, and the 20linkages between them to userspace. 21 22sysfs is tied inherently to the kobject infrastructure. Please read 23Documentation/core-api/kobject.rst for more information concerning the kobject 24interface. 25 26 27Using sysfs 28~~~~~~~~~~~ 29 30sysfs is always compiled in if CONFIG_SYSFS is defined. You can access 31it by doing:: 32 33 mount -t sysfs sysfs /sys 34 35 36Directory Creation 37~~~~~~~~~~~~~~~~~~ 38 39For every kobject that is registered with the system, a directory is 40created for it in sysfs. That directory is created as a subdirectory 41of the kobject's parent, expressing internal object hierarchies to 42userspace. Top-level directories in sysfs represent the common 43ancestors of object hierarchies; i.e. the subsystems the objects 44belong to. 45 46Sysfs internally stores a pointer to the kobject that implements a 47directory in the kernfs_node object associated with the directory. In 48the past this kobject pointer has been used by sysfs to do reference 49counting directly on the kobject whenever the file is opened or closed. 50With the current sysfs implementation the kobject reference count is 51only modified directly by the function sysfs_schedule_callback(). 52 53 54Attributes 55~~~~~~~~~~ 56 57Attributes can be exported for kobjects in the form of regular files in 58the filesystem. Sysfs forwards file I/O operations to methods defined 59for the attributes, providing a means to read and write kernel 60attributes. 61 62Attributes should be ASCII text files, preferably with only one value 63per file. It is noted that it may not be efficient to contain only one 64value per file, so it is socially acceptable to express an array of 65values of the same type. 66 67Mixing types, expressing multiple lines of data, and doing fancy 68formatting of data is heavily frowned upon. Doing these things may get 69you 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 the 86attribute. Subsystems are encouraged to define their own attribute 87structure and wrapper functions for adding and removing attributes for 88a 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? Generally 124considered a bad idea." so trying to set a sysfs file writable for 125everyone will fail reverting to RO mode for "Others". 126 127For the common cases sysfs.h provides convenience macros to make 128defining attributes easier as well as making code more concise and 129readable. 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 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 fore 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 151Subsystem-Specific Callbacks 152~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 153 154When a subsystem defines a new attribute type, it must implement a 155set of sysfs operations for forwarding read and write calls to the 156show 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 164descriptor for this type, which is where the sysfs_ops pointer is 165stored. See the kobject documentation for more information. ] 166 167When a file is read or written, sysfs calls the appropriate method 168for the type. The method then translates the generic struct kobject 169and struct attribute pointers to the appropriate pointer types, and 170calls 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 Data 196~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 197 198To read or write attributes, show() or store() methods must be 199specified when declaring the attribute. The method types should be as 200simple 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 the 210method. Sysfs will call the method exactly once for each read or 211write. This forces the following behavior on the method 212implementations: 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 235Other 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 i386, this 241 is 4096. 242 243- show() methods should return the number of bytes printed into the 244 buffer. 245 246- show() should only use sysfs_emit() or sysfs_emit_at() when formatting 247 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 referencing 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 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 scnprintf(buf, PAGE_SIZE, "%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 281name for a device.) 282 283 284Top Level Directory Layout 285~~~~~~~~~~~~~~~~~~~~~~~~~~ 286 287The sysfs directory arrangement exposes the relationship of kernel 288data structures. 289 290The top level sysfs directory looks like:: 291 292 block/ 293 bus/ 294 class/ 295 dev/ 296 devices/ 297 firmware/ 298 net/ 299 fs/ 300 301devices/ contains a filesystem representation of the device tree. It maps 302directly to the internal kernel device tree, which is a hierarchy of 303struct device. 304 305bus/ contains flat directory layout of the various bus types in the 306kernel. Each bus's directory contains two subdirectories:: 307 308 devices/ 309 drivers/ 310 311devices/ contains symlinks for each device discovered in the system 312that point to the device's directory under root/. 313 314drivers/ contains a directory for each device driver that is loaded 315for devices on that particular bus (this assumes that drivers do not 316span multiple bus types). 317 318fs/ contains a directory for some filesystems. Currently each 319filesystem wanting to export attributes must create its own hierarchy 320below fs/ (see ./fuse.txt for an example). 321 322dev/ contains two directories char/ and block/. Inside these two 323directories there are symlinks named <major>:<minor>. These symlinks 324point to the sysfs directory for the given device. /sys/dev provides a 325quick way to lookup the sysfs interface for a device from the result of 326a stat(2) operation. 327 328More information can driver-model specific features can be found in 329Documentation/driver-api/driver-model/. 330 331 332TODO: Finish this section. 333 334 335Current Interfaces 336~~~~~~~~~~~~~~~~~~ 337 338The following interface layers currently exist in sysfs: 339 340 341devices (include/linux/device.h) 342-------------------------------- 343Structure:: 344 345 struct device_attribute { 346 struct attribute attr; 347 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 348 char *buf); 349 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 350 const char *buf, size_t count); 351 }; 352 353Declaring:: 354 355 DEVICE_ATTR(_name, _mode, _show, _store); 356 357Creation/Removal:: 358 359 int device_create_file(struct device *dev, const struct device_attribute * attr); 360 void device_remove_file(struct device *dev, const struct device_attribute * attr); 361 362 363bus drivers (include/linux/device.h) 364------------------------------------ 365Structure:: 366 367 struct bus_attribute { 368 struct attribute attr; 369 ssize_t (*show)(struct bus_type *, char * buf); 370 ssize_t (*store)(struct bus_type *, const char * buf, size_t count); 371 }; 372 373Declaring:: 374 375 static BUS_ATTR_RW(name); 376 static BUS_ATTR_RO(name); 377 static BUS_ATTR_WO(name); 378 379Creation/Removal:: 380 381 int bus_create_file(struct bus_type *, struct bus_attribute *); 382 void bus_remove_file(struct bus_type *, struct bus_attribute *); 383 384 385device drivers (include/linux/device.h) 386--------------------------------------- 387 388Structure:: 389 390 struct driver_attribute { 391 struct attribute attr; 392 ssize_t (*show)(struct device_driver *, char * buf); 393 ssize_t (*store)(struct device_driver *, const char * buf, 394 size_t count); 395 }; 396 397Declaring:: 398 399 DRIVER_ATTR_RO(_name) 400 DRIVER_ATTR_RW(_name) 401 402Creation/Removal:: 403 404 int driver_create_file(struct device_driver *, const struct driver_attribute *); 405 void driver_remove_file(struct device_driver *, const struct driver_attribute *); 406 407 408Documentation 409~~~~~~~~~~~~~ 410 411The sysfs directory structure and the attributes in each directory define an 412ABI between the kernel and user space. As for any ABI, it is important that 413this ABI is stable and properly documented. All new sysfs attributes must be 414documented in Documentation/ABI. See also Documentation/ABI/README for more 415information.