Root/
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. This removes the kset from sysfs and decrements its reference |
346 | count. When the reference count goes to zero, the kset will be released. |
347 | Because other references to the kset may still exist, the release may happen |
348 | after kset_unregister() returns. |
349 | |
350 | An example of using a kset can be seen in the |
351 | samples/kobject/kset-example.c file in the kernel tree. |
352 | |
353 | If a kset wishes to control the uevent operations of the kobjects |
354 | associated with it, it can use the struct kset_uevent_ops to handle it: |
355 | |
356 | struct 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 | |
364 | The filter function allows a kset to prevent a uevent from being emitted to |
365 | userspace for a specific kobject. If the function returns 0, the uevent |
366 | will not be emitted. |
367 | |
368 | The name function will be called to override the default name of the kset |
369 | that the uevent sends to userspace. By default, the name will be the same |
370 | as the kset itself, but this function, if present, can override that name. |
371 | |
372 | The uevent function will be called when the uevent is about to be sent to |
373 | userspace to allow more environment variables to be added to the uevent. |
374 | |
375 | One might ask how, exactly, a kobject is added to a kset, given that no |
376 | functions which perform that function have been presented. The answer is |
377 | that this task is handled by kobject_add(). When a kobject is passed to |
378 | kobject_add(), its kset member should point to the kset to which the |
379 | kobject will belong. kobject_add() will handle the rest. |
380 | |
381 | If the kobject belonging to a kset has no parent kobject set, it will be |
382 | added to the kset's directory. Not all members of a kset do necessarily |
383 | live in the kset directory. If an explicit parent kobject is assigned |
384 | before the kobject is added, the kobject is registered with the kset, but |
385 | added below the parent kobject. |
386 | |
387 | |
388 | Kobject removal |
389 | |
390 | After a kobject has been registered with the kobject core successfully, it |
391 | must be cleaned up when the code is finished with it. To do that, call |
392 | kobject_put(). By doing this, the kobject core will automatically clean up |
393 | all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been |
394 | sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and |
395 | any other sysfs housekeeping will be handled for the caller properly. |
396 | |
397 | If you need to do a two-stage delete of the kobject (say you are not |
398 | allowed to sleep when you need to destroy the object), then call |
399 | kobject_del() which will unregister the kobject from sysfs. This makes the |
400 | kobject "invisible", but it is not cleaned up, and the reference count of |
401 | the object is still the same. At a later time call kobject_put() to finish |
402 | the cleanup of the memory associated with the kobject. |
403 | |
404 | kobject_del() can be used to drop the reference to the parent object, if |
405 | circular references are constructed. It is valid in some cases, that a |
406 | parent objects references a child. Circular references _must_ be broken |
407 | with an explicit call to kobject_del(), so that a release functions will be |
408 | called, and the objects in the former circle release each other. |
409 | |
410 | |
411 | Example code to copy from |
412 | |
413 | For a more complete example of using ksets and kobjects properly, see the |
414 | example programs samples/kobject/{kobject-example.c,kset-example.c}, |
415 | which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT. |
416 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9