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