sysfs.txt 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346
  1. sysfs - _The_ filesystem for exporting kernel objects.
  2. Patrick Mochel <mochel@osdl.org>
  3. 10 January 2003
  4. What it is:
  5. ~~~~~~~~~~~
  6. sysfs is a ram-based filesystem initially based on ramfs. It provides
  7. a means to export kernel data structures, their attributes, and the
  8. linkages between them to userspace.
  9. sysfs is tied inherently to the kobject infrastructure. Please read
  10. Documentation/kobject.txt for more information concerning the kobject
  11. interface.
  12. Using sysfs
  13. ~~~~~~~~~~~
  14. sysfs is always compiled in. You can access it by doing:
  15. mount -t sysfs sysfs /sys
  16. Directory Creation
  17. ~~~~~~~~~~~~~~~~~~
  18. For every kobject that is registered with the system, a directory is
  19. created for it in sysfs. That directory is created as a subdirectory
  20. of the kobject's parent, expressing internal object hierarchies to
  21. userspace. Top-level directories in sysfs represent the common
  22. ancestors of object hierarchies; i.e. the subsystems the objects
  23. belong to.
  24. Sysfs internally stores the kobject that owns the directory in the
  25. ->d_fsdata pointer of the directory's dentry. This allows sysfs to do
  26. reference counting directly on the kobject when the file is opened and
  27. closed.
  28. Attributes
  29. ~~~~~~~~~~
  30. Attributes can be exported for kobjects in the form of regular files in
  31. the filesystem. Sysfs forwards file I/O operations to methods defined
  32. for the attributes, providing a means to read and write kernel
  33. attributes.
  34. Attributes should be ASCII text files, preferably with only one value
  35. per file. It is noted that it may not be efficient to contain only
  36. value per file, so it is socially acceptable to express an array of
  37. values of the same type.
  38. Mixing types, expressing multiple lines of data, and doing fancy
  39. formatting of data is heavily frowned upon. Doing these things may get
  40. you publically humiliated and your code rewritten without notice.
  41. An attribute definition is simply:
  42. struct attribute {
  43. char * name;
  44. mode_t mode;
  45. };
  46. int sysfs_create_file(struct kobject * kobj, struct attribute * attr);
  47. void sysfs_remove_file(struct kobject * kobj, struct attribute * attr);
  48. A bare attribute contains no means to read or write the value of the
  49. attribute. Subsystems are encouraged to define their own attribute
  50. structure and wrapper functions for adding and removing attributes for
  51. a specific object type.
  52. For example, the driver model defines struct device_attribute like:
  53. struct device_attribute {
  54. struct attribute attr;
  55. ssize_t (*show)(struct device * dev, char * buf);
  56. ssize_t (*store)(struct device * dev, const char * buf);
  57. };
  58. int device_create_file(struct device *, struct device_attribute *);
  59. void device_remove_file(struct device *, struct device_attribute *);
  60. It also defines this helper for defining device attributes:
  61. #define DEVICE_ATTR(_name, _mode, _show, _store) \
  62. struct device_attribute dev_attr_##_name = { \
  63. .attr = {.name = __stringify(_name) , .mode = _mode }, \
  64. .show = _show, \
  65. .store = _store, \
  66. };
  67. For example, declaring
  68. static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
  69. is equivalent to doing:
  70. static struct device_attribute dev_attr_foo = {
  71. .attr = {
  72. .name = "foo",
  73. .mode = S_IWUSR | S_IRUGO,
  74. },
  75. .show = show_foo,
  76. .store = store_foo,
  77. };
  78. Subsystem-Specific Callbacks
  79. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80. When a subsystem defines a new attribute type, it must implement a
  81. set of sysfs operations for forwarding read and write calls to the
  82. show and store methods of the attribute owners.
  83. struct sysfs_ops {
  84. ssize_t (*show)(struct kobject *, struct attribute *, char *);
  85. ssize_t (*store)(struct kobject *, struct attribute *, const char *);
  86. };
  87. [ Subsystems should have already defined a struct kobj_type as a
  88. descriptor for this type, which is where the sysfs_ops pointer is
  89. stored. See the kobject documentation for more information. ]
  90. When a file is read or written, sysfs calls the appropriate method
  91. for the type. The method then translates the generic struct kobject
  92. and struct attribute pointers to the appropriate pointer types, and
  93. calls the associated methods.
  94. To illustrate:
  95. #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
  96. #define to_dev(d) container_of(d, struct device, kobj)
  97. static ssize_t
  98. dev_attr_show(struct kobject * kobj, struct attribute * attr, char * buf)
  99. {
  100. struct device_attribute * dev_attr = to_dev_attr(attr);
  101. struct device * dev = to_dev(kobj);
  102. ssize_t ret = 0;
  103. if (dev_attr->show)
  104. ret = dev_attr->show(dev, buf);
  105. return ret;
  106. }
  107. Reading/Writing Attribute Data
  108. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  109. To read or write attributes, show() or store() methods must be
  110. specified when declaring the attribute. The method types should be as
  111. simple as those defined for device attributes:
  112. ssize_t (*show)(struct device * dev, char * buf);
  113. ssize_t (*store)(struct device * dev, const char * buf);
  114. IOW, they should take only an object and a buffer as parameters.
  115. sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the
  116. method. Sysfs will call the method exactly once for each read or
  117. write. This forces the following behavior on the method
  118. implementations:
  119. - On read(2), the show() method should fill the entire buffer.
  120. Recall that an attribute should only be exporting one value, or an
  121. array of similar values, so this shouldn't be that expensive.
  122. This allows userspace to do partial reads and seeks arbitrarily over
  123. the entire file at will.
  124. - On write(2), sysfs expects the entire buffer to be passed during the
  125. first write. Sysfs then passes the entire buffer to the store()
  126. method.
  127. When writing sysfs files, userspace processes should first read the
  128. entire file, modify the values it wishes to change, then write the
  129. entire buffer back.
  130. Attribute method implementations should operate on an identical
  131. buffer when reading and writing values.
  132. Other notes:
  133. - The buffer will always be PAGE_SIZE bytes in length. On i386, this
  134. is 4096.
  135. - show() methods should return the number of bytes printed into the
  136. buffer. This is the return value of snprintf().
  137. - show() should always use snprintf().
  138. - store() should return the number of bytes used from the buffer. This
  139. can be done using strlen().
  140. - show() or store() can always return errors. If a bad value comes
  141. through, be sure to return an error.
  142. - The object passed to the methods will be pinned in memory via sysfs
  143. referencing counting its embedded object. However, the physical
  144. entity (e.g. device) the object represents may not be present. Be
  145. sure to have a way to check this, if necessary.
  146. A very simple (and naive) implementation of a device attribute is:
  147. static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf)
  148. {
  149. return snprintf(buf, PAGE_SIZE, "%s\n", dev->name);
  150. }
  151. static ssize_t store_name(struct device * dev, const char * buf)
  152. {
  153. sscanf(buf, "%20s", dev->name);
  154. return strnlen(buf, PAGE_SIZE);
  155. }
  156. static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
  157. (Note that the real implementation doesn't allow userspace to set the
  158. name for a device.)
  159. Top Level Directory Layout
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. The sysfs directory arrangement exposes the relationship of kernel
  162. data structures.
  163. The top level sysfs directory looks like:
  164. block/
  165. bus/
  166. class/
  167. devices/
  168. firmware/
  169. net/
  170. fs/
  171. devices/ contains a filesystem representation of the device tree. It maps
  172. directly to the internal kernel device tree, which is a hierarchy of
  173. struct device.
  174. bus/ contains flat directory layout of the various bus types in the
  175. kernel. Each bus's directory contains two subdirectories:
  176. devices/
  177. drivers/
  178. devices/ contains symlinks for each device discovered in the system
  179. that point to the device's directory under root/.
  180. drivers/ contains a directory for each device driver that is loaded
  181. for devices on that particular bus (this assumes that drivers do not
  182. span multiple bus types).
  183. fs/ contains a directory for some filesystems. Currently each
  184. filesystem wanting to export attributes must create its own hierarchy
  185. below fs/ (see ./fuse.txt for an example).
  186. More information can driver-model specific features can be found in
  187. Documentation/driver-model/.
  188. TODO: Finish this section.
  189. Current Interfaces
  190. ~~~~~~~~~~~~~~~~~~
  191. The following interface layers currently exist in sysfs:
  192. - devices (include/linux/device.h)
  193. ----------------------------------
  194. Structure:
  195. struct device_attribute {
  196. struct attribute attr;
  197. ssize_t (*show)(struct device * dev, char * buf);
  198. ssize_t (*store)(struct device * dev, const char * buf);
  199. };
  200. Declaring:
  201. DEVICE_ATTR(_name, _str, _mode, _show, _store);
  202. Creation/Removal:
  203. int device_create_file(struct device *device, struct device_attribute * attr);
  204. void device_remove_file(struct device * dev, struct device_attribute * attr);
  205. - bus drivers (include/linux/device.h)
  206. --------------------------------------
  207. Structure:
  208. struct bus_attribute {
  209. struct attribute attr;
  210. ssize_t (*show)(struct bus_type *, char * buf);
  211. ssize_t (*store)(struct bus_type *, const char * buf);
  212. };
  213. Declaring:
  214. BUS_ATTR(_name, _mode, _show, _store)
  215. Creation/Removal:
  216. int bus_create_file(struct bus_type *, struct bus_attribute *);
  217. void bus_remove_file(struct bus_type *, struct bus_attribute *);
  218. - device drivers (include/linux/device.h)
  219. -----------------------------------------
  220. Structure:
  221. struct driver_attribute {
  222. struct attribute attr;
  223. ssize_t (*show)(struct device_driver *, char * buf);
  224. ssize_t (*store)(struct device_driver *, const char * buf);
  225. };
  226. Declaring:
  227. DRIVER_ATTR(_name, _mode, _show, _store)
  228. Creation/Removal:
  229. int driver_create_file(struct device_driver *, struct driver_attribute *);
  230. void driver_remove_file(struct device_driver *, struct driver_attribute *);