Lines Matching +full:2 +full:- +full:a
2 Configfs - Userspace-driven Kernel Object Configuration
16 configfs is a ram-based filesystem that provides the converse of
17 sysfs's functionality. Where sysfs is a filesystem-based view of
18 kernel objects, configfs is a filesystem-based manager of kernel
21 With sysfs, an object is created in kernel (for example, when a device
24 readdir(3)/read(2). It may allow some attributes to be modified via
25 write(2). The important point is that the object is created and
27 representation, and sysfs is merely a window on all this.
29 A configfs config_item is created via an explicit userspace operation:
30 mkdir(2). It is destroyed via rmdir(2). The attributes appear at
31 mkdir(2) time, and can be read or modified via read(2) and write(2).
33 symlink(2) can be used to group items together. Unlike sysfs, the
38 system. One is not a replacement for the other.
43 configfs can be compiled as a module or into the kernel. You can access
46 mount -t configfs none /config
50 subsystems. Once a client subsystem is loaded, it will appear as a
54 An item is created via mkdir(2). The item's attributes will also
56 read(2) can query their default values, and write(2) can store new
62 files, with a maximum size of one page (PAGE_SIZE, 4096 on i386). Preferably
64 Configfs expects write(2) to store the entire buffer at once. When writing to
70 but with a few slight changes to semantics. The PAGE_SIZE limitation does not
72 The write(2) calls from user space are buffered, and the attributes'
74 imperative for user-space to check the return code of close(2) in order to
76 To avoid a malicious user OOMing the kernel, there's a per-binary attribute
79 When an item needs to be destroyed, remove it with rmdir(2). An
80 item cannot be destroyed if any other item has a link to it (via
81 symlink(2)). Links can be removed via unlink(2).
86 Imagine there's a Network Block Device (NBD) driver that allows you to
88 for its configuration. Obviously, there will be a nice program that
98 A fakenbd connection can be created with mkdir(2). The name is
100 it is a uuid or a disk name::
109 read-only or read-write::
121 Every object in configfs is a config_item. A config_item reflects an
127 Items are created and destroyed inside a config_group. A group is a
129 Items are created by mkdir(2) and removed by rmdir(2), but configfs
130 handles that. The group has a set of operations to perform these tasks
132 A subsystem is the top level of a client module. During initialization,
134 appears as a directory at the top of the configfs filesystem. A
135 subsystem is also a config_group, and can do everything a config_group
161 Generally, struct config_item is embedded in a container structure, a
166 Whether statically defined in a source file or created by a parent
167 config_group, a config_item must have one of the _init() functions
171 All users of a config_item should have a reference on it via
175 By itself, a config_item cannot do much more than appear in configfs.
176 Usually a subsystem wants the item to display and/or store attributes,
177 among other things. For that, it needs a type.
200 The most basic function of a config_item_type is to define what
201 operations can be performed on a config_item. All items that have been
202 allocated dynamically will need to provide the ct_item_ops->release()
219 When a config_item wants an attribute to appear as a file in the item's
220 configfs directory, it must define a configfs_attribute describing it.
221 It then adds the attribute to the NULL-terminated array
222 config_item_type->ct_attrs. When the item appears in configfs, the
223 attribute file will appear with the configfs_attribute->ca_name
224 filename. configfs_attribute->ca_mode specifies the file permissions.
226 If an attribute is readable and provides a ->show method, that method will
227 be called whenever userspace asks for a read(2) on the attribute. If an
228 attribute is writable and provides a ->store method, that method will be
229 called whenever userspace asks for a write(2) on the attribute.
243 appear as the contents of a file in the item's configfs directory.
244 To do so add the binary attribute to the NULL-terminated array
245 config_item_type->ct_bin_attrs, and the item appears in configfs, the
246 attribute file will appear with the configfs_bin_attribute->cb_attr.ca_name
247 filename. configfs_bin_attribute->cb_attr.ca_mode specifies the file
253 If binary attribute is readable and the config_item provides a
254 ct_item_ops->read_bin_attribute() method, that method will be called
255 whenever userspace asks for a read(2) on the attribute. The converse
256 will happen for write(2). The reads/writes are buffered so only a
263 A config_item cannot live in a vacuum. The only way one can be created
264 is via mkdir(2) on a config_group. This will trigger creation of a
281 The config_group structure contains a config_item. Properly configuring
282 that item means that a group can behave as an item in its own right.
298 A group creates child items by providing the
299 ct_group_ops->make_item() method. If provided, this method is called from
300 mkdir(2) in the group's directory. The subsystem allocates a new
305 If the subsystem wants the child to be a group itself, the subsystem
306 provides ct_group_ops->make_group(). Everything else behaves the same,
309 Finally, when userspace calls rmdir(2) on the item or group,
310 ct_group_ops->drop_item() is called. As a config_group is also a
311 config_item, it is not necessary for a separate drop_group() method.
313 upon item allocation. If a subsystem has no work to do, it may omit
314 the ct_group_ops->drop_item() method, and configfs will call
318 drop_item() is void, and as such cannot fail. When rmdir(2)
327 down. It no longer has a reference on its parent and has no place in
328 the item hierarchy. If a client needs to do some cleanup before this
330 ct_group_ops->disconnect_notify() method. The method is called after
336 A config_group cannot be removed while it still has child items. This
337 is implemented in the configfs rmdir(2) code. ->drop_item() will not be
338 called, as the item has not been dropped. rmdir(2) will fail, as the
344 A subsystem must register itself, usually at module_init time. This
355 A subsystem consists of a toplevel config_group and a mutex.
356 The group is where child config_items are created. For a subsystem,
363 will be visible via configfs. At that point, mkdir(2) can be called and
371 samples/configfs/configfs_sample.c. It shows a trivial object displaying
372 and storing an attribute, and a simple group creating and destroying
379 config_items are arranged in a hierarchy due to the fact that they
380 appear in a filesystem. A subsystem is NEVER to touch the filesystem
382 this reason, the hierarchy is mirrored via the config_group->cg_children
383 and config_item->ci_parent structure members.
385 A subsystem can navigate the cg_children list and the ci_parent pointer
388 protect modifications. Whenever a subsystem wants to navigate the
392 A subsystem will be prevented from acquiring the mutex while a newly
394 will not be able to acquire the mutex while a dropping item has not
398 a subsystem to trust ci_parent and cg_children while they hold the
401 Item Aggregation Via symlink(2)
404 configfs provides a simple group via the group->item parent/child
405 relationship. Often, however, a larger environment requires aggregation
407 symlink(2).
409 A config_item may provide the ct_item_ops->allow_link() and
410 ct_item_ops->drop_link() methods. If the ->allow_link() method exists,
411 symlink(2) may be called with the config_item as the source of the link.
413 symlink(2) attempt outside the configfs filesystem will be denied.
415 When symlink(2) is called, the source config_item's ->allow_link()
416 method is called with itself and a target item. If the source item
417 allows linking to target item, it returns 0. A source item may wish to
418 reject a link if it only wants links to a certain type of object (say,
421 When unlink(2) is called on the symbolic link, the source item is
422 notified via the ->drop_link() method. Like the ->drop_item() method,
423 this is a void function and cannot return failure. The subsystem is
426 A config_item cannot be removed while it links to any other item, nor
433 A new config_group may want to have two types of child config_items.
434 While this could be codified by magic names in ->make_item(), it is much
435 more explicit to have a method whereby userspace sees this divergence.
437 Rather than have a group where some items behave differently than
438 others, configfs provides a method whereby one or many subgroups are
446 children of the parent group. If ct_group_ops->make_group() exists,
449 A configfs subsystem specifies default groups by adding them using the
453 as the parent. No extra notification is provided. When a ->drop_item()
457 As a consequence of this, default groups cannot be removed directly via
458 rmdir(2). They also are not considered when rmdir(2) on the parent
465 example, ocfs2 mounts depend on a heartbeat region item. If that
466 region item is removed with rmdir(2), the ocfs2 mount must BUG or go
470 configfs_undepend_item(). A client driver can call
472 depended on. configfs will then return -EBUSY from rmdir(2) for that
477 they will conflict. They can block and allocate. A client driver
482 it asks for a heartbeat region item. This is done via a call into the