Documentation/core-api/kobject.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/kobject.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/kobject.rst
Extension
.rst
Size
19258 bytes
Lines
435
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

If you have a struct uio_map structure, finding its embedded kobject is
just a matter of using the kobj member.  Code that works with kobjects will
often 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 the container_of() macro, found in ``<linux/container_of.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 which ``pointer`` points.

The return value from container_of() is a pointer to the corresponding
container type. So, for example, a pointer ``kp`` to a struct kobject
embedded **within** a struct uio_map could be converted to a pointer to the
**containing** uio_map structure with::

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

For convenience, programmers often define a simple macro for **back-casting**
kobject pointers to the containing type.  Exactly this happens in the
earlier ``drivers/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 in
question.  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. Some
of the internal fields are setup with a (mandatory) call to kobject_init()::

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

The ktype is required for a kobject to be created properly, as every kobject
must have an associated kobj_type.  After calling kobject_init(), to
register the kobject with sysfs, the function kobject_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 kobject
properly.  If the kobject is to be associated with a specific kset,
kobj->kset must be assigned before calling kobject_add().  If a kset is
associated with a kobject, then the parent for the kobject can be set to
NULL in the call to kobject_add() and then the kobject's parent will be the
kset itself.

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

Annotation

Implementation Notes