About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kobject.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:03 EST.

1	Everything you never wanted to know about kobjects, ksets, and ktypes
2	
3	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
4	
5	Based on an original article by Jon Corbet for lwn.net written October 1,
6	2003 and located at http://lwn.net/Articles/51437/
7	
8	Last updated December 19, 2007
9	
10	
11	Part of the difficulty in understanding the driver model - and the kobject
12	abstraction upon which it is built - is that there is no obvious starting
13	place. Dealing with kobjects requires understanding a few different types,
14	all of which make reference to each other. In an attempt to make things
15	easier, we'll take a multi-pass approach, starting with vague terms and
16	adding detail as we go. To that end, here are some quick definitions of
17	some terms we will be working with.
18	
19	 - A kobject is an object of type struct kobject.  Kobjects have a name
20	   and a reference count.  A kobject also has a parent pointer (allowing
21	   objects to be arranged into hierarchies), a specific type, and,
22	   usually, a representation in the sysfs virtual filesystem.
23	
24	   Kobjects are generally not interesting on their own; instead, they are
25	   usually embedded within some other structure which contains the stuff
26	   the code is really interested in.
27	
28	   No structure should EVER have more than one kobject embedded within it.
29	   If it does, the reference counting for the object is sure to be messed
30	   up and incorrect, and your code will be buggy.  So do not do this.
31	
32	 - A ktype is the type of object that embeds a kobject.  Every structure
33	   that embeds a kobject needs a corresponding ktype.  The ktype controls
34	   what happens to the kobject when it is created and destroyed.
35	
36	 - A kset is a group of kobjects.  These kobjects can be of the same ktype
37	   or belong to different ktypes.  The kset is the basic container type for
38	   collections of kobjects. Ksets contain their own kobjects, but you can
39	   safely ignore that implementation detail as the kset core code handles
40	   this kobject automatically.
41	
42	   When you see a sysfs directory full of other directories, generally each
43	   of those directories corresponds to a kobject in the same kset.
44	
45	We'll look at how to create and manipulate all of these types. A bottom-up
46	approach will be taken, so we'll go back to kobjects.
47	
48	
49	Embedding kobjects
50	
51	It is rare for kernel code to create a standalone kobject, with one major
52	exception explained below.  Instead, kobjects are used to control access to
53	a larger, domain-specific object.  To this end, kobjects will be found
54	embedded in other structures.  If you are used to thinking of things in
55	object-oriented terms, kobjects can be seen as a top-level, abstract class
56	from which other classes are derived.  A kobject implements a set of
57	capabilities which are not particularly useful by themselves, but which are
58	nice to have in other objects.  The C language does not allow for the
59	direct expression of inheritance, so other techniques - such as structure
60	embedding - must be used.
61	
62	(As an aside, for those familiar with the kernel linked list implementation,
63	this is analogous as to how "list_head" structs are rarely useful on
64	their own, but are invariably found embedded in the larger objects of
65	interest.)
66	
67	So, for example, the UIO code in drivers/uio/uio.c has a structure that
68	defines the memory region associated with a uio device:
69	
70	    struct uio_map {
71		struct kobject kobj;
72		struct uio_mem *mem;
73	    };
74	
75	If you have a struct uio_map structure, finding its embedded kobject is
76	just a matter of using the kobj member.  Code that works with kobjects will
77	often have the opposite problem, however: given a struct kobject pointer,
78	what is the pointer to the containing structure?  You must avoid tricks
79	(such as assuming that the kobject is at the beginning of the structure)
80	and, instead, use the container_of() macro, found in <linux/kernel.h>:
81	
82	    container_of(pointer, type, member)
83	
84	where:
85	
86	  * "pointer" is the pointer to the embedded kobject,
87	  * "type" is the type of the containing structure, and
88	  * "member" is the name of the structure field to which "pointer" points.
89	
90	The return value from container_of() is a pointer to the corresponding
91	container type. So, for example, a pointer "kp" to a struct kobject
92	embedded *within* a struct uio_map could be converted to a pointer to the
93	*containing* uio_map structure with:
94	
95	    struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
96	
97	For convenience, programmers often define a simple macro for "back-casting"
98	kobject pointers to the containing type.  Exactly this happens in the
99	earlier drivers/uio/uio.c, as you can see here:
100	
101	    struct uio_map {
102	        struct kobject kobj;
103	        struct uio_mem *mem;
104	    };
105	
106	    #define to_map(map) container_of(map, struct uio_map, kobj)
107	
108	where the macro argument "map" is a pointer to the struct kobject in
109	question.  That macro is subsequently invoked with:
110	
111	    struct uio_map *map = to_map(kobj);
112	
113	
114	Initialization of kobjects
115	
116	Code which creates a kobject must, of course, initialize that object. Some
117	of the internal fields are setup with a (mandatory) call to kobject_init():
118	
119	    void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
120	
121	The ktype is required for a kobject to be created properly, as every kobject
122	must have an associated kobj_type.  After calling kobject_init(), to
123	register the kobject with sysfs, the function kobject_add() must be called:
124	
125	    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);
126	
127	This sets up the parent of the kobject and the name for the kobject
128	properly.  If the kobject is to be associated with a specific kset,
129	kobj->kset must be assigned before calling kobject_add().  If a kset is
130	associated with a kobject, then the parent for the kobject can be set to
131	NULL in the call to kobject_add() and then the kobject's parent will be the
132	kset itself.
133	
134	As the name of the kobject is set when it is added to the kernel, the name
135	of the kobject should never be manipulated directly.  If you must change
136	the name of the kobject, call kobject_rename():
137	
138	    int kobject_rename(struct kobject *kobj, const char *new_name);
139	
140	kobject_rename does not perform any locking or have a solid notion of
141	what names are valid so the caller must provide their own sanity checking
142	and serialization.
143	
144	There is a function called kobject_set_name() but that is legacy cruft and
145	is being removed.  If your code needs to call this function, it is
146	incorrect and needs to be fixed.
147	
148	To properly access the name of the kobject, use the function
149	kobject_name():
150	
151	    const char *kobject_name(const struct kobject * kobj);
152	
153	There is a helper function to both initialize and add the kobject to the
154	kernel at the same time, called surprisingly enough kobject_init_and_add():
155	
156	    int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
157	                             struct kobject *parent, const char *fmt, ...);
158	
159	The arguments are the same as the individual kobject_init() and
160	kobject_add() functions described above.
161	
162	
163	Uevents
164	
165	After a kobject has been registered with the kobject core, you need to
166	announce to the world that it has been created.  This can be done with a
167	call to kobject_uevent():
168	
169	    int kobject_uevent(struct kobject *kobj, enum kobject_action action);
170	
171	Use the KOBJ_ADD action for when the kobject is first added to the kernel.
172	This should be done only after any attributes or children of the kobject
173	have been initialized properly, as userspace will instantly start to look
174	for them when this call happens.
175	
176	When the kobject is removed from the kernel (details on how to do that is
177	below), the uevent for KOBJ_REMOVE will be automatically created by the
178	kobject core, so the caller does not have to worry about doing that by
179	hand.
180	
181	
182	Reference counts
183	
184	One of the key functions of a kobject is to serve as a reference counter
185	for the object in which it is embedded. As long as references to the object
186	exist, the object (and the code which supports it) must continue to exist.
187	The low-level functions for manipulating a kobject's reference counts are:
188	
189	    struct kobject *kobject_get(struct kobject *kobj);
190	    void kobject_put(struct kobject *kobj);
191	
192	A successful call to kobject_get() will increment the kobject's reference
193	counter and return the pointer to the kobject.
194	
195	When a reference is released, the call to kobject_put() will decrement the
196	reference count and, possibly, free the object. Note that kobject_init()
197	sets the reference count to one, so the code which sets up the kobject will
198	need to do a kobject_put() eventually to release that reference.
199	
200	Because kobjects are dynamic, they must not be declared statically or on
201	the stack, but instead, always allocated dynamically.  Future versions of
202	the kernel will contain a run-time check for kobjects that are created
203	statically and will warn the developer of this improper usage.
204	
205	If all that you want to use a kobject for is to provide a reference counter
206	for your structure, please use the struct kref instead; a kobject would be
207	overkill.  For more information on how to use struct kref, please see the
208	file Documentation/kref.txt in the Linux kernel source tree.
209	
210	
211	Creating "simple" kobjects
212	
213	Sometimes all that a developer wants is a way to create a simple directory
214	in the sysfs hierarchy, and not have to mess with the whole complication of
215	ksets, show and store functions, and other details.  This is the one
216	exception where a single kobject should be created.  To create such an
217	entry, use the function:
218	
219	    struct kobject *kobject_create_and_add(char *name, struct kobject *parent);
220	
221	This function will create a kobject and place it in sysfs in the location
222	underneath the specified parent kobject.  To create simple attributes
223	associated with this kobject, use:
224	
225	    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
226	or
227	    int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);
228	
229	Both types of attributes used here, with a kobject that has been created
230	with the kobject_create_and_add(), can be of type kobj_attribute, so no
231	special custom attribute is needed to be created.
232	
233	See the example module, samples/kobject/kobject-example.c for an
234	implementation of a simple kobject and attributes.
235	
236	
237	
238	ktypes and release methods
239	
240	One important thing still missing from the discussion is what happens to a
241	kobject when its reference count reaches zero. The code which created the
242	kobject generally does not know when that will happen; if it did, there
243	would be little point in using a kobject in the first place. Even
244	predictable object lifecycles become more complicated when sysfs is brought
245	in as other portions of the kernel can get a reference on any kobject that
246	is registered in the system.
247	
248	The end result is that a structure protected by a kobject cannot be freed
249	before its reference count goes to zero. The reference count is not under
250	the direct control of the code which created the kobject. So that code must
251	be notified asynchronously whenever the last reference to one of its
252	kobjects goes away.
253	
254	Once you registered your kobject via kobject_add(), you must never use
255	kfree() to free it directly. The only safe way is to use kobject_put(). It
256	is good practice to always use kobject_put() after kobject_init() to avoid
257	errors creeping in.
258	
259	This notification is done through a kobject's release() method. Usually
260	such a method has a form like:
261	
262	    void my_object_release(struct kobject *kobj)
263	    {
264	    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);
265	
266		    /* Perform any additional cleanup on this object, then... */
267		    kfree(mine);
268	    }
269	
270	One important point cannot be overstated: every kobject must have a
271	release() method, and the kobject must persist (in a consistent state)
272	until that method is called. If these constraints are not met, the code is
273	flawed.  Note that the kernel will warn you if you forget to provide a
274	release() method.  Do not try to get rid of this warning by providing an
275	"empty" release function; you will be mocked mercilessly by the kobject
276	maintainer if you attempt this.
277	
278	Note, the name of the kobject is available in the release function, but it
279	must NOT be changed within this callback.  Otherwise there will be a memory
280	leak in the kobject core, which makes people unhappy.
281	
282	Interestingly, the release() method is not stored in the kobject itself;
283	instead, it is associated with the ktype. So let us introduce struct
284	kobj_type:
285	
286	    struct kobj_type {
287		    void (*release)(struct kobject *kobj);
288		    const struct sysfs_ops *sysfs_ops;
289		    struct attribute **default_attrs;
290		    const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
291		    const void *(*namespace)(struct kobject *kobj);
292	    };
293	
294	This structure is used to describe a particular type of kobject (or, more
295	correctly, of containing object). Every kobject needs to have an associated
296	kobj_type structure; a pointer to that structure must be specified when you
297	call kobject_init() or kobject_init_and_add().
298	
299	The release field in struct kobj_type is, of course, a pointer to the
300	release() method for this type of kobject. The other two fields (sysfs_ops
301	and default_attrs) control how objects of this type are represented in
302	sysfs; they are beyond the scope of this document.
303	
304	The default_attrs pointer is a list of default attributes that will be
305	automatically created for any kobject that is registered with this ktype.
306	
307	
308	ksets
309	
310	A kset is merely a collection of kobjects that want to be associated with
311	each other.  There is no restriction that they be of the same ktype, but be
312	very careful if they are not.
313	
314	A kset serves these functions:
315	
316	 - It serves as a bag containing a group of objects. A kset can be used by
317	   the kernel to track "all block devices" or "all PCI device drivers."
318	
319	 - A kset is also a subdirectory in sysfs, where the associated kobjects
320	   with the kset can show up.  Every kset contains a kobject which can be
321	   set up to be the parent of other kobjects; the top-level directories of
322	   the sysfs hierarchy are constructed in this way.
323	
324	 - Ksets can support the "hotplugging" of kobjects and influence how
325	   uevent events are reported to user space.
326	
327	In object-oriented terms, "kset" is the top-level container class; ksets
328	contain their own kobject, but that kobject is managed by the kset code and
329	should not be manipulated by any other user.
330	
331	A kset keeps its children in a standard kernel linked list.  Kobjects point
332	back to their containing kset via their kset field. In almost all cases,
333	the kobjects belonging to a kset have that kset (or, strictly, its embedded
334	kobject) in their parent.
335	
336	As a kset contains a kobject within it, it should always be dynamically
337	created and never declared statically or on the stack.  To create a new
338	kset use:
339	  struct kset *kset_create_and_add(const char *name,
340					   struct kset_uevent_ops *u,
341					   struct kobject *parent);
342	
343	When you are finished with the kset, call:
344	  void kset_unregister(struct kset *kset);
345	to destroy it.
346	
347	An example of using a kset can be seen in the
348	samples/kobject/kset-example.c file in the kernel tree.
349	
350	If a kset wishes to control the uevent operations of the kobjects
351	associated with it, it can use the struct kset_uevent_ops to handle it:
352	
353	struct kset_uevent_ops {
354	        int (*filter)(struct kset *kset, struct kobject *kobj);
355	        const char *(*name)(struct kset *kset, struct kobject *kobj);
356	        int (*uevent)(struct kset *kset, struct kobject *kobj,
357	                      struct kobj_uevent_env *env);
358	};
359	
360	
361	The filter function allows a kset to prevent a uevent from being emitted to
362	userspace for a specific kobject.  If the function returns 0, the uevent
363	will not be emitted.
364	
365	The name function will be called to override the default name of the kset
366	that the uevent sends to userspace.  By default, the name will be the same
367	as the kset itself, but this function, if present, can override that name.
368	
369	The uevent function will be called when the uevent is about to be sent to
370	userspace to allow more environment variables to be added to the uevent.
371	
372	One might ask how, exactly, a kobject is added to a kset, given that no
373	functions which perform that function have been presented.  The answer is
374	that this task is handled by kobject_add().  When a kobject is passed to
375	kobject_add(), its kset member should point to the kset to which the
376	kobject will belong.  kobject_add() will handle the rest.
377	
378	If the kobject belonging to a kset has no parent kobject set, it will be
379	added to the kset's directory.  Not all members of a kset do necessarily
380	live in the kset directory.  If an explicit parent kobject is assigned
381	before the kobject is added, the kobject is registered with the kset, but
382	added below the parent kobject.
383	
384	
385	Kobject removal
386	
387	After a kobject has been registered with the kobject core successfully, it
388	must be cleaned up when the code is finished with it.  To do that, call
389	kobject_put().  By doing this, the kobject core will automatically clean up
390	all of the memory allocated by this kobject.  If a KOBJ_ADD uevent has been
391	sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
392	any other sysfs housekeeping will be handled for the caller properly.
393	
394	If you need to do a two-stage delete of the kobject (say you are not
395	allowed to sleep when you need to destroy the object), then call
396	kobject_del() which will unregister the kobject from sysfs.  This makes the
397	kobject "invisible", but it is not cleaned up, and the reference count of
398	the object is still the same.  At a later time call kobject_put() to finish
399	the cleanup of the memory associated with the kobject.
400	
401	kobject_del() can be used to drop the reference to the parent object, if
402	circular references are constructed.  It is valid in some cases, that a
403	parent objects references a child.  Circular references _must_ be broken
404	with an explicit call to kobject_del(), so that a release functions will be
405	called, and the objects in the former circle release each other.
406	
407	
408	Example code to copy from
409	
410	For a more complete example of using ksets and kobjects properly, see the
411	example programs samples/kobject/{kobject-example.c,kset-example.c},
412	which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.
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.