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 (*drop_item)(struct config_group *group, 242 struct config_item *item); 243 }; 244 245A group creates child items by providing the 246ct_group_ops->make_item() method. If provided, this method is called from mkdir(2) in the group's directory. The subsystem allocates a new 247config_item (or more likely, its container structure), initializes it, 248and returns it to configfs. Configfs will then populate the filesystem 249tree to reflect the new item. 250 251If the subsystem wants the child to be a group itself, the subsystem 252provides ct_group_ops->make_group(). Everything else behaves the same, 253using the group _init() functions on the group. 254 255Finally, when userspace calls rmdir(2) on the item or group, 256ct_group_ops->drop_item() is called. As a config_group is also a 257config_item, it is not necessary for a separate drop_group() method. 258The subsystem must config_item_put() the reference that was initialized 259upon item allocation. If a subsystem has no work to do, it may omit 260the ct_group_ops->drop_item() method, and configfs will call 261config_item_put() on the item on behalf of the subsystem. 262 263IMPORTANT: drop_item() is void, and as such cannot fail. When rmdir(2) 264is called, configfs WILL remove the item from the filesystem tree 265(assuming that it has no children to keep it busy). The subsystem is 266responsible for responding to this. If the subsystem has references to 267the item in other threads, the memory is safe. It may take some time 268for the item to actually disappear from the subsystem's usage. But it 269is gone from configfs. 270 271A config_group cannot be removed while it still has child items. This 272is implemented in the configfs rmdir(2) code. ->drop_item() will not be 273called, as the item has not been dropped. rmdir(2) will fail, as the 274directory is not empty. 275 276[struct configfs_subsystem] 277 278A subsystem must register itself, usually at module_init time. This 279tells configfs to make the subsystem appear in the file tree. 280 281 struct configfs_subsystem { 282 struct config_group su_group; 283 struct semaphore su_sem; 284 }; 285 286 int configfs_register_subsystem(struct configfs_subsystem *subsys); 287 void configfs_unregister_subsystem(struct configfs_subsystem *subsys); 288 289 A subsystem consists of a toplevel config_group and a semaphore. 290The group is where child config_items are created. For a subsystem, 291this group is usually defined statically. Before calling 292configfs_register_subsystem(), the subsystem must have initialized the 293group via the usual group _init() functions, and it must also have 294initialized the semaphore. 295 When the register call returns, the subsystem is live, and it 296will be visible via configfs. At that point, mkdir(2) can be called and 297the subsystem must be ready for it. 298 299[An Example] 300 301The best example of these basic concepts is the simple_children 302subsystem/group and the simple_child item in configfs_example.c It 303shows a trivial object displaying and storing an attribute, and a simple 304group creating and destroying these children. 305 306[Hierarchy Navigation and the Subsystem Semaphore] 307 308There is an extra bonus that configfs provides. The config_groups and 309config_items are arranged in a hierarchy due to the fact that they 310appear in a filesystem. A subsystem is NEVER to touch the filesystem 311parts, but the subsystem might be interested in this hierarchy. For 312this reason, the hierarchy is mirrored via the config_group->cg_children 313and config_item->ci_parent structure members. 314 315A subsystem can navigate the cg_children list and the ci_parent pointer 316to see the tree created by the subsystem. This can race with configfs' 317management of the hierarchy, so configfs uses the subsystem semaphore to 318protect modifications. Whenever a subsystem wants to navigate the 319hierarchy, it must do so under the protection of the subsystem 320semaphore. 321 322A subsystem will be prevented from acquiring the semaphore while a newly 323allocated item has not been linked into this hierarchy. Similarly, it 324will not be able to acquire the semaphore while a dropping item has not 325yet been unlinked. This means that an item's ci_parent pointer will 326never be NULL while the item is in configfs, and that an item will only 327be in its parent's cg_children list for the same duration. This allows 328a subsystem to trust ci_parent and cg_children while they hold the 329semaphore. 330 331[Item Aggregation Via symlink(2)] 332 333configfs provides a simple group via the group->item parent/child 334relationship. Often, however, a larger environment requires aggregation 335outside of the parent/child connection. This is implemented via 336symlink(2). 337 338A config_item may provide the ct_item_ops->allow_link() and 339ct_item_ops->drop_link() methods. If the ->allow_link() method exists, 340symlink(2) may be called with the config_item as the source of the link. 341These links are only allowed between configfs config_items. Any 342symlink(2) attempt outside the configfs filesystem will be denied. 343 344When symlink(2) is called, the source config_item's ->allow_link() 345method is called with itself and a target item. If the source item 346allows linking to target item, it returns 0. A source item may wish to 347reject a link if it only wants links to a certain type of object (say, 348in its own subsystem). 349 350When unlink(2) is called on the symbolic link, the source item is 351notified via the ->drop_link() method. Like the ->drop_item() method, 352this is a void function and cannot return failure. The subsystem is 353responsible for responding to the change. 354 355A config_item cannot be removed while it links to any other item, nor 356can it be removed while an item links to it. Dangling symlinks are not 357allowed in configfs. 358 359[Automatically Created Subgroups] 360 361A new config_group may want to have two types of child config_items. 362While this could be codified by magic names in ->make_item(), it is much 363more explicit to have a method whereby userspace sees this divergence. 364 365Rather than have a group where some items behave differently than 366others, configfs provides a method whereby one or many subgroups are 367automatically created inside the parent at its creation. Thus, 368mkdir("parent) results in "parent", "parent/subgroup1", up through 369"parent/subgroupN". Items of type 1 can now be created in 370"parent/subgroup1", and items of type N can be created in 371"parent/subgroupN". 372 373These automatic subgroups, or default groups, do not preclude other 374children of the parent group. If ct_group_ops->make_group() exists, 375other child groups can be created on the parent group directly. 376 377A configfs subsystem specifies default groups by filling in the 378NULL-terminated array default_groups on the config_group structure. 379Each group in that array is populated in the configfs tree at the same 380time as the parent group. Similarly, they are removed at the same time 381as the parent. No extra notification is provided. When a ->drop_item() 382method call notifies the subsystem the parent group is going away, it 383also means every default group child associated with that parent group. 384 385As a consequence of this, default_groups cannot be removed directly via 386rmdir(2). They also are not considered when rmdir(2) on the parent 387group is checking for children. 388 389[Committable Items] 390 391NOTE: Committable items are currently unimplemented. 392 393Some config_items cannot have a valid initial state. That is, no 394default values can be specified for the item's attributes such that the 395item can do its work. Userspace must configure one or more attributes, 396after which the subsystem can start whatever entity this item 397represents. 398 399Consider the FakeNBD device from above. Without a target address *and* 400a target device, the subsystem has no idea what block device to import. 401The simple example assumes that the subsystem merely waits until all the 402appropriate attributes are configured, and then connects. This will, 403indeed, work, but now every attribute store must check if the attributes 404are initialized. Every attribute store must fire off the connection if 405that condition is met. 406 407Far better would be an explicit action notifying the subsystem that the 408config_item is ready to go. More importantly, an explicit action allows 409the subsystem to provide feedback as to whether the attributes are 410initialized in a way that makes sense. configfs provides this as 411committable items. 412 413configfs still uses only normal filesystem operations. An item is 414committed via rename(2). The item is moved from a directory where it 415can be modified to a directory where it cannot. 416 417Any group that provides the ct_group_ops->commit_item() method has 418committable items. When this group appears in configfs, mkdir(2) will 419not work directly in the group. Instead, the group will have two 420subdirectories: "live" and "pending". The "live" directory does not 421support mkdir(2) or rmdir(2) either. It only allows rename(2). The 422"pending" directory does allow mkdir(2) and rmdir(2). An item is 423created in the "pending" directory. Its attributes can be modified at 424will. Userspace commits the item by renaming it into the "live" 425directory. At this point, the subsystem receives the ->commit_item() 426callback. If all required attributes are filled to satisfaction, the 427method returns zero and the item is moved to the "live" directory. 428 429As rmdir(2) does not work in the "live" directory, an item must be 430shutdown, or "uncommitted". Again, this is done via rename(2), this 431time from the "live" directory back to the "pending" one. The subsystem 432is notified by the ct_group_ops->uncommit_object() method. 433