About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / configfs / configfs.txt




Custom Search

Based on kernel version 4.8. Page generated on 2016-10-06 23:15 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.