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