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