blob: 7310247310a0c13429646af04a6dc0ea7d9ed19e [file] [log] [blame]
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -03001=====================================================================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -08002Everything you never wanted to know about kobjects, ksets, and ktypes
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -03003=====================================================================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -08004
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -03005:Author: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
6:Last updated: December 19, 2007
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -08007
8Based on an original article by Jon Corbet for lwn.net written October 1,
Alexander A. Klimov92f5e6b2020-07-13 16:41:03 +020092003 and located at https://lwn.net/Articles/51437/
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080010
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080011Part 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
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000028 No structure should **EVER** have more than one kobject embedded within it.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080029 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
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -030050==================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080051
52It is rare for kernel code to create a standalone kobject, with one major
53exception explained below. Instead, kobjects are used to control access to
54a larger, domain-specific object. To this end, kobjects will be found
55embedded in other structures. If you are used to thinking of things in
56object-oriented terms, kobjects can be seen as a top-level, abstract class
57from which other classes are derived. A kobject implements a set of
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000058capabilities which are not particularly useful by themselves, but are
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080059nice to have in other objects. The C language does not allow for the
60direct expression of inheritance, so other techniques - such as structure
61embedding - must be used.
62
Robert P. J. Day462bd292010-03-11 07:59:09 -050063(As an aside, for those familiar with the kernel linked list implementation,
64this is analogous as to how "list_head" structs are rarely useful on
65their own, but are invariably found embedded in the larger objects of
66interest.)
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080067
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000068So, for example, the UIO code in ``drivers/uio/uio.c`` has a structure that
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -030069defines the memory region associated with a uio device::
Robert P. J. Day462bd292010-03-11 07:59:09 -050070
71 struct uio_map {
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000072 struct kobject kobj;
73 struct uio_mem *mem;
Robert P. J. Day462bd292010-03-11 07:59:09 -050074 };
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080075
Robert P. J. Day462bd292010-03-11 07:59:09 -050076If you have a struct uio_map structure, finding its embedded kobject is
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080077just a matter of using the kobj member. Code that works with kobjects will
78often have the opposite problem, however: given a struct kobject pointer,
79what is the pointer to the containing structure? You must avoid tricks
80(such as assuming that the kobject is at the beginning of the structure)
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000081and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080082
Qi Zheng3eaa3bf2020-05-05 14:18:28 +080083 container_of(ptr, type, member)
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080084
Robert P. J. Day462bd292010-03-11 07:59:09 -050085where:
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080086
Qi Zheng3eaa3bf2020-05-05 14:18:28 +080087 * ``ptr`` is the pointer to the embedded kobject,
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000088 * ``type`` is the type of the containing structure, and
89 * ``member`` is the name of the structure field to which ``pointer`` points.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -080090
Robert P. J. Day462bd292010-03-11 07:59:09 -050091The return value from container_of() is a pointer to the corresponding
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000092container type. So, for example, a pointer ``kp`` to a struct kobject
93embedded **within** a struct uio_map could be converted to a pointer to the
94**containing** uio_map structure with::
Robert P. J. Day462bd292010-03-11 07:59:09 -050095
96 struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
97
Sameer Rahmani669a5cc2020-02-25 22:21:24 +000098For convenience, programmers often define a simple macro for **back-casting**
Robert P. J. Day462bd292010-03-11 07:59:09 -050099kobject pointers to the containing type. Exactly this happens in the
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000100earlier ``drivers/uio/uio.c``, as you can see here::
Robert P. J. Day462bd292010-03-11 07:59:09 -0500101
102 struct uio_map {
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000103 struct kobject kobj;
104 struct uio_mem *mem;
Robert P. J. Day462bd292010-03-11 07:59:09 -0500105 };
106
107 #define to_map(map) container_of(map, struct uio_map, kobj)
108
109where the macro argument "map" is a pointer to the struct kobject in
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300110question. That macro is subsequently invoked with::
Robert P. J. Day462bd292010-03-11 07:59:09 -0500111
112 struct uio_map *map = to_map(kobj);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800113
114
115Initialization of kobjects
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300116==========================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800117
118Code which creates a kobject must, of course, initialize that object. Some
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300119of the internal fields are setup with a (mandatory) call to kobject_init()::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800120
Wedson Almeida Filhoee6d3dd2021-12-24 23:13:45 +0000121 void kobject_init(struct kobject *kobj, const struct kobj_type *ktype);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800122
123The ktype is required for a kobject to be created properly, as every kobject
124must have an associated kobj_type. After calling kobject_init(), to
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300125register the kobject with sysfs, the function kobject_add() must be called::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800126
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300127 int kobject_add(struct kobject *kobj, struct kobject *parent,
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000128 const char *fmt, ...);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800129
130This sets up the parent of the kobject and the name for the kobject
131properly. If the kobject is to be associated with a specific kset,
132kobj->kset must be assigned before calling kobject_add(). If a kset is
133associated with a kobject, then the parent for the kobject can be set to
134NULL in the call to kobject_add() and then the kobject's parent will be the
135kset itself.
136
137As the name of the kobject is set when it is added to the kernel, the name
138of the kobject should never be manipulated directly. If you must change
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300139the name of the kobject, call kobject_rename()::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800140
141 int kobject_rename(struct kobject *kobj, const char *new_name);
142
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800143kobject_rename() does not perform any locking or have a solid notion of
Rusty Russell0732b492008-12-09 08:32:14 +1030144what names are valid so the caller must provide their own sanity checking
Eric W. Biederman030c1d22008-05-08 14:41:00 -0700145and serialization.
146
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800147There is a function called kobject_set_name() but that is legacy cruft and
148is being removed. If your code needs to call this function, it is
149incorrect and needs to be fixed.
150
151To properly access the name of the kobject, use the function
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300152kobject_name()::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800153
154 const char *kobject_name(const struct kobject * kobj);
155
156There is a helper function to both initialize and add the kobject to the
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300157kernel at the same time, called surprisingly enough kobject_init_and_add()::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800158
Wedson Almeida Filhoee6d3dd2021-12-24 23:13:45 +0000159 int kobject_init_and_add(struct kobject *kobj, const struct kobj_type *ktype,
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800160 struct kobject *parent, const char *fmt, ...);
161
162The arguments are the same as the individual kobject_init() and
163kobject_add() functions described above.
164
165
166Uevents
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300167=======
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800168
169After a kobject has been registered with the kobject core, you need to
170announce to the world that it has been created. This can be done with a
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300171call to kobject_uevent()::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800172
173 int kobject_uevent(struct kobject *kobj, enum kobject_action action);
174
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000175Use the **KOBJ_ADD** action for when the kobject is first added to the kernel.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800176This should be done only after any attributes or children of the kobject
177have been initialized properly, as userspace will instantly start to look
178for them when this call happens.
179
John de la Garza9b64c092014-12-06 16:38:57 -0500180When the kobject is removed from the kernel (details on how to do that are
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000181below), the uevent for **KOBJ_REMOVE** will be automatically created by the
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800182kobject core, so the caller does not have to worry about doing that by
183hand.
184
185
186Reference counts
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300187================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800188
189One of the key functions of a kobject is to serve as a reference counter
190for the object in which it is embedded. As long as references to the object
191exist, the object (and the code which supports it) must continue to exist.
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300192The low-level functions for manipulating a kobject's reference counts are::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800193
194 struct kobject *kobject_get(struct kobject *kobj);
195 void kobject_put(struct kobject *kobj);
196
197A successful call to kobject_get() will increment the kobject's reference
198counter and return the pointer to the kobject.
199
200When a reference is released, the call to kobject_put() will decrement the
201reference count and, possibly, free the object. Note that kobject_init()
202sets the reference count to one, so the code which sets up the kobject will
203need to do a kobject_put() eventually to release that reference.
204
205Because kobjects are dynamic, they must not be declared statically or on
206the stack, but instead, always allocated dynamically. Future versions of
207the kernel will contain a run-time check for kobjects that are created
208statically and will warn the developer of this improper usage.
209
210If all that you want to use a kobject for is to provide a reference counter
211for your structure, please use the struct kref instead; a kobject would be
212overkill. For more information on how to use struct kref, please see the
Mauro Carvalho Chehab1ac00662020-05-01 17:37:52 +0200213file Documentation/core-api/kref.rst in the Linux kernel source tree.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800214
215
216Creating "simple" kobjects
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300217==========================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800218
219Sometimes all that a developer wants is a way to create a simple directory
220in the sysfs hierarchy, and not have to mess with the whole complication of
221ksets, show and store functions, and other details. This is the one
222exception where a single kobject should be created. To create such an
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300223entry, use the function::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800224
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800225 struct kobject *kobject_create_and_add(const char *name, struct kobject *parent);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800226
227This function will create a kobject and place it in sysfs in the location
228underneath the specified parent kobject. To create simple attributes
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300229associated with this kobject, use::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800230
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800231 int sysfs_create_file(struct kobject *kobj, const struct attribute *attr);
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300232
233or::
234
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800235 int sysfs_create_group(struct kobject *kobj, const struct attribute_group *grp);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800236
237Both types of attributes used here, with a kobject that has been created
238with the kobject_create_and_add(), can be of type kobj_attribute, so no
239special custom attribute is needed to be created.
240
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000241See the example module, ``samples/kobject/kobject-example.c`` for an
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800242implementation of a simple kobject and attributes.
243
244
245
246ktypes and release methods
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300247==========================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800248
249One important thing still missing from the discussion is what happens to a
250kobject when its reference count reaches zero. The code which created the
251kobject generally does not know when that will happen; if it did, there
252would be little point in using a kobject in the first place. Even
253predictable object lifecycles become more complicated when sysfs is brought
254in as other portions of the kernel can get a reference on any kobject that
255is registered in the system.
256
257The end result is that a structure protected by a kobject cannot be freed
258before its reference count goes to zero. The reference count is not under
259the direct control of the code which created the kobject. So that code must
260be notified asynchronously whenever the last reference to one of its
261kobjects goes away.
262
263Once you registered your kobject via kobject_add(), you must never use
264kfree() to free it directly. The only safe way is to use kobject_put(). It
265is good practice to always use kobject_put() after kobject_init() to avoid
266errors creeping in.
267
268This notification is done through a kobject's release() method. Usually
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300269such a method has a form like::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800270
271 void my_object_release(struct kobject *kobj)
272 {
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000273 struct my_object *mine = container_of(kobj, struct my_object, kobj);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800274
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000275 /* Perform any additional cleanup on this object, then... */
276 kfree(mine);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800277 }
278
279One important point cannot be overstated: every kobject must have a
280release() method, and the kobject must persist (in a consistent state)
281until that method is called. If these constraints are not met, the code is
Ezequiel Garcia186bddb2018-12-03 13:44:35 -0300282flawed. Note that the kernel will warn you if you forget to provide a
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800283release() method. Do not try to get rid of this warning by providing an
Ezequiel Garcia186bddb2018-12-03 13:44:35 -0300284"empty" release function.
285
286If all your cleanup function needs to do is call kfree(), then you must
287create a wrapper function which uses container_of() to upcast to the correct
288type (as shown in the example above) and then calls kfree() on the overall
289structure.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800290
291Note, the name of the kobject is available in the release function, but it
292must NOT be changed within this callback. Otherwise there will be a memory
293leak in the kobject core, which makes people unhappy.
294
295Interestingly, the release() method is not stored in the kobject itself;
296instead, it is associated with the ktype. So let us introduce struct
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300297kobj_type::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800298
299 struct kobj_type {
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000300 void (*release)(struct kobject *kobj);
301 const struct sysfs_ops *sysfs_ops;
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800302 const struct attribute_group **default_groups;
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000303 const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
304 const void *(*namespace)(struct kobject *kobj);
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800305 void (*get_ownership)(struct kobject *kobj, kuid_t *uid, kgid_t *gid);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800306 };
307
308This structure is used to describe a particular type of kobject (or, more
309correctly, of containing object). Every kobject needs to have an associated
310kobj_type structure; a pointer to that structure must be specified when you
311call kobject_init() or kobject_init_and_add().
312
313The release field in struct kobj_type is, of course, a pointer to the
314release() method for this type of kobject. The other two fields (sysfs_ops
Greg Kroah-Hartmanc9512fd2022-01-04 11:50:24 +0100315and default_groups) control how objects of this type are represented in
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800316sysfs; they are beyond the scope of this document.
317
Greg Kroah-Hartmanc9512fd2022-01-04 11:50:24 +0100318The default_groups pointer is a list of default attributes that will be
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800319automatically created for any kobject that is registered with this ktype.
320
321
322ksets
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300323=====
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800324
325A kset is merely a collection of kobjects that want to be associated with
326each other. There is no restriction that they be of the same ktype, but be
327very careful if they are not.
328
329A kset serves these functions:
330
331 - It serves as a bag containing a group of objects. A kset can be used by
332 the kernel to track "all block devices" or "all PCI device drivers."
333
334 - A kset is also a subdirectory in sysfs, where the associated kobjects
335 with the kset can show up. Every kset contains a kobject which can be
336 set up to be the parent of other kobjects; the top-level directories of
337 the sysfs hierarchy are constructed in this way.
338
339 - Ksets can support the "hotplugging" of kobjects and influence how
340 uevent events are reported to user space.
341
342In object-oriented terms, "kset" is the top-level container class; ksets
343contain their own kobject, but that kobject is managed by the kset code and
344should not be manipulated by any other user.
345
346A kset keeps its children in a standard kernel linked list. Kobjects point
347back to their containing kset via their kset field. In almost all cases,
David Brigadaacccafe2008-06-11 13:27:32 -0400348the kobjects belonging to a kset have that kset (or, strictly, its embedded
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800349kobject) in their parent.
350
351As a kset contains a kobject within it, it should always be dynamically
352created and never declared statically or on the stack. To create a new
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300353kset use::
354
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800355 struct kset *kset_create_and_add(const char *name,
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800356 const struct kset_uevent_ops *uevent_ops,
357 struct kobject *parent_kobj);
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800358
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300359When you are finished with the kset, call::
360
Qi Zheng3eaa3bf2020-05-05 14:18:28 +0800361 void kset_unregister(struct kset *k);
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300362
Bjorn Helgaas35a5fe62013-12-05 17:38:00 -0700363to destroy it. This removes the kset from sysfs and decrements its reference
364count. When the reference count goes to zero, the kset will be released.
365Because other references to the kset may still exist, the release may happen
366after kset_unregister() returns.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800367
368An example of using a kset can be seen in the
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000369``samples/kobject/kset-example.c`` file in the kernel tree.
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800370
371If a kset wishes to control the uevent operations of the kobjects
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300372associated with it, it can use the struct kset_uevent_ops to handle it::
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800373
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300374 struct kset_uevent_ops {
Greg Kroah-Hartmancf6299b62021-12-27 17:39:24 +0100375 int (* const filter)(struct kobject *kobj);
376 const char *(* const name)(struct kobject *kobj);
377 int (* const uevent)(struct kobject *kobj, struct kobj_uevent_env *env);
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300378 };
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800379
380
381The filter function allows a kset to prevent a uevent from being emitted to
382userspace for a specific kobject. If the function returns 0, the uevent
383will not be emitted.
384
385The name function will be called to override the default name of the kset
386that the uevent sends to userspace. By default, the name will be the same
387as the kset itself, but this function, if present, can override that name.
388
389The uevent function will be called when the uevent is about to be sent to
390userspace to allow more environment variables to be added to the uevent.
391
392One might ask how, exactly, a kobject is added to a kset, given that no
393functions which perform that function have been presented. The answer is
394that this task is handled by kobject_add(). When a kobject is passed to
395kobject_add(), its kset member should point to the kset to which the
396kobject will belong. kobject_add() will handle the rest.
397
398If the kobject belonging to a kset has no parent kobject set, it will be
399added to the kset's directory. Not all members of a kset do necessarily
400live in the kset directory. If an explicit parent kobject is assigned
401before the kobject is added, the kobject is registered with the kset, but
402added below the parent kobject.
403
404
405Kobject removal
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300406===============
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800407
408After a kobject has been registered with the kobject core successfully, it
409must be cleaned up when the code is finished with it. To do that, call
410kobject_put(). By doing this, the kobject core will automatically clean up
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000411all of the memory allocated by this kobject. If a ``KOBJ_ADD`` uevent has been
412sent for the object, a corresponding ``KOBJ_REMOVE`` uevent will be sent, and
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800413any other sysfs housekeeping will be handled for the caller properly.
414
415If you need to do a two-stage delete of the kobject (say you are not
416allowed to sleep when you need to destroy the object), then call
417kobject_del() which will unregister the kobject from sysfs. This makes the
418kobject "invisible", but it is not cleaned up, and the reference count of
419the object is still the same. At a later time call kobject_put() to finish
420the cleanup of the memory associated with the kobject.
421
422kobject_del() can be used to drop the reference to the parent object, if
423circular references are constructed. It is valid in some cases, that a
424parent objects references a child. Circular references _must_ be broken
425with an explicit call to kobject_del(), so that a release functions will be
426called, and the objects in the former circle release each other.
427
428
429Example code to copy from
Mauro Carvalho Chehab74727232017-05-14 16:25:04 -0300430=========================
Greg Kroah-Hartman36d78d62007-11-27 11:28:26 -0800431
432For a more complete example of using ksets and kobjects properly, see the
Sameer Rahmani669a5cc2020-02-25 22:21:24 +0000433example programs ``samples/kobject/{kobject-example.c,kset-example.c}``,
434which will be built as loadable modules if you select ``CONFIG_SAMPLE_KOBJECT``.