Commit | Line | Data |
---|---|---|
36d78d6c GKH |
1 | Everything you never wanted to know about kobjects, ksets, and ktypes |
2 | ||
bc5bca53 | 3 | Greg Kroah-Hartman <gregkh@linuxfoundation.org> |
36d78d6c GKH |
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 | ||
462bd295 RD |
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.) | |
36d78d6c | 66 | |
462bd295 RD |
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 { | |
36d78d6c | 71 | struct kobject kobj; |
462bd295 RD |
72 | struct uio_mem *mem; |
73 | }; | |
36d78d6c | 74 | |
462bd295 | 75 | If you have a struct uio_map structure, finding its embedded kobject is |
36d78d6c GKH |
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 | ||
462bd295 RD |
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 | }; | |
36d78d6c | 105 | |
462bd295 | 106 | #define to_map(map) container_of(map, struct uio_map, kobj) |
36d78d6c | 107 | |
462bd295 RD |
108 | where the macro argument "map" is a pointer to the struct kobject in |
109 | question. That macro is subsequently invoked with: | |
36d78d6c | 110 | |
462bd295 | 111 | struct uio_map *map = to_map(kobj); |
36d78d6c GKH |
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 | ||
0732b49c RR |
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 | |
030c1d2b EB |
142 | and serialization. |
143 | ||
36d78d6c GKH |
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 | |
19f59460 | 154 | kernel 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 | ||
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 | ||
9b64c09b | 176 | When the kobject is removed from the kernel (details on how to do that are |
36d78d6c GKH |
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 { | |
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 | ||
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, | |
acccafe9 | 333 | the kobjects belonging to a kset have that kset (or, strictly, its embedded |
36d78d6c GKH |
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); | |
35a5fe69 BH |
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. | |
36d78d6c GKH |
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 | |
178a5b35 RD |
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. |