The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/Documentation/kobject.txt

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 Everything you never wanted to know about kobjects, ksets, and ktypes
    2 
    3 Greg Kroah-Hartman <gregkh@linuxfoundation.org>
    4 
    5 Based on an original article by Jon Corbet for lwn.net written October 1,
    6 2003 and located at http://lwn.net/Articles/51437/
    7 
    8 Last updated December 19, 2007
    9 
   10 
   11 Part of the difficulty in understanding the driver model - and the kobject
   12 abstraction upon which it is built - is that there is no obvious starting
   13 place. Dealing with kobjects requires understanding a few different types,
   14 all of which make reference to each other. In an attempt to make things
   15 easier, we'll take a multi-pass approach, starting with vague terms and
   16 adding detail as we go. To that end, here are some quick definitions of
   17 some 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 
   28    No structure should EVER have more than one kobject embedded within it.
   29    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 
   45 We'll look at how to create and manipulate all of these types. A bottom-up
   46 approach will be taken, so we'll go back to kobjects.
   47 
   48 
   49 Embedding kobjects
   50 
   51 It is rare for kernel code to create a standalone kobject, with one major
   52 exception explained below.  Instead, kobjects are used to control access to
   53 a larger, domain-specific object.  To this end, kobjects will be found
   54 embedded in other structures.  If you are used to thinking of things in
   55 object-oriented terms, kobjects can be seen as a top-level, abstract class
   56 from which other classes are derived.  A kobject implements a set of
   57 capabilities which are not particularly useful by themselves, but which are
   58 nice to have in other objects.  The C language does not allow for the
   59 direct expression of inheritance, so other techniques - such as structure
   60 embedding - must be used.
   61 
   62 (As an aside, for those familiar with the kernel linked list implementation,
   63 this is analogous as to how "list_head" structs are rarely useful on
   64 their own, but are invariably found embedded in the larger objects of
   65 interest.)
   66 
   67 So, for example, the UIO code in drivers/uio/uio.c has a structure that
   68 defines the memory region associated with a uio device:
   69 
   70     struct uio_map {
   71         struct kobject kobj;
   72         struct uio_mem *mem;
   73     };
   74 
   75 If you have a struct uio_map structure, finding its embedded kobject is
   76 just a matter of using the kobj member.  Code that works with kobjects will
   77 often have the opposite problem, however: given a struct kobject pointer,
   78 what is the pointer to the containing structure?  You must avoid tricks
   79 (such as assuming that the kobject is at the beginning of the structure)
   80 and, instead, use the container_of() macro, found in <linux/kernel.h>:
   81 
   82     container_of(pointer, type, member)
   83 
   84 where:
   85 
   86   * "pointer" is the pointer to the embedded kobject,
   87   * "type" is the type of the containing structure, and
   88   * "member" is the name of the structure field to which "pointer" points.
   89 
   90 The return value from container_of() is a pointer to the corresponding
   91 container type. So, for example, a pointer "kp" to a struct kobject
   92 embedded *within* a struct uio_map could be converted to a pointer to the
   93 *containing* uio_map structure with:
   94 
   95     struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
   96 
   97 For convenience, programmers often define a simple macro for "back-casting"
   98 kobject pointers to the containing type.  Exactly this happens in the
   99 earlier drivers/uio/uio.c, as you can see here:
  100 
  101     struct uio_map {
  102         struct kobject kobj;
  103         struct uio_mem *mem;
  104     };
  105 
  106     #define to_map(map) container_of(map, struct uio_map, kobj)
  107 
  108 where the macro argument "map" is a pointer to the struct kobject in
  109 question.  That macro is subsequently invoked with:
  110 
  111     struct uio_map *map = to_map(kobj);
  112 
  113 
  114 Initialization of kobjects
  115 
  116 Code which creates a kobject must, of course, initialize that object. Some
  117 of the internal fields are setup with a (mandatory) call to kobject_init():
  118 
  119     void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
  120 
  121 The ktype is required for a kobject to be created properly, as every kobject
  122 must have an associated kobj_type.  After calling kobject_init(), to
  123 register the kobject with sysfs, the function kobject_add() must be called:
  124 
  125     int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);
  126 
  127 This sets up the parent of the kobject and the name for the kobject
  128 properly.  If the kobject is to be associated with a specific kset,
  129 kobj->kset must be assigned before calling kobject_add().  If a kset is
  130 associated with a kobject, then the parent for the kobject can be set to
  131 NULL in the call to kobject_add() and then the kobject's parent will be the
  132 kset itself.
  133 
  134 As the name of the kobject is set when it is added to the kernel, the name
  135 of the kobject should never be manipulated directly.  If you must change
  136 the name of the kobject, call kobject_rename():
  137 
  138     int kobject_rename(struct kobject *kobj, const char *new_name);
  139 
  140 kobject_rename does not perform any locking or have a solid notion of
  141 what names are valid so the caller must provide their own sanity checking
  142 and serialization.
  143 
  144 There is a function called kobject_set_name() but that is legacy cruft and
  145 is being removed.  If your code needs to call this function, it is
  146 incorrect and needs to be fixed.
  147 
  148 To properly access the name of the kobject, use the function
  149 kobject_name():
  150 
  151     const char *kobject_name(const struct kobject * kobj);
  152 
  153 There is a helper function to both initialize and add the kobject to the
  154 kernel at the same time, called surprisingly enough kobject_init_and_add():
  155 
  156     int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
  157                              struct kobject *parent, const char *fmt, ...);
  158 
  159 The arguments are the same as the individual kobject_init() and
  160 kobject_add() functions described above.
  161 
  162 
  163 Uevents
  164 
  165 After a kobject has been registered with the kobject core, you need to
  166 announce to the world that it has been created.  This can be done with a
  167 call to kobject_uevent():
  168 
  169     int kobject_uevent(struct kobject *kobj, enum kobject_action action);
  170 
  171 Use the KOBJ_ADD action for when the kobject is first added to the kernel.
  172 This should be done only after any attributes or children of the kobject
  173 have been initialized properly, as userspace will instantly start to look
  174 for them when this call happens.
  175 
  176 When the kobject is removed from the kernel (details on how to do that is
  177 below), the uevent for KOBJ_REMOVE will be automatically created by the
  178 kobject core, so the caller does not have to worry about doing that by
  179 hand.
  180 
  181 
  182 Reference counts
  183 
  184 One of the key functions of a kobject is to serve as a reference counter
  185 for the object in which it is embedded. As long as references to the object
  186 exist, the object (and the code which supports it) must continue to exist.
  187 The low-level functions for manipulating a kobject's reference counts are:
  188 
  189     struct kobject *kobject_get(struct kobject *kobj);
  190     void kobject_put(struct kobject *kobj);
  191 
  192 A successful call to kobject_get() will increment the kobject's reference
  193 counter and return the pointer to the kobject.
  194 
  195 When a reference is released, the call to kobject_put() will decrement the
  196 reference count and, possibly, free the object. Note that kobject_init()
  197 sets the reference count to one, so the code which sets up the kobject will
  198 need to do a kobject_put() eventually to release that reference.
  199 
  200 Because kobjects are dynamic, they must not be declared statically or on
  201 the stack, but instead, always allocated dynamically.  Future versions of
  202 the kernel will contain a run-time check for kobjects that are created
  203 statically and will warn the developer of this improper usage.
  204 
  205 If all that you want to use a kobject for is to provide a reference counter
  206 for your structure, please use the struct kref instead; a kobject would be
  207 overkill.  For more information on how to use struct kref, please see the
  208 file Documentation/kref.txt in the Linux kernel source tree.
  209 
  210 
  211 Creating "simple" kobjects
  212 
  213 Sometimes all that a developer wants is a way to create a simple directory
  214 in the sysfs hierarchy, and not have to mess with the whole complication of
  215 ksets, show and store functions, and other details.  This is the one
  216 exception where a single kobject should be created.  To create such an
  217 entry, use the function:
  218 
  219     struct kobject *kobject_create_and_add(char *name, struct kobject *parent);
  220 
  221 This function will create a kobject and place it in sysfs in the location
  222 underneath the specified parent kobject.  To create simple attributes
  223 associated with this kobject, use:
  224 
  225     int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
  226 or
  227     int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);
  228 
  229 Both types of attributes used here, with a kobject that has been created
  230 with the kobject_create_and_add(), can be of type kobj_attribute, so no
  231 special custom attribute is needed to be created.
  232 
  233 See the example module, samples/kobject/kobject-example.c for an
  234 implementation of a simple kobject and attributes.
  235 
  236 
  237 
  238 ktypes and release methods
  239 
  240 One important thing still missing from the discussion is what happens to a
  241 kobject when its reference count reaches zero. The code which created the
  242 kobject generally does not know when that will happen; if it did, there
  243 would be little point in using a kobject in the first place. Even
  244 predictable object lifecycles become more complicated when sysfs is brought
  245 in as other portions of the kernel can get a reference on any kobject that
  246 is registered in the system.
  247 
  248 The end result is that a structure protected by a kobject cannot be freed
  249 before its reference count goes to zero. The reference count is not under
  250 the direct control of the code which created the kobject. So that code must
  251 be notified asynchronously whenever the last reference to one of its
  252 kobjects goes away.
  253 
  254 Once you registered your kobject via kobject_add(), you must never use
  255 kfree() to free it directly. The only safe way is to use kobject_put(). It
  256 is good practice to always use kobject_put() after kobject_init() to avoid
  257 errors creeping in.
  258 
  259 This notification is done through a kobject's release() method. Usually
  260 such a method has a form like:
  261 
  262     void my_object_release(struct kobject *kobj)
  263     {
  264             struct my_object *mine = container_of(kobj, struct my_object, kobj);
  265 
  266             /* Perform any additional cleanup on this object, then... */
  267             kfree(mine);
  268     }
  269 
  270 One important point cannot be overstated: every kobject must have a
  271 release() method, and the kobject must persist (in a consistent state)
  272 until that method is called. If these constraints are not met, the code is
  273 flawed.  Note that the kernel will warn you if you forget to provide a
  274 release() method.  Do not try to get rid of this warning by providing an
  275 "empty" release function; you will be mocked mercilessly by the kobject
  276 maintainer if you attempt this.
  277 
  278 Note, the name of the kobject is available in the release function, but it
  279 must NOT be changed within this callback.  Otherwise there will be a memory
  280 leak in the kobject core, which makes people unhappy.
  281 
  282 Interestingly, the release() method is not stored in the kobject itself;
  283 instead, it is associated with the ktype. So let us introduce struct
  284 kobj_type:
  285 
  286     struct kobj_type {
  287             void (*release)(struct kobject *kobj);
  288             const struct sysfs_ops *sysfs_ops;
  289             struct attribute **default_attrs;
  290             const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
  291             const void *(*namespace)(struct kobject *kobj);
  292     };
  293 
  294 This structure is used to describe a particular type of kobject (or, more
  295 correctly, of containing object). Every kobject needs to have an associated
  296 kobj_type structure; a pointer to that structure must be specified when you
  297 call kobject_init() or kobject_init_and_add().
  298 
  299 The release field in struct kobj_type is, of course, a pointer to the
  300 release() method for this type of kobject. The other two fields (sysfs_ops
  301 and default_attrs) control how objects of this type are represented in
  302 sysfs; they are beyond the scope of this document.
  303 
  304 The default_attrs pointer is a list of default attributes that will be
  305 automatically created for any kobject that is registered with this ktype.
  306 
  307 
  308 ksets
  309 
  310 A kset is merely a collection of kobjects that want to be associated with
  311 each other.  There is no restriction that they be of the same ktype, but be
  312 very careful if they are not.
  313 
  314 A kset serves these functions:
  315 
  316  - It serves as a bag containing a group of objects. A kset can be used by
  317    the kernel to track "all block devices" or "all PCI device drivers."
  318 
  319  - A kset is also a subdirectory in sysfs, where the associated kobjects
  320    with the kset can show up.  Every kset contains a kobject which can be
  321    set up to be the parent of other kobjects; the top-level directories of
  322    the sysfs hierarchy are constructed in this way.
  323 
  324  - Ksets can support the "hotplugging" of kobjects and influence how
  325    uevent events are reported to user space.
  326 
  327 In object-oriented terms, "kset" is the top-level container class; ksets
  328 contain their own kobject, but that kobject is managed by the kset code and
  329 should not be manipulated by any other user.
  330 
  331 A kset keeps its children in a standard kernel linked list.  Kobjects point
  332 back to their containing kset via their kset field. In almost all cases,
  333 the kobjects belonging to a kset have that kset (or, strictly, its embedded
  334 kobject) in their parent.
  335 
  336 As a kset contains a kobject within it, it should always be dynamically
  337 created and never declared statically or on the stack.  To create a new
  338 kset use:
  339   struct kset *kset_create_and_add(const char *name,
  340                                    struct kset_uevent_ops *u,
  341                                    struct kobject *parent);
  342 
  343 When you are finished with the kset, call:
  344   void kset_unregister(struct kset *kset);
  345 to destroy it.
  346 
  347 An example of using a kset can be seen in the
  348 samples/kobject/kset-example.c file in the kernel tree.
  349 
  350 If a kset wishes to control the uevent operations of the kobjects
  351 associated with it, it can use the struct kset_uevent_ops to handle it:
  352 
  353 struct kset_uevent_ops {
  354         int (*filter)(struct kset *kset, struct kobject *kobj);
  355         const char *(*name)(struct kset *kset, struct kobject *kobj);
  356         int (*uevent)(struct kset *kset, struct kobject *kobj,
  357                       struct kobj_uevent_env *env);
  358 };
  359 
  360 
  361 The filter function allows a kset to prevent a uevent from being emitted to
  362 userspace for a specific kobject.  If the function returns 0, the uevent
  363 will not be emitted.
  364 
  365 The name function will be called to override the default name of the kset
  366 that the uevent sends to userspace.  By default, the name will be the same
  367 as the kset itself, but this function, if present, can override that name.
  368 
  369 The uevent function will be called when the uevent is about to be sent to
  370 userspace to allow more environment variables to be added to the uevent.
  371 
  372 One might ask how, exactly, a kobject is added to a kset, given that no
  373 functions which perform that function have been presented.  The answer is
  374 that this task is handled by kobject_add().  When a kobject is passed to
  375 kobject_add(), its kset member should point to the kset to which the
  376 kobject will belong.  kobject_add() will handle the rest.
  377 
  378 If the kobject belonging to a kset has no parent kobject set, it will be
  379 added to the kset's directory.  Not all members of a kset do necessarily
  380 live in the kset directory.  If an explicit parent kobject is assigned
  381 before the kobject is added, the kobject is registered with the kset, but
  382 added below the parent kobject.
  383 
  384 
  385 Kobject removal
  386 
  387 After a kobject has been registered with the kobject core successfully, it
  388 must be cleaned up when the code is finished with it.  To do that, call
  389 kobject_put().  By doing this, the kobject core will automatically clean up
  390 all of the memory allocated by this kobject.  If a KOBJ_ADD uevent has been
  391 sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
  392 any other sysfs housekeeping will be handled for the caller properly.
  393 
  394 If you need to do a two-stage delete of the kobject (say you are not
  395 allowed to sleep when you need to destroy the object), then call
  396 kobject_del() which will unregister the kobject from sysfs.  This makes the
  397 kobject "invisible", but it is not cleaned up, and the reference count of
  398 the object is still the same.  At a later time call kobject_put() to finish
  399 the cleanup of the memory associated with the kobject.
  400 
  401 kobject_del() can be used to drop the reference to the parent object, if
  402 circular references are constructed.  It is valid in some cases, that a
  403 parent objects references a child.  Circular references _must_ be broken
  404 with an explicit call to kobject_del(), so that a release functions will be
  405 called, and the objects in the former circle release each other.
  406 
  407 
  408 Example code to copy from
  409 
  410 For a more complete example of using ksets and kobjects properly, see the
  411 example programs samples/kobject/{kobject-example.c,kset-example.c},
  412 which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.

Cache object: c1a6e4525e87e3715f3f143b7b33f3fc


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.