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