Lines Matching full:a
13 place. Dealing with kobjects requires understanding a few different types,
15 easier, we'll take a multi-pass approach, starting with vague terms and
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.
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
36 - A kset is a group of kobjects. These kobjects can be of the same ktype
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.
45 We'll look at how to create and manipulate all of these types. A bottom-up
52 It is rare for kernel code to create a standalone kobject, with one major
54 a larger, domain-specific object. To this end, kobjects will be found
56 object-oriented terms, kobjects can be seen as a top-level, abstract class
57 from which other classes are derived. A kobject implements a set of
68 So, for example, the UIO code in ``drivers/uio/uio.c`` has a structure that
69 defines the memory region associated with a uio device::
76 If you have a struct uio_map structure, finding its embedded kobject is
77 just a matter of using the kobj member. Code that works with kobjects will
78 often have the opposite problem, however: given a struct kobject pointer,
91 The return value from container_of() is a pointer to the corresponding
92 container type. So, for example, a pointer ``kp`` to a struct kobject
93 embedded **within** a struct uio_map could be converted to a pointer to the
98 For convenience, programmers often define a simple macro for **back-casting**
109 where the macro argument "map" is a pointer to the struct kobject in
118 Code which creates a kobject must, of course, initialize that object. Some
119 of the internal fields are setup with a (mandatory) call to kobject_init()::
123 The ktype is required for a kobject to be created properly, as every kobject
131 properly. If the kobject is to be associated with a specific kset,
132 kobj->kset must be assigned before calling kobject_add(). If a kset is
133 associated with a kobject, then the parent for the kobject can be set to
143 kobject_rename() does not perform any locking or have a solid notion of
147 There is a function called kobject_set_name() but that is legacy cruft and
156 There is a helper function to both initialize and add the kobject to the
169 After a kobject has been registered with the kobject core, you need to
170 announce to the world that it has been created. This can be done with a
189 One of the key functions of a kobject is to serve as a reference counter
192 The low-level functions for manipulating a kobject's reference counts are::
197 A successful call to kobject_get() will increment the kobject's reference
200 When a reference is released, the call to kobject_put() will decrement the
203 need to do a kobject_put() eventually to release that reference.
207 the kernel will contain a run-time check for kobjects that are created
210 If all that you want to use a kobject for is to provide a reference counter
211 for your structure, please use the struct kref instead; a kobject would be
219 Sometimes all that a developer wants is a way to create a simple directory
222 exception where a single kobject should be created. To create such an
227 This function will create a kobject and place it in sysfs in the location
237 Both types of attributes used here, with a kobject that has been created
242 implementation of a simple kobject and attributes.
249 One important thing still missing from the discussion is what happens to a
252 would be little point in using a kobject in the first place. Even
254 in as other portions of the kernel can get a reference on any kobject that
257 The end result is that a structure protected by a kobject cannot be freed
268 This notification is done through a kobject's release() method. Usually
269 such a method has a form like::
279 One important point cannot be overstated: every kobject must have a
280 release() method, and the kobject must persist (in a consistent state)
282 flawed. Note that the kernel will warn you if you forget to provide a
287 create a wrapper function which uses container_of() to upcast to the correct
292 must NOT be changed within this callback. Otherwise there will be a memory
309 This structure is used to describe a particular type of kobject (or, more
311 kobj_type structure; a pointer to that structure must be specified when you
314 The release field in struct kobj_type is, of course, a pointer to the
319 The default_attrs pointer is a list of default attributes that will be
326 A kset is merely a collection of kobjects that want to be associated with
330 A kset serves these functions:
332 - It serves as a bag containing a group of objects. A kset can be used by
335 - A kset is also a subdirectory in sysfs, where the associated kobjects
336 with the kset can show up. Every kset contains a kobject which can be
347 A kset keeps its children in a standard kernel linked list. Kobjects point
349 the kobjects belonging to a kset have that kset (or, strictly, its embedded
352 As a kset contains a kobject within it, it should always be dynamically
353 created and never declared statically or on the stack. To create a new
369 An example of using a kset can be seen in the
372 If a kset wishes to control the uevent operations of the kobjects
383 The filter function allows a kset to prevent a uevent from being emitted to
384 userspace for a specific kobject. If the function returns 0, the uevent
394 One might ask how, exactly, a kobject is added to a kset, given that no
396 that this task is handled by kobject_add(). When a kobject is passed to
400 If the kobject belonging to a kset has no parent kobject set, it will be
401 added to the kset's directory. Not all members of a kset do necessarily
410 After a kobject has been registered with the kobject core successfully, it
413 all of the memory allocated by this kobject. If a ``KOBJ_ADD`` uevent has been
414 sent for the object, a corresponding ``KOBJ_REMOVE`` uevent will be sent, and
417 If you need to do a two-stage delete of the kobject (say you are not
421 the object is still the same. At a later time call kobject_put() to finish
425 circular references are constructed. It is valid in some cases, that a
426 parent objects references a child. Circular references _must_ be broken
427 with an explicit call to kobject_del(), so that a release functions will be
434 For a more complete example of using ksets and kobjects properly, see the