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