Documentation/core-api/kobject.rst

11 Part of the difficulty in understanding the driver model - and the kobject
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
28    No structure should **EVER** have more than one kobject embedded within it.
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.
40    this kobject automatically.
43    of those directories corresponds to a kobject in the same kset.
52 It is rare for kernel code to create a standalone kobject, with one major
57 from which other classes are derived.  A kobject implements a set of
72             struct kobject kobj;
76 If you have a struct uio_map structure, finding its embedded kobject is
78 often have the opposite problem, however: given a struct kobject pointer,
80 (such as assuming that the kobject is at the beginning of the structure)
87   * ``ptr`` is the pointer to the embedded kobject,
92 container type. So, for example, a pointer ``kp`` to a struct kobject
99 kobject pointers to the containing type.  Exactly this happens in the
103             struct kobject kobj;
109 where the macro argument "map" is a pointer to the struct kobject in
118 Code which creates a kobject must, of course, initialize that object. Some
121     void kobject_init(struct kobject *kobj, const struct kobj_type *ktype);
123 The ktype is required for a kobject to be created properly, as every kobject
125 register the kobject with sysfs, the function kobject_add() must be called::
127     int kobject_add(struct kobject *kobj, struct kobject *parent,
130 This sets up the parent of the kobject and the name for the kobject
131 properly.  If the kobject is to be associated with a specific kset,
133 associated with a kobject, then the parent for the kobject can be set to
134 NULL in the call to kobject_add() and then the kobject's parent will be the
137 As the name of the kobject is set when it is added to the kernel, the name
138 of the kobject should never be manipulated directly.  If you must change
139 the name of the kobject, call kobject_rename()::
141     int kobject_rename(struct kobject *kobj, const char *new_name);
151 To properly access the name of the kobject, use the function
154     const char *kobject_name(const struct kobject * kobj);
156 There is a helper function to both initialize and add the kobject to the
159     int kobject_init_and_add(struct kobject *kobj, const struct kobj_type *ktype,
160                              struct kobject *parent, const char *fmt, ...);
169 After a kobject has been registered with the kobject core, you need to
173     int kobject_uevent(struct kobject *kobj, enum kobject_action action);
175 Use the **KOBJ_ADD** action for when the kobject is first added to the kernel.
176 This should be done only after any attributes or children of the kobject
180 When the kobject is removed from the kernel (details on how to do that are
182 kobject core, so the caller does not have to worry about doing that by
189 One of the key functions of a kobject is to serve as a reference counter
192 The low-level functions for manipulating a kobject's reference counts are::
194     struct kobject *kobject_get(struct kobject *kobj);
195     void kobject_put(struct kobject *kobj);
197 A successful call to kobject_get() will increment the kobject's reference
198 counter and return the pointer to the kobject.
202 sets the reference count to one, so the code which sets up the kobject will
210 If all that you want to use a kobject for is to provide a reference counter
211 for your structure, please use the struct kref instead; a kobject would be
222 exception where a single kobject should be created.  To create such an
225     struct kobject *kobject_create_and_add(const char *name, struct kobject *parent);
227 This function will create a kobject and place it in sysfs in the location
228 underneath the specified parent kobject.  To create simple attributes
229 associated with this kobject, use::
231     int sysfs_create_file(struct kobject *kobj, const struct attribute *attr);
235     int sysfs_create_group(struct kobject *kobj, const struct attribute_group *grp);
237 Both types of attributes used here, with a kobject that has been created
241 See the example module, ``samples/kobject/kobject-example.c`` for an
242 implementation of a simple kobject and attributes.
250 kobject when its reference count reaches zero. The code which created the
251 kobject generally does not know when that will happen; if it did, there
252 would be little point in using a kobject in the first place. Even
254 in as other portions of the kernel can get a reference on any kobject that
257 The end result is that a structure protected by a kobject cannot be freed
259 the direct control of the code which created the kobject. So that code must
263 Once you registered your kobject via kobject_add(), you must never use
268 This notification is done through a kobject's release() method. Usually
271     void my_object_release(struct kobject *kobj)
279 One important point cannot be overstated: every kobject must have a
280 release() method, and the kobject must persist (in a consistent state)
291 Note, the name of the kobject is available in the release function, but it
293 leak in the kobject core, which makes people unhappy.
295 Interestingly, the release() method is not stored in the kobject itself;
300             void (*release)(struct kobject *kobj);
303             const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
304             const void *(*namespace)(struct kobject *kobj);
305             void (*get_ownership)(struct kobject *kobj, kuid_t *uid, kgid_t *gid);
308 This structure is used to describe a particular type of kobject (or, more
309 correctly, of containing object). Every kobject needs to have an associated
314 release() method for this type of kobject. The other two fields (sysfs_ops
319 automatically created for any kobject that is registered with this ktype.
335    with the kset can show up.  Every kset contains a kobject which can be
343 contain their own kobject, but that kobject is managed by the kset code and
349 kobject) in their parent.
351 As a kset contains a kobject within it, it should always be dynamically
357                                    struct kobject *parent_kobj);
369 ``samples/kobject/kset-example.c`` file in the kernel tree.
375           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);
382 userspace for a specific kobject.  If the function returns 0, the uevent
392 One might ask how, exactly, a kobject is added to a kset, given that no
394 that this task is handled by kobject_add().  When a kobject is passed to
396 kobject will belong.  kobject_add() will handle the rest.
398 If the kobject belonging to a kset has no parent kobject set, it will be
400 live in the kset directory.  If an explicit parent kobject is assigned
401 before the kobject is added, the kobject is registered with the kset, but
402 added below the parent kobject.
408 After a kobject has been registered with the kobject core successfully, it
410 kobject_put().  By doing this, the kobject core will automatically clean up
411 all of the memory allocated by this kobject.  If a ``KOBJ_ADD`` uevent has been
415 If you need to do a two-stage delete of the kobject (say you are not
417 kobject_del() which will unregister the kobject from sysfs.  This makes the
418 kobject "invisible", but it is not cleaned up, and the reference count of
420 the cleanup of the memory associated with the kobject.
433 example programs ``samples/kobject/{kobject-example.c,kset-example.c}``,