configfs.txt

ocfs1.2.7 源码

configfs - Userspace-driven kernel object configuation.

Joel Becker <[e-mail]>

Updated: 31 March 2005

Copyright (c) 2005 Oracle Corporation,
	Joel Becker <[e-mail]>


[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.

[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.  Like sysfs, attributes should be ASCII text files, preferably
with only one value per file.  The same efficiency caveats from sysfs
apply.  Don't mix more than one attribute in one attribute file.

Like sysfs, configfs expects write(2) to store the entire buffer at
once.  When writing to configfs attributes, userspace processes should
first read the entire file, modify the portions they wish to change, and
then write the entire buffer back.  Attribute files have a maximum size
of one page (PAGE_SIZE, 4096 on i386).

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).

[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.

[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 *);
		ssize_t (*show_attribute)(struct config_item *,
					  struct configfs_attribute *,
					  char *);
		ssize_t (*store_attribute)(struct config_item *,
					   struct configfs_attribute *,
					   const char *, size_t);
		int (*allow_link)(struct config_item *src,
				  struct config_item *target);
		int (*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;
	};

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.  Items that wish to display an attribute need to provide
the ct_item_ops->show_attribute() method.  Similarly, storing a new
attribute value uses the store_attribute() method.

[struct configfs_attribute]

	struct configfs_attribute {
		char                    *ca_name;
		struct module           *ca_owner;
		mode_t                  ca_mode;
	};

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 the config_item provides a
ct_item_ops->show_attribute() method, that method will be called
whenever userspace asks for a read(2) on the attribute.  The converse
will happen for write(2).

[struct config_group]

A config_item cannot live in a vaccum.  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;