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
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
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 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
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
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
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
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
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
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
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
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