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