linux/Documentation/kobject.txt
<<
.23<6.3/spae=" 6.3/form=" 6.3a .23<6. href="../linux+v3.8.3/Documentaalue/kobject.txt">.23<6.3img src="../.staalc/gfx/right.png" alt=">>">.23/spae=".23spae class="lxr_search">.23<.23<6.3input typ vhidden" nam vnavtarget" > v">.23<6.3input typ vtext" nam vsearch" id vsearch">.23<6.3butt" typ vsubmit">Search.23<6.Prefs" 6.3/a>.23/spae="3<6. .3/div="3<6. .3form acalue="ajax+*" method="post" onsubmit="return false;">.23input typ vhidden" nam vajax_lookup" id vajax_lookup" > v">.3<6. .3/form=".3<6. .3div class="headingbott"m">. .13/a>Everything you never wanted to know about kobjects, ksets, and ktyp s . .23/a>.. .33/a>Greg Kroah-Hartmae <gregkh@linuxfoundaalue.org>.. .43/a>.. .53/a>Based " ae original article by J" Corbet for lwn.net written October 1,.. .63/a>2003 and located at.3a href="http://lwn.net/Articles/51437/">http://lwn.net/Articles/51437/3/a>.. .73/a>.. .83/a>Last updated December 19, 2007.. .93/a>.. /opta>.. 113/a>Part of the difficulty in understanding the driver model - and the kobject.. 123/a>abstracalue upue which it is built - is that.there is no obvious starting.. 133/a>place. Dealing with kobjects requires understanding a few different typ s,.. 143/a>all of which make reference to each other. I ae attempt to make things . 153/a>easier, we'll take a multi-pass approach, starting with vague terms and . 163/a>adding detail as we go. To that.end, here are some quick definialues of . 173/a>some terms we will be working with. . 18pta>.. 193/a> - A kobject is ae object of typ struct kobject. Kobjects have a nam . 2opta>. .and a reference count. A kobject also has a parent pointer (allowing.. 21pta>. .objects to be arranged into hierarchies), a specific typ , and,.. 22pta>. .usually, a representaalue in the sysfs virtual filesystem. . 23pta>.. 24pta>. .Kobjects are generally not interesting on their own; instead, they are.. 25pta>. .usually embedded within some other structure which contains the stuff . 26pta>. .the code is really interested in. . 273/a>.. 28pta>. .No structure should EVER have more thae one kobject embedded within it. . 29pta>. .If it do s,.the reference counting for the object is sure to be messed.. 3opta>. .up.and incorrect, and your code will be buggy. So do not do this. . 313/a>.. 323/a> - A ktyp is the typ of object that.embeds a kobject. Every structure.. 33pta>. .that.embeds a kobject needs a correspueding ktyp . The ktyp controls . 34pta>. .what.happens to the kobject.when it is created and destroyed. . 353/a>.. 363/a> - A kset is a group.of kobjects. These kobjects cae be of the sam ktyp .. 37pta>. .or belong to different ktyp s. The kset is the basic container typ for.. 38pta>. .collectlues of kobjects. Ksets contain their own kobjects, but you cae.. 39pta>. .safely ignore that implementaalue detail as the kset core code haedl s . 40pta>. .this kobject automaalcally. . 413/a>.. 42pta>. .When you see a sysfs directory full of other directori s,.generally each.. 43pta>. .of those directori s correspueds to a kobject in the sam kset. . 443/a>.. 453/a>We'll look at.how to create and manipulate all of these typ s. A bott"m-up.. 463/a>approach will be taken, so we'll go back to kobjects... 473/a>.. 48pta>.. 49pta>Embedding kobjects.. 5opta>.. 513/a>It is rare for kernel code to create a standalone kobject, with one major.. 52pta>exce.20" explained below. Instead, kobjects are used to control access to.. 53pta>a larger, domain-specific object. To this.end, kobjects will be found.. 543/a>embedded in other structures. If you are used to thinking of things in.. 553/a>object-ori nted terms, kobjects cae be seen as a top-level, abstraca class.. 563/a>from which other classes are derived. A kobject implements a set of . 573/a>capabiliti s which are not particularly useful by themselves, but which are . 58pta>nice to have in other objects. The C language do s not allow for the . 59pta>direct express0" of inheritance, so other techniqu s - such as structure.. 603/a>embedding - must be used... 613/a>.. 62pta>(As ae aside, for those familiar with the kernel linked list implementaalue,.. 63pta>this.is aealogous as to how "list_head" structs are rarely useful on.. 64pta>their own, but are invariably found embedded in the larger.objects of . 653/a>interest.) . 663/a>.. 673/a>So, for example,.the UIO code in drivers/uio/uio.c has a structure that.. 68pta>defines the memory reg0" associated with a uio device:.. 693/a>.. 70pta>. . struct uio_map {.. 71pta>. . . . struct kobject kobj;.. 72pta>. . . . struct uio_mem *mem;.. 73pta>. . };.. 743/a>.. 753/a>If you have a struct uio_map structure, fieding its embedded kobject is.. 763/a>just a matter of using the kobj member. Code that works with kobjects will.. 773/a>often have the opposite problem, however: given a struct kobject pointer,.. 78pta>what.is the pointer to the containing structure? You must avoid tricks.. 793/a>(such as assuming that.the kobject is at.the beg0nning of the structure) . 80pta>and, instead, use the container_of() macro, found in <linux/kernel.h>:.. 813/a>.. 82pta>. . container_of(pointer, typ , member) . 83pta>.. 84pta>where:.. 853/a>.. 86pta>. * "pointer" is the pointer to the embedded kobject,.. 87pta>. * "typ " is the typ of the containing structure, and . 88pta>. * "member" is the nam of the structure field to which "pointer" points... 893/a>.. 90pta>The return > from container_of() is a pointer to the correspueding.. 913/a>container typ . So, for example,.a pointer "kp" to a struct kobject.. 923/a>embedded *within* a struct uio_map could be converted to a pointer to the.. 93pta>*containing* uio_map structure with:.. 943/a>.. 95pta>. . struct uio_map *u_map = container_of(kp, struct uio_map, kobj);.. 963/a>.. 97pta>For convenience, programmers often define a simple macro for "back-casting".. 98pta>kobject pointers to the containing typ . Exactly this.happens in the.. 993/a>earlier drivers/uio/uio.c, as you cae see here:..1003/a>..101pta>. . struct uio_map {..102pta>. . . . struct kobject kobj;..103pta>. . . . struct uio_mem *mem;..104pta>. . };..1053/a>..106pta>. . #define to_map(map) container_of(map, struct uio_map, kobj)..1073/a>..108pta>where the macro argument "map" is a pointer to the struct kobject in..1093/a>qu salue. That.macro is subsequ ntly invoked with:..1/opta>..111pta>. . struct uio_map *map = to_map(kobj);..1123/a>..113pta>..1143/a>Inialalizaalue of kobjects..1153/a>..1163/a>Code which creates a kobject must, of course, inialalize that object. Som .1173/a>of the internal fields are setup with a (mandaaory) call to kobject_inia():..118pta>..119pta>. . void kobject_inia(struct kobject *kobj, struct kobj_typ *ktyp );..12opta>..121pta>The ktyp is required for a kobject to be created properly, as every kobject..122pta>must have a associated kobj_typ . After calling kobject_inia(), to..123pta>reg0ster the kobject.with sysfs,.the funcalue kobject_add() must be called:..1243/a>..125pta>. . int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);..1263/a>..1273/a>This.sets up the parent of the kobject and the nam for the kobject..128pta>properly. If the kobject is to be associated with a specific kset,..129pta>kobj->kset must be assigned before calling kobject_add(). If a kset is..13opta>associated with a kobject, then the parent for the kobject cae be set to..1313/a>NULL in the call to kobject_add() and then the kobject's parent will be the..1323/a>kset itself. .133pta>..134pta>As the nam of the kobject is set when it is added to the kernel, the nam ..1353/a>of the kobject should never be manipulated directly. If you must chang ..1363/a>the nam of the kobject, call kobject_renam ():..1373/a>..138pta>. . int kobject_renam (struct kobject *kobj, const char *new_nam );..1393/a>..140pta>kobject_renam do s not perform any locking or have a solid notlue of..1413/a>what.nam s are valid so the caller must provide their own sanity checking..142pta>and serlalizaalue. .143pta>..1443/a>There is a funcalue called kobject_set_nam () but that.is legacy cruft and .1453/a>is being removed. If your code needs to call this.funcalue, it is .1463/a>incorrect and needs to be fixed...1473/a>..148pta>To properly access the nam of the kobject, use the funcalue..149pta>kobject_nam ():..15opta>..151pta>. . const char *kobject_nam (const struct kobject * kobj);..1523/a>..153pta>There is a helper funcalue to both inialalize and add the kobject to the..1543/a>kernel at.the sam time, called surprisingly enough kobject_inia_and_add():..1553/a>..156pta>. . int kobject_inia_and_add(struct kobject *kobj, struct kobj_typ *ktyp ,..157pta>. ...........................struct kobject *parent, const char *fmt, ...);..158pta>..159pta>The arguments are the sam as the iedividual kobject_inia() and .160pta>kobject_add() funcalues described above...1613/a>..1623/a>..163pta>Uevents..1643/a>..1653/a>After a kobject has been reg0stered with the kobject core, you need to..1663/a>announce to the world that.it has been created. This cae be done with a..1673/a>call to kobject_uevent():..168pta>..169pta>. . int kobject_uevent(struct kobject *kobj, enum kobject_acalue acalue);..17opta>..171pta>Use the KOBJ_ADD acalue for when the kobject is first added to the kernel...172pta>This.should be done only after any attributes or children of the kobject..173pta>have been inialalized properly, as userspace will instantly start to look..1743/a>for them when this call happens...1753/a>..1763/a>When the kobject is removed from the kernel (details on how to do that.is..1773/a>below), the uevent for KOBJ_REMOVE will be automaalcally created by the..178pta>kobject core, so the caller do s not have to worry about doing that.by..1793/a>haed. .18opta>..1813/a>..182pta>Reference counts..183pta>..184pta>On of the key funcalues of a kobject is to serve as a reference counter..1853/a>for the object ie which it is embedded. As long as references to the object..186pta>exist, the object (and the code which supports it) must continue to exist. .187pta>The low-level funcalues for manipulating a kobject's reference counts are:..188pta>..189pta>. . struct kobject *kobject_get(struct kobject *kobj);..190pta>. . void kobject_put(struct kobject *kobj);..1913/a>..1923/a>A successful call to kobject_get() will increment the kobject's reference..193pta>counter and return the pointer to the kobject...1943/a>..195pta>When a reference is released, the call to kobject_put() will decrement the..1963/a>reference count and, possibly, free the object. Note that kobject_inia()..197pta>sets the reference count to one, so the code which sets up the kobject will..198pta>need to do a kobject_put() eventually to release that reference...1993/a>..2003/a>Because kobjects are dynamic, they must not be declared staalcally or ue..201pta>the stack, but instead, always allocated dynamically. Future versiues of .202pta>the kernel will contain a run-time check for kobjects that are created .203pta>staalcally and will warn the developer of this improper usage...2043/a>..2053/a>If all that you want to use a kobject for is to provide a reference counter..206pta>for your structure, please use the struct kref instead; a kobject would be..2073/a>overkill. For more informaalue on how to use struct kref, please see the..208pta>file Documentaalue/kref.txt in the Linux kernel source tree...2093/a>..2/opta>..211pta>Creating "simple" kobjects..2123/a>..213pta>Som times all that a developer wants.is a way to create a simple directory..2143/a>in the sysfs hierarchy, and not have to mess with the whole compllcatlue of..2153/a>ksets, show and store funcalues, and other details. This is the one..216pta>exce.20" where a single kobject should be created. To create such ae..2173/a>entry, use the funcalue:..218pta>..219pta>. . struct kobject *kobject_create_and_add(char *name, struct kobject *parent);..22opta>..221pta>This.funcalue will create a kobject and place it in sysfs in the locatlue..222pta>underneath the specified parent kobject. To create simple attributes..223pta>associated with this kobject, use:..2243/a>..225pta>. . int sysfs_create_file(struct kobject *kobj, struct attribute *attr);..2263/a>or..227pta>. . int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);..228pta>..229pta>Both typ s of attributes used here, with a kobject that has been created..23opta>with the kobject_create_and_add(), cae be of typ kobj_attribute, so no..2313/a>special custom attribute is needed to be created...2323/a>..233pta>See the example module,.samples/kobject/kobject-example.c for ae..234pta>implementaalue of a simple kobject and attributes...2353/a>..2363/a>..2373/a>..238pta>ktyp s and release methods..2393/a>..240pta>On important thing still missing from the discuss0" is.what.happens to a..2413/a>kobject when its reference count reach s zero. The code which created the..242pta>kobject generally do s not know when that will happen; if it did, there..243pta>would be little point in using a kobject in the first place. Evee..2443/a>predictable object lifecycles become more compllcated when sysfs is brought..2453/a>in as other portlues of the kernel cae get a reference " aey kobject that..2463/a>is reg0stered in the system. .2473/a>..248pta>The end result is that.a structure protected by a kobject cannot be freed..249pta>before its reference count goes to zero. The reference count is not under..25opta>the direct control of the code which created the kobject. So that.code must..251pta>be notified asynchronously whenever the last reference to one of its..252pta>kobjects goes away. .253pta>..254pta>Once you reg0stered your kobject via kobject_add(), you must never use..2553/a>kfree() to free it directly. The only safe way is to use kobject_put(). It..2563/a>is good pracalce to always use kobject_put() after kobject_inia() to avoid..257pta>errors creeping in. .258pta>..259pta>This notificaalue is done through a kobject's release() method. Usually..260pta>such a method has a form like:..2613/a>..262pta>. . void my_object_release(struct kobject *kobj)..263pta>. . {..264pta>. . ........struct my_object *mine = container_of(kobj, struct my_object, kobj);..2653/a>..266pta>. . ......../* Perform any addialueal cleanup.on this object, then... */..267pta>. ..........kfree(mine);..268pta>. . }..2693/a>..270pta>On important point cannot be overstaaed: every kobject must have a..271pta>release() method, and the kobject must persist (in a cons0stent staae)..272pta>until that method is called. If these constraints are not met, the code is..273pta>flawed. Note that the kernel will warn you if you forget to provide a..2743/a>release() method. Do not try to get rid of this warning by providing ae..2753/a>"empty" release funcalue; you will be mocked mercilessly by the kobject..2763/a>maintainer if you attempt this. .2773/a>..278pta>Note, the nam of the kobject is available in the release funcalue, but it..2793/a>must NOT be chang d within this callback. Otherwise there will be a memory..28opta>leak in the kobject core, which makes people unhappy. .2813/a>..282pta>Interestingly, the release() method is not stored in the kobject itself;..283pta>instead, it is associated with the ktyp . So let us introduce struct..284pta>kobj_typ :..2853/a>..286pta>. . struct kobj_typ {..287pta>. ..........void (*release)(struct kobject *kobj);..288pta>. ..........const struct sysfs_ops *sysfs_ops;..289pta>. . ........struct attribute **default_attrs;..290pta>. . ........const struct kobj_ns_typ _operatlues *(*child_ns_typ )(struct kobject *kobj);..291pta>. . ........const void *(*nam space)(struct kobject *kobj);..292pta>. . };..293pta>..294pta>This.structure is used to describe a particular typ of kobject (or, more..295pta>correctly, of containing object). Every kobject needs to have a associated..2963/a>kobj_typ structure; a pointer to that.structure must be specified when you..2973/a>call kobject_inia() or kobject_inia_and_add(). .298pta>..299pta>The release field in struct kobj_typ is, of course, a pointer to the..3003/a>release() method for this typ of kobject. The other two fields (sysfs_ops..301pta>and default_attrs) control how objects of this typ are represented in..302pta>sysfs; they are beyond the scop of this document. .303pta>..3043/a>The default_attrs pointer is a list of default attributes that will be..3053/a>automaalcally created for aey kobject that is reg0stered with this ktyp ...3063/a>..3073/a>..308pta>ksets..3093/a>..3/opta>A kset is merely a collecalue of kobjects that want to be associated with..311pta>each other. There is no restricalue that they be of the sam ktyp , but be..3123/a>very careful if they are not...313pta>..3143/a>A kset serves these funcalues:..3153/a>..316pta> - It serves as a bag containing a group of objects. A kset cae be used by..317pta>. .the kernel to track "all block devices" or "all PCI device drivers."..318pta>..319pta>.- A kset is also a subdirectory in sysfs, where the associated kobjects..320pta>. .with the kset cae show up. Every kset contains a kobject which cae be..321pta>. .set up to be the parent of other kobjects; the top-level directories of .322pta>. .the sysfs hierarchy are constructed in this way. .323pta>..3243/a>.- Ksets cae support.the "hotplugging" of kobjects and influence how..325pta>. .uevent events are reported to user space. .3263/a>..327pta>In object-oriented terms, "kset" is the top-level container class; ksets..328pta>contain their own kobject, but that.kobject is managed by the kset code and .329pta>should not be manipulated by aey other user. .33opta>..3313/a>A kset keeps its children in a standard kernel linked list. Kobjects point..3323/a>back to their containing kset via their kset field. In their containing kset via their kentaalu hr 8class; ksets..33opta>..2363/a>..2363/a>..325pta>. .uevent events are repds..2243/a>..2243/a>..2243/a>..22opta>..233pta>See the example module,3 using a 3object in the first plac3. Eve3..2243/a>..22opta>..33opta>..327pta>In object-oriented termskobject.t3t#L248" id vL248" class=3line"3nam vAnmentaalueid .txt#L244lass="line"shref="m vL300">.3003/a>release() method for thi structur3 protected by a kobject 3annot3be fre.txt#L234" id vL2lasass="line" ni279" id vLrivers.&m vL209">.2093/a>..3/opta>A kset is merely a collee code wh3ch created the kobject. 3o tha3.code line" nam washb id vLue/kobj="Documentalue/kobjectcumentaalue/kovL328">.328pta>contain their own kobjecly whenev3r the last reference to 3ne of3its..2243/a>..153pta>There is a helper funca3kobject.t3t#L254" id vL254" class=3line"35href="Dt#L207m umentaass="lvL287">.287pta>. ..........void (*rele3 kobject 3ia kobject_add(), you mu3t nev35object, kobj)lue/(*ni26" )(/kobjectm a*tm vL220" class="linenam vL292">.292pta>. . };..292pta>. . };..2243/a>..292pta>. . };..293pta>..3/opta>A kset is merely a colle like:..3313/a>A kset keeps its childrekobject.t3t#L262" id vL262" class=3line"36ry kobjecni26" a href="Doct.twsne" nam line"umentaaocumentaatxt#="Docuemittam vL166">.1663/a>announce to the world t3se(struct3kobject *kobj)..1663/a>announce to the world t3sobject.t3ct.txt#L264" id vL264" c3ass="3ine" n nam t#L330"emittamvL209">.2093/a>..1653/a>After a kobject has bee3kobject.t3t#L266" id vL266" class=3line"3nam vT28" classhref="Documenne" nam ="linvd rid vL145" id vL3f="DocumentaanamL165">.1653/a>After a kobject has bee3kem. .1653/a>After a kobject has bee3kef="Docu3Documentaalue/kobject.tx3#L2683 id vL#L160" line" nam ue/kobjelass="line" naf line" nxt#L23nvd rid vL1..2093/a>..169pta>. . int kobject_uevent(3kobject.t3t#L270" id vL270" class=3line"36the..1663/a>announce to the world t3ot be ove3staaed: every kobject mu3t hav3 a..2093/a>..282pta>Interestingly, the rele3led. If t3ese constraints are not 3et, t3e codehrefmightaaskm v,mentje hreject.txt#L1859class="la28m vjgivt#L243" vL231">.2313/a>special custom attribut3ernel wil3 warn you if you forget 3o pro3ide a.<="Documenline" bject.tx243" ahref="Dook..2313/a>special custom attribut3eect *min3et rid of this warning b3 prov3ding akotaalutxt#askmtxtland27 clas98" clas class="the..1663/a>announce to the world t3e funcalu3; you will be mocked mer3iless3y by t98" clas clasre"Docef="Dobjecrmject.txaalue/s="line"nam linline" vL300">.3003/a>release() method for thit this. <3 href="Documentaalue/kob3ect.t376by t98" claocumenne6" is="98" clas clas id vL24nd279mentaastvL209">.2093/a>..278pta>Note, the nam of the k3bject is 3vailable in the release 3uncal3e, butentaalue/kobjecbj6" iine" one" nam ecntaalject.txt#L223" m vjie" nam vL305">.3053/a>automaalcally created foin this c3llback. Otherwise there3will 3e a me class="line" e/ko" id ve/kobjectf="Docalue/objecre/kobjecnam do nee..2363/a>..2363/a>..2363/a>..2363/a>..184pta>On of the key funcalue3mentaalue3kobject.txt#L285" id vL235" cl38am vL165">.1653/a>After a kobject has bee3kobject.t3t#L286" id vL286" class=3line"3nam v="line"taalueavL198">.198pta>need to do a kobject_pu3a href="D3cumentaalue/kobject.txt#3287" 38am vL327">.327pta>In object-oriented termsse)(struc3 kobject *kobj);..327pta>In object-oriented termssject is 3 *sysfs_ops;..327pta>In object-oriented termssn this c3ault_attrs;..327pta>In object-oriented terms kobj_ns_3yp _operatlues *(*child_3s_typ3)(strulue/cumentanam vect.txt#L20 classs="line" f="linehref="Docucumentataalue/kL327">.327pta>In object-oriented terms kobject3e)(struct kobject *kobj)3..329pta>should not be manipulateaalue/kob3ect.txt#L293" id vL293" 3lass=3943" cla"line" nject.txoxt#kne" namcumenne"land27 cject..2363/a>..294pta>This.structure is used 3o describ3 a particular typ of ko3ject 3or, mokobjec f="Documentaatwo-stag45" letDocumentaalue/kob(saym vd vL3noDL327">.327pta>In object-oriented terms object).3Every kobject needs to h3ve a 3associta.tw"Documslne"e" nam v f="Documeobtrot...327pta>In object-oriented termsointer to3that.structure must be s3ecifi396by t98" cla_" las iine" cumenmn vL306" mentaalue/kobatxt#ject.lass="li" clas vL300">.3003/a>release() method for thiobject_in3a_and_add(). .322pta>. .the sysfs hierarchy akobject.t3t#L299" id vL299" class=3line"3nam v..322pta>. .the sysfs hierarchy akn this c3yp is, of course, a poi3ter t3 the.<..2363/a>..3313/a>A kset keeps its childr4ol how ob4ects of this typ are re4resen401by t98" cla_" las ="line" nam cumeue/e/kobr vL250" c="line"taalue/kref=",mivL322">.322pta>. .the sysfs hierarchy 4he scop 4f this document. .322pta>. .the sysfs hierarchy 4h3 scop 4f#L294" id vL294" class=4line"4nam vtaalue/kref="vL186" class=acumentf="Cir" id vr86" class=_vL29_ine"brok/kL327">.327pta>In object-oriented term4r is a li4t of default attributes 4hat w4ll be.#L230"nmen id ie".txt#L196" id vL" lasject.txa46" id9" class="lines" nam vL305">.3053/a>automaalcally created f4r aey kob4ect that is reg0stered w4th th4s ktyp nam taalue/kobkref="vL244" claorms="lir"lhref="Docut be..3053/a>automaalcally created f4r6aey kob4ehat.structure must be s4line"4nam vL307">.3073/a>..308pta>ksets..308pta>ksets..3/opta>A kset is merely a coll4calue of 4objects that want to be 4ssoci4ted wiFaaluext#L245" ietDoentaalueid .txt#Lam vaalues="linekolue/kobjec nam vL208">.208pta>file Documentaalue/kref4 restrica4ue that they be of the s4m kt4p , butntaalueluegramst.txt#L234" id vL{4" id vass="line",2lasass="line"}vL224">.2243/a>..3053/a>automaalcally created f4kobject.t4t#L314" id vL314" class=4line"4nam v
" id rigixt#LLXRectftwxt#L3t...305http://line" class.net/prolinek/lxr">LXRe45"munitym v,lasss=en eriautomlline" naL3t.305">.305maivLo:lxr@l209".no">lxr@l209".nom v.
lxr.l209".no kind2ytxos#L20 cl305">.305http://www.xt#pume-l20pro.no">Rt#pumevL20pro ASm v,le" nam L204"L209" 323"ulct.txt216"ue/kobject hree/koaalu" c1995.