configfs.rst 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535
  1. =======================================================
  2. Configfs - Userspace-driven Kernel Object Configuration
  3. =======================================================
  4. Joel Becker <joel.becker@oracle.com>
  5. Updated: 31 March 2005
  6. Copyright (c) 2005 Oracle Corporation,
  7. Joel Becker <joel.becker@oracle.com>
  8. What is configfs?
  9. =================
  10. configfs is a ram-based filesystem that provides the converse of
  11. sysfs's functionality. Where sysfs is a filesystem-based view of
  12. kernel objects, configfs is a filesystem-based manager of kernel
  13. objects, or config_items.
  14. With sysfs, an object is created in kernel (for example, when a device
  15. is discovered) and it is registered with sysfs. Its attributes then
  16. appear in sysfs, allowing userspace to read the attributes via
  17. readdir(3)/read(2). It may allow some attributes to be modified via
  18. write(2). The important point is that the object is created and
  19. destroyed in kernel, the kernel controls the lifecycle of the sysfs
  20. representation, and sysfs is merely a window on all this.
  21. A configfs config_item is created via an explicit userspace operation:
  22. mkdir(2). It is destroyed via rmdir(2). The attributes appear at
  23. mkdir(2) time, and can be read or modified via read(2) and write(2).
  24. As with sysfs, readdir(3) queries the list of items and/or attributes.
  25. symlink(2) can be used to group items together. Unlike sysfs, the
  26. lifetime of the representation is completely driven by userspace. The
  27. kernel modules backing the items must respond to this.
  28. Both sysfs and configfs can and should exist together on the same
  29. system. One is not a replacement for the other.
  30. Using configfs
  31. ==============
  32. configfs can be compiled as a module or into the kernel. You can access
  33. it by doing::
  34. mount -t configfs none /config
  35. The configfs tree will be empty unless client modules are also loaded.
  36. These are modules that register their item types with configfs as
  37. subsystems. Once a client subsystem is loaded, it will appear as a
  38. subdirectory (or more than one) under /config. Like sysfs, the
  39. configfs tree is always there, whether mounted on /config or not.
  40. An item is created via mkdir(2). The item's attributes will also
  41. appear at this time. readdir(3) can determine what the attributes are,
  42. read(2) can query their default values, and write(2) can store new
  43. values. Don't mix more than one attribute in one attribute file.
  44. There are two types of configfs attributes:
  45. * Normal attributes, which similar to sysfs attributes, are small ASCII text
  46. files, with a maximum size of one page (PAGE_SIZE, 4096 on i386). Preferably
  47. only one value per file should be used, and the same caveats from sysfs apply.
  48. Configfs expects write(2) to store the entire buffer at once. When writing to
  49. normal configfs attributes, userspace processes should first read the entire
  50. file, modify the portions they wish to change, and then write the entire
  51. buffer back.
  52. * Binary attributes, which are somewhat similar to sysfs binary attributes,
  53. but with a few slight changes to semantics. The PAGE_SIZE limitation does not
  54. apply, but the whole binary item must fit in single kernel vmalloc'ed buffer.
  55. The write(2) calls from user space are buffered, and the attributes'
  56. write_bin_attribute method will be invoked on the final close, therefore it is
  57. imperative for user-space to check the return code of close(2) in order to
  58. verify that the operation finished successfully.
  59. To avoid a malicious user OOMing the kernel, there's a per-binary attribute
  60. maximum buffer value.
  61. When an item needs to be destroyed, remove it with rmdir(2). An
  62. item cannot be destroyed if any other item has a link to it (via
  63. symlink(2)). Links can be removed via unlink(2).
  64. Configuring FakeNBD: an Example
  65. ===============================
  66. Imagine there's a Network Block Device (NBD) driver that allows you to
  67. access remote block devices. Call it FakeNBD. FakeNBD uses configfs
  68. for its configuration. Obviously, there will be a nice program that
  69. sysadmins use to configure FakeNBD, but somehow that program has to tell
  70. the driver about it. Here's where configfs comes in.
  71. When the FakeNBD driver is loaded, it registers itself with configfs.
  72. readdir(3) sees this just fine::
  73. # ls /config
  74. fakenbd
  75. A fakenbd connection can be created with mkdir(2). The name is
  76. arbitrary, but likely the tool will make some use of the name. Perhaps
  77. it is a uuid or a disk name::
  78. # mkdir /config/fakenbd/disk1
  79. # ls /config/fakenbd/disk1
  80. target device rw
  81. The target attribute contains the IP address of the server FakeNBD will
  82. connect to. The device attribute is the device on the server.
  83. Predictably, the rw attribute determines whether the connection is
  84. read-only or read-write::
  85. # echo 10.0.0.1 > /config/fakenbd/disk1/target
  86. # echo /dev/sda1 > /config/fakenbd/disk1/device
  87. # echo 1 > /config/fakenbd/disk1/rw
  88. That's it. That's all there is. Now the device is configured, via the
  89. shell no less.
  90. Coding With configfs
  91. ====================
  92. Every object in configfs is a config_item. A config_item reflects an
  93. object in the subsystem. It has attributes that match values on that
  94. object. configfs handles the filesystem representation of that object
  95. and its attributes, allowing the subsystem to ignore all but the
  96. basic show/store interaction.
  97. Items are created and destroyed inside a config_group. A group is a
  98. collection of items that share the same attributes and operations.
  99. Items are created by mkdir(2) and removed by rmdir(2), but configfs
  100. handles that. The group has a set of operations to perform these tasks
  101. A subsystem is the top level of a client module. During initialization,
  102. the client module registers the subsystem with configfs, the subsystem
  103. appears as a directory at the top of the configfs filesystem. A
  104. subsystem is also a config_group, and can do everything a config_group
  105. can.
  106. struct config_item
  107. ==================
  108. ::
  109. struct config_item {
  110. char *ci_name;
  111. char ci_namebuf[UOBJ_NAME_LEN];
  112. struct kref ci_kref;
  113. struct list_head ci_entry;
  114. struct config_item *ci_parent;
  115. struct config_group *ci_group;
  116. struct config_item_type *ci_type;
  117. struct dentry *ci_dentry;
  118. };
  119. void config_item_init(struct config_item *);
  120. void config_item_init_type_name(struct config_item *,
  121. const char *name,
  122. struct config_item_type *type);
  123. struct config_item *config_item_get(struct config_item *);
  124. void config_item_put(struct config_item *);
  125. Generally, struct config_item is embedded in a container structure, a
  126. structure that actually represents what the subsystem is doing. The
  127. config_item portion of that structure is how the object interacts with
  128. configfs.
  129. Whether statically defined in a source file or created by a parent
  130. config_group, a config_item must have one of the _init() functions
  131. called on it. This initializes the reference count and sets up the
  132. appropriate fields.
  133. All users of a config_item should have a reference on it via
  134. config_item_get(), and drop the reference when they are done via
  135. config_item_put().
  136. By itself, a config_item cannot do much more than appear in configfs.
  137. Usually a subsystem wants the item to display and/or store attributes,
  138. among other things. For that, it needs a type.
  139. struct config_item_type
  140. =======================
  141. ::
  142. struct configfs_item_operations {
  143. void (*release)(struct config_item *);
  144. int (*allow_link)(struct config_item *src,
  145. struct config_item *target);
  146. void (*drop_link)(struct config_item *src,
  147. struct config_item *target);
  148. };
  149. struct config_item_type {
  150. struct module *ct_owner;
  151. struct configfs_item_operations *ct_item_ops;
  152. struct configfs_group_operations *ct_group_ops;
  153. struct configfs_attribute **ct_attrs;
  154. struct configfs_bin_attribute **ct_bin_attrs;
  155. };
  156. The most basic function of a config_item_type is to define what
  157. operations can be performed on a config_item. All items that have been
  158. allocated dynamically will need to provide the ct_item_ops->release()
  159. method. This method is called when the config_item's reference count
  160. reaches zero.
  161. struct configfs_attribute
  162. =========================
  163. ::
  164. struct configfs_attribute {
  165. char *ca_name;
  166. struct module *ca_owner;
  167. umode_t ca_mode;
  168. ssize_t (*show)(struct config_item *, char *);
  169. ssize_t (*store)(struct config_item *, const char *, size_t);
  170. };
  171. When a config_item wants an attribute to appear as a file in the item's
  172. configfs directory, it must define a configfs_attribute describing it.
  173. It then adds the attribute to the NULL-terminated array
  174. config_item_type->ct_attrs. When the item appears in configfs, the
  175. attribute file will appear with the configfs_attribute->ca_name
  176. filename. configfs_attribute->ca_mode specifies the file permissions.
  177. If an attribute is readable and provides a ->show method, that method will
  178. be called whenever userspace asks for a read(2) on the attribute. If an
  179. attribute is writable and provides a ->store method, that method will be
  180. called whenever userspace asks for a write(2) on the attribute.
  181. struct configfs_bin_attribute
  182. =============================
  183. ::
  184. struct configfs_bin_attribute {
  185. struct configfs_attribute cb_attr;
  186. void *cb_private;
  187. size_t cb_max_size;
  188. };
  189. The binary attribute is used when the one needs to use binary blob to
  190. appear as the contents of a file in the item's configfs directory.
  191. To do so add the binary attribute to the NULL-terminated array
  192. config_item_type->ct_bin_attrs, and the item appears in configfs, the
  193. attribute file will appear with the configfs_bin_attribute->cb_attr.ca_name
  194. filename. configfs_bin_attribute->cb_attr.ca_mode specifies the file
  195. permissions.
  196. The cb_private member is provided for use by the driver, while the
  197. cb_max_size member specifies the maximum amount of vmalloc buffer
  198. to be used.
  199. If binary attribute is readable and the config_item provides a
  200. ct_item_ops->read_bin_attribute() method, that method will be called
  201. whenever userspace asks for a read(2) on the attribute. The converse
  202. will happen for write(2). The reads/writes are bufferred so only a
  203. single read/write will occur; the attributes' need not concern itself
  204. with it.
  205. struct config_group
  206. ===================
  207. A config_item cannot live in a vacuum. The only way one can be created
  208. is via mkdir(2) on a config_group. This will trigger creation of a
  209. child item::
  210. struct config_group {
  211. struct config_item cg_item;
  212. struct list_head cg_children;
  213. struct configfs_subsystem *cg_subsys;
  214. struct list_head default_groups;
  215. struct list_head group_entry;
  216. };
  217. void config_group_init(struct config_group *group);
  218. void config_group_init_type_name(struct config_group *group,
  219. const char *name,
  220. struct config_item_type *type);
  221. The config_group structure contains a config_item. Properly configuring
  222. that item means that a group can behave as an item in its own right.
  223. However, it can do more: it can create child items or groups. This is
  224. accomplished via the group operations specified on the group's
  225. config_item_type::
  226. struct configfs_group_operations {
  227. struct config_item *(*make_item)(struct config_group *group,
  228. const char *name);
  229. struct config_group *(*make_group)(struct config_group *group,
  230. const char *name);
  231. int (*commit_item)(struct config_item *item);
  232. void (*disconnect_notify)(struct config_group *group,
  233. struct config_item *item);
  234. void (*drop_item)(struct config_group *group,
  235. struct config_item *item);
  236. };
  237. A group creates child items by providing the
  238. ct_group_ops->make_item() method. If provided, this method is called from
  239. mkdir(2) in the group's directory. The subsystem allocates a new
  240. config_item (or more likely, its container structure), initializes it,
  241. and returns it to configfs. Configfs will then populate the filesystem
  242. tree to reflect the new item.
  243. If the subsystem wants the child to be a group itself, the subsystem
  244. provides ct_group_ops->make_group(). Everything else behaves the same,
  245. using the group _init() functions on the group.
  246. Finally, when userspace calls rmdir(2) on the item or group,
  247. ct_group_ops->drop_item() is called. As a config_group is also a
  248. config_item, it is not necessary for a separate drop_group() method.
  249. The subsystem must config_item_put() the reference that was initialized
  250. upon item allocation. If a subsystem has no work to do, it may omit
  251. the ct_group_ops->drop_item() method, and configfs will call
  252. config_item_put() on the item on behalf of the subsystem.
  253. Important:
  254. drop_item() is void, and as such cannot fail. When rmdir(2)
  255. is called, configfs WILL remove the item from the filesystem tree
  256. (assuming that it has no children to keep it busy). The subsystem is
  257. responsible for responding to this. If the subsystem has references to
  258. the item in other threads, the memory is safe. It may take some time
  259. for the item to actually disappear from the subsystem's usage. But it
  260. is gone from configfs.
  261. When drop_item() is called, the item's linkage has already been torn
  262. down. It no longer has a reference on its parent and has no place in
  263. the item hierarchy. If a client needs to do some cleanup before this
  264. teardown happens, the subsystem can implement the
  265. ct_group_ops->disconnect_notify() method. The method is called after
  266. configfs has removed the item from the filesystem view but before the
  267. item is removed from its parent group. Like drop_item(),
  268. disconnect_notify() is void and cannot fail. Client subsystems should
  269. not drop any references here, as they still must do it in drop_item().
  270. A config_group cannot be removed while it still has child items. This
  271. is implemented in the configfs rmdir(2) code. ->drop_item() will not be
  272. called, as the item has not been dropped. rmdir(2) will fail, as the
  273. directory is not empty.
  274. struct configfs_subsystem
  275. =========================
  276. A subsystem must register itself, usually at module_init time. This
  277. tells configfs to make the subsystem appear in the file tree::
  278. struct configfs_subsystem {
  279. struct config_group su_group;
  280. struct mutex su_mutex;
  281. };
  282. int configfs_register_subsystem(struct configfs_subsystem *subsys);
  283. void configfs_unregister_subsystem(struct configfs_subsystem *subsys);
  284. A subsystem consists of a toplevel config_group and a mutex.
  285. The group is where child config_items are created. For a subsystem,
  286. this group is usually defined statically. Before calling
  287. configfs_register_subsystem(), the subsystem must have initialized the
  288. group via the usual group _init() functions, and it must also have
  289. initialized the mutex.
  290. When the register call returns, the subsystem is live, and it
  291. will be visible via configfs. At that point, mkdir(2) can be called and
  292. the subsystem must be ready for it.
  293. An Example
  294. ==========
  295. The best example of these basic concepts is the simple_children
  296. subsystem/group and the simple_child item in
  297. samples/configfs/configfs_sample.c. It shows a trivial object displaying
  298. and storing an attribute, and a simple group creating and destroying
  299. these children.
  300. Hierarchy Navigation and the Subsystem Mutex
  301. ============================================
  302. There is an extra bonus that configfs provides. The config_groups and
  303. config_items are arranged in a hierarchy due to the fact that they
  304. appear in a filesystem. A subsystem is NEVER to touch the filesystem
  305. parts, but the subsystem might be interested in this hierarchy. For
  306. this reason, the hierarchy is mirrored via the config_group->cg_children
  307. and config_item->ci_parent structure members.
  308. A subsystem can navigate the cg_children list and the ci_parent pointer
  309. to see the tree created by the subsystem. This can race with configfs'
  310. management of the hierarchy, so configfs uses the subsystem mutex to
  311. protect modifications. Whenever a subsystem wants to navigate the
  312. hierarchy, it must do so under the protection of the subsystem
  313. mutex.
  314. A subsystem will be prevented from acquiring the mutex while a newly
  315. allocated item has not been linked into this hierarchy. Similarly, it
  316. will not be able to acquire the mutex while a dropping item has not
  317. yet been unlinked. This means that an item's ci_parent pointer will
  318. never be NULL while the item is in configfs, and that an item will only
  319. be in its parent's cg_children list for the same duration. This allows
  320. a subsystem to trust ci_parent and cg_children while they hold the
  321. mutex.
  322. Item Aggregation Via symlink(2)
  323. ===============================
  324. configfs provides a simple group via the group->item parent/child
  325. relationship. Often, however, a larger environment requires aggregation
  326. outside of the parent/child connection. This is implemented via
  327. symlink(2).
  328. A config_item may provide the ct_item_ops->allow_link() and
  329. ct_item_ops->drop_link() methods. If the ->allow_link() method exists,
  330. symlink(2) may be called with the config_item as the source of the link.
  331. These links are only allowed between configfs config_items. Any
  332. symlink(2) attempt outside the configfs filesystem will be denied.
  333. When symlink(2) is called, the source config_item's ->allow_link()
  334. method is called with itself and a target item. If the source item
  335. allows linking to target item, it returns 0. A source item may wish to
  336. reject a link if it only wants links to a certain type of object (say,
  337. in its own subsystem).
  338. When unlink(2) is called on the symbolic link, the source item is
  339. notified via the ->drop_link() method. Like the ->drop_item() method,
  340. this is a void function and cannot return failure. The subsystem is
  341. responsible for responding to the change.
  342. A config_item cannot be removed while it links to any other item, nor
  343. can it be removed while an item links to it. Dangling symlinks are not
  344. allowed in configfs.
  345. Automatically Created Subgroups
  346. ===============================
  347. A new config_group may want to have two types of child config_items.
  348. While this could be codified by magic names in ->make_item(), it is much
  349. more explicit to have a method whereby userspace sees this divergence.
  350. Rather than have a group where some items behave differently than
  351. others, configfs provides a method whereby one or many subgroups are
  352. automatically created inside the parent at its creation. Thus,
  353. mkdir("parent") results in "parent", "parent/subgroup1", up through
  354. "parent/subgroupN". Items of type 1 can now be created in
  355. "parent/subgroup1", and items of type N can be created in
  356. "parent/subgroupN".
  357. These automatic subgroups, or default groups, do not preclude other
  358. children of the parent group. If ct_group_ops->make_group() exists,
  359. other child groups can be created on the parent group directly.
  360. A configfs subsystem specifies default groups by adding them using the
  361. configfs_add_default_group() function to the parent config_group
  362. structure. Each added group is populated in the configfs tree at the same
  363. time as the parent group. Similarly, they are removed at the same time
  364. as the parent. No extra notification is provided. When a ->drop_item()
  365. method call notifies the subsystem the parent group is going away, it
  366. also means every default group child associated with that parent group.
  367. As a consequence of this, default groups cannot be removed directly via
  368. rmdir(2). They also are not considered when rmdir(2) on the parent
  369. group is checking for children.
  370. Dependent Subsystems
  371. ====================
  372. Sometimes other drivers depend on particular configfs items. For
  373. example, ocfs2 mounts depend on a heartbeat region item. If that
  374. region item is removed with rmdir(2), the ocfs2 mount must BUG or go
  375. readonly. Not happy.
  376. configfs provides two additional API calls: configfs_depend_item() and
  377. configfs_undepend_item(). A client driver can call
  378. configfs_depend_item() on an existing item to tell configfs that it is
  379. depended on. configfs will then return -EBUSY from rmdir(2) for that
  380. item. When the item is no longer depended on, the client driver calls
  381. configfs_undepend_item() on it.
  382. These API cannot be called underneath any configfs callbacks, as
  383. they will conflict. They can block and allocate. A client driver
  384. probably shouldn't calling them of its own gumption. Rather it should
  385. be providing an API that external subsystems call.
  386. How does this work? Imagine the ocfs2 mount process. When it mounts,
  387. it asks for a heartbeat region item. This is done via a call into the
  388. heartbeat code. Inside the heartbeat code, the region item is looked
  389. up. Here, the heartbeat code calls configfs_depend_item(). If it
  390. succeeds, then heartbeat knows the region is safe to give to ocfs2.
  391. If it fails, it was being torn down anyway, and heartbeat can gracefully
  392. pass up an error.
  393. Committable Items
  394. =================
  395. Note:
  396. Committable items are currently unimplemented.
  397. Some config_items cannot have a valid initial state. That is, no
  398. default values can be specified for the item's attributes such that the
  399. item can do its work. Userspace must configure one or more attributes,
  400. after which the subsystem can start whatever entity this item
  401. represents.
  402. Consider the FakeNBD device from above. Without a target address *and*
  403. a target device, the subsystem has no idea what block device to import.
  404. The simple example assumes that the subsystem merely waits until all the
  405. appropriate attributes are configured, and then connects. This will,
  406. indeed, work, but now every attribute store must check if the attributes
  407. are initialized. Every attribute store must fire off the connection if
  408. that condition is met.
  409. Far better would be an explicit action notifying the subsystem that the
  410. config_item is ready to go. More importantly, an explicit action allows
  411. the subsystem to provide feedback as to whether the attributes are
  412. initialized in a way that makes sense. configfs provides this as
  413. committable items.
  414. configfs still uses only normal filesystem operations. An item is
  415. committed via rename(2). The item is moved from a directory where it
  416. can be modified to a directory where it cannot.
  417. Any group that provides the ct_group_ops->commit_item() method has
  418. committable items. When this group appears in configfs, mkdir(2) will
  419. not work directly in the group. Instead, the group will have two
  420. subdirectories: "live" and "pending". The "live" directory does not
  421. support mkdir(2) or rmdir(2) either. It only allows rename(2). The
  422. "pending" directory does allow mkdir(2) and rmdir(2). An item is
  423. created in the "pending" directory. Its attributes can be modified at
  424. will. Userspace commits the item by renaming it into the "live"
  425. directory. At this point, the subsystem receives the ->commit_item()
  426. callback. If all required attributes are filled to satisfaction, the
  427. method returns zero and the item is moved to the "live" directory.
  428. As rmdir(2) does not work in the "live" directory, an item must be
  429. shutdown, or "uncommitted". Again, this is done via rename(2), this
  430. time from the "live" directory back to the "pending" one. The subsystem
  431. is notified by the ct_group_ops->uncommit_object() method.