1 ==============================================
2 Configfs - Userspace-driven Kernel Object Conf
3 ==============================================
4
5 Joel Becker <joel.becker@oracle.com>
6
7 Updated: 31 March 2005
8
9 Copyright (c) 2005 Oracle Corporation,
10 Joel Becker <joel.becker@oracle.com>
11
12
13 What is configfs?
14 =================
15
16 configfs is a ram-based filesystem that provid
17 sysfs's functionality. Where sysfs is a files
18 kernel objects, configfs is a filesystem-based
19 objects, or config_items.
20
21 With sysfs, an object is created in kernel (fo
22 is discovered) and it is registered with sysfs
23 appear in sysfs, allowing userspace to read th
24 readdir(3)/read(2). It may allow some attribu
25 write(2). The important point is that the obj
26 destroyed in kernel, the kernel controls the l
27 representation, and sysfs is merely a window o
28
29 A configfs config_item is created via an expli
30 mkdir(2). It is destroyed via rmdir(2). The
31 mkdir(2) time, and can be read or modified via
32 As with sysfs, readdir(3) queries the list of
33 symlink(2) can be used to group items together
34 lifetime of the representation is completely d
35 kernel modules backing the items must respond
36
37 Both sysfs and configfs can and should exist t
38 system. One is not a replacement for the othe
39
40 Using configfs
41 ==============
42
43 configfs can be compiled as a module or into t
44 it by doing::
45
46 mount -t configfs none /config
47
48 The configfs tree will be empty unless client
49 These are modules that register their item typ
50 subsystems. Once a client subsystem is loaded
51 subdirectory (or more than one) under /config.
52 configfs tree is always there, whether mounted
53
54 An item is created via mkdir(2). The item's a
55 appear at this time. readdir(3) can determine
56 read(2) can query their default values, and wr
57 values. Don't mix more than one attribute in
58
59 There are two types of configfs attributes:
60
61 * Normal attributes, which similar to sysfs at
62 files, with a maximum size of one page (PAGE
63 only one value per file should be used, and
64 Configfs expects write(2) to store the entir
65 normal configfs attributes, userspace proces
66 file, modify the portions they wish to chang
67 buffer back.
68
69 * Binary attributes, which are somewhat simila
70 but with a few slight changes to semantics.
71 apply, but the whole binary item must fit in
72 The write(2) calls from user space are buffe
73 write_bin_attribute method will be invoked o
74 imperative for user-space to check the retur
75 verify that the operation finished successfu
76 To avoid a malicious user OOMing the kernel,
77 maximum buffer value.
78
79 When an item needs to be destroyed, remove it
80 item cannot be destroyed if any other item has
81 symlink(2)). Links can be removed via unlink(
82
83 Configuring FakeNBD: an Example
84 ===============================
85
86 Imagine there's a Network Block Device (NBD) d
87 access remote block devices. Call it FakeNBD.
88 for its configuration. Obviously, there will
89 sysadmins use to configure FakeNBD, but someho
90 the driver about it. Here's where configfs co
91
92 When the FakeNBD driver is loaded, it register
93 readdir(3) sees this just fine::
94
95 # ls /config
96 fakenbd
97
98 A fakenbd connection can be created with mkdir
99 arbitrary, but likely the tool will make some
100 it is a uuid or a disk name::
101
102 # mkdir /config/fakenbd/disk1
103 # ls /config/fakenbd/disk1
104 target device rw
105
106 The target attribute contains the IP address o
107 connect to. The device attribute is the devic
108 Predictably, the rw attribute determines wheth
109 read-only or read-write::
110
111 # echo 10.0.0.1 > /config/fakenbd/disk
112 # echo /dev/sda1 > /config/fakenbd/dis
113 # echo 1 > /config/fakenbd/disk1/rw
114
115 That's it. That's all there is. Now the devi
116 shell no less.
117
118 Coding With configfs
119 ====================
120
121 Every object in configfs is a config_item. A
122 object in the subsystem. It has attributes th
123 object. configfs handles the filesystem repre
124 and its attributes, allowing the subsystem to
125 basic show/store interaction.
126
127 Items are created and destroyed inside a confi
128 collection of items that share the same attrib
129 Items are created by mkdir(2) and removed by r
130 handles that. The group has a set of operatio
131
132 A subsystem is the top level of a client modul
133 the client module registers the subsystem with
134 appears as a directory at the top of the confi
135 subsystem is also a config_group, and can do e
136 can.
137
138 struct config_item
139 ==================
140
141 ::
142
143 struct config_item {
144 char *ci_na
145 char ci_nam
146 struct kref ci_kre
147 struct list_head ci_ent
148 struct config_item *ci_pa
149 struct config_group *ci_gr
150 struct config_item_type *ci_ty
151 struct dentry *ci_de
152 };
153
154 void config_item_init(struct config_it
155 void config_item_init_type_name(struct
156 const
157 struct
158 struct config_item *config_item_get(st
159 void config_item_put(struct config_ite
160
161 Generally, struct config_item is embedded in a
162 structure that actually represents what the su
163 config_item portion of that structure is how t
164 configfs.
165
166 Whether statically defined in a source file or
167 config_group, a config_item must have one of t
168 called on it. This initializes the reference
169 appropriate fields.
170
171 All users of a config_item should have a refer
172 config_item_get(), and drop the reference when
173 config_item_put().
174
175 By itself, a config_item cannot do much more t
176 Usually a subsystem wants the item to display
177 among other things. For that, it needs a type
178
179 struct config_item_type
180 =======================
181
182 ::
183
184 struct configfs_item_operations {
185 void (*release)(struct config_
186 int (*allow_link)(struct confi
187 struct confi
188 void (*drop_link)(struct confi
189 struct config
190 };
191
192 struct config_item_type {
193 struct module
194 struct configfs_item_operation
195 struct configfs_group_operatio
196 struct configfs_attribute
197 struct configfs_bin_attribute
198 };
199
200 The most basic function of a config_item_type
201 operations can be performed on a config_item.
202 allocated dynamically will need to provide the
203 method. This method is called when the config
204 reaches zero.
205
206 struct configfs_attribute
207 =========================
208
209 ::
210
211 struct configfs_attribute {
212 char *ca_na
213 struct module *ca_ow
214 umode_t ca_mo
215 ssize_t (*show)(struct config_
216 ssize_t (*store)(struct config
217 };
218
219 When a config_item wants an attribute to appea
220 configfs directory, it must define a configfs_
221 It then adds the attribute to the NULL-termina
222 config_item_type->ct_attrs. When the item app
223 attribute file will appear with the configfs_a
224 filename. configfs_attribute->ca_mode specifi
225
226 If an attribute is readable and provides a ->s
227 be called whenever userspace asks for a read(2
228 attribute is writable and provides a ->store
229 called whenever userspace asks for a write(2)
230
231 struct configfs_bin_attribute
232 =============================
233
234 ::
235
236 struct configfs_bin_attribute {
237 struct configfs_attribute
238 void
239 size_t
240 };
241
242 The binary attribute is used when the one need
243 appear as the contents of a file in the item's
244 To do so add the binary attribute to the NULL-
245 config_item_type->ct_bin_attrs, and the item a
246 attribute file will appear with the configfs_b
247 filename. configfs_bin_attribute->cb_attr.ca_
248 permissions.
249 The cb_private member is provided for use by t
250 cb_max_size member specifies the maximum amoun
251 to be used.
252
253 If binary attribute is readable and the config
254 ct_item_ops->read_bin_attribute() method, that
255 whenever userspace asks for a read(2) on the a
256 will happen for write(2). The reads/writes are
257 single read/write will occur; the attributes'
258 with it.
259
260 struct config_group
261 ===================
262
263 A config_item cannot live in a vacuum. The on
264 is via mkdir(2) on a config_group. This will
265 child item::
266
267 struct config_group {
268 struct config_item
269 struct list_head
270 struct configfs_subsystem
271 struct list_head
272 struct list_head
273 };
274
275 void config_group_init(struct config_g
276 void config_group_init_type_name(struc
277 const
278 struc
279
280
281 The config_group structure contains a config_i
282 that item means that a group can behave as an
283 However, it can do more: it can create child i
284 accomplished via the group operations specifie
285 config_item_type::
286
287 struct configfs_group_operations {
288 struct config_item *(*make_ite
289
290 struct config_group *(*make_gr
291
292 void (*disconnect_notify)(stru
293 stru
294 void (*drop_item)(struct confi
295 struct confi
296 };
297
298 A group creates child items by providing the
299 ct_group_ops->make_item() method. If provided
300 mkdir(2) in the group's directory. The subsys
301 config_item (or more likely, its container str
302 and returns it to configfs. Configfs will the
303 tree to reflect the new item.
304
305 If the subsystem wants the child to be a group
306 provides ct_group_ops->make_group(). Everythi
307 using the group _init() functions on the group
308
309 Finally, when userspace calls rmdir(2) on the
310 ct_group_ops->drop_item() is called. As a con
311 config_item, it is not necessary for a separat
312 The subsystem must config_item_put() the refer
313 upon item allocation. If a subsystem has no w
314 the ct_group_ops->drop_item() method, and conf
315 config_item_put() on the item on behalf of the
316
317 Important:
318 drop_item() is void, and as such cannot fai
319 is called, configfs WILL remove the item fr
320 (assuming that it has no children to keep i
321 responsible for responding to this. If the
322 the item in other threads, the memory is sa
323 for the item to actually disappear from the
324 is gone from configfs.
325
326 When drop_item() is called, the item's linkage
327 down. It no longer has a reference on its par
328 the item hierarchy. If a client needs to do s
329 teardown happens, the subsystem can implement
330 ct_group_ops->disconnect_notify() method. The
331 configfs has removed the item from the filesys
332 item is removed from its parent group. Like d
333 disconnect_notify() is void and cannot fail.
334 not drop any references here, as they still mu
335
336 A config_group cannot be removed while it stil
337 is implemented in the configfs rmdir(2) code.
338 called, as the item has not been dropped. rmd
339 directory is not empty.
340
341 struct configfs_subsystem
342 =========================
343
344 A subsystem must register itself, usually at m
345 tells configfs to make the subsystem appear in
346
347 struct configfs_subsystem {
348 struct config_group su_gro
349 struct mutex su_mut
350 };
351
352 int configfs_register_subsystem(struct
353 void configfs_unregister_subsystem(str
354
355 A subsystem consists of a toplevel config_grou
356 The group is where child config_items are crea
357 this group is usually defined statically. Bef
358 configfs_register_subsystem(), the subsystem m
359 group via the usual group _init() functions, a
360 initialized the mutex.
361
362 When the register call returns, the subsystem
363 will be visible via configfs. At that point,
364 the subsystem must be ready for it.
365
366 An Example
367 ==========
368
369 The best example of these basic concepts is th
370 subsystem/group and the simple_child item in
371 samples/configfs/configfs_sample.c. It shows a
372 and storing an attribute, and a simple group c
373 these children.
374
375 Hierarchy Navigation and the Subsystem Mutex
376 ============================================
377
378 There is an extra bonus that configfs provides
379 config_items are arranged in a hierarchy due t
380 appear in a filesystem. A subsystem is NEVER
381 parts, but the subsystem might be interested i
382 this reason, the hierarchy is mirrored via the
383 and config_item->ci_parent structure members.
384
385 A subsystem can navigate the cg_children list
386 to see the tree created by the subsystem. Thi
387 management of the hierarchy, so configfs uses
388 protect modifications. Whenever a subsystem w
389 hierarchy, it must do so under the protection
390 mutex.
391
392 A subsystem will be prevented from acquiring t
393 allocated item has not been linked into this h
394 will not be able to acquire the mutex while a
395 yet been unlinked. This means that an item's
396 never be NULL while the item is in configfs, a
397 be in its parent's cg_children list for the sa
398 a subsystem to trust ci_parent and cg_children
399 mutex.
400
401 Item Aggregation Via symlink(2)
402 ===============================
403
404 configfs provides a simple group via the group
405 relationship. Often, however, a larger enviro
406 outside of the parent/child connection. This
407 symlink(2).
408
409 A config_item may provide the ct_item_ops->all
410 ct_item_ops->drop_link() methods. If the ->al
411 symlink(2) may be called with the config_item
412 These links are only allowed between configfs
413 symlink(2) attempt outside the configfs filesy
414
415 When symlink(2) is called, the source config_i
416 method is called with itself and a target item
417 allows linking to target item, it returns 0.
418 reject a link if it only wants links to a cert
419 in its own subsystem).
420
421 When unlink(2) is called on the symbolic link,
422 notified via the ->drop_link() method. Like t
423 this is a void function and cannot return fail
424 responsible for responding to the change.
425
426 A config_item cannot be removed while it links
427 can it be removed while an item links to it.
428 allowed in configfs.
429
430 Automatically Created Subgroups
431 ===============================
432
433 A new config_group may want to have two types
434 While this could be codified by magic names in
435 more explicit to have a method whereby userspa
436
437 Rather than have a group where some items beha
438 others, configfs provides a method whereby one
439 automatically created inside the parent at its
440 mkdir("parent") results in "parent", "parent/s
441 "parent/subgroupN". Items of type 1 can now b
442 "parent/subgroup1", and items of type N can be
443 "parent/subgroupN".
444
445 These automatic subgroups, or default groups,
446 children of the parent group. If ct_group_ops
447 other child groups can be created on the paren
448
449 A configfs subsystem specifies default groups
450 configfs_add_default_group() function to the p
451 structure. Each added group is populated in t
452 time as the parent group. Similarly, they are
453 as the parent. No extra notification is provi
454 method call notifies the subsystem the parent
455 also means every default group child associate
456
457 As a consequence of this, default groups canno
458 rmdir(2). They also are not considered when r
459 group is checking for children.
460
461 Dependent Subsystems
462 ====================
463
464 Sometimes other drivers depend on particular c
465 example, ocfs2 mounts depend on a heartbeat re
466 region item is removed with rmdir(2), the ocfs
467 readonly. Not happy.
468
469 configfs provides two additional API calls: co
470 configfs_undepend_item(). A client driver can
471 configfs_depend_item() on an existing item to
472 depended on. configfs will then return -EBUSY
473 item. When the item is no longer depended on,
474 configfs_undepend_item() on it.
475
476 These API cannot be called underneath any conf
477 they will conflict. They can block and alloca
478 probably shouldn't calling them of its own gum
479 be providing an API that external subsystems c
480
481 How does this work? Imagine the ocfs2 mount p
482 it asks for a heartbeat region item. This is
483 heartbeat code. Inside the heartbeat code, th
484 up. Here, the heartbeat code calls configfs_d
485 succeeds, then heartbeat knows the region is s
486 If it fails, it was being torn down anyway, an
487 pass up an error.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.