sysfs.rst 13 KB

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