Configfs - Userspace-driven Kernel Object Configuration

Configfs와 sysfs의 수명 모델

Configfs는 Joel Becker가 작성하고 2005년 3월 31일 갱신한 userspace-driven kernel object configuration 문서입니다. configfs는 RAM 기반 filesystem이며 sysfs 기능의 반대 방향을 제공합니다.

sysfs가 kernel object를 filesystem으로 보여주는 view라면 configfs는 `config_item`이라는 kernel object를 filesystem operation으로 관리하는 manager입니다.

sysfs에서는 device 발견 같은 kernel event가 object를 만들고 sysfs에 등록합니다. attributes가 나타나 userspace가 `readdir(3)`·`read(2)`로 보고 일부를 `write(2)`로 수정할 수 있지만, object 생성·파괴와 sysfs representation의 lifecycle은 kernel이 통제합니다. sysfs는 그 상태를 보는 창입니다.

configfs에서는 userspace의 명시적인 `mkdir(2)`가 `config_item`을 만들고 `rmdir(2)`가 파괴합니다. 생성 시 attributes가 나타나고 `read(2)`·`write(2)`로 읽고 수정합니다. `readdir(3)`는 item과 attribute 목록을 보고 `symlink(2)`는 item을 묶습니다. representation 수명이 userspace에 의해 완전히 결정되므로 이를 뒷받침하는 kernel module이 각 operation에 응답해야 합니다.

sysfs와 configfs는 같은 system에서 함께 존재해야 하며 서로를 대체하지 않습니다.

=======================================================
Configfs - Userspace-driven Kernel Object Configuration
=======================================================

Joel Becker <[email protected]>

Updated: 31 March 2005

Copyright (c) 2005 Oracle Corporation,
        Joel Becker <[email protected]>


What is configfs?
=================

configfs is a ram-based filesystem that provides the converse of
sysfs's functionality.  Where sysfs is a filesystem-based view of
kernel objects, configfs is a filesystem-based manager of kernel
objects, or config_items.

With sysfs, an object is created in kernel (for example, when a device
is discovered) and it is registered with sysfs.  Its attributes then
appear in sysfs, allowing userspace to read the attributes via
readdir(3)/read(2).  It may allow some attributes to be modified via
write(2).  The important point is that the object is created and
destroyed in kernel, the kernel controls the lifecycle of the sysfs
representation, and sysfs is merely a window on all this.

A configfs config_item is created via an explicit userspace operation:
mkdir(2).  It is destroyed via rmdir(2).  The attributes appear at
mkdir(2) time, and can be read or modified via read(2) and write(2).
As with sysfs, readdir(3) queries the list of items and/or attributes.
symlink(2) can be used to group items together.  Unlike sysfs, the
lifetime of the representation is completely driven by userspace.  The
kernel modules backing the items must respond to this.

Both sysfs and configfs can and should exist together on the same
system.  One is not a replacement for the other.

Mount와 normal·binary attribute

configfs는 module 또는 built-in으로 compile할 수 있으며 `mount -t configfs none /config`로 접근합니다. client module이 subsystem으로 item type을 등록하지 않으면 tree는 비어 있습니다. subsystem을 load하면 `/config` 아래에 하나 이상의 directory로 나타납니다. sysfs와 마찬가지로 실제 tree는 `/config`에 mount했는지와 무관하게 항상 존재합니다.

item은 `mkdir(2)`로 만들며 attributes도 동시에 나타납니다. `readdir(3)`로 attribute 목록을 확인하고 `read(2)`로 default value를 읽고 `write(2)`로 새 값을 저장합니다. attribute file 하나에 여러 attribute를 섞지 않아야 합니다.

normal attribute는 sysfs attribute와 비슷한 작은 ASCII text file입니다. 최대 크기는 한 page인 `PAGE_SIZE`, i386에서는 4096 byte입니다. 가능하면 file 하나에 값 하나만 두고 sysfs와 같은 주의사항을 따릅니다. configfs는 `write(2)`가 전체 buffer를 한 번에 저장한다고 기대하므로 userspace는 먼저 file 전체를 읽고 필요한 부분을 수정한 뒤 전체 buffer를 다시 써야 합니다.

binary attribute는 sysfs binary attribute와 비슷하지만 semantic이 조금 다릅니다. `PAGE_SIZE` 제한은 없으나 binary item 전체가 하나의 kernel `vmalloc` buffer에 들어가야 합니다. userspace의 여러 write는 buffer에 모이고 마지막 `close(2)`에서 `write_bin_attribute` method를 호출합니다. 따라서 userspace는 close return code를 확인해야 실제 operation 성공을 검증할 수 있습니다.

악의적인 user가 kernel을 OOM 상태로 만들지 못하도록 binary attribute마다 maximum buffer size가 있습니다.

item 파괴는 `rmdir(2)`로 합니다. 다른 item이 `symlink(2)`로 이 item을 가리키면 파괴할 수 없고, link는 `unlink(2)`로 먼저 제거합니다.

Using configfs
==============

configfs can be compiled as a module or into the kernel.  You can access
it by doing::

        mount -t configfs none /config

The configfs tree will be empty unless client modules are also loaded.
These are modules that register their item types with configfs as
subsystems.  Once a client subsystem is loaded, it will appear as a
subdirectory (or more than one) under /config.  Like sysfs, the
configfs tree is always there, whether mounted on /config or not.

An item is created via mkdir(2).  The item's attributes will also
appear at this time.  readdir(3) can determine what the attributes are,
read(2) can query their default values, and write(2) can store new
values.  Don't mix more than one attribute in one attribute file.

There are two types of configfs attributes:

* Normal attributes, which similar to sysfs attributes, are small ASCII text
  files, with a maximum size of one page (PAGE_SIZE, 4096 on i386).  Preferably
  only one value per file should be used, and the same caveats from sysfs apply.
  Configfs expects write(2) to store the entire buffer at once.  When writing to
  normal configfs attributes, userspace processes should first read the entire
  file, modify the portions they wish to change, and then write the entire
  buffer back.

* Binary attributes, which are somewhat similar to sysfs binary attributes,
  but with a few slight changes to semantics.  The PAGE_SIZE limitation does not
  apply, but the whole binary item must fit in single kernel vmalloc'ed buffer.
  The write(2) calls from user space are buffered, and the attributes'
  write_bin_attribute method will be invoked on the final close, therefore it is
  imperative for user-space to check the return code of close(2) in order to
  verify that the operation finished successfully.
  To avoid a malicious user OOMing the kernel, there's a per-binary attribute
  maximum buffer value.

When an item needs to be destroyed, remove it with rmdir(2).  An
item cannot be destroyed if any other item has a link to it (via
symlink(2)).  Links can be removed via unlink(2).

FakeNBD 구성 예제

가상의 Network Block Device driver인 FakeNBD가 remote block device 설정에 configfs를 사용한다고 가정합니다. 관리용 program이 있더라도 최종적으로 driver에 configuration을 전달해야 하며 configfs가 그 filesystem interface를 제공합니다.

FakeNBD driver가 load되면 subsystem을 등록해 `ls /config`에 `fakenbd` directory가 나타납니다.

connection은 `mkdir /config/fakenbd/disk1`로 만듭니다. 이름은 임의지만 tool이 UUID나 disk name으로 활용할 수 있습니다. 생성 직후 item directory에는 `target`, `device`, `rw` attributes가 나타납니다.

`target`은 연결할 server IP address, `device`는 server의 device path, `rw`는 read-only 또는 read-write 여부입니다. 예제는 각각 `10.0.0.1`, `/dev/sda1`, `1`을 shell `echo`로 씁니다. 이 세 write만으로 driver object 구성이 끝납니다.

Configuring FakeNBD: an Example
===============================

Imagine there's a Network Block Device (NBD) driver that allows you to
access remote block devices.  Call it FakeNBD.  FakeNBD uses configfs
for its configuration.  Obviously, there will be a nice program that
sysadmins use to configure FakeNBD, but somehow that program has to tell
the driver about it.  Here's where configfs comes in.

When the FakeNBD driver is loaded, it registers itself with configfs.
readdir(3) sees this just fine::

        # ls /config
        fakenbd

A fakenbd connection can be created with mkdir(2).  The name is
arbitrary, but likely the tool will make some use of the name.  Perhaps
it is a uuid or a disk name::

        # mkdir /config/fakenbd/disk1
        # ls /config/fakenbd/disk1
        target device rw

The target attribute contains the IP address of the server FakeNBD will
connect to.  The device attribute is the device on the server.
Predictably, the rw attribute determines whether the connection is
read-only or read-write::

        # echo 10.0.0.1 > /config/fakenbd/disk1/target
        # echo /dev/sda1 > /config/fakenbd/disk1/device
        # echo 1 > /config/fakenbd/disk1/rw

That's it.  That's all there is.  Now the device is configured, via the
shell no less.

config_item과 config_item_type

configfs의 모든 object는 subsystem object를 반영하는 `config_item`입니다. object value와 대응하는 attributes가 있고, configfs가 object·attribute의 filesystem representation을 맡으므로 subsystem은 기본적인 show/store interaction만 처리하면 됩니다.

item은 같은 attributes와 operation을 공유하는 item collection인 `config_group` 안에서 생성·파괴됩니다. userspace는 `mkdir(2)`·`rmdir(2)`를 호출하지만 실제 처리는 configfs가 group operations를 통해 subsystem에 위임합니다. client module의 top level인 subsystem도 `config_group`이므로 group이 할 수 있는 일을 모두 할 수 있습니다.

`struct config_item`에는 이름과 inline name buffer, `kref`, sibling entry, parent pointer, owning group, `config_item_type`, dentry가 있습니다. 보통 subsystem의 실제 object container structure 안에 embed하며, 이 부분이 configfs와 상호작용하는 handle이 됩니다.

source에 static하게 정의했든 parent group이 동적으로 만들었든 모든 item은 `config_item_init()` 또는 `config_item_init_type_name()`으로 초기화해야 합니다. 이 함수가 reference count와 필드를 설정합니다. 모든 사용자는 `config_item_get()`으로 reference를 얻고 끝나면 `config_item_put()`으로 놓아야 합니다.

item만으로는 configfs에 나타나는 것 이상을 할 수 없으므로 attribute 표시·저장과 link 같은 operation을 위해 `config_item_type`이 필요합니다.

`configfs_item_operations`는 reference가 0일 때의 `release`, symlink 허가를 판단하는 `allow_link`, link 제거 통지인 `drop_link`를 정의합니다. `config_item_type`은 module owner, item operations, group operations, normal attribute array와 binary attribute array를 묶습니다.

동적으로 할당한 모든 item type은 `ct_item_ops->release()`를 제공해야 합니다. config_item reference count가 0에 도달하면 이 method가 호출되어 container memory를 해제할 수 있습니다.

Coding With configfs
====================

Every object in configfs is a config_item.  A config_item reflects an
object in the subsystem.  It has attributes that match values on that
object.  configfs handles the filesystem representation of that object
and its attributes, allowing the subsystem to ignore all but the
basic show/store interaction.

Items are created and destroyed inside a config_group.  A group is a
collection of items that share the same attributes and operations.
Items are created by mkdir(2) and removed by rmdir(2), but configfs
handles that.  The group has a set of operations to perform these tasks

A subsystem is the top level of a client module.  During initialization,
the client module registers the subsystem with configfs, the subsystem
appears as a directory at the top of the configfs filesystem.  A
subsystem is also a config_group, and can do everything a config_group
can.

struct config_item
==================

::

        struct config_item {
                char                    *ci_name;
                char                    ci_namebuf[UOBJ_NAME_LEN];
                struct kref             ci_kref;
                struct list_head        ci_entry;
                struct config_item      *ci_parent;
                struct config_group     *ci_group;
                struct config_item_type *ci_type;
                struct dentry           *ci_dentry;
        };

        void config_item_init(struct config_item *);
        void config_item_init_type_name(struct config_item *,
                                        const char *name,
                                        struct config_item_type *type);
        struct config_item *config_item_get(struct config_item *);
        void config_item_put(struct config_item *);

Generally, struct config_item is embedded in a container structure, a
structure that actually represents what the subsystem is doing.  The
config_item portion of that structure is how the object interacts with
configfs.

Whether statically defined in a source file or created by a parent
config_group, a config_item must have one of the _init() functions
called on it.  This initializes the reference count and sets up the
appropriate fields.

All users of a config_item should have a reference on it via
config_item_get(), and drop the reference when they are done via
config_item_put().

By itself, a config_item cannot do much more than appear in configfs.
Usually a subsystem wants the item to display and/or store attributes,
among other things.  For that, it needs a type.

struct config_item_type
=======================

::

        struct configfs_item_operations {
                void (*release)(struct config_item *);
                int (*allow_link)(struct config_item *src,
                                  struct config_item *target);
                void (*drop_link)(struct config_item *src,
                                 struct config_item *target);
        };

        struct config_item_type {
                struct module                           *ct_owner;
                struct configfs_item_operations         *ct_item_ops;
                struct configfs_group_operations        *ct_group_ops;
                struct configfs_attribute               **ct_attrs;
                struct configfs_bin_attribute                **ct_bin_attrs;
        };

The most basic function of a config_item_type is to define what
operations can be performed on a config_item.  All items that have been
allocated dynamically will need to provide the ct_item_ops->release()
method.  This method is called when the config_item's reference count
reaches zero.

Normal·binary attribute 구조체

normal attribute를 item directory의 file로 표시하려면 `struct configfs_attribute`를 정의해 NULL-terminated `config_item_type->ct_attrs` array에 넣습니다. `ca_name`이 filename, `ca_mode`가 permission을 정하고 `ca_owner`는 owning module입니다.

readable attribute가 `show` method를 제공하면 userspace의 `read(2)` 때 호출됩니다. writable attribute가 `store` method를 제공하면 `write(2)` 때 호출됩니다.

binary blob을 file 내용으로 표시하려면 `struct configfs_bin_attribute`를 NULL-terminated `ct_bin_attrs` array에 넣습니다. 내부 `cb_attr.ca_name`과 `cb_attr.ca_mode`가 filename과 permission을 정합니다.

`cb_private`는 driver 전용 pointer이고 `cb_max_size`는 사용할 수 있는 `vmalloc` buffer 최대량입니다. readable binary attribute는 item operation의 `read_bin_attribute()`, writable binary attribute는 대응 write method를 사용합니다. configfs가 여러 user read/write를 buffer해 backend에는 한 번만 전달하므로 attribute 구현이 부분 I/O를 직접 조립할 필요가 없습니다.

struct configfs_attribute
=========================

::

        struct configfs_attribute {
                char                    *ca_name;
                struct module           *ca_owner;
                umode_t                  ca_mode;
                ssize_t (*show)(struct config_item *, char *);
                ssize_t (*store)(struct config_item *, const char *, size_t);
        };

When a config_item wants an attribute to appear as a file in the item's
configfs directory, it must define a configfs_attribute describing it.
It then adds the attribute to the NULL-terminated array
config_item_type->ct_attrs.  When the item appears in configfs, the
attribute file will appear with the configfs_attribute->ca_name
filename.  configfs_attribute->ca_mode specifies the file permissions.

If an attribute is readable and provides a ->show method, that method will
be called whenever userspace asks for a read(2) on the attribute.  If an
attribute is writable and provides a ->store  method, that method will be
called whenever userspace asks for a write(2) on the attribute.

struct configfs_bin_attribute
=============================

::

        struct configfs_bin_attribute {
                struct configfs_attribute        cb_attr;
                void                                *cb_private;
                size_t                                cb_max_size;
        };

The binary attribute is used when the one needs to use binary blob to
appear as the contents of a file in the item's configfs directory.
To do so add the binary attribute to the NULL-terminated array
config_item_type->ct_bin_attrs, and the item appears in configfs, the
attribute file will appear with the configfs_bin_attribute->cb_attr.ca_name
filename.  configfs_bin_attribute->cb_attr.ca_mode specifies the file
permissions.
The cb_private member is provided for use by the driver, while the
cb_max_size member specifies the maximum amount of vmalloc buffer
to be used.

If binary attribute is readable and the config_item provides a
ct_item_ops->read_bin_attribute() method, that method will be called
whenever userspace asks for a read(2) on the attribute.  The converse
will happen for write(2). The reads/writes are buffered so only a
single read/write will occur; the attributes' need not concern itself
with it.

config_group 생성·삭제 계약

config_item은 독립적으로 생성될 수 없고 `config_group` directory에서 `mkdir(2)`를 해야 child item이 생깁니다. `config_group`은 자체 `config_item`, child list, subsystem pointer, default group list와 parent entry를 갖습니다. `config_group_init()` 또는 `config_group_init_type_name()`으로 초기화합니다.

group 안의 embedded item을 올바르게 설정하면 group 자체도 item처럼 동작하면서 child item 또는 child group을 만들 수 있습니다. `configfs_group_operations`는 `make_item`, `make_group`, `disconnect_notify`, `drop_item`을 정의합니다.

group directory의 `mkdir(2)`는 제공된 `ct_group_ops->make_item()`을 호출합니다. subsystem은 새 config_item, 보통 container structure를 할당·초기화해 configfs에 반환하고, configfs는 filesystem tree를 채웁니다. child도 group이어야 한다면 `make_group()`과 group init 함수를 사용하며 나머지 동작은 같습니다.

userspace가 item 또는 group에 `rmdir(2)`를 호출하면 `drop_item()`이 불립니다. config_group도 config_item이므로 별도 `drop_group()`은 필요 없습니다. subsystem은 item allocation 때 생긴 initial reference를 `config_item_put()`으로 놓아야 합니다. 정리할 일이 없으면 `drop_item()`을 생략할 수 있고 configfs가 대신 put합니다.

중요하게도 `drop_item()`은 void라 실패할 수 없습니다. child 때문에 busy하지 않다면 configfs는 rmdir 때 filesystem tree에서 item을 반드시 제거합니다. 다른 thread가 reference를 잡고 있으면 memory는 안전하고 subsystem 내부 사용이 실제로 끝나는 데 시간이 걸릴 수 있지만 configfs view에서는 이미 사라졌습니다.

`drop_item()` 시점에는 parent reference와 hierarchy linkage가 이미 해체되어 있습니다. teardown 전에 cleanup이 필요하면 `disconnect_notify()`를 구현합니다. 이 callback은 filesystem view에서 제거한 뒤 parent group에서 unlink하기 전에 호출되며 void라 실패할 수 없습니다. 여기서는 reference를 놓지 말고 여전히 `drop_item()`에서 놓아야 합니다.

child item이 남은 config_group은 제거할 수 없습니다. configfs의 rmdir code가 directory-not-empty로 실패하며 item을 drop하지 않았으므로 `drop_item()`도 호출하지 않습니다.

struct config_group
===================

A config_item cannot live in a vacuum.  The only way one can be created
is via mkdir(2) on a config_group.  This will trigger creation of a
child item::

        struct config_group {
                struct config_item                cg_item;
                struct list_head                cg_children;
                struct configfs_subsystem         *cg_subsys;
                struct list_head                default_groups;
                struct list_head                group_entry;
        };

        void config_group_init(struct config_group *group);
        void config_group_init_type_name(struct config_group *group,
                                         const char *name,
                                         struct config_item_type *type);


The config_group structure contains a config_item.  Properly configuring
that item means that a group can behave as an item in its own right.
However, it can do more: it can create child items or groups.  This is
accomplished via the group operations specified on the group's
config_item_type::

        struct configfs_group_operations {
                struct config_item *(*make_item)(struct config_group *group,
                                                 const char *name);
                struct config_group *(*make_group)(struct config_group *group,
                                                   const char *name);
                void (*disconnect_notify)(struct config_group *group,
                                          struct config_item *item);
                void (*drop_item)(struct config_group *group,
                                  struct config_item *item);
        };

A group creates child items by providing the
ct_group_ops->make_item() method.  If provided, this method is called from
mkdir(2) in the group's directory.  The subsystem allocates a new
config_item (or more likely, its container structure), initializes it,
and returns it to configfs.  Configfs will then populate the filesystem
tree to reflect the new item.

If the subsystem wants the child to be a group itself, the subsystem
provides ct_group_ops->make_group().  Everything else behaves the same,
using the group _init() functions on the group.

Finally, when userspace calls rmdir(2) on the item or group,
ct_group_ops->drop_item() is called.  As a config_group is also a
config_item, it is not necessary for a separate drop_group() method.
The subsystem must config_item_put() the reference that was initialized
upon item allocation.  If a subsystem has no work to do, it may omit
the ct_group_ops->drop_item() method, and configfs will call
config_item_put() on the item on behalf of the subsystem.

Important:
   drop_item() is void, and as such cannot fail.  When rmdir(2)
   is called, configfs WILL remove the item from the filesystem tree
   (assuming that it has no children to keep it busy).  The subsystem is
   responsible for responding to this.  If the subsystem has references to
   the item in other threads, the memory is safe.  It may take some time
   for the item to actually disappear from the subsystem's usage.  But it
   is gone from configfs.

When drop_item() is called, the item's linkage has already been torn
down.  It no longer has a reference on its parent and has no place in
the item hierarchy.  If a client needs to do some cleanup before this
teardown happens, the subsystem can implement the
ct_group_ops->disconnect_notify() method.  The method is called after
configfs has removed the item from the filesystem view but before the
item is removed from its parent group.  Like drop_item(),
disconnect_notify() is void and cannot fail.  Client subsystems should
not drop any references here, as they still must do it in drop_item().

A config_group cannot be removed while it still has child items.  This
is implemented in the configfs rmdir(2) code.  ->drop_item() will not be
called, as the item has not been dropped.  rmdir(2) will fail, as the
directory is not empty.

Subsystem 등록과 hierarchy mutex

subsystem은 보통 `module_init`에서 `configfs_register_subsystem()`으로 등록하고 종료 시 `configfs_unregister_subsystem()`으로 해제합니다. `struct configfs_subsystem`은 top-level `config_group`과 `mutex`로 구성됩니다.

top-level group에서 child config_item을 만듭니다. 보통 이 group은 static하게 정의하며 register 전에 일반 group init 함수로 초기화하고 mutex도 초기화해야 합니다.

register가 반환하면 subsystem은 live 상태로 configfs에 보이고 userspace가 즉시 `mkdir(2)`를 호출할 수 있으므로 모든 callback과 상태가 준비되어 있어야 합니다.

기본 개념 예제는 `samples/configfs/configfs_sample.c`의 `simple_children` subsystem/group과 `simple_child` item입니다. attribute 하나를 표시·저장하는 object와 group의 child 생성·파괴를 보여줍니다.

configfs는 filesystem에 나타나는 group·item hierarchy를 `config_group->cg_children`과 `config_item->ci_parent`에도 mirror합니다. subsystem은 filesystem 내부 부분을 직접 만져서는 안 되지만 이 두 member로 자신이 만든 tree를 탐색할 수 있습니다.

hierarchy 변경과 탐색이 race할 수 있으므로 모든 navigation은 subsystem mutex 아래에서 수행해야 합니다. 새 item이 hierarchy에 link되기 전이나 dropping item이 unlink되기 전에는 subsystem이 mutex를 획득하지 못합니다.

따라서 mutex를 보유한 동안 configfs 안의 item은 `ci_parent`가 절대 NULL이 아니고 정확히 같은 기간 parent의 `cg_children` list에 존재합니다. subsystem은 lock 아래에서 두 관계를 신뢰할 수 있습니다.

struct configfs_subsystem
=========================

A subsystem must register itself, usually at module_init time.  This
tells configfs to make the subsystem appear in the file tree::

        struct configfs_subsystem {
                struct config_group        su_group;
                struct mutex                su_mutex;
        };

        int configfs_register_subsystem(struct configfs_subsystem *subsys);
        void configfs_unregister_subsystem(struct configfs_subsystem *subsys);

A subsystem consists of a toplevel config_group and a mutex.
The group is where child config_items are created.  For a subsystem,
this group is usually defined statically.  Before calling
configfs_register_subsystem(), the subsystem must have initialized the
group via the usual group _init() functions, and it must also have
initialized the mutex.

When the register call returns, the subsystem is live, and it
will be visible via configfs.  At that point, mkdir(2) can be called and
the subsystem must be ready for it.

An Example
==========

The best example of these basic concepts is the simple_children
subsystem/group and the simple_child item in
samples/configfs/configfs_sample.c. It shows a trivial object displaying
and storing an attribute, and a simple group creating and destroying
these children.

Hierarchy Navigation and the Subsystem Mutex
============================================

There is an extra bonus that configfs provides.  The config_groups and
config_items are arranged in a hierarchy due to the fact that they
appear in a filesystem.  A subsystem is NEVER to touch the filesystem
parts, but the subsystem might be interested in this hierarchy.  For
this reason, the hierarchy is mirrored via the config_group->cg_children
and config_item->ci_parent structure members.

A subsystem can navigate the cg_children list and the ci_parent pointer
to see the tree created by the subsystem.  This can race with configfs'
management of the hierarchy, so configfs uses the subsystem mutex to
protect modifications.  Whenever a subsystem wants to navigate the
hierarchy, it must do so under the protection of the subsystem
mutex.

A subsystem will be prevented from acquiring the mutex while a newly
allocated item has not been linked into this hierarchy.   Similarly, it
will not be able to acquire the mutex while a dropping item has not
yet been unlinked.  This means that an item's ci_parent pointer will
never be NULL while the item is in configfs, and that an item will only
be in its parent's cg_children list for the same duration.  This allows
a subsystem to trust ci_parent and cg_children while they hold the
mutex.

Symlink aggregation, default group과 dependency

parent/child 관계 밖에서 item을 aggregate하려면 configfs의 `symlink(2)`를 사용합니다. source item type이 `allow_link()`와 `drop_link()`를 제공할 수 있습니다. `allow_link()`가 있으면 해당 item을 source로 symlink를 만들 수 있지만 link는 configfs item 사이에서만 허용되고 filesystem 밖의 target은 거부됩니다.

symlink 생성 시 source의 `allow_link(src, target)`이 호출되고 허용하면 0을 반환합니다. source가 자기 subsystem의 특정 object type만 허용하도록 거부할 수도 있습니다. `unlink(2)` 시 `drop_link()`가 통지되며 void라 실패할 수 없습니다.

config_item은 자신이 다른 item을 link 중이거나 다른 item이 자신을 가리키는 동안 제거할 수 없습니다. configfs는 dangling symlink를 허용하지 않습니다.

새 config_group 아래에 여러 종류의 child가 필요하면 `make_item()`에서 magic name을 해석하는 대신 자동 생성 subgroup인 default group을 사용할 수 있습니다. `mkdir("parent")`가 `parent/subgroup1`부터 `subgroupN`까지 함께 만들고 각 subgroup에서 서로 다른 type의 item을 생성하게 합니다.

default group이 있어도 parent의 다른 child를 막지 않으며 `make_group()`이 있으면 직접 child group도 만들 수 있습니다. `configfs_add_default_group()`으로 parent에 추가하면 parent와 동시에 tree에 나타나고 동시에 제거됩니다. 별도 notification은 없으며 parent의 `drop_item()`은 모든 default child도 사라진다는 뜻입니다.

default group은 `rmdir(2)`로 직접 제거할 수 없고 parent rmdir이 child 존재를 검사할 때도 busy child로 세지 않습니다.

다른 driver가 특정 configfs item에 의존할 수 있습니다. 예를 들어 ocfs2 mount는 heartbeat region item에 의존하므로 사용 중 rmdir되면 BUG 또는 read-only 전환이 필요해집니다. `configfs_depend_item()`이 dependency를 등록하면 해당 item의 `rmdir(2)`은 `-EBUSY`를 반환하고, 더 이상 필요 없을 때 `configfs_undepend_item()`으로 해제합니다.

두 dependency API는 configfs callback 안에서 호출하면 충돌하므로 사용할 수 없습니다. block하거나 memory를 allocate할 수 있으며 client driver가 임의로 직접 쓰기보다는 external subsystem이 호출할 API를 제공하는 편이 좋습니다.

ocfs2 mount 예에서는 heartbeat code가 region item을 lookup한 뒤 `configfs_depend_item()`을 호출합니다. 성공하면 region을 ocfs2에 안전하게 넘기고, 실패하면 이미 teardown 중이므로 mount 경로에 정상적인 오류를 전달합니다.

Item Aggregation Via symlink(2)
===============================

configfs provides a simple group via the group->item parent/child
relationship.  Often, however, a larger environment requires aggregation
outside of the parent/child connection.  This is implemented via
symlink(2).

A config_item may provide the ct_item_ops->allow_link() and
ct_item_ops->drop_link() methods.  If the ->allow_link() method exists,
symlink(2) may be called with the config_item as the source of the link.
These links are only allowed between configfs config_items.  Any
symlink(2) attempt outside the configfs filesystem will be denied.

When symlink(2) is called, the source config_item's ->allow_link()
method is called with itself and a target item.  If the source item
allows linking to target item, it returns 0.  A source item may wish to
reject a link if it only wants links to a certain type of object (say,
in its own subsystem).

When unlink(2) is called on the symbolic link, the source item is
notified via the ->drop_link() method.  Like the ->drop_item() method,
this is a void function and cannot return failure.  The subsystem is
responsible for responding to the change.

A config_item cannot be removed while it links to any other item, nor
can it be removed while an item links to it.  Dangling symlinks are not
allowed in configfs.

Automatically Created Subgroups
===============================

A new config_group may want to have two types of child config_items.
While this could be codified by magic names in ->make_item(), it is much
more explicit to have a method whereby userspace sees this divergence.

Rather than have a group where some items behave differently than
others, configfs provides a method whereby one or many subgroups are
automatically created inside the parent at its creation.  Thus,
mkdir("parent") results in "parent", "parent/subgroup1", up through
"parent/subgroupN".  Items of type 1 can now be created in
"parent/subgroup1", and items of type N can be created in
"parent/subgroupN".

These automatic subgroups, or default groups, do not preclude other
children of the parent group.  If ct_group_ops->make_group() exists,
other child groups can be created on the parent group directly.

A configfs subsystem specifies default groups by adding them using the
configfs_add_default_group() function to the parent config_group
structure.  Each added group is populated in the configfs tree at the same
time as the parent group.  Similarly, they are removed at the same time
as the parent.  No extra notification is provided.  When a ->drop_item()
method call notifies the subsystem the parent group is going away, it
also means every default group child associated with that parent group.

As a consequence of this, default groups cannot be removed directly via
rmdir(2).  They also are not considered when rmdir(2) on the parent
group is checking for children.

Dependent Subsystems
====================

Sometimes other drivers depend on particular configfs items.  For
example, ocfs2 mounts depend on a heartbeat region item.  If that
region item is removed with rmdir(2), the ocfs2 mount must BUG or go
readonly.  Not happy.

configfs provides two additional API calls: configfs_depend_item() and
configfs_undepend_item().  A client driver can call
configfs_depend_item() on an existing item to tell configfs that it is
depended on.  configfs will then return -EBUSY from rmdir(2) for that
item.  When the item is no longer depended on, the client driver calls
configfs_undepend_item() on it.

These API cannot be called underneath any configfs callbacks, as
they will conflict.  They can block and allocate.  A client driver
probably shouldn't calling them of its own gumption.  Rather it should
be providing an API that external subsystems call.

How does this work?  Imagine the ocfs2 mount process.  When it mounts,
it asks for a heartbeat region item.  This is done via a call into the
heartbeat code.  Inside the heartbeat code, the region item is looked
up.  Here, the heartbeat code calls configfs_depend_item().  If it
succeeds, then heartbeat knows the region is safe to give to ocfs2.
If it fails, it was being torn down anyway, and heartbeat can gracefully
pass up an error.