1 ==============================================
2 Everything you never wanted to know about kobj
3 ==============================================
4
5 :Author: Greg Kroah-Hartman <gregkh@linuxfounda
6 :Last updated: December 19, 2007
7
8 Based on an original article by Jon Corbet for
9 2003 and located at https://lwn.net/Articles/5
10
11 Part of the difficulty in understanding the dr
12 abstraction upon which it is built - is that t
13 place. Dealing with kobjects requires understa
14 all of which make reference to each other. In
15 easier, we'll take a multi-pass approach, star
16 adding detail as we go. To that end, here are
17 some terms we will be working with.
18
19 - A kobject is an object of type struct kobje
20 and a reference count. A kobject also has
21 objects to be arranged into hierarchies), a
22 usually, a representation in the sysfs virt
23
24 Kobjects are generally not interesting on t
25 usually embedded within some other structur
26 the code is really interested in.
27
28 No structure should **EVER** have more than
29 If it does, the reference counting for the
30 up and incorrect, and your code will be bug
31
32 - A ktype is the type of object that embeds a
33 that embeds a kobject needs a corresponding
34 what happens to the kobject when it is crea
35
36 - A kset is a group of kobjects. These kobje
37 or belong to different ktypes. The kset is
38 collections of kobjects. Ksets contain thei
39 safely ignore that implementation detail as
40 this kobject automatically.
41
42 When you see a sysfs directory full of othe
43 of those directories corresponds to a kobje
44
45 We'll look at how to create and manipulate all
46 approach will be taken, so we'll go back to ko
47
48
49 Embedding kobjects
50 ==================
51
52 It is rare for kernel code to create a standal
53 exception explained below. Instead, kobjects
54 a larger, domain-specific object. To this end
55 embedded in other structures. If you are used
56 object-oriented terms, kobjects can be seen as
57 from which other classes are derived. A kobje
58 capabilities which are not particularly useful
59 nice to have in other objects. The C language
60 direct expression of inheritance, so other tec
61 embedding - must be used.
62
63 (As an aside, for those familiar with the kern
64 this is analogous as to how "list_head" struct
65 their own, but are invariably found embedded i
66 interest.)
67
68 So, for example, the UIO code in ``drivers/uio
69 defines the memory region associated with a ui
70
71 struct uio_map {
72 struct kobject kobj;
73 struct uio_mem *mem;
74 };
75
76 If you have a struct uio_map structure, findin
77 just a matter of using the kobj member. Code
78 often have the opposite problem, however: give
79 what is the pointer to the containing structur
80 (such as assuming that the kobject is at the b
81 and, instead, use the container_of() macro, fo
82
83 container_of(ptr, type, member)
84
85 where:
86
87 * ``ptr`` is the pointer to the embedded kob
88 * ``type`` is the type of the containing str
89 * ``member`` is the name of the structure fi
90
91 The return value from container_of() is a poin
92 container type. So, for example, a pointer ``k
93 embedded **within** a struct uio_map could be
94 **containing** uio_map structure with::
95
96 struct uio_map *u_map = container_of(kp, s
97
98 For convenience, programmers often define a si
99 kobject pointers to the containing type. Exac
100 earlier ``drivers/uio/uio.c``, as you can see
101
102 struct uio_map {
103 struct kobject kobj;
104 struct uio_mem *mem;
105 };
106
107 #define to_map(map) container_of(map, stru
108
109 where the macro argument "map" is a pointer to
110 question. That macro is subsequently invoked
111
112 struct uio_map *map = to_map(kobj);
113
114
115 Initialization of kobjects
116 ==========================
117
118 Code which creates a kobject must, of course,
119 of the internal fields are setup with a (manda
120
121 void kobject_init(struct kobject *kobj, co
122
123 The ktype is required for a kobject to be crea
124 must have an associated kobj_type. After call
125 register the kobject with sysfs, the function
126
127 int kobject_add(struct kobject *kobj, stru
128 const char *fmt, ...);
129
130 This sets up the parent of the kobject and the
131 properly. If the kobject is to be associated
132 kobj->kset must be assigned before calling kob
133 associated with a kobject, then the parent for
134 NULL in the call to kobject_add() and then the
135 kset itself.
136
137 As the name of the kobject is set when it is a
138 of the kobject should never be manipulated dir
139 the name of the kobject, call kobject_rename()
140
141 int kobject_rename(struct kobject *kobj, c
142
143 kobject_rename() does not perform any locking
144 what names are valid so the caller must provid
145 and serialization.
146
147 There is a function called kobject_set_name()
148 is being removed. If your code needs to call
149 incorrect and needs to be fixed.
150
151 To properly access the name of the kobject, us
152 kobject_name()::
153
154 const char *kobject_name(const struct kobj
155
156 There is a helper function to both initialize
157 kernel at the same time, called surprisingly e
158
159 int kobject_init_and_add(struct kobject *k
160 struct kobject *p
161
162 The arguments are the same as the individual k
163 kobject_add() functions described above.
164
165
166 Uevents
167 =======
168
169 After a kobject has been registered with the k
170 announce to the world that it has been created
171 call to kobject_uevent()::
172
173 int kobject_uevent(struct kobject *kobj, e
174
175 Use the **KOBJ_ADD** action for when the kobje
176 This should be done only after any attributes
177 have been initialized properly, as userspace w
178 for them when this call happens.
179
180 When the kobject is removed from the kernel (d
181 below), the uevent for **KOBJ_REMOVE** will be
182 kobject core, so the caller does not have to w
183 hand.
184
185
186 Reference counts
187 ================
188
189 One of the key functions of a kobject is to se
190 for the object in which it is embedded. As lon
191 exist, the object (and the code which supports
192 The low-level functions for manipulating a kob
193
194 struct kobject *kobject_get(struct kobject
195 void kobject_put(struct kobject *kobj);
196
197 A successful call to kobject_get() will increm
198 counter and return the pointer to the kobject.
199
200 When a reference is released, the call to kobj
201 reference count and, possibly, free the object
202 sets the reference count to one, so the code w
203 need to do a kobject_put() eventually to relea
204
205 Because kobjects are dynamic, they must not be
206 the stack, but instead, always allocated dynam
207 the kernel will contain a run-time check for k
208 statically and will warn the developer of this
209
210 If all that you want to use a kobject for is t
211 for your structure, please use the struct kref
212 overkill. For more information on how to use
213 file Documentation/core-api/kref.rst in the Li
214
215
216 Creating "simple" kobjects
217 ==========================
218
219 Sometimes all that a developer wants is a way
220 in the sysfs hierarchy, and not have to mess w
221 ksets, show and store functions, and other det
222 exception where a single kobject should be cre
223 entry, use the function::
224
225 struct kobject *kobject_create_and_add(con
226
227 This function will create a kobject and place
228 underneath the specified parent kobject. To c
229 associated with this kobject, use::
230
231 int sysfs_create_file(struct kobject *kobj
232
233 or::
234
235 int sysfs_create_group(struct kobject *kob
236
237 Both types of attributes used here, with a kob
238 with the kobject_create_and_add(), can be of t
239 special custom attribute is needed to be creat
240
241 See the example module, ``samples/kobject/kobj
242 implementation of a simple kobject and attribu
243
244
245
246 ktypes and release methods
247 ==========================
248
249 One important thing still missing from the dis
250 kobject when its reference count reaches zero.
251 kobject generally does not know when that will
252 would be little point in using a kobject in th
253 predictable object lifecycles become more comp
254 in as other portions of the kernel can get a r
255 is registered in the system.
256
257 The end result is that a structure protected b
258 before its reference count goes to zero. The r
259 the direct control of the code which created t
260 be notified asynchronously whenever the last r
261 kobjects goes away.
262
263 Once you registered your kobject via kobject_a
264 kfree() to free it directly. The only safe way
265 is good practice to always use kobject_put() a
266 errors creeping in.
267
268 This notification is done through a kobject's
269 such a method has a form like::
270
271 void my_object_release(struct kobject *kob
272 {
273 struct my_object *mine = container
274
275 /* Perform any additional cleanup
276 kfree(mine);
277 }
278
279 One important point cannot be overstated: ever
280 release() method, and the kobject must persist
281 until that method is called. If these constrai
282 flawed. Note that the kernel will warn you if
283 release() method. Do not try to get rid of th
284 "empty" release function.
285
286 If all your cleanup function needs to do is ca
287 create a wrapper function which uses container
288 type (as shown in the example above) and then
289 structure.
290
291 Note, the name of the kobject is available in
292 must NOT be changed within this callback. Oth
293 leak in the kobject core, which makes people u
294
295 Interestingly, the release() method is not sto
296 instead, it is associated with the ktype. So l
297 kobj_type::
298
299 struct kobj_type {
300 void (*release)(struct kobject *ko
301 const struct sysfs_ops *sysfs_ops;
302 const struct attribute_group **def
303 const struct kobj_ns_type_operatio
304 const void *(*namespace)(struct ko
305 void (*get_ownership)(struct kobje
306 };
307
308 This structure is used to describe a particula
309 correctly, of containing object). Every kobjec
310 kobj_type structure; a pointer to that structu
311 call kobject_init() or kobject_init_and_add().
312
313 The release field in struct kobj_type is, of c
314 release() method for this type of kobject. The
315 and default_groups) control how objects of thi
316 sysfs; they are beyond the scope of this docum
317
318 The default_groups pointer is a list of defaul
319 automatically created for any kobject that is
320
321
322 ksets
323 =====
324
325 A kset is merely a collection of kobjects that
326 each other. There is no restriction that they
327 very careful if they are not.
328
329 A kset serves these functions:
330
331 - It serves as a bag containing a group of ob
332 the kernel to track "all block devices" or
333
334 - A kset is also a subdirectory in sysfs, whe
335 with the kset can show up. Every kset cont
336 set up to be the parent of other kobjects;
337 the sysfs hierarchy are constructed in this
338
339 - Ksets can support the "hotplugging" of kobj
340 uevent events are reported to user space.
341
342 In object-oriented terms, "kset" is the top-le
343 contain their own kobject, but that kobject is
344 should not be manipulated by any other user.
345
346 A kset keeps its children in a standard kernel
347 back to their containing kset via their kset f
348 the kobjects belonging to a kset have that kse
349 kobject) in their parent.
350
351 As a kset contains a kobject within it, it sho
352 created and never declared statically or on th
353 kset use::
354
355 struct kset *kset_create_and_add(const char
356 const struc
357 struct kobj
358
359 When you are finished with the kset, call::
360
361 void kset_unregister(struct kset *k);
362
363 to destroy it. This removes the kset from sys
364 count. When the reference count goes to zero,
365 Because other references to the kset may still
366 after kset_unregister() returns.
367
368 An example of using a kset can be seen in the
369 ``samples/kobject/kset-example.c`` file in the
370
371 If a kset wishes to control the uevent operati
372 associated with it, it can use the struct kset
373
374 struct kset_uevent_ops {
375 int (* const filter)(struct kobject
376 const char *(* const name)(struct ko
377 int (* const uevent)(struct kobject
378 };
379
380
381 The filter function allows a kset to prevent a
382 userspace for a specific kobject. If the func
383 will not be emitted.
384
385 The name function will be called to override t
386 that the uevent sends to userspace. By defaul
387 as the kset itself, but this function, if pres
388
389 The uevent function will be called when the ue
390 userspace to allow more environment variables
391
392 One might ask how, exactly, a kobject is added
393 functions which perform that function have bee
394 that this task is handled by kobject_add(). W
395 kobject_add(), its kset member should point to
396 kobject will belong. kobject_add() will handl
397
398 If the kobject belonging to a kset has no pare
399 added to the kset's directory. Not all member
400 live in the kset directory. If an explicit pa
401 before the kobject is added, the kobject is re
402 added below the parent kobject.
403
404
405 Kobject removal
406 ===============
407
408 After a kobject has been registered with the k
409 must be cleaned up when the code is finished w
410 kobject_put(). By doing this, the kobject cor
411 all of the memory allocated by this kobject.
412 sent for the object, a corresponding ``KOBJ_RE
413 any other sysfs housekeeping will be handled f
414
415 If you need to do a two-stage delete of the ko
416 allowed to sleep when you need to destroy the
417 kobject_del() which will unregister the kobjec
418 kobject "invisible", but it is not cleaned up,
419 the object is still the same. At a later time
420 the cleanup of the memory associated with the
421
422 kobject_del() can be used to drop the referenc
423 circular references are constructed. It is va
424 parent objects references a child. Circular r
425 with an explicit call to kobject_del(), so tha
426 called, and the objects in the former circle r
427
428
429 Example code to copy from
430 =========================
431
432 For a more complete example of using ksets and
433 example programs ``samples/kobject/{kobject-ex
434 which will be built as loadable modules if you
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.