Embedding kobjects¶

It is rare for kernel code to create a standalone kobject, with one majorexception explained below. Instead, kobjects are used to control access toa larger, domain-specific object. To this end, kobjects will be foundembedded in other structures. If you are used to thinking of things inobject-oriented terms, kobjects can be seen as a top-level, abstract classfrom which other classes are derived. A kobject implements a set ofcapabilities which are not particularly useful by themselves, but arenice to have in other objects. The C language does not allow for thedirect expression of inheritance, so other techniques - such as structureembedding - must be used.

(As an aside, for those familiar with the kernel linked list implementation,this is analogous as to how “list_head” structs are rarely useful ontheir own, but are invariably found embedded in the larger objects ofinterest.)

So, for example, the UIO code indrivers/uio/uio.c has a structure thatdefines the memory region associated with a uio device:

struct uio_map {        struct kobject kobj;        struct uio_mem *mem;};

If you have a struct uio_map structure, finding its embedded kobject isjust a matter of using the kobj member. Code that works with kobjects willoften have the opposite problem, however: given a struct kobject pointer,what is the pointer to the containing structure? You must avoid tricks(such as assuming that the kobject is at the beginning of the structure)and, instead, use thecontainer_of() macro, found in<linux/kernel.h>:

container_of(ptr, type, member)

where:

• ptr is the pointer to the embedded kobject,
• type is the type of the containing structure, and
• member is the name of the structure field to whichpointer points.

The return value fromcontainer_of() is a pointer to the correspondingcontainer type. So, for example, a pointerkp to a struct kobjectembeddedwithin a struct uio_map could be converted to a pointer to thecontaining uio_map structure with:

struct uio_map *u_map = container_of(kp, struct uio_map, kobj);

For convenience, programmers often define a simple macro forback-castingkobject pointers to the containing type. Exactly this happens in theearlierdrivers/uio/uio.c, as you can see here:

struct uio_map {        struct kobject kobj;        struct uio_mem *mem;};#define to_map(map) container_of(map, struct uio_map, kobj)

where the macro argument “map” is a pointer to the struct kobject inquestion. That macro is subsequently invoked with:

struct uio_map *map = to_map(kobj);

Initialization of kobjects¶

Code which creates a kobject must, of course, initialize that object. Someof the internal fields are setup with a (mandatory) call tokobject_init():

void kobject_init(struct kobject *kobj, struct kobj_type *ktype);

The ktype is required for a kobject to be created properly, as every kobjectmust have an associated kobj_type. After callingkobject_init(), toregister the kobject with sysfs, the functionkobject_add() must be called:

int kobject_add(struct kobject *kobj, struct kobject *parent,                const char *fmt, ...);

This sets up the parent of the kobject and the name for the kobjectproperly. If the kobject is to be associated with a specific kset,kobj->kset must be assigned before callingkobject_add(). If a kset isassociated with a kobject, then the parent for the kobject can be set toNULL in the call tokobject_add() and then the kobject’s parent will be thekset itself.

As the name of the kobject is set when it is added to the kernel, the nameof the kobject should never be manipulated directly. If you must changethe name of the kobject, callkobject_rename():

int kobject_rename(struct kobject *kobj, const char *new_name);

kobject_rename() does not perform any locking or have a solid notion ofwhat names are valid so the caller must provide their own sanity checkingand serialization.

There is a function calledkobject_set_name() but that is legacy cruft andis being removed. If your code needs to call this function, it isincorrect and needs to be fixed.

To properly access the name of the kobject, use the functionkobject_name():

const char *kobject_name(const struct kobject * kobj);

There is a helper function to both initialize and add the kobject to thekernel at the same time, called surprisingly enoughkobject_init_and_add():

int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,                         struct kobject *parent, const char *fmt, ...);

The arguments are the same as the individualkobject_init() andkobject_add() functions described above.

Uevents¶

After a kobject has been registered with the kobject core, you need toannounce to the world that it has been created. This can be done with acall to kobject_uevent():

int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use theKOBJ_ADD action for when the kobject is first added to the kernel.This should be done only after any attributes or children of the kobjecthave been initialized properly, as userspace will instantly start to lookfor them when this call happens.

When the kobject is removed from the kernel (details on how to do that arebelow), the uevent forKOBJ_REMOVE will be automatically created by thekobject core, so the caller does not have to worry about doing that byhand.

Reference counts¶

One of the key functions of a kobject is to serve as a reference counterfor the object in which it is embedded. As long as references to the objectexist, the object (and the code which supports it) must continue to exist.The low-level functions for manipulating a kobject’s reference counts are:

struct kobject *kobject_get(struct kobject *kobj);void kobject_put(struct kobject *kobj);

A successful call tokobject_get() will increment the kobject’s referencecounter and return the pointer to the kobject.

When a reference is released, the call tokobject_put() will decrement thereference count and, possibly, free the object. Note thatkobject_init()sets the reference count to one, so the code which sets up the kobject willneed to do akobject_put() eventually to release that reference.

Because kobjects are dynamic, they must not be declared statically or onthe stack, but instead, always allocated dynamically. Future versions ofthe kernel will contain a run-time check for kobjects that are createdstatically and will warn the developer of this improper usage.

If all that you want to use a kobject for is to provide a reference counterfor your structure, please use the struct kref instead; a kobject would beoverkill. For more information on how to use struct kref, please see thefile Documentation/core-api/kref.rst in the Linux kernel source tree.

Creating “simple” kobjects¶

Sometimes all that a developer wants is a way to create a simple directoryin the sysfs hierarchy, and not have to mess with the whole complication ofksets, show and store functions, and other details. This is the oneexception where a single kobject should be created. To create such anentry, use the function:

struct kobject *kobject_create_and_add(const char *name, struct kobject *parent);

This function will create a kobject and place it in sysfs in the locationunderneath the specified parent kobject. To create simple attributesassociated with this kobject, use:

int sysfs_create_file(struct kobject *kobj, const struct attribute *attr);

or:

int sysfs_create_group(struct kobject *kobj, const struct attribute_group *grp);

Both types of attributes used here, with a kobject that has been createdwith thekobject_create_and_add(), can be of type kobj_attribute, so nospecial custom attribute is needed to be created.

See the example module,samples/kobject/kobject-example.c for animplementation of a simple kobject and attributes.

ktypes and release methods¶

One important thing still missing from the discussion is what happens to akobject when its reference count reaches zero. The code which created thekobject generally does not know when that will happen; if it did, therewould be little point in using a kobject in the first place. Evenpredictable object lifecycles become more complicated when sysfs is broughtin as other portions of the kernel can get a reference on any kobject thatis registered in the system.

The end result is that a structure protected by a kobject cannot be freedbefore its reference count goes to zero. The reference count is not underthe direct control of the code which created the kobject. So that code mustbe notified asynchronously whenever the last reference to one of itskobjects goes away.

Once you registered your kobject viakobject_add(), you must never usekfree() to free it directly. The only safe way is to usekobject_put(). Itis good practice to always usekobject_put() afterkobject_init() to avoiderrors creeping in.

This notification is done through a kobject’s release() method. Usuallysuch a method has a form like:

void my_object_release(struct kobject *kobj){        struct my_object *mine = container_of(kobj, struct my_object, kobj);        /* Perform any additional cleanup on this object, then... */        kfree(mine);}

One important point cannot be overstated: every kobject must have arelease() method, and the kobject must persist (in a consistent state)until that method is called. If these constraints are not met, the code isflawed. Note that the kernel will warn you if you forget to provide arelease() method. Do not try to get rid of this warning by providing an“empty” release function.

If all your cleanup function needs to do is callkfree(), then you mustcreate a wrapper function which usescontainer_of() to upcast to the correcttype (as shown in the example above) and then callskfree() on the overallstructure.

Note, the name of the kobject is available in the release function, but itmust NOT be changed within this callback. Otherwise there will be a memoryleak in the kobject core, which makes people unhappy.

Interestingly, the release() method is not stored in the kobject itself;instead, it is associated with the ktype. So let us introduce structkobj_type:

struct kobj_type {        void (*release)(struct kobject *kobj);        const struct sysfs_ops *sysfs_ops;        struct attribute **default_attrs;        const struct attribute_group **default_groups;        const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);        const void *(*namespace)(struct kobject *kobj);        void (*get_ownership)(struct kobject *kobj, kuid_t *uid, kgid_t *gid);};

This structure is used to describe a particular type of kobject (or, morecorrectly, of containing object). Every kobject needs to have an associatedkobj_type structure; a pointer to that structure must be specified when youcallkobject_init() orkobject_init_and_add().

The release field in struct kobj_type is, of course, a pointer to therelease() method for this type of kobject. The other two fields (sysfs_opsand default_attrs) control how objects of this type are represented insysfs; they are beyond the scope of this document.

The default_attrs pointer is a list of default attributes that will beautomatically created for any kobject that is registered with this ktype.

ksets¶

A kset is merely a collection of kobjects that want to be associated witheach other. There is no restriction that they be of the same ktype, but bevery careful if they are not.

A kset serves these functions:

• It serves as a bag containing a group of objects. A kset can be used bythe kernel to track “all block devices” or “all PCI device drivers.”
• A kset is also a subdirectory in sysfs, where the associated kobjectswith the kset can show up. Every kset contains a kobject which can beset up to be the parent of other kobjects; the top-level directories ofthe sysfs hierarchy are constructed in this way.
• Ksets can support the “hotplugging” of kobjects and influence howuevent events are reported to user space.

In object-oriented terms, “kset” is the top-level container class; ksetscontain their own kobject, but that kobject is managed by the kset code andshould not be manipulated by any other user.

A kset keeps its children in a standard kernel linked list. Kobjects pointback to their containing kset via their kset field. In almost all cases,the kobjects belonging to a kset have that kset (or, strictly, its embeddedkobject) in their parent.

As a kset contains a kobject within it, it should always be dynamicallycreated and never declared statically or on the stack. To create a newkset use:

struct kset *kset_create_and_add(const char *name,                                 const struct kset_uevent_ops *uevent_ops,                                 struct kobject *parent_kobj);

When you are finished with the kset, call:

void kset_unregister(struct kset *k);

to destroy it. This removes the kset from sysfs and decrements its referencecount. When the reference count goes to zero, the kset will be released.Because other references to the kset may still exist, the release may happenafterkset_unregister() returns.

An example of using a kset can be seen in thesamples/kobject/kset-example.c file in the kernel tree.

If a kset wishes to control the uevent operations of the kobjectsassociated with it, it can use the struct kset_uevent_ops to handle it:

struct kset_uevent_ops {        int (* const filter)(struct kset *kset, struct kobject *kobj);        const char *(* const name)(struct kset *kset, struct kobject *kobj);        int (* const uevent)(struct kset *kset, struct kobject *kobj,                      struct kobj_uevent_env *env);};

The filter function allows a kset to prevent a uevent from being emitted touserspace for a specific kobject. If the function returns 0, the ueventwill not be emitted.

The name function will be called to override the default name of the ksetthat the uevent sends to userspace. By default, the name will be the sameas the kset itself, but this function, if present, can override that name.

The uevent function will be called when the uevent is about to be sent touserspace to allow more environment variables to be added to the uevent.

One might ask how, exactly, a kobject is added to a kset, given that nofunctions which perform that function have been presented. The answer isthat this task is handled bykobject_add(). When a kobject is passed tokobject_add(), its kset member should point to the kset to which thekobject will belong.kobject_add() will handle the rest.

If the kobject belonging to a kset has no parent kobject set, it will beadded to the kset’s directory. Not all members of a kset do necessarilylive in the kset directory. If an explicit parent kobject is assignedbefore the kobject is added, the kobject is registered with the kset, butadded below the parent kobject.

Kobject removal¶

After a kobject has been registered with the kobject core successfully, itmust be cleaned up when the code is finished with it. To do that, callkobject_put(). By doing this, the kobject core will automatically clean upall of the memory allocated by this kobject. If aKOBJ_ADD uevent has beensent for the object, a correspondingKOBJ_REMOVE uevent will be sent, andany other sysfs housekeeping will be handled for the caller properly.

If you need to do a two-stage delete of the kobject (say you are notallowed to sleep when you need to destroy the object), then callkobject_del() which will unregister the kobject from sysfs. This makes thekobject “invisible”, but it is not cleaned up, and the reference count ofthe object is still the same. At a later time callkobject_put() to finishthe cleanup of the memory associated with the kobject.

kobject_del() can be used to drop the reference to the parent object, ifcircular references are constructed. It is valid in some cases, that aparent objects references a child. Circular references _must_ be brokenwith an explicit call tokobject_del(), so that a release functions will becalled, and the objects in the former circle release each other.

Example code to copy from¶

For a more complete example of using ksets and kobjects properly, see theexample programssamples/kobject/{kobject-example.c,kset-example.c},which will be built as loadable modules if you selectCONFIG_SAMPLE_KOBJECT.