sysfs - _The_ filesystem for exporting kernel objects — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Core subsystems Human interfaces Networking interfaces Storage interfaces Filesystems in the Linux kernel Block CD-ROM SCSI Subsystem TCM Virtual Device NVMe Subsystem Other subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source sysfs - _The_ filesystem for exporting kernel objects ¶ Patrick Mochel < mochel @ osdl . org > Mike Murphy < mamurph @ cs . clemson . edu > Revised : 16 August 2011 Original : 10 January 2003 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 Everything you never wanted to know about kobjects, ksets, and ktypes for more information concerning the kobject interface. Using sysfs ¶ sysfs is always compiled in if CONFIG_SYSFS is defined. You can access it by doing: 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. sysfs internally stores a pointer to the kobject that implements a directory in the kernfs_node 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() . 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 per file.
It is noted that it may not be efficient to contain only one 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 you publicly humiliated and your code rewritten without notice. An attribute definition is simply: struct attribute { char *name; struct module *owner; umode_t mode; }; int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); 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 { 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); }; int device_create_file(struct device *, const struct device_attribute *); void device_remove_file(struct device *, const struct device_attribute *); It also defines this helper for defining device attributes: #define DEVICE_ATTR(_name, _mode, _show, _store) \ struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) For example, declaring: static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); is equivalent to doing: static struct device_attribute dev_attr_foo = { .attr = { .name = "foo", .mode = S_IWUSR | S_IRUGO, }, .show = show_foo, .store = store_foo, }; Note as stated in include/linux/sysfs.h “OTHER_WRITABLE?
Generally considered a bad idea.” so trying to set a sysfs file writable for everyone will fail reverting to RO mode for “Others”. For the common cases sysfs.h provides convenience macros to make defining attributes easier as well as making code more concise and readable. The above case could be shortened to: static struct device_attribute dev_attr_foo = __ATTR_RW(foo); the list of helpers available to define your wrapper function is: __ATTR_RO(name): assumes default name_show and mode 0444 __ATTR_WO(name): assumes a name_store only and is restricted to mode 0200 that is root write access only. __ATTR_RO_MODE(name, mode): for more restrictive RO access; currently only use case is the EFI System Resource Table (see drivers/firmware/efi/esrt.c) __ATTR_RW(name): assumes default name_show, name_store and setting mode to 0644. __ATTR_NULL: which sets the name to NULL and is used as end of list indicator (see: kernel/workqueue.c) 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 { ssize_t (*show)(struct kobject *, struct attribute *, char *); ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); }; [ 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: #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, char *buf) { struct device_attribute *dev_attr = to_dev_attr(attr); struct device *dev = kobj_to_dev(kobj); ssize_t ret = -EIO; if (dev_attr->show) ret = dev_attr->show(dev, dev_attr, buf); if (ret >= (ssize_t)PAGE_SIZE) { printk("dev_attr_show: %pS returned bad count\n", dev_attr->show); } 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: 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); IOW, they should take only an object, an attribute, and a buffer as parameters. 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. 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.
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. A terminating null is
The rest of this page is on the live site.