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