=============================
= REF: =
= 1. Documentation/kobject.txt =
= 2. http://lwn.net/Articles/51437/ =
=============================
1. A simple example
2. Detail introduction of kobject, kset, ktype
2.1 kobject
2.2 kset
2.3
ktypes and release methods
3. A relatively complex example
-------------------------------------------------------------
1. A simple example
samples/kobject/kobject-example.c
2. Detail introduction of kobject, kset, ktype
*A kobjects
can be used to (1) maintain a reference count for an object and clean up when the object is no longer used,
and (2) create a hierarchical data structure through kset membership.
* A ktype
is a type associated with a kobject. The ktype controls what happens to the kobject when it is created and destroyed.
* A kset
is a group of kobjects all of which are embedded in
structures of the same type. When you see a sysfs directory full of entries,
generally each of
those entries corresponds to a kobject in the same kset
Relationship between kset and kobject is as the following figure.
2.1 kobject
First, let us get a peek of the the struct kobject.
The "kobject" structure first made its appearance in the 2.5.45 development kernel.
One of the key functions of a kobject is to serve as a reference counter for the object in which it is embedded.
If you are used to thinking of things in object-oriented terms, kobjects can be seen as a top-level, abstract class
from which other classes are derived.
2.1.1 Initialization of kobjects
* struct kobject *kobj;
kobj = kzalloc(sizeof(*kobj), GFP_KERNEL);
NOTE: Because kobjects are dynamic, they must not be declared statically or on the stack, but instead,
always allocated dynamically.
* kobject_init() - This function will properly initialize a kobject such that it can then be passed to the kobject_add() call.
* After calling kobject_init(), to register the kobject with sysfs, the function kobject_add() must be called.
int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
struct kobject *parent, const char *fmt, ...);
The combination of memory allocated, kobject_init() and kobject_add().
2.1.2 Kobject removal
After a kobject has been registered with the kobject core successfully, it
must be cleaned up when the code is finished with it. To do that, call
kobject_put(). By doing this, the kobject core will automatically clean up
all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been
sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
any other sysfs housekeeping will be handled for the caller properly.
If you need to do a two-stage delete of the kobject (say you are not
allowed to sleep when you need to destroy the object), then call
kobject_del() which will unregister the kobject from sysfs. This makes the
kobject "invisible", but it is not cleaned up, and the reference count of
the object is still the same. At a later time call kobject_put() to finish
the cleanup of the memory associated with the kobject.
2.1.3 Reference counts
One of the key functions of a kobject is to serve as a reference counter
for the object in which it is embedded.
struct kobject *kobject_get(struct kobject *kobj);
void kobject_put(struct kobject *kobj);
A successful call to kobject_get() will increment the kobject's reference
counter and return the pointer to the kobject.
When a reference is released, the call to kobject_put() will decrement the
reference count and, possibly, free the object. Note that kobject_init()
sets the reference count to one, so the code which sets up the kobject will
need to do a kobject_put() eventually to release that reference.
2.2 kset
A kset is merely a collection of kobjects that want to be associated with each other.
A kset serves these functions:
- It serves as a bag containing a group of objects. A kset can be used by
the kernel to track "all block devices" or "all PCI device drivers."
- A kset is also a subdirectory in sysfs, where the associated kobjects
with the kset can show up. Every kset contains a kobject which can be
set up to be the parent of other kobjects; the top-level directories of
the sysfs hierarchy are constructed in this way.
- Ksets can support the "hotplugging" of kobjects and influence how
uevent events are reported to user space.
* As a kset contains a kobject within it, it should always be dynamically
created and never declared statically or on the stack.
kset struct:
struct kset_uevent_ops:
kset use:
struct kset *kset_create_and_add(const char *name,
struct kset_uevent_ops *u,
struct kobject *parent);
When you are finished with the kset, call:
void kset_unregister(struct kset *kset); to destroy it.
The filter function allows a kset to prevent a uevent from being emitted to
userspace for a specific kobject. If the function returns 0, the uevent
will not be emitted.
The name function will be called to override the default name of the kset
that the uevent sends to userspace. By default, the name will be the same
as the kset itself, but this function, if present, can override that name.
The uevent function will be called when the uevent is about to be sent to
userspace to allow more environment variables to be added to the uevent.
NOTE
: How a kobject can asociate with kset?
When a kobject is passed to kobject_add(), its kset member should point to
the kset to which the kobject will belong. kobject_add() will handle the rest.
2.3 ktypes and release methods
Once you registered your kobject via kobject_add(), you must never use
kfree() to free it directly. The only safe way is to use kobject_put(). It
is good practice to always use kobject_put() after kobject_init() to avoid
errors creeping in.
struct kobj_type {
void (*release)(struct kobject *kobj);
const struct sysfs_ops *sysfs_ops;
struct attribute **default_attrs;
const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
const void *(*namespace)(struct kobject *kobj);
};
This structure is used to describe a particular type of kobject (or, more
correctly, of containing object). Every kobject needs to have an associated
kobj_type structure;
The release field in struct kobj_type is, of course, a pointer to the
release() method for this type of kobject. The other two fields (sysfs_ops
and default_attrs) control how objects of this type are represented in
sysfs;
The default_attrs pointer is a list of default attributes that will be
automatically created for any kobject that is registered with this ktype.
3. A relatively complex example