linux/Documentation/filesystems/configfs/configfs.txt
<<
>>
Prefs
   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                umode_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
 485