Back to home page

LXR

 
 

    


0001 Everything you never wanted to know about kobjects, ksets, and ktypes
0002 
0003 Greg Kroah-Hartman <gregkh@linuxfoundation.org>
0004 
0005 Based on an original article by Jon Corbet for lwn.net written October 1,
0006 2003 and located at http://lwn.net/Articles/51437/
0007 
0008 Last updated December 19, 2007
0009 
0010 
0011 Part of the difficulty in understanding the driver model - and the kobject
0012 abstraction upon which it is built - is that there is no obvious starting
0013 place. Dealing with kobjects requires understanding a few different types,
0014 all of which make reference to each other. In an attempt to make things
0015 easier, we'll take a multi-pass approach, starting with vague terms and
0016 adding detail as we go. To that end, here are some quick definitions of
0017 some terms we will be working with.
0018 
0019  - A kobject is an object of type struct kobject.  Kobjects have a name
0020    and a reference count.  A kobject also has a parent pointer (allowing
0021    objects to be arranged into hierarchies), a specific type, and,
0022    usually, a representation in the sysfs virtual filesystem.
0023 
0024    Kobjects are generally not interesting on their own; instead, they are
0025    usually embedded within some other structure which contains the stuff
0026    the code is really interested in.
0027 
0028    No structure should EVER have more than one kobject embedded within it.
0029    If it does, the reference counting for the object is sure to be messed
0030    up and incorrect, and your code will be buggy.  So do not do this.
0031 
0032  - A ktype is the type of object that embeds a kobject.  Every structure
0033    that embeds a kobject needs a corresponding ktype.  The ktype controls
0034    what happens to the kobject when it is created and destroyed.
0035 
0036  - A kset is a group of kobjects.  These kobjects can be of the same ktype
0037    or belong to different ktypes.  The kset is the basic container type for
0038    collections of kobjects. Ksets contain their own kobjects, but you can
0039    safely ignore that implementation detail as the kset core code handles
0040    this kobject automatically.
0041 
0042    When you see a sysfs directory full of other directories, generally each
0043    of those directories corresponds to a kobject in the same kset.
0044 
0045 We'll look at how to create and manipulate all of these types. A bottom-up
0046 approach will be taken, so we'll go back to kobjects.
0047 
0048 
0049 Embedding kobjects
0050 
0051 It is rare for kernel code to create a standalone kobject, with one major
0052 exception explained below.  Instead, kobjects are used to control access to
0053 a larger, domain-specific object.  To this end, kobjects will be found
0054 embedded in other structures.  If you are used to thinking of things in
0055 object-oriented terms, kobjects can be seen as a top-level, abstract class
0056 from which other classes are derived.  A kobject implements a set of
0057 capabilities which are not particularly useful by themselves, but which are
0058 nice to have in other objects.  The C language does not allow for the
0059 direct expression of inheritance, so other techniques - such as structure
0060 embedding - must be used.
0061 
0062 (As an aside, for those familiar with the kernel linked list implementation,
0063 this is analogous as to how "list_head" structs are rarely useful on
0064 their own, but are invariably found embedded in the larger objects of
0065 interest.)
0066 
0067 So, for example, the UIO code in drivers/uio/uio.c has a structure that
0068 defines the memory region associated with a uio device:
0069 
0070     struct uio_map {
0071         struct kobject kobj;
0072         struct uio_mem *mem;
0073     };
0074 
0075 If you have a struct uio_map structure, finding its embedded kobject is
0076 just a matter of using the kobj member.  Code that works with kobjects will
0077 often have the opposite problem, however: given a struct kobject pointer,
0078 what is the pointer to the containing structure?  You must avoid tricks
0079 (such as assuming that the kobject is at the beginning of the structure)
0080 and, instead, use the container_of() macro, found in <linux/kernel.h>:
0081 
0082     container_of(pointer, type, member)
0083 
0084 where:
0085 
0086   * "pointer" is the pointer to the embedded kobject,
0087   * "type" is the type of the containing structure, and
0088   * "member" is the name of the structure field to which "pointer" points.
0089 
0090 The return value from container_of() is a pointer to the corresponding
0091 container type. So, for example, a pointer "kp" to a struct kobject
0092 embedded *within* a struct uio_map could be converted to a pointer to the
0093 *containing* uio_map structure with:
0094 
0095     struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
0096 
0097 For convenience, programmers often define a simple macro for "back-casting"
0098 kobject pointers to the containing type.  Exactly this happens in the
0099 earlier drivers/uio/uio.c, as you can see here:
0100 
0101     struct uio_map {
0102         struct kobject kobj;
0103         struct uio_mem *mem;
0104     };
0105 
0106     #define to_map(map) container_of(map, struct uio_map, kobj)
0107 
0108 where the macro argument "map" is a pointer to the struct kobject in
0109 question.  That macro is subsequently invoked with:
0110 
0111     struct uio_map *map = to_map(kobj);
0112 
0113 
0114 Initialization of kobjects
0115 
0116 Code which creates a kobject must, of course, initialize that object. Some
0117 of the internal fields are setup with a (mandatory) call to kobject_init():
0118 
0119     void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
0120 
0121 The ktype is required for a kobject to be created properly, as every kobject
0122 must have an associated kobj_type.  After calling kobject_init(), to
0123 register the kobject with sysfs, the function kobject_add() must be called:
0124 
0125     int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);
0126 
0127 This sets up the parent of the kobject and the name for the kobject
0128 properly.  If the kobject is to be associated with a specific kset,
0129 kobj->kset must be assigned before calling kobject_add().  If a kset is
0130 associated with a kobject, then the parent for the kobject can be set to
0131 NULL in the call to kobject_add() and then the kobject's parent will be the
0132 kset itself.
0133 
0134 As the name of the kobject is set when it is added to the kernel, the name
0135 of the kobject should never be manipulated directly.  If you must change
0136 the name of the kobject, call kobject_rename():
0137 
0138     int kobject_rename(struct kobject *kobj, const char *new_name);
0139 
0140 kobject_rename does not perform any locking or have a solid notion of
0141 what names are valid so the caller must provide their own sanity checking
0142 and serialization.
0143 
0144 There is a function called kobject_set_name() but that is legacy cruft and
0145 is being removed.  If your code needs to call this function, it is
0146 incorrect and needs to be fixed.
0147 
0148 To properly access the name of the kobject, use the function
0149 kobject_name():
0150 
0151     const char *kobject_name(const struct kobject * kobj);
0152 
0153 There is a helper function to both initialize and add the kobject to the
0154 kernel at the same time, called surprisingly enough kobject_init_and_add():
0155 
0156     int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
0157                              struct kobject *parent, const char *fmt, ...);
0158 
0159 The arguments are the same as the individual kobject_init() and
0160 kobject_add() functions described above.
0161 
0162 
0163 Uevents
0164 
0165 After a kobject has been registered with the kobject core, you need to
0166 announce to the world that it has been created.  This can be done with a
0167 call to kobject_uevent():
0168 
0169     int kobject_uevent(struct kobject *kobj, enum kobject_action action);
0170 
0171 Use the KOBJ_ADD action for when the kobject is first added to the kernel.
0172 This should be done only after any attributes or children of the kobject
0173 have been initialized properly, as userspace will instantly start to look
0174 for them when this call happens.
0175 
0176 When the kobject is removed from the kernel (details on how to do that are
0177 below), the uevent for KOBJ_REMOVE will be automatically created by the
0178 kobject core, so the caller does not have to worry about doing that by
0179 hand.
0180 
0181 
0182 Reference counts
0183 
0184 One of the key functions of a kobject is to serve as a reference counter
0185 for the object in which it is embedded. As long as references to the object
0186 exist, the object (and the code which supports it) must continue to exist.
0187 The low-level functions for manipulating a kobject's reference counts are:
0188 
0189     struct kobject *kobject_get(struct kobject *kobj);
0190     void kobject_put(struct kobject *kobj);
0191 
0192 A successful call to kobject_get() will increment the kobject's reference
0193 counter and return the pointer to the kobject.
0194 
0195 When a reference is released, the call to kobject_put() will decrement the
0196 reference count and, possibly, free the object. Note that kobject_init()
0197 sets the reference count to one, so the code which sets up the kobject will
0198 need to do a kobject_put() eventually to release that reference.
0199 
0200 Because kobjects are dynamic, they must not be declared statically or on
0201 the stack, but instead, always allocated dynamically.  Future versions of
0202 the kernel will contain a run-time check for kobjects that are created
0203 statically and will warn the developer of this improper usage.
0204 
0205 If all that you want to use a kobject for is to provide a reference counter
0206 for your structure, please use the struct kref instead; a kobject would be
0207 overkill.  For more information on how to use struct kref, please see the
0208 file Documentation/kref.txt in the Linux kernel source tree.
0209 
0210 
0211 Creating "simple" kobjects
0212 
0213 Sometimes all that a developer wants is a way to create a simple directory
0214 in the sysfs hierarchy, and not have to mess with the whole complication of
0215 ksets, show and store functions, and other details.  This is the one
0216 exception where a single kobject should be created.  To create such an
0217 entry, use the function:
0218 
0219     struct kobject *kobject_create_and_add(char *name, struct kobject *parent);
0220 
0221 This function will create a kobject and place it in sysfs in the location
0222 underneath the specified parent kobject.  To create simple attributes
0223 associated with this kobject, use:
0224 
0225     int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
0226 or
0227     int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);
0228 
0229 Both types of attributes used here, with a kobject that has been created
0230 with the kobject_create_and_add(), can be of type kobj_attribute, so no
0231 special custom attribute is needed to be created.
0232 
0233 See the example module, samples/kobject/kobject-example.c for an
0234 implementation of a simple kobject and attributes.
0235 
0236 
0237 
0238 ktypes and release methods
0239 
0240 One important thing still missing from the discussion is what happens to a
0241 kobject when its reference count reaches zero. The code which created the
0242 kobject generally does not know when that will happen; if it did, there
0243 would be little point in using a kobject in the first place. Even
0244 predictable object lifecycles become more complicated when sysfs is brought
0245 in as other portions of the kernel can get a reference on any kobject that
0246 is registered in the system.
0247 
0248 The end result is that a structure protected by a kobject cannot be freed
0249 before its reference count goes to zero. The reference count is not under
0250 the direct control of the code which created the kobject. So that code must
0251 be notified asynchronously whenever the last reference to one of its
0252 kobjects goes away.
0253 
0254 Once you registered your kobject via kobject_add(), you must never use
0255 kfree() to free it directly. The only safe way is to use kobject_put(). It
0256 is good practice to always use kobject_put() after kobject_init() to avoid
0257 errors creeping in.
0258 
0259 This notification is done through a kobject's release() method. Usually
0260 such a method has a form like:
0261 
0262     void my_object_release(struct kobject *kobj)
0263     {
0264             struct my_object *mine = container_of(kobj, struct my_object, kobj);
0265 
0266             /* Perform any additional cleanup on this object, then... */
0267             kfree(mine);
0268     }
0269 
0270 One important point cannot be overstated: every kobject must have a
0271 release() method, and the kobject must persist (in a consistent state)
0272 until that method is called. If these constraints are not met, the code is
0273 flawed.  Note that the kernel will warn you if you forget to provide a
0274 release() method.  Do not try to get rid of this warning by providing an
0275 "empty" release function; you will be mocked mercilessly by the kobject
0276 maintainer if you attempt this.
0277 
0278 Note, the name of the kobject is available in the release function, but it
0279 must NOT be changed within this callback.  Otherwise there will be a memory
0280 leak in the kobject core, which makes people unhappy.
0281 
0282 Interestingly, the release() method is not stored in the kobject itself;
0283 instead, it is associated with the ktype. So let us introduce struct
0284 kobj_type:
0285 
0286     struct kobj_type {
0287             void (*release)(struct kobject *kobj);
0288             const struct sysfs_ops *sysfs_ops;
0289             struct attribute **default_attrs;
0290             const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
0291             const void *(*namespace)(struct kobject *kobj);
0292     };
0293 
0294 This structure is used to describe a particular type of kobject (or, more
0295 correctly, of containing object). Every kobject needs to have an associated
0296 kobj_type structure; a pointer to that structure must be specified when you
0297 call kobject_init() or kobject_init_and_add().
0298 
0299 The release field in struct kobj_type is, of course, a pointer to the
0300 release() method for this type of kobject. The other two fields (sysfs_ops
0301 and default_attrs) control how objects of this type are represented in
0302 sysfs; they are beyond the scope of this document.
0303 
0304 The default_attrs pointer is a list of default attributes that will be
0305 automatically created for any kobject that is registered with this ktype.
0306 
0307 
0308 ksets
0309 
0310 A kset is merely a collection of kobjects that want to be associated with
0311 each other.  There is no restriction that they be of the same ktype, but be
0312 very careful if they are not.
0313 
0314 A kset serves these functions:
0315 
0316  - It serves as a bag containing a group of objects. A kset can be used by
0317    the kernel to track "all block devices" or "all PCI device drivers."
0318 
0319  - A kset is also a subdirectory in sysfs, where the associated kobjects
0320    with the kset can show up.  Every kset contains a kobject which can be
0321    set up to be the parent of other kobjects; the top-level directories of
0322    the sysfs hierarchy are constructed in this way.
0323 
0324  - Ksets can support the "hotplugging" of kobjects and influence how
0325    uevent events are reported to user space.
0326 
0327 In object-oriented terms, "kset" is the top-level container class; ksets
0328 contain their own kobject, but that kobject is managed by the kset code and
0329 should not be manipulated by any other user.
0330 
0331 A kset keeps its children in a standard kernel linked list.  Kobjects point
0332 back to their containing kset via their kset field. In almost all cases,
0333 the kobjects belonging to a kset have that kset (or, strictly, its embedded
0334 kobject) in their parent.
0335 
0336 As a kset contains a kobject within it, it should always be dynamically
0337 created and never declared statically or on the stack.  To create a new
0338 kset use:
0339   struct kset *kset_create_and_add(const char *name,
0340                                    struct kset_uevent_ops *u,
0341                                    struct kobject *parent);
0342 
0343 When you are finished with the kset, call:
0344   void kset_unregister(struct kset *kset);
0345 to destroy it.  This removes the kset from sysfs and decrements its reference
0346 count.  When the reference count goes to zero, the kset will be released.
0347 Because other references to the kset may still exist, the release may happen
0348 after kset_unregister() returns.
0349 
0350 An example of using a kset can be seen in the
0351 samples/kobject/kset-example.c file in the kernel tree.
0352 
0353 If a kset wishes to control the uevent operations of the kobjects
0354 associated with it, it can use the struct kset_uevent_ops to handle it:
0355 
0356 struct kset_uevent_ops {
0357         int (*filter)(struct kset *kset, struct kobject *kobj);
0358         const char *(*name)(struct kset *kset, struct kobject *kobj);
0359         int (*uevent)(struct kset *kset, struct kobject *kobj,
0360                       struct kobj_uevent_env *env);
0361 };
0362 
0363 
0364 The filter function allows a kset to prevent a uevent from being emitted to
0365 userspace for a specific kobject.  If the function returns 0, the uevent
0366 will not be emitted.
0367 
0368 The name function will be called to override the default name of the kset
0369 that the uevent sends to userspace.  By default, the name will be the same
0370 as the kset itself, but this function, if present, can override that name.
0371 
0372 The uevent function will be called when the uevent is about to be sent to
0373 userspace to allow more environment variables to be added to the uevent.
0374 
0375 One might ask how, exactly, a kobject is added to a kset, given that no
0376 functions which perform that function have been presented.  The answer is
0377 that this task is handled by kobject_add().  When a kobject is passed to
0378 kobject_add(), its kset member should point to the kset to which the
0379 kobject will belong.  kobject_add() will handle the rest.
0380 
0381 If the kobject belonging to a kset has no parent kobject set, it will be
0382 added to the kset's directory.  Not all members of a kset do necessarily
0383 live in the kset directory.  If an explicit parent kobject is assigned
0384 before the kobject is added, the kobject is registered with the kset, but
0385 added below the parent kobject.
0386 
0387 
0388 Kobject removal
0389 
0390 After a kobject has been registered with the kobject core successfully, it
0391 must be cleaned up when the code is finished with it.  To do that, call
0392 kobject_put().  By doing this, the kobject core will automatically clean up
0393 all of the memory allocated by this kobject.  If a KOBJ_ADD uevent has been
0394 sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
0395 any other sysfs housekeeping will be handled for the caller properly.
0396 
0397 If you need to do a two-stage delete of the kobject (say you are not
0398 allowed to sleep when you need to destroy the object), then call
0399 kobject_del() which will unregister the kobject from sysfs.  This makes the
0400 kobject "invisible", but it is not cleaned up, and the reference count of
0401 the object is still the same.  At a later time call kobject_put() to finish
0402 the cleanup of the memory associated with the kobject.
0403 
0404 kobject_del() can be used to drop the reference to the parent object, if
0405 circular references are constructed.  It is valid in some cases, that a
0406 parent objects references a child.  Circular references _must_ be broken
0407 with an explicit call to kobject_del(), so that a release functions will be
0408 called, and the objects in the former circle release each other.
0409 
0410 
0411 Example code to copy from
0412 
0413 For a more complete example of using ksets and kobjects properly, see the
0414 example programs samples/kobject/{kobject-example.c,kset-example.c},
0415 which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.