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