Lines Matching refs:the
11 Part of the difficulty in understanding the driver model - and the kobject
22 usually, a representation in the sysfs virtual filesystem.
25 usually embedded within some other structure which contains the stuff
26 the code is really interested in.
29 If it does, the reference counting for the object is sure to be messed
32 - A ktype is the type of object that embeds a kobject. Every structure
34 what happens to the kobject when it is created and destroyed.
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
39 safely ignore that implementation detail as the kset core code handles
43 of those directories corresponds to a kobject in the same kset.
58 nice to have in other objects. The C language does not allow for the
62 (As an aside, for those familiar with the kernel linked list implementation,
64 their own, but are invariably found embedded in the larger objects of
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:
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>:
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.
90 The return value from container_of() is a pointer to the corresponding
92 embedded *within* a struct uio_map could be converted to a pointer to the
98 kobject pointers to the containing type. Exactly this happens in the
108 where the macro argument "map" is a pointer to the struct kobject in
117 of the internal fields are setup with a (mandatory) call to kobject_init():
123 register the kobject with sysfs, the function kobject_add() must be called:
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,
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
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():
141 what names are valid so the caller must provide their own sanity checking
148 To properly access the name of the kobject, use the function
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():
159 The arguments are the same as the individual kobject_init() and
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
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
176 When the kobject is removed from the kernel (details on how to do that are
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
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.
192 A successful call to kobject_get() will increment the kobject's reference
193 counter and return the pointer to the kobject.
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
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.
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.
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
217 entry, use the function:
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
230 with the kobject_create_and_add(), can be of type kobj_attribute, so no
233 See the example module, samples/kobject/kobject-example.c for an
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
243 would be little point in using a kobject in the first place. Even
245 in as other portions of the kernel can get a reference on any kobject that
246 is registered in the system.
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
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
275 "empty" release function; you will be mocked mercilessly by the kobject
278 Note, the name of the kobject is available in the release function, but it
280 leak in the kobject core, which makes people unhappy.
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
299 The release field in struct kobj_type is, of course, a pointer to the
302 sysfs; they are beyond the scope of this document.
311 each other. There is no restriction that they be of the same ktype, but be
317 the kernel to track "all block devices" or "all PCI device drivers."
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.
324 - Ksets can support the "hotplugging" of kobjects and influence how
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
333 the kobjects belonging to a kset have that kset (or, strictly, its embedded
337 created and never declared statically or on the stack. To create a new
343 When you are finished with the kset, call:
345 to destroy it. This removes the kset from sysfs and decrements its reference
346 count. When the reference count goes to zero, the kset will be released.
347 Because other references to the kset may still exist, the release may happen
350 An example of using a kset can be seen in the
351 samples/kobject/kset-example.c file in the kernel tree.
353 If a kset wishes to control the uevent operations of the kobjects
354 associated with it, it can use the struct kset_uevent_ops to handle it:
365 userspace for a specific kobject. If the function returns 0, the uevent
368 The name function will be called to override the default name of the kset
369 that the uevent sends to userspace. By default, the name will be the same
370 as the kset itself, but this function, if present, can override that name.
372 The uevent function will be called when the uevent is about to be sent to
373 userspace to allow more environment variables to be added to the uevent.
378 kobject_add(), its kset member should point to the kset to which the
379 kobject will belong. kobject_add() will handle the rest.
381 If the kobject belonging to a kset has no parent kobject set, it will be
382 added to the kset's directory. Not all members of a kset do necessarily
383 live in the kset directory. If an explicit parent kobject is assigned
384 before the kobject is added, the kobject is registered with the kset, but
385 added below the parent kobject.
390 After a kobject has been registered with the kobject core successfully, it
391 must be cleaned up when the code is finished with it. To do that, call
392 kobject_put(). By doing this, the kobject core will automatically clean up
393 all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been
394 sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
395 any other sysfs housekeeping will be handled for the caller properly.
397 If you need to do a two-stage delete of the kobject (say you are not
398 allowed to sleep when you need to destroy the object), then call
399 kobject_del() which will unregister the kobject from sysfs. This makes the
400 kobject "invisible", but it is not cleaned up, and the reference count of
401 the object is still the same. At a later time call kobject_put() to finish
402 the cleanup of the memory associated with the kobject.
404 kobject_del() can be used to drop the reference to the parent object, if
408 called, and the objects in the former circle release each other.
413 For a more complete example of using ksets and kobjects properly, see the