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