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. This is the return value of scnprintf(). 245 246- show() must not use snprintf() when formatting the value to be 247 returned to user space. If you can guarantee that an overflow 248 will never happen you can use sprintf() otherwise you must use 249 scnprintf(). 250 251- store() should return the number of bytes used from the buffer. If the 252 entire buffer has been used, just return the count argument. 253 254- show() or store() can always return errors. If a bad value comes 255 through, be sure to return an error. 256 257- The object passed to the methods will be pinned in memory via sysfs 258 referencing counting its embedded object. However, the physical 259 entity (e.g. device) the object represents may not be present. Be 260 sure to have a way to check this, if necessary. 261 262 263A very simple (and naive) implementation of a device attribute is:: 264 265 static ssize_t show_name(struct device *dev, struct device_attribute *attr, 266 char *buf) 267 { 268 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); 269 } 270 271 static ssize_t store_name(struct device *dev, struct device_attribute *attr, 272 const char *buf, size_t count) 273 { 274 snprintf(dev->name, sizeof(dev->name), "%.*s", 275 (int)min(count, sizeof(dev->name) - 1), buf); 276 return count; 277 } 278 279 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); 280 281 282(Note that the real implementation doesn't allow userspace to set the 283name for a device.) 284 285 286Top Level Directory Layout 287~~~~~~~~~~~~~~~~~~~~~~~~~~ 288 289The sysfs directory arrangement exposes the relationship of kernel 290data structures. 291 292The top level sysfs directory looks like:: 293 294 block/ 295 bus/ 296 class/ 297 dev/ 298 devices/ 299 firmware/ 300 net/ 301 fs/ 302 303devices/ contains a filesystem representation of the device tree. It maps 304directly to the internal kernel device tree, which is a hierarchy of 305struct device. 306 307bus/ contains flat directory layout of the various bus types in the 308kernel. Each bus's directory contains two subdirectories:: 309 310 devices/ 311 drivers/ 312 313devices/ contains symlinks for each device discovered in the system 314that point to the device's directory under root/. 315 316drivers/ contains a directory for each device driver that is loaded 317for devices on that particular bus (this assumes that drivers do not 318span multiple bus types). 319 320fs/ contains a directory for some filesystems. Currently each 321filesystem wanting to export attributes must create its own hierarchy 322below fs/ (see ./fuse.txt for an example). 323 324dev/ contains two directories char/ and block/. Inside these two 325directories there are symlinks named <major>:<minor>. These symlinks 326point to the sysfs directory for the given device. /sys/dev provides a 327quick way to lookup the sysfs interface for a device from the result of 328a stat(2) operation. 329 330More information can driver-model specific features can be found in 331Documentation/driver-api/driver-model/. 332 333 334TODO: Finish this section. 335 336 337Current Interfaces 338~~~~~~~~~~~~~~~~~~ 339 340The following interface layers currently exist in sysfs: 341 342 343devices (include/linux/device.h) 344-------------------------------- 345Structure:: 346 347 struct device_attribute { 348 struct attribute attr; 349 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 350 char *buf); 351 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 352 const char *buf, size_t count); 353 }; 354 355Declaring:: 356 357 DEVICE_ATTR(_name, _mode, _show, _store); 358 359Creation/Removal:: 360 361 int device_create_file(struct device *dev, const struct device_attribute * attr); 362 void device_remove_file(struct device *dev, const struct device_attribute * attr); 363 364 365bus drivers (include/linux/device.h) 366------------------------------------ 367Structure:: 368 369 struct bus_attribute { 370 struct attribute attr; 371 ssize_t (*show)(struct bus_type *, char * buf); 372 ssize_t (*store)(struct bus_type *, const char * buf, size_t count); 373 }; 374 375Declaring:: 376 377 static BUS_ATTR_RW(name); 378 static BUS_ATTR_RO(name); 379 static BUS_ATTR_WO(name); 380 381Creation/Removal:: 382 383 int bus_create_file(struct bus_type *, struct bus_attribute *); 384 void bus_remove_file(struct bus_type *, struct bus_attribute *); 385 386 387device drivers (include/linux/device.h) 388--------------------------------------- 389 390Structure:: 391 392 struct driver_attribute { 393 struct attribute attr; 394 ssize_t (*show)(struct device_driver *, char * buf); 395 ssize_t (*store)(struct device_driver *, const char * buf, 396 size_t count); 397 }; 398 399Declaring:: 400 401 DRIVER_ATTR_RO(_name) 402 DRIVER_ATTR_RW(_name) 403 404Creation/Removal:: 405 406 int driver_create_file(struct device_driver *, const struct driver_attribute *); 407 void driver_remove_file(struct device_driver *, const struct driver_attribute *); 408 409 410Documentation 411~~~~~~~~~~~~~ 412 413The sysfs directory structure and the attributes in each directory define an 414ABI between the kernel and user space. As for any ABI, it is important that 415this ABI is stable and properly documented. All new sysfs attributes must be 416documented in Documentation/ABI. See also Documentation/ABI/README for more 417information. 418