0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =====================================================
0004 sysfs - _The_ filesystem for exporting kernel objects
0005 =====================================================
0006
0007 Patrick Mochel <mochel@osdl.org>
0008
0009 Mike Murphy <mamurph@cs.clemson.edu>
0010
0011 :Revised: 16 August 2011
0012 :Original: 10 January 2003
0013
0014
0015 What it is:
0016 ~~~~~~~~~~~
0017
0018 sysfs is a ram-based filesystem initially based on ramfs. It provides
0019 a means to export kernel data structures, their attributes, and the
0020 linkages between them to userspace.
0021
0022 sysfs is tied inherently to the kobject infrastructure. Please read
0023 Documentation/core-api/kobject.rst for more information concerning the kobject
0024 interface.
0025
0026
0027 Using sysfs
0028 ~~~~~~~~~~~
0029
0030 sysfs is always compiled in if CONFIG_SYSFS is defined. You can access
0031 it by doing::
0032
0033 mount -t sysfs sysfs /sys
0034
0035
0036 Directory Creation
0037 ~~~~~~~~~~~~~~~~~~
0038
0039 For every kobject that is registered with the system, a directory is
0040 created for it in sysfs. That directory is created as a subdirectory
0041 of the kobject's parent, expressing internal object hierarchies to
0042 userspace. Top-level directories in sysfs represent the common
0043 ancestors of object hierarchies; i.e. the subsystems the objects
0044 belong to.
0045
0046 Sysfs internally stores a pointer to the kobject that implements a
0047 directory in the kernfs_node object associated with the directory. In
0048 the past this kobject pointer has been used by sysfs to do reference
0049 counting directly on the kobject whenever the file is opened or closed.
0050 With the current sysfs implementation the kobject reference count is
0051 only modified directly by the function sysfs_schedule_callback().
0052
0053
0054 Attributes
0055 ~~~~~~~~~~
0056
0057 Attributes can be exported for kobjects in the form of regular files in
0058 the filesystem. Sysfs forwards file I/O operations to methods defined
0059 for the attributes, providing a means to read and write kernel
0060 attributes.
0061
0062 Attributes should be ASCII text files, preferably with only one value
0063 per file. It is noted that it may not be efficient to contain only one
0064 value per file, so it is socially acceptable to express an array of
0065 values of the same type.
0066
0067 Mixing types, expressing multiple lines of data, and doing fancy
0068 formatting of data is heavily frowned upon. Doing these things may get
0069 you publicly humiliated and your code rewritten without notice.
0070
0071
0072 An attribute definition is simply::
0073
0074 struct attribute {
0075 char * name;
0076 struct module *owner;
0077 umode_t mode;
0078 };
0079
0080
0081 int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
0082 void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
0083
0084
0085 A bare attribute contains no means to read or write the value of the
0086 attribute. Subsystems are encouraged to define their own attribute
0087 structure and wrapper functions for adding and removing attributes for
0088 a specific object type.
0089
0090 For example, the driver model defines struct device_attribute like::
0091
0092 struct device_attribute {
0093 struct attribute attr;
0094 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
0095 char *buf);
0096 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0097 const char *buf, size_t count);
0098 };
0099
0100 int device_create_file(struct device *, const struct device_attribute *);
0101 void device_remove_file(struct device *, const struct device_attribute *);
0102
0103 It also defines this helper for defining device attributes::
0104
0105 #define DEVICE_ATTR(_name, _mode, _show, _store) \
0106 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
0107
0108 For example, declaring::
0109
0110 static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
0111
0112 is equivalent to doing::
0113
0114 static struct device_attribute dev_attr_foo = {
0115 .attr = {
0116 .name = "foo",
0117 .mode = S_IWUSR | S_IRUGO,
0118 },
0119 .show = show_foo,
0120 .store = store_foo,
0121 };
0122
0123 Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally
0124 considered a bad idea." so trying to set a sysfs file writable for
0125 everyone will fail reverting to RO mode for "Others".
0126
0127 For the common cases sysfs.h provides convenience macros to make
0128 defining attributes easier as well as making code more concise and
0129 readable. The above case could be shortened to:
0130
0131 static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
0132
0133 the list of helpers available to define your wrapper function is:
0134
0135 __ATTR_RO(name):
0136 assumes default name_show and mode 0444
0137 __ATTR_WO(name):
0138 assumes a name_store only and is restricted to mode
0139 0200 that is root write access only.
0140 __ATTR_RO_MODE(name, mode):
0141 fore more restrictive RO access currently
0142 only use case is the EFI System Resource Table
0143 (see drivers/firmware/efi/esrt.c)
0144 __ATTR_RW(name):
0145 assumes default name_show, name_store and setting
0146 mode to 0644.
0147 __ATTR_NULL:
0148 which sets the name to NULL and is used as end of list
0149 indicator (see: kernel/workqueue.c)
0150
0151 Subsystem-Specific Callbacks
0152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0153
0154 When a subsystem defines a new attribute type, it must implement a
0155 set of sysfs operations for forwarding read and write calls to the
0156 show and store methods of the attribute owners::
0157
0158 struct sysfs_ops {
0159 ssize_t (*show)(struct kobject *, struct attribute *, char *);
0160 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
0161 };
0162
0163 [ Subsystems should have already defined a struct kobj_type as a
0164 descriptor for this type, which is where the sysfs_ops pointer is
0165 stored. See the kobject documentation for more information. ]
0166
0167 When a file is read or written, sysfs calls the appropriate method
0168 for the type. The method then translates the generic struct kobject
0169 and struct attribute pointers to the appropriate pointer types, and
0170 calls the associated methods.
0171
0172
0173 To illustrate::
0174
0175 #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
0176
0177 static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
0178 char *buf)
0179 {
0180 struct device_attribute *dev_attr = to_dev_attr(attr);
0181 struct device *dev = kobj_to_dev(kobj);
0182 ssize_t ret = -EIO;
0183
0184 if (dev_attr->show)
0185 ret = dev_attr->show(dev, dev_attr, buf);
0186 if (ret >= (ssize_t)PAGE_SIZE) {
0187 printk("dev_attr_show: %pS returned bad count\n",
0188 dev_attr->show);
0189 }
0190 return ret;
0191 }
0192
0193
0194
0195 Reading/Writing Attribute Data
0196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0197
0198 To read or write attributes, show() or store() methods must be
0199 specified when declaring the attribute. The method types should be as
0200 simple as those defined for device attributes::
0201
0202 ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
0203 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0204 const char *buf, size_t count);
0205
0206 IOW, they should take only an object, an attribute, and a buffer as parameters.
0207
0208
0209 sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
0210 method. Sysfs will call the method exactly once for each read or
0211 write. This forces the following behavior on the method
0212 implementations:
0213
0214 - On read(2), the show() method should fill the entire buffer.
0215 Recall that an attribute should only be exporting one value, or an
0216 array of similar values, so this shouldn't be that expensive.
0217
0218 This allows userspace to do partial reads and forward seeks
0219 arbitrarily over the entire file at will. If userspace seeks back to
0220 zero or does a pread(2) with an offset of '0' the show() method will
0221 be called again, rearmed, to fill the buffer.
0222
0223 - On write(2), sysfs expects the entire buffer to be passed during the
0224 first write. Sysfs then passes the entire buffer to the store() method.
0225 A terminating null is added after the data on stores. This makes
0226 functions like sysfs_streq() safe to use.
0227
0228 When writing sysfs files, userspace processes should first read the
0229 entire file, modify the values it wishes to change, then write the
0230 entire buffer back.
0231
0232 Attribute method implementations should operate on an identical
0233 buffer when reading and writing values.
0234
0235 Other notes:
0236
0237 - Writing causes the show() method to be rearmed regardless of current
0238 file position.
0239
0240 - The buffer will always be PAGE_SIZE bytes in length. On i386, this
0241 is 4096.
0242
0243 - show() methods should return the number of bytes printed into the
0244 buffer.
0245
0246 - show() should only use sysfs_emit() or sysfs_emit_at() when formatting
0247 the value to be returned to user space.
0248
0249 - store() should return the number of bytes used from the buffer. If the
0250 entire buffer has been used, just return the count argument.
0251
0252 - show() or store() can always return errors. If a bad value comes
0253 through, be sure to return an error.
0254
0255 - The object passed to the methods will be pinned in memory via sysfs
0256 referencing counting its embedded object. However, the physical
0257 entity (e.g. device) the object represents may not be present. Be
0258 sure to have a way to check this, if necessary.
0259
0260
0261 A very simple (and naive) implementation of a device attribute is::
0262
0263 static ssize_t show_name(struct device *dev, struct device_attribute *attr,
0264 char *buf)
0265 {
0266 return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
0267 }
0268
0269 static ssize_t store_name(struct device *dev, struct device_attribute *attr,
0270 const char *buf, size_t count)
0271 {
0272 snprintf(dev->name, sizeof(dev->name), "%.*s",
0273 (int)min(count, sizeof(dev->name) - 1), buf);
0274 return count;
0275 }
0276
0277 static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
0278
0279
0280 (Note that the real implementation doesn't allow userspace to set the
0281 name for a device.)
0282
0283
0284 Top Level Directory Layout
0285 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0286
0287 The sysfs directory arrangement exposes the relationship of kernel
0288 data structures.
0289
0290 The top level sysfs directory looks like::
0291
0292 block/
0293 bus/
0294 class/
0295 dev/
0296 devices/
0297 firmware/
0298 net/
0299 fs/
0300
0301 devices/ contains a filesystem representation of the device tree. It maps
0302 directly to the internal kernel device tree, which is a hierarchy of
0303 struct device.
0304
0305 bus/ contains flat directory layout of the various bus types in the
0306 kernel. Each bus's directory contains two subdirectories::
0307
0308 devices/
0309 drivers/
0310
0311 devices/ contains symlinks for each device discovered in the system
0312 that point to the device's directory under root/.
0313
0314 drivers/ contains a directory for each device driver that is loaded
0315 for devices on that particular bus (this assumes that drivers do not
0316 span multiple bus types).
0317
0318 fs/ contains a directory for some filesystems. Currently each
0319 filesystem wanting to export attributes must create its own hierarchy
0320 below fs/ (see ./fuse.txt for an example).
0321
0322 dev/ contains two directories char/ and block/. Inside these two
0323 directories there are symlinks named <major>:<minor>. These symlinks
0324 point to the sysfs directory for the given device. /sys/dev provides a
0325 quick way to lookup the sysfs interface for a device from the result of
0326 a stat(2) operation.
0327
0328 More information can driver-model specific features can be found in
0329 Documentation/driver-api/driver-model/.
0330
0331
0332 TODO: Finish this section.
0333
0334
0335 Current Interfaces
0336 ~~~~~~~~~~~~~~~~~~
0337
0338 The following interface layers currently exist in sysfs:
0339
0340
0341 devices (include/linux/device.h)
0342 --------------------------------
0343 Structure::
0344
0345 struct device_attribute {
0346 struct attribute attr;
0347 ssize_t (*show)(struct device *dev, struct device_attribute *attr,
0348 char *buf);
0349 ssize_t (*store)(struct device *dev, struct device_attribute *attr,
0350 const char *buf, size_t count);
0351 };
0352
0353 Declaring::
0354
0355 DEVICE_ATTR(_name, _mode, _show, _store);
0356
0357 Creation/Removal::
0358
0359 int device_create_file(struct device *dev, const struct device_attribute * attr);
0360 void device_remove_file(struct device *dev, const struct device_attribute * attr);
0361
0362
0363 bus drivers (include/linux/device.h)
0364 ------------------------------------
0365 Structure::
0366
0367 struct bus_attribute {
0368 struct attribute attr;
0369 ssize_t (*show)(struct bus_type *, char * buf);
0370 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
0371 };
0372
0373 Declaring::
0374
0375 static BUS_ATTR_RW(name);
0376 static BUS_ATTR_RO(name);
0377 static BUS_ATTR_WO(name);
0378
0379 Creation/Removal::
0380
0381 int bus_create_file(struct bus_type *, struct bus_attribute *);
0382 void bus_remove_file(struct bus_type *, struct bus_attribute *);
0383
0384
0385 device drivers (include/linux/device.h)
0386 ---------------------------------------
0387
0388 Structure::
0389
0390 struct driver_attribute {
0391 struct attribute attr;
0392 ssize_t (*show)(struct device_driver *, char * buf);
0393 ssize_t (*store)(struct device_driver *, const char * buf,
0394 size_t count);
0395 };
0396
0397 Declaring::
0398
0399 DRIVER_ATTR_RO(_name)
0400 DRIVER_ATTR_RW(_name)
0401
0402 Creation/Removal::
0403
0404 int driver_create_file(struct device_driver *, const struct driver_attribute *);
0405 void driver_remove_file(struct device_driver *, const struct driver_attribute *);
0406
0407
0408 Documentation
0409 ~~~~~~~~~~~~~
0410
0411 The sysfs directory structure and the attributes in each directory define an
0412 ABI between the kernel and user space. As for any ABI, it is important that
0413 this ABI is stable and properly documented. All new sysfs attributes must be
0414 documented in Documentation/ABI. See also Documentation/ABI/README for more
0415 information.
