Skip to contentSkip to conversation

kobject/kset/ktype documentation and example code updated

RFC Greg KH 8 participants 21 messages Dec 20, 2007 – Jan 3, 2008

lore
Share & tools
lore

Greg KH

author
#0 lore raw

Thanks to everyone for your last round of review comments and changes to the kobject documentation.

I now have over 130 patches reworking the kset/ktype and kobject apis in the kernel tree, and here is the updated documentation and example code that shows how things work now.

Things different from the last time around are the kobject_add() and kobject_init() functions now take a bunch of required parameters, and the kobject cleanup code is much more forgiving.

I want to drop kobject_unregister() but as this patch series is so big already, I think it's time to let it bake in -mm and push into 2.6.25 before attempting it.

Below is the kobject documentation, and I'll follow this up with the two example programs as well.

Any review comments that people might have on both the document, and the two sample modules would be greatly appreciated.

thanks,

greg k-h

-----------------------------

Everything you never wanted to know about kobjects, ksets, and ktypes

Greg Kroah-Hartman <[email protected]>

Based on an original article by Jon Corbet for lwn.net written October 1, 2003 and located at http://lwn.net/Articles/51437/

Last updated December 19, 2007

Part of the difficulty in understanding the driver model - and the kobject abstraction upon which it is built - is that there is no obvious starting place. Dealing with kobjects requires understanding a few different types, all of which make reference to each other. In an attempt to make things easier, we'll take a multi-pass approach, starting with vague terms and adding detail as we go. To that end, here are some quick definitions of some terms we will be working with.

- A kobject is an object of type struct kobject. Kobjects have a name and a reference count. A kobject also has a parent pointer (allowing objects to be arranged into hierarchies), a specific type, and, usually, a representation in the sysfs virtual filesystem.

Kobjects are generally not interesting on their own; instead, they are usually embedded within some other structure which contains the stuff the code is really interested in.

No structure should EVER have more than one kobject embedded within it. If it does, the reference counting for the object is sure to be messed up and incorrect, and your code will be buggy. So do not do this.

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

- A kset is a group of kobjects. These kobjects can be of the same ktype or belong to different ktypes. The kset is the basic container type for collections of kobjects. Ksets contain their own kobjects, but you can safely ignore that implementation detail as the kset core code handles this kobject automatically.

When you see a sysfs directory full of other directories, generally each of those directories corresponds to a kobject in the same kset.

We'll look at how to create and manipulate all of these types. A bottom-up approach will be taken, so we'll go back to kobjects.

Embedding kobjects

It is rare for kernel code to create a standalone kobject; with one major exception explained below. Instead, kobjects are used to control access to a larger, domain-specific object. To this end, kobjects will be found embedded in other structures. 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. A kobject implements a set of capabilities which are not particularly useful by themselves, but which are nice to have in other objects. The C language does not allow for the direct expression of inheritance, so other techniques - such as structure embedding - must be used.

So, for example, the UIO code has a structure that defines the memory region associated with a uio device:

struct uio_mem {
	struct kobject kobj;
	unsigned long addr;
	unsigned long size;
	int memtype;
	void __iomem *internal_addr;
};

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>:

container_of(pointer, type, member)

where pointer is the pointer to the embedded kobject, type is the type of the containing structure, and member is the name of the structure field to which pointer points. The return value from container_of() is a pointer to the given type. So, for example, a pointer to a struct kobject embedded within a struct uio_mem called "kp" could be converted to a pointer to the containing structure with:

    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);

Programmers will often define a simple macro for "back-casting" kobject pointers to the containing type.

Initialization of kobjects

Code which creates a kobject must, of course, initialize that object. Some of the internal fields are setup with a (mandatory) call to kobject_init():

    void kobject_init(struct kobject *kobj, struct kobj_type *ktype);

The ktype is required for a kobject to be created properly, as every kobject must have an associated kobj_type. Among other things, kobject_init() sets the kobject's reference count to one. After calling kobject_init(), to register the kobject with sysfs, the function kobject_add() must be called:

    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

This sets up the parent of the kobject, and the name for the kobject properly. If the kobject is to be associated with a specific kset, that assignment must be done before calling kobject_add(). If a kset is associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

As the name of the kobject is set when it is added to the kernel, the name of the kobject should never be manipulated directly. If you must change the name of the kobject, call kobject_rename():

    int kobject_rename(struct kobject *kobj, const char *new_name);

There is a function called kobject_set_name() but that is legacy cruft and is being removed. If your code needs to call this function, it is incorrect and needs to be fixed.

To properly access the name of the kobject, use the function kobject_name():

    const char *kobject_name(const struct kobject * kobj);

There is a helper function to both initialize and add the kobject to the kernel at the same time, called supprisingly enough kobject_init_and_add():

int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
struct kobject *parent, const char *fmt, ...);

The arguments are the same as the individual kobject_init() and kobject_add() functions described above.

Uevents

After a kobject has been registered with the kobject core, it needs to be announced to the world that it has been created. This can be done with call to kobject_uevent():

    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look for them when this call happens.

When the kobject is removed from the kernel (details on how to do that is below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand.

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. As long as references to the object exist, the object (and the code which supports it) must continue to exist. The low-level functions for manipulating a kobject's reference counts are:

    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.

Because kobjects are dynamic, they must not be declared statically or on the stack, but instead, always allocated from the heap. Future versions of the kernel will contain a run-time check for kobjects that are created statically and will warn the developer of this improper usage.

If all that you are wanting to use a kobject for is to provide a reference counter for your structure, please use the struct kref instead, a kobject would be overkill. For more information on how to use struct kref, please see the file, Documentation/kref.txt in the Linux kernel source tree.

Creating "simple" kobjects

Sometimes all that a developer wants is a way to create a simple directory in the sysfs hierarchy, and not have to mess with the whole complication of ksets, show and store functions, and other details. This is the one exception where a single kobject should be created. To create such an entry, use the function:

    struct kobject *kobject_create_and_add(char *name, struct kobject *parent);

This function will create a kobject and place it in sysfs in the location underneath the specified parent kobject. To create simple attributes associated with this kobject, use:

    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
or
    int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);

Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add() can be of type kobj_attribute, no special custom attribute is needed to be created.

See the example module, samples/kobject/kobject-example.c for an implementation of a simple kobject and attributes.

ktypes and release methods

One important thing still missing from the discussion is what happens to a kobject when its reference count reaches zero. The code which created the kobject generally does not know when that will happen; if it did, there would be little point in using a kobject in the first place. Even predictable object lifecycles become more complicated when sysfs is brought in as other portions of the kernel can get a reference on any kobject that is registered in the system.

The end result is that a structure protected by a kobject cannot be freed before its reference count goes to zero. The reference count is not under the direct control of the code which created the kobject. So that code must be notified asynchronously whenever the last reference to one of its kobjects goes away.

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.

This notification is done through a kobject's release() method. Usually such a method has a form like:

    void my_object_release(struct kobject *kobj)
    {
    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);

	    /* Perform any additional cleanup on this object, then... */
	    kfree (mine);
    }

One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is flawed. Note that the kernel will warn you if you forget to provide a release() method. Do not try to get rid of this warning by providing an "empty" release function, you will be mocked mercilessly by the kobject maintainer if you attempt this.

Note, the name of the kobject is available in the release function, but it must NOT be changed within this callback. Otherwise there will be a memory leak in the kobject core, which makes people unhappy.

Interestingly, the release() method is not stored in the kobject itself; instead, it is associated with the ktype. So let us introduce struct kobj_type:

    struct kobj_type {
	    void (*release)(struct kobject *);
	    struct sysfs_ops	*sysfs_ops;
	    struct attribute	**default_attrs;
    };

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; a pointer to that structure can be placed in the kobject's ktype field at initialization time, or (more likely) it can be defined by the kobject's containing kset.

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; they are beyond the scope of this document.

The default_attrs pointer is a list of default attributes that will be automatically created for any kobject that is registered with this ktype.

ksets

A kset is merely a collection of kobjects that want to be associated with each other. There is no restriction that they be of the same ktype, but be very careful if they are not.

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; in this way the device model hierarchy is constructed.

- Ksets can support the "hotplugging" of kobjects and influence how uevent events are reported to user space.

In object-oriented terms, "kset" is the top-level container class; ksets contain their own kobject, but that kobject is managed by the kset code and should not be manipulated by any other user.

A kset keeps its children in a standard kernel linked list. Kobjects point back to their containing kset via their kset field. In almost all cases, the contained kobjects also have a pointer to the kset (or, strictly, its embedded kobject) in their parent field.

As a kset contains a kobject within it, it should always be dynamically created and never declared statically or on the stack. To create a new kset use:
struct kset *kset_create_and_add(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.

An example of using a kset can be seen in the samples/kobject/kset-example.c file in the kernel tree.

If a kset wishes to control the uevent operations of the kobjects associated with it, it can use the struct kset_uevent_ops to handle it:

struct kset_uevent_ops {
        int (*filter)(struct kset *kset, struct kobject *kobj);
        const char *(*name)(struct kset *kset, struct kobject *kobj);
        int (*uevent)(struct kset *kset, struct kobject *kobj,
                      struct kobj_uevent_env *env);
};

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.

One might ask how, exactly, a kobject is added to a kset, given that no functions which perform that function have been presented. The answer is that this task is handled by kobject_add(). 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.

If the kobject belonging to a kset has no parent kobject set, it will be added to the kset's directory. Not all members of a kset do necessarily live in the kset directory. If an explicit parent kobject is assigned before the kobject is added, the kobject is registered with the kset, but added below the parent kobject.

Kobject cleaning up

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_unregister(), or kobject_del() followed with a call to kobject_put().

Any initialization of the kobject that has been done will be automatically cleaned up by the kobject core. If a KOBJ_ADD uevent has been sent for the object, a corrisponding KOBJ_REMOVE uevent will be sent, and any other sysfs housekeeping will be handled for the caller properly.

In the future, the kobject_unregister() call will be going away to help clean up the kobject api.

For a more complete example of using ksets and kobjects properly, see the sample/kobject/kset-example.c code.

author
#1 lore raw

[RFC] sample kobject implementation code

/*
* Sample kobject implementation
*
* Copyright (C) 2004-2007 Greg Kroah-Hartman <[email protected]>
* Copyright (C) 2007 Novell Inc.
*
* Released under the GPL version 2 only.
*
*/
#include <linux/kobject.h>
#include <linux/string.h>
#include <linux/sysfs.h>
#include <linux/module.h>
#include <linux/init.h>

/*
* This module shows how to create a simple subdirectory in sysfs called
* /sys/kernel/kobject-example In that directory, 3 files are created:
* "foo", "baz", and "bar". If an integer is written to these files, it can be
* later read out of it.
*/

static int foo;
static int baz;
static int bar;

/*
* The "foo" file where a static variable is read from and written to. */
static ssize_t foo_show(struct kobject *kobj, struct kobj_attribute *attr,
char *buf)

{
	return sprintf(buf, "%d\n", foo);
}

static ssize_t foo_store(struct kobject *kobj, struct kobj_attribute *attr,
const char *buf, size_t count)

{
	sscanf(buf, "%du", &foo);
	return count;
}

static struct kobj_attribute foo_attribute =

	__ATTR(foo, 0666, foo_show, foo_store);

/*
* More complex function where we determine which varible is being accessed by
* looking at the attribute for the "baz" and "bar" files.
*/
static ssize_t b_show(struct kobject *kobj, struct kobj_attribute *attr,
char *buf)

{
	int var;

	if (strcmp(attr->attr.name, "baz") == 0)
		var = baz;
	else
		var = bar;
	return sprintf(buf, "%d\n", var);
}

static ssize_t b_store(struct kobject *kobj, struct kobj_attribute *attr,
const char *buf, size_t count)

{
	int var;

	sscanf(buf, "%du", &var);
	if (strcmp(attr->attr.name, "baz") == 0)
		baz = var;
	else
		bar = var;
	return count;
}

static struct kobj_attribute baz_attribute =

	__ATTR(baz, 0666, b_show, b_store);
static struct kobj_attribute bar_attribute =
	__ATTR(bar, 0666, b_show, b_store);

/*
* Create a group of attributes so that we can create and destory them all
* at once.
*/
static struct attribute *attrs[] = {
&foo_attribute.attr,
&baz_attribute.attr,
&bar_attribute.attr,
NULL, /* need to NULL terminate the list of attributes */
};

/*
* An unnamed attribute group will put all of the attributes directly in
* the kobject directory. If we specify a name, a subdirectory will be
* created for the attributes with the directory being the name of the
* attribute group.
*/
static struct attribute_group attr_group = {
.attrs = attrs,
};

static struct kobject *example_kobj;

static int example_init(void)

{
	int retval;

	/*
	 * Create a simple kobject with the name of "kobject_example",
	 * located under /sys/kernel/
	 *
	 * As this is a simple directory, no uevent will be sent to
	 * userspace.  That is why this function should not be used for
	 * any type of dynamic kobjects, where the name and number are
	 * not known ahead of time.
	 */
	example_kobj = kobject_create_and_add("kobject_example", kernel_kobj);
	if (!example_kobj)
		return -ENOMEM;

	/* Create the files associated with this kobject */
	retval = sysfs_create_group(example_kobj, &attr_group);
	if (retval)
		kobject_unregister(example_kobj);

	return retval;
}

static void example_exit(void)

{
	kobject_unregister(example_kobj);
}

module_init(example_init); module_exit(example_exit); MODULE_LICENSE("GPL");
MODULE_AUTHOR("Greg Kroah-Hartman <[email protected]>");

author
#2 lore raw

[RFC] sample kset/ktype/kobject implementation code

In reply to Greg KH

/*
* Sample kset and ktype implementation
*
* Copyright (C) 2004-2007 Greg Kroah-Hartman <[email protected]>
* Copyright (C) 2007 Novell Inc.
*
* Released under the GPL version 2 only.
*
*/
#include <linux/kobject.h>
#include <linux/string.h>
#include <linux/sysfs.h>
#include <linux/module.h>
#include <linux/init.h>

/*
* This module shows how to create a kset in sysfs called
* /sys/kernel/kset-example
* Then tree kobjects are created and assigned to this kset, "foo", "baz",
* and "bar". In those kobjects, attributes of the same name are also
* created and if an integer is written to these files, it can be later
* read out of it.
*/

/*
* This is our "object" that we will create a few of and register them with
* sysfs.
*/

struct foo_obj {
	struct kobject kobj;
	int foo;
	int baz;
	int bar;
};

#define to_foo_obj(x) container_of(x, struct foo_obj, kobj)

/* a custom attribute that works just for a struct foo_obj. */

struct foo_attribute {
	struct attribute attr;
	ssize_t (*show)(struct foo_obj *foo, struct foo_attribute *attr, char *buf);
	ssize_t (*store)(struct foo_obj *foo, struct foo_attribute *attr, const char *buf, size_t count);
};

#define to_foo_attr(x) container_of(x, struct foo_attribute, attr)

/*
* The default show function that must be passed to sysfs. This will be
* called by sysfs for whenever a show function is called by the user on a
* sysfs file associated with the kobjects we have registered. We need to
* transpose back from a "default" kobject to our custom struct foo_obj and
* then call the show function for that specific object.
*/
static ssize_t foo_attr_show(struct kobject *kobj,
struct attribute *attr,
char *buf)

{
	struct foo_attribute *attribute;
	struct foo_obj *foo;

	attribute = to_foo_attr(attr);
	foo = to_foo_obj(kobj);

	if (!attribute->show)
		return -EIO;

	return attribute->show(foo, attribute, buf);
}

/*
* Just like the default show function above, but this one is for when the
* sysfs "store" is requested (when a value is written to a file.) */
static ssize_t foo_attr_store(struct kobject *kobj,
struct attribute *attr,
const char *buf, size_t len)

{
	struct foo_attribute *attribute;
	struct foo_obj *foo;

	attribute = to_foo_attr(attr);
	foo = to_foo_obj(kobj);

	if (!attribute->store)
		return -EIO;

	return attribute->store(foo, attribute, buf, len);
}

/* Our custom sysfs_ops that we will associate with our ktype later on */ static struct sysfs_ops foo_sysfs_ops = {
.show = foo_attr_show,
.store = foo_attr_store,
};

/*
* The release function for our object. This is REQUIRED by the kernel to
* have. We free the memory held in our object here.
*
* NEVER try to get away with just a "blank" release function to try to be
* smarter than the kernel. Turns out, no one ever is...
*/
static void foo_release(struct kobject *kobj)

{
	struct foo_obj *foo;

	foo = to_foo_obj(kobj);
	kfree(foo);
}

/*
* The "foo" file where the .foo variable is read from and written to. */
static ssize_t foo_show(struct foo_obj *foo_obj, struct foo_attribute *attr,
char *buf)

{
	return sprintf(buf, "%d\n", foo_obj->foo);
}

static ssize_t foo_store(struct foo_obj *foo_obj, struct foo_attribute *attr,
const char *buf, size_t count)

{
	sscanf(buf, "%du", &foo_obj->foo);
	return count;
}

static struct foo_attribute foo_attribute =

	__ATTR(foo, 0666, foo_show, foo_store);

/*
* More complex function where we determine which varible is being accessed by
* looking at the attribute for the "baz" and "bar" files.
*/
static ssize_t b_show(struct foo_obj *foo_obj, struct foo_attribute *attr,
char *buf)

{
	int var;

	if (strcmp(attr->attr.name, "baz") == 0)
		var = foo_obj->baz;
	else
		var = foo_obj->bar;
	return sprintf(buf, "%d\n", var);
}

static ssize_t b_store(struct foo_obj *foo_obj, struct foo_attribute *attr,
const char *buf, size_t count)

{
	int var;

	sscanf(buf, "%du", &var);
	if (strcmp(attr->attr.name, "baz") == 0)
		foo_obj->baz = var;
	else
		foo_obj->bar = var;
	return count;
}

static struct foo_attribute baz_attribute =

	__ATTR(baz, 0666, b_show, b_store);
static struct foo_attribute bar_attribute =
	__ATTR(bar, 0666, b_show, b_store);

/*
* Create a group of attributes so that we can create and destory them all
* at once.
*/
static struct attribute *foo_default_attrs[] = {
&foo_attribute.attr,
&baz_attribute.attr,
&bar_attribute.attr,
NULL, /* need to NULL terminate the list of attributes */
};

/*
* Our own ktype for our kobjects. Here we specify our sysfs ops, the
* release function, and the set of default attributes we want created
* whenever a kobject of this type is registered with the kernel. */
static struct kobj_type foo_ktype = {
.sysfs_ops = &foo_sysfs_ops,
.release = foo_release,
.default_attrs = foo_default_attrs,
};

static struct kset *example_kset; static struct foo_obj *foo_obj; static struct foo_obj *bar_obj; static struct foo_obj *baz_obj;

static struct foo_obj *create_foo_obj(const char *name)

{
	struct foo_obj *foo;
	int retval;

	/* allocate the memory for the whole object */
	foo = kzalloc(sizeof(*foo), GFP_KERNEL);
	if (!foo)
		return NULL;

	/*
	 * As we have a kset for this kobject, we need to set it before calling
	 * the kobject core.
	 */
	foo->kobj.kset = example_kset;

	/*
	 * Initialize and add the kobject to the kernel.  All the default files
	 * will be created here.  As we have already specified a kset for this
	 * kobject, we don't have to set a parent for the kobject, the kobject
	 * will be placed beneath that kset automatically.
	 */
	retval = kobject_init_and_add(&foo->kobj, &foo_ktype, NULL, "%s", name);
	if (retval) {
		kfree(foo);
		return NULL;
	}

	/*
	 * We are always responsible for sending the uevent that the kobject
	 * was added to the system.
	 */
	kobject_uevent(&foo->kobj, KOBJ_ADD);

	return foo;
}

static void destroy_foo_obj(struct foo_obj *foo)

{
	kobject_unregister(&foo->kobj);
}

static int example_init(void)

{
	/*
	 * Create a kset with the name of "kset_example",
	 * located under /sys/kernel/
	 */
	example_kset = kset_create_and_add("kset_example", NULL, kernel_kobj);
	if (!example_kset)
		return -ENOMEM;

	/*
	 * Create three objects and register them with our kset
	 */
	foo_obj = create_foo_obj("foo");
	if (!foo_obj)
		goto foo_error;

	bar_obj = create_foo_obj("bar");
	if (!bar_obj)
		goto bar_error;

	baz_obj = create_foo_obj("baz");
	if (!baz_obj)
		goto baz_error;

	return 0;

baz_error:

	destroy_foo_obj(bar_obj);
bar_error:
	destroy_foo_obj(foo_obj);
foo_error:
	return -EINVAL;
}

static void example_exit(void)

{
	destroy_foo_obj(baz_obj);
	destroy_foo_obj(bar_obj);
	destroy_foo_obj(foo_obj);
	kset_unregister(example_kset);
}

module_init(example_init); module_exit(example_exit); MODULE_LICENSE("GPL");
MODULE_AUTHOR("Greg Kroah-Hartman <[email protected]>");

#3 lore raw

Re: [RFC] sample kset/ktype/kobject implementation code

Quoted 11 lines · Greg KH
	/*
	 * Initialize and add the kobject to the kernel.  All the default files
	 * will be created here.  As we have already specified a kset for this
	 * kobject, we don't have to set a parent for the kobject, the kobject
	 * will be placed beneath that kset automatically.
	 */
	retval = kobject_init_and_add(&foo->kobj, &foo_ktype, NULL, "%s", name);
	if (retval) {
		kfree(foo);
		return NULL;
	}

I really hate to say this, but the example is still wrong. There needs to be a kobject_put(&foo->kobj) instead of the kfree(foo) (as the comments for kobject_init_and_add() resp. kobject_add_ng() correctly explain :))

#4 lore raw
In reply to Greg KH
Quoted 2 lines · Greg KH

Any review comments that people might have on both the document, and the two sample modules would be greatly appreciated.

Here are some things I noticed on a first reading:

Quoted 27 lines

Everything you never wanted to know about kobjects, ksets, and ktypes

Greg Kroah-Hartman <[email protected]>

Based on an original article by Jon Corbet for lwn.net written October 1, 2003 and located at http://lwn.net/Articles/51437/

Last updated December 19, 2007

Part of the difficulty in understanding the driver model - and the kobject abstraction upon which it is built - is that there is no obvious starting place. Dealing with kobjects requires understanding a few different types, all of which make reference to each other. In an attempt to make things easier, we'll take a multi-pass approach, starting with vague terms and adding detail as we go. To that end, here are some quick definitions of some terms we will be working with.

- A kobject is an object of type struct kobject. Kobjects have a name and a reference count. A kobject also has a parent pointer (allowing objects to be arranged into hierarchies), a specific type, and, usually, a representation in the sysfs virtual filesystem.

Kobjects are generally not interesting on their own; instead, they are usually embedded within some other structure which contains the stuff the code is really interested in.

Quoted 6 lines

No structure should EVER have more than one kobject embedded within it. If it does, the reference counting for the object is sure to be messed up and incorrect, and your code will be buggy. So do not do this.

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls

I think the wording here is a little misleading. It might be better to
say: "For every kind of structure with an embedded kobject, there should be a corresponding ktype object. In each structure of that kind the embedded kobject should contain a pointer to that ktype."

Even that isn't great. Maybe somebody can suggest something better.

Quoted 12 lines

what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

- A kset is a group of kobjects. These kobjects can be of the same ktype or belong to different ktypes. The kset is the basic container type for collections of kobjects. Ksets contain their own kobjects, but you can safely ignore that implementation detail as the kset core code handles this kobject automatically.

When you see a sysfs directory full of other directories, generally each of those directories corresponds to a kobject in the same kset.

Quoted 7 lines

We'll look at how to create and manipulate all of these types. A bottom-up approach will be taken, so we'll go back to kobjects.

Embedding kobjects

It is rare for kernel code to create a standalone kobject; with one major

The ';' should be a ','.

Quoted 21 lines

exception explained below. Instead, kobjects are used to control access to a larger, domain-specific object. To this end, kobjects will be found embedded in other structures. 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. A kobject implements a set of capabilities which are not particularly useful by themselves, but which are nice to have in other objects. The C language does not allow for the direct expression of inheritance, so other techniques - such as structure embedding - must be used.

So, for example, the UIO code has a structure that defines the memory region associated with a uio device:

struct uio_mem {
	struct kobject kobj;
	unsigned long addr;
	unsigned long size;
	int memtype;
	void __iomem *internal_addr;
};
Quoted 2 lines

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects

"using the kobj member."

Quoted 23 lines

will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>:

container_of(pointer, type, member)

where pointer is the pointer to the embedded kobject, type is the type of the containing structure, and member is the name of the structure field to which pointer points. The return value from container_of() is a pointer to the given type. So, for example, a pointer to a struct kobject embedded within a struct uio_mem called "kp" could be converted to a pointer to the containing structure with:

    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);

Programmers will often define a simple macro for "back-casting" kobject pointers to the containing type.

Initialization of kobjects

Quoted 8 lines

Code which creates a kobject must, of course, initialize that object. Some of the internal fields are setup with a (mandatory) call to kobject_init():

    void kobject_init(struct kobject *kobj, struct kobj_type *ktype);

The ktype is required for a kobject to be created properly, as every kobject must have an associated kobj_type. Among other things, kobject_init() sets the kobject's reference count to one. After calling kobject_init(), to

Setting the reference count to one is explained below, so the sentence can be omitted here.

Quoted 7 lines

register the kobject with sysfs, the function kobject_add() must be called:

    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

This sets up the parent of the kobject, and the name for the kobject properly. If the kobject is to be associated with a specific kset, that assignment must be done before calling kobject_add(). If a kset is

"kobj->kset must be assigned" instead of "that assignment must be done"

Quoted 3 lines

associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

"and then the kobject's parent will be set to the kset itself."

Kay, in my version of kobject_add() it says:

	if (kobj->kset) {
		kobj->kset = kset_get(kobj->kset);

		if (!parent) {
			parent = kobject_get(&kobj->kset->kobj);
			/*
			 * If the kset is our parent, get a second
			 * reference, we drop both the kset and the
			 * parent ref on cleanup
			 */
			kobject_get(parent);
		}

That last call to kobject_get(parent) doesn't make sense. The code has already taken two references to the kset: one in the assignment of kobj->kset and the other in the assignment of parent. The final kobject_get() then acquires a third reference, which will never be dropped.

Quoted 22 lines

As the name of the kobject is set when it is added to the kernel, the name of the kobject should never be manipulated directly. If you must change the name of the kobject, call kobject_rename():

    int kobject_rename(struct kobject *kobj, const char *new_name);

There is a function called kobject_set_name() but that is legacy cruft and is being removed. If your code needs to call this function, it is incorrect and needs to be fixed.

To properly access the name of the kobject, use the function kobject_name():

    const char *kobject_name(const struct kobject * kobj);

There is a helper function to both initialize and add the kobject to the kernel at the same time, called supprisingly enough kobject_init_and_add():

int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
struct kobject *parent, const char *fmt, ...);

Quoted 8 lines

The arguments are the same as the individual kobject_init() and kobject_add() functions described above.

Uevents

After a kobject has been registered with the kobject core, it needs to be announced to the world that it has been created. This can be done with

"you need to announce"

Quoted 33 lines

call to kobject_uevent():

    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look for them when this call happens.

When the kobject is removed from the kernel (details on how to do that is below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand.

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. As long as references to the object exist, the object (and the code which supports it) must continue to exist. The low-level functions for manipulating a kobject's reference counts are:

    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.

Quoted 7 lines

Because kobjects are dynamic, they must not be declared statically or on the stack, but instead, always allocated from the heap. Future versions of the kernel will contain a run-time check for kobjects that are created statically and will warn the developer of this improper usage.

If all that you are wanting to use a kobject for is to provide a reference counter for your structure, please use the struct kref instead, a kobject

The second ',' in the line above should be a ';'.

Quoted 85 lines

would be overkill. For more information on how to use struct kref, please see the file, Documentation/kref.txt in the Linux kernel source tree.

Creating "simple" kobjects

Sometimes all that a developer wants is a way to create a simple directory in the sysfs hierarchy, and not have to mess with the whole complication of ksets, show and store functions, and other details. This is the one exception where a single kobject should be created. To create such an entry, use the function:

    struct kobject *kobject_create_and_add(char *name, struct kobject *parent);

This function will create a kobject and place it in sysfs in the location underneath the specified parent kobject. To create simple attributes associated with this kobject, use:

    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
or
    int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);

Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add() can be of type kobj_attribute, no special custom attribute is needed to be created.

See the example module, samples/kobject/kobject-example.c for an implementation of a simple kobject and attributes.

ktypes and release methods

One important thing still missing from the discussion is what happens to a kobject when its reference count reaches zero. The code which created the kobject generally does not know when that will happen; if it did, there would be little point in using a kobject in the first place. Even predictable object lifecycles become more complicated when sysfs is brought in as other portions of the kernel can get a reference on any kobject that is registered in the system.

The end result is that a structure protected by a kobject cannot be freed before its reference count goes to zero. The reference count is not under the direct control of the code which created the kobject. So that code must be notified asynchronously whenever the last reference to one of its kobjects goes away.

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.

This notification is done through a kobject's release() method. Usually such a method has a form like:

    void my_object_release(struct kobject *kobj)
    {
    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);

	    /* Perform any additional cleanup on this object, then... */
	    kfree (mine);
    }

One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is flawed. Note that the kernel will warn you if you forget to provide a release() method. Do not try to get rid of this warning by providing an "empty" release function, you will be mocked mercilessly by the kobject maintainer if you attempt this.

Note, the name of the kobject is available in the release function, but it must NOT be changed within this callback. Otherwise there will be a memory leak in the kobject core, which makes people unhappy.

Interestingly, the release() method is not stored in the kobject itself; instead, it is associated with the ktype. So let us introduce struct kobj_type:

    struct kobj_type {
	    void (*release)(struct kobject *);
	    struct sysfs_ops	*sysfs_ops;
	    struct attribute	**default_attrs;
    };
Quoted 5 lines

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; a pointer to that structure can be placed in the kobject's ktype field at initialization time, or (more likely) it can be defined by the kobject's containing kset.

"a pointer to that structure must be specified when you call kobject_init() or kobject_init_and_add()."

Quoted 18 lines

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; they are beyond the scope of this document.

The default_attrs pointer is a list of default attributes that will be automatically created for any kobject that is registered with this ktype.

ksets

A kset is merely a collection of kobjects that want to be associated with each other. There is no restriction that they be of the same ktype, but be very careful if they are not.

A kset serves these functions:

Quoted 7 lines

- 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; in this way the device model hierarchy is constructed.

"the top-level directories of the sysfs hierarchy are constructed in this way."

Quoted 7 lines

- Ksets can support the "hotplugging" of kobjects and influence how uevent events are reported to user space.

In object-oriented terms, "kset" is the top-level container class; ksets contain their own kobject, but that kobject is managed by the kset code and should not be manipulated by any other user.

Don't you want to include the definition of struct kset here?

Quoted 5 lines

A kset keeps its children in a standard kernel linked list. Kobjects point back to their containing kset via their kset field. In almost all cases, the contained kobjects also have a pointer to the kset (or, strictly, its embedded kobject) in their parent field.

"In almost all cases, the kobjects belonging to a kset have that kset (or, strictly, its embedded kobject) as their parent."

Quoted 43 lines

As a kset contains a kobject within it, it should always be dynamically created and never declared statically or on the stack. To create a new kset use:
struct kset *kset_create_and_add(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.

An example of using a kset can be seen in the samples/kobject/kset-example.c file in the kernel tree.

If a kset wishes to control the uevent operations of the kobjects associated with it, it can use the struct kset_uevent_ops to handle it:

struct kset_uevent_ops {
        int (*filter)(struct kset *kset, struct kobject *kobj);
        const char *(*name)(struct kset *kset, struct kobject *kobj);
        int (*uevent)(struct kset *kset, struct kobject *kobj,
                      struct kobj_uevent_env *env);
};

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.

One might ask how, exactly, a kobject is added to a kset, given that no functions which perform that function have been presented. The answer is that this task is handled by kobject_add(). 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.

Quoted 5 lines

If the kobject belonging to a kset has no parent kobject set, it will be added to the kset's directory. Not all members of a kset do necessarily live in the kset directory. If an explicit parent kobject is assigned before the kobject is added, the kobject is registered with the kset, but added below the parent kobject.

This paragraph is unnecessary since it is already explained in the section about kobject_add().

Quoted 9 lines

Kobject cleaning up

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_unregister(), or kobject_del() followed with a call to kobject_put().

Quoted 7 lines

Any initialization of the kobject that has been done will be automatically cleaned up by the kobject core. If a KOBJ_ADD uevent has been sent for the object, a corrisponding KOBJ_REMOVE uevent will be sent, and any other sysfs housekeeping will be handled for the caller properly.

In the future, the kobject_unregister() call will be going away to help clean up the kobject api.

Will there be a kobject_del_and_put() routine, to complement kobject_init_and_add()?

Quoted 4 lines

For a more complete example of using ksets and kobjects properly, see the sample/kobject/kset-example.c code.

Alan Stern

#5 lore raw
Quoted 23 lines · Alan Stern
Quoted 3 lines · Greg KH

associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

"and then the kobject's parent will be set to the kset itself."

Kay, in my version of kobject_add() it says:

	if (kobj->kset) {
		kobj->kset = kset_get(kobj->kset);

		if (!parent) {
			parent = kobject_get(&kobj->kset->kobj);
			/*
			 * If the kset is our parent, get a second
			 * reference, we drop both the kset and the
			 * parent ref on cleanup
			 */
			kobject_get(parent);
		}
Quoted 5 lines

That last call to kobject_get(parent) doesn't make sense. The code has already taken two references to the kset: one in the assignment of kobj->kset and the other in the assignment of parent. The final kobject_get() then acquires a third reference, which will never be dropped.

Yeah, that's wrong, and caused by two patches trying to solve the same problem. We had users assigning the kset before kobject_init() and users doing that after it. We moved the kset referencing from kobiect_init to kobject_add, which introduced the third reference, while we already added the second one to fix the issues. We could drop one of the patches in the series, but this is all already gone with the latest changes in Greg's tree.

Thanks,
Kay

author
#6 lore raw
In reply to Alan Stern
Quoted 10 lines · Alan Stern
Quoted 2 lines · Greg KH

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls

I think the wording here is a little misleading. It might be better to
say: "For every kind of structure with an embedded kobject, there should be a corresponding ktype object. In each structure of that kind the embedded kobject should contain a pointer to that ktype."

Even that isn't great. Maybe somebody can suggest something better.

See the version I just suggested to Randy for this paragraph. It's all I can come up with right now too :)

Quoted 4 lines
Quoted 2 lines

It is rare for kernel code to create a standalone kobject; with one major

The ';' should be a ','.

fixed.

Quoted 4 lines
Quoted 2 lines

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects

"using the kobj member."

fixed.

Quoted 6 lines
Quoted 3 lines

The ktype is required for a kobject to be created properly, as every kobject must have an associated kobj_type. Among other things, kobject_init() sets the kobject's reference count to one. After calling kobject_init(), to

Setting the reference count to one is explained below, so the sentence can be omitted here.

Ok, dropped.

Quoted 9 lines
Quoted 7 lines

register the kobject with sysfs, the function kobject_add() must be called:

    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

This sets up the parent of the kobject, and the name for the kobject properly. If the kobject is to be associated with a specific kset, that assignment must be done before calling kobject_add(). If a kset is

"kobj->kset must be assigned" instead of "that assignment must be done"

fixed, thanks.

Quoted 5 lines
Quoted 3 lines

associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

"and then the kobject's parent will be set to the kset itself."

changed, thanks.

Quoted 6 lines
Quoted 4 lines

Uevents

After a kobject has been registered with the kobject core, it needs to be announced to the world that it has been created. This can be done with

"you need to announce"

changed.

Quoted 4 lines
Quoted 2 lines

If all that you are wanting to use a kobject for is to provide a reference counter for your structure, please use the struct kref instead, a kobject

The second ',' in the line above should be a ';'.

I always never know when to use a ';', thanks.

Quoted 8 lines
Quoted 5 lines

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; a pointer to that structure can be placed in the kobject's ktype field at initialization time, or (more likely) it can be defined by the kobject's containing kset.

"a pointer to that structure must be specified when you call kobject_init() or kobject_init_and_add()."

Thanks, that was a big miss.

Quoted 7 lines
Quoted 4 lines

- 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; in this way the device model hierarchy is constructed.

"the top-level directories of the sysfs hierarchy are constructed in this way."

thanks.

Quoted 8 lines
Quoted 6 lines

- Ksets can support the "hotplugging" of kobjects and influence how uevent events are reported to user space.

In object-oriented terms, "kset" is the top-level container class; ksets contain their own kobject, but that kobject is managed by the kset code and should not be manipulated by any other user.

Don't you want to include the definition of struct kset here?

Not really, you never touch the "raw" kset, you only use functions to create it. There's nothing in the structure for someone to mess with.

Quoted 7 lines
Quoted 4 lines

A kset keeps its children in a standard kernel linked list. Kobjects point back to their containing kset via their kset field. In almost all cases, the contained kobjects also have a pointer to the kset (or, strictly, its embedded kobject) in their parent field.

"In almost all cases, the kobjects belonging to a kset have that kset (or, strictly, its embedded kobject) as their parent."

changed, thanks.

Quoted 8 lines
Quoted 5 lines

If the kobject belonging to a kset has no parent kobject set, it will be added to the kset's directory. Not all members of a kset do necessarily live in the kset directory. If an explicit parent kobject is assigned before the kobject is added, the kobject is registered with the kset, but added below the parent kobject.

This paragraph is unnecessary since it is already explained in the section about kobject_add().

good catch.

Quoted 5 lines
Quoted 2 lines

In the future, the kobject_unregister() call will be going away to help clean up the kobject api.

Will there be a kobject_del_and_put() routine, to complement kobject_init_and_add()?

Nope, all you need is 'kobject_put()' I've already added that change to the tree, turned out it was already all implemented, all I had to do was the search-and-replace, thanks to Kay :)

thanks for the review.

greg k-h

#7 lore raw
In reply to Greg KH
Quoted 10 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:

Everything you never wanted to know about kobjects, ksets, and ktypes

Greg Kroah-Hartman <[email protected]>

Based on an original article by Jon Corbet for lwn.net written October 1, 2003 and located at http://lwn.net/Articles/51437/

Last updated December 19, 2007

...

Quoted 4 lines

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

I can't quite parse the last sentence above. Is it:

The ktype controls (a) what happens ...
and (b) the kobject's default representation in sysfs.

?

Quoted 21 lines

Embedding kobjects

So, for example, the UIO code has a structure that defines the memory region associated with a uio device:

struct uio_mem {
	struct kobject kobj;
	unsigned long addr;
	unsigned long size;
	int memtype;
	void __iomem *internal_addr;
};

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>:

Quoted 6 lines

container_of(pointer, type, member)

where pointer is the pointer to the embedded kobject, type is the type of the containing structure, and member is the name of the structure field to which pointer points. The return value from container_of() is a pointer to the given type. So, for example, a pointer to a struct kobject embedded

This is (still) confusing to me. Is it:
a pointer "kp" to a ...
or is struct uio_mem the "kp"?

Quoted 6 lines

within a struct uio_mem called "kp" could be converted to a pointer to the containing structure with:

    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);

Programmers will often define a simple macro for "back-casting" kobject

Drop the "will".

Quoted 9 lines

pointers to the containing type.

Initialization of kobjects

    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

This sets up the parent of the kobject, and the name for the kobject

Drop the comma.

Quoted 10 lines

properly. If the kobject is to be associated with a specific kset, that assignment must be done before calling kobject_add(). If a kset is associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

As the name of the kobject is set when it is added to the kernel, the name of the kobject should never be manipulated directly. If you must change the name of the kobject, call kobject_rename():

Quoted 5 lines
    int kobject_rename(struct kobject *kobj, const char *new_name);

There is a function called kobject_set_name() but that is legacy cruft and is being removed. If your code needs to call this function, it is incorrect and needs to be fixed.

Is kobject_set_name() marked as __deprecated ?

Quoted 5 lines

Uevents

After a kobject has been registered with the kobject core, it needs to be announced to the world that it has been created. This can be done with call to kobject_uevent():

a call ...

Quoted 6 lines
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

		s/will/may/
Quoted 3 lines

for them when this call happens.

When the kobject is removed from the kernel (details on how to do that is

are

Quoted 7 lines

below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand.

Reference counts

...

Quoted 3 lines

Because kobjects are dynamic, they must not be declared statically or on the stack, but instead, always allocated from the heap. Future versions of

The kernel has heapspace?

Quoted 4 lines

the kernel will contain a run-time check for kobjects that are created statically and will warn the developer of this improper usage.

If all that you are wanting to use a kobject for is to provide a reference

If all that you want to use a kobject for is to provide a reference

Quoted 3 lines

counter for your structure, please use the struct kref instead, a kobject would be overkill. For more information on how to use struct kref, please see the file, Documentation/kref.txt in the Linux kernel source tree.

Drop comma.

Quoted 16 lines

Creating "simple" kobjects

Sometimes all that a developer wants is a way to create a simple directory in the sysfs hierarchy, and not have to mess with the whole complication of ksets, show and store functions, and other details. This is the one exception where a single kobject should be created. To create such an entry, use the function:

    struct kobject *kobject_create_and_add(char *name, struct kobject *parent);

This function will create a kobject and place it in sysfs in the location underneath the specified parent kobject. To create simple attributes associated with this kobject, use:

Quoted 7 lines
    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
or
    int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);

Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add() can be of type kobj_attribute, no special custom attribute is needed to be created.

^ multi-run-on sentences....

Quoted 7 lines

See the example module, samples/kobject/kobject-example.c for an implementation of a simple kobject and attributes.

ktypes and release methods

...

Quoted 3 lines

The end result is that a structure protected by a kobject cannot be freed before its reference count goes to zero. The reference count is not under the direct control of the code which created the kobject. So that code must

kobject, so that code

Quoted 11 lines

be notified asynchronously whenever the last reference to one of its kobjects goes away.

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.

This notification is done through a kobject's release() method. Usually such a method has a form like:

Quoted 6 lines
    void my_object_release(struct kobject *kobj)
    {
    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);

	    /* Perform any additional cleanup on this object, then... */
	    kfree (mine);

No space after "kfree". :)

Quoted 8 lines
    }

One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is flawed. Note that the kernel will warn you if you forget to provide a release() method. Do not try to get rid of this warning by providing an "empty" release function, you will be mocked mercilessly by the kobject

s/,/;/

Quoted 2 lines

maintainer if you attempt this.

...

Quoted 9 lines

ksets

A kset is merely a collection of kobjects that want to be associated with each other. There is no restriction that they be of the same ktype, but be very careful if they are not.

A kset serves these functions:

...

Quoted 3 lines

Kobject cleaning up

...

Quoted 3 lines

Any initialization of the kobject that has been done will be automatically cleaned up by the kobject core. If a KOBJ_ADD uevent has been sent for the object, a corrisponding KOBJ_REMOVE uevent will be sent, and any other

corresponding

Quoted 9 lines

sysfs housekeeping will be handled for the caller properly.

In the future, the kobject_unregister() call will be going away to help clean up the kobject api.

For a more complete example of using ksets and kobjects properly, see the sample/kobject/kset-example.c code.
--

---
~Randy

author
#8 lore raw
Quoted 18 lines · Randy Dunlap
Quoted 10 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:

Everything you never wanted to know about kobjects, ksets, and ktypes

Greg Kroah-Hartman <[email protected]>

Based on an original article by Jon Corbet for lwn.net written October 1, 2003 and located at http://lwn.net/Articles/51437/

Last updated December 19, 2007

...

Quoted 4 lines

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

Quoted 6 lines

I can't quite parse the last sentence above. Is it:

The ktype controls (a) what happens ...
and (b) the kobject's default representation in sysfs.

?

How about:
- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens to the kobject when it is created and destroyed.

Quoted 23 lines
Quoted 23 lines

Embedding kobjects

So, for example, the UIO code has a structure that defines the memory region associated with a uio device:

struct uio_mem {
	struct kobject kobj;
	unsigned long addr;
	unsigned long size;
	int memtype;
	void __iomem *internal_addr;
};

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>:

container_of(pointer, type, member)

Quoted 8 lines
Quoted 4 lines

where pointer is the pointer to the embedded kobject, type is the type of the containing structure, and member is the name of the structure field to which pointer points. The return value from container_of() is a pointer to the given type. So, for example, a pointer to a struct kobject embedded

This is (still) confusing to me. Is it:
a pointer "kp" to a ...
or is struct uio_mem the "kp"?

How about:
So, for example, a pointer "kp" to a struct kobject embedded within a struct uio_mem could be converted to a pointer to the containing uio_mem structure with:

Quoted 8 lines
Quoted 6 lines

within a struct uio_mem called "kp" could be converted to a pointer to the containing structure with:

    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);

Programmers will often define a simple macro for "back-casting" kobject

Drop the "will".

dropped.

Quoted 11 lines
Quoted 9 lines

pointers to the containing type.

Initialization of kobjects

    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

This sets up the parent of the kobject, and the name for the kobject

Drop the comma.

dropped.

Quoted 10 lines
Quoted 10 lines

properly. If the kobject is to be associated with a specific kset, that assignment must be done before calling kobject_add(). If a kset is associated with a kobject, then the parent for the kobject can be set to NULL in the call to kobject_add() and then the kobject will be placed under the kset itself.

As the name of the kobject is set when it is added to the kernel, the name of the kobject should never be manipulated directly. If you must change the name of the kobject, call kobject_rename():

Quoted 7 lines
Quoted 5 lines
    int kobject_rename(struct kobject *kobj, const char *new_name);

There is a function called kobject_set_name() but that is legacy cruft and is being removed. If your code needs to call this function, it is incorrect and needs to be fixed.

Is kobject_set_name() marked as __deprecated ?

No. Core code that everyone uses still uses this function, including the kobject core, so to mark it __deprecated would not make much sense. Once I clean up the core code, I'll just delete it from the whole kernel :)

Quoted 7 lines
Quoted 5 lines

Uevents

After a kobject has been registered with the kobject core, it needs to be announced to the world that it has been created. This can be done with call to kobject_uevent():

a call ...

Heh, thanks.

Quoted 7 lines
Quoted 5 lines
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

Quoted 5 lines
Quoted 3 lines

Because kobjects are dynamic, they must not be declared statically or on the stack, but instead, always allocated from the heap. Future versions of

The kernel has heapspace?

Heh, sorry. Now fixed.

Quoted 6 lines
Quoted 4 lines

the kernel will contain a run-time check for kobjects that are created statically and will warn the developer of this improper usage.

If all that you are wanting to use a kobject for is to provide a reference

If all that you want to use a kobject for is to provide a reference

Thanks, fixed.

Quoted 5 lines
Quoted 3 lines

counter for your structure, please use the struct kref instead, a kobject would be overkill. For more information on how to use struct kref, please see the file, Documentation/kref.txt in the Linux kernel source tree.

Drop comma.

dropped.

Quoted 5 lines
Quoted 3 lines

Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add() can be of type kobj_attribute, no special custom attribute is needed to be created.

^ multi-run-on sentences....

Is this better:
Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add(), can be of type kobj_attribute, so no special custom attribute is needed to be created.

If not, any suggestions?

Quoted 8 lines
Quoted 6 lines
    void my_object_release(struct kobject *kobj)
    {
    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);

	    /* Perform any additional cleanup on this object, then... */
	    kfree (mine);

No space after "kfree". :)

Heh, fixed.

Quoted 8 lines
Quoted 6 lines

One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is flawed. Note that the kernel will warn you if you forget to provide a release() method. Do not try to get rid of this warning by providing an "empty" release function, you will be mocked mercilessly by the kobject

s/,/;/

fixed.

Quoted 5 lines
Quoted 3 lines

Any initialization of the kobject that has been done will be automatically cleaned up by the kobject core. If a KOBJ_ADD uevent has been sent for the object, a corrisponding KOBJ_REMOVE uevent will be sent, and any other

corresponding

/me kicks his spell checker for missing this.

thanks for the review, I really appreciate it.

greg k-h

#9 lore raw
Quoted 2 lines · Greg KH

How about:
- A ktype is the type of object that embeds a kobject.

if i were reading the above for the first time, i would have no idea what was being embedded where. "embeds a kobject" where? what's being embedded in what? that sentence doesn't make it clear. what's the current definition for a "struct kobject"?

Quoted 1 line

Every structure that embeds a kobject needs a corresponding ktype.

and if it does, whose responsibility is it to provide one? mine? that's not clear.

Quoted 2 lines

The ktype controls what happens to the kobject when it is created and destroyed.

i doubt that. i wouldn't say that the ktype "controls" what happens,
i would say that it "defines" what happens. to control suggests active participation.

rday

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

author
#10 lore raw
Quoted 9 lines · Robert P. J. Day
Quoted 2 lines · Greg KH

How about:
- A ktype is the type of object that embeds a kobject.

if i were reading the above for the first time, i would have no idea what was being embedded where. "embeds a kobject" where? what's being embedded in what? that sentence doesn't make it clear. what's the current definition for a "struct kobject"?

Read on and hopefully you will learn more. As the beginning of the article states, you have to start somewhere, it's all a circular reference in the end :)

Quoted 4 lines
Quoted 1 line

Every structure that embeds a kobject needs a corresponding ktype.

and if it does, whose responsibility is it to provide one? mine? that's not clear.

Well, someone has to provide it, the code will not compile without one...

Quoted 6 lines
Quoted 2 lines

The ktype controls what happens to the kobject when it is created and destroyed.

i doubt that. i wouldn't say that the ktype "controls" what happens,
i would say that it "defines" what happens. to control suggests active participation.

Well, it controls how it is destroyed, and it controls how the uevents happen when it is created. It is quite active :)

thanks,

greg k-h

#11 lore raw
In reply to Greg KH
Quoted 14 lines · On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
Quoted 13 lines · Randy Dunlap

On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:

...

Quoted 4 lines

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

I can't quite parse the last sentence above. Is it:

The ktype controls (a) what happens ...
and (b) the kobject's default representation in sysfs.

Quoted 7 lines
Quoted 1 line

?

How about:
- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens to the kobject when it is created and destroyed.

OK.

Quoted 28 lines
Quoted 28 lines
Quoted 27 lines

Embedding kobjects

So, for example, the UIO code has a structure that defines the memory region associated with a uio device:

struct uio_mem {
	struct kobject kobj;
	unsigned long addr;
	unsigned long size;
	int memtype;
	void __iomem *internal_addr;
};

If you have a struct uio_mem structure, finding its embedded kobject is just a matter of using the kobj structure. Code that works with kobjects will often have the opposite problem, however: given a struct kobject pointer, what is the pointer to the containing structure? You must avoid tricks (such as assuming that the kobject is at the beginning of the structure) and, instead, use the container_of() macro, found in <linux/kernel.h>:

container_of(pointer, type, member)

where pointer is the pointer to the embedded kobject, type is the type of the containing structure, and member is the name of the structure field to which pointer points. The return value from container_of() is a pointer to the given type. So, for example, a pointer to a struct kobject embedded

Quoted 8 lines
Quoted 3 lines

This is (still) confusing to me. Is it:
a pointer "kp" to a ...
or is struct uio_mem the "kp"?

How about:
So, for example, a pointer "kp" to a struct kobject embedded within a struct uio_mem could be converted to a pointer to the containing uio_mem structure with:

ack.

Quoted 9 lines
Quoted 7 lines
Quoted 5 lines
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

But that's the point. It assumes that udev is being used. :(

Quoted 6 lines
Quoted 5 lines
Quoted 3 lines

Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add() can be of type kobj_attribute, no special custom attribute is needed to be created.

^ multi-run-on sentences....

Quoted 7 lines

Is this better:
Both types of attributes used here, with a kobject that has been created with the kobject_create_and_add(), can be of type kobj_attribute, so no special custom attribute is needed to be created.

If not, any suggestions?

I'm lost in the twisty maze. I suppose that will do until someone can make it better. ;)

Who is your spell checker?

---
~Randy

author
#12 lore raw
Quoted 9 lines · Randy Dunlap
Quoted 8 lines · On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
Quoted 7 lines · Randy Dunlap
Quoted 5 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

Quoted 5 lines
Quoted 3 lines
Quoted 1 line
		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

But that's the point. It assumes that udev is being used. :(

Yes, kernel developers need to be aware that udev _will_ be used, you can not do things that will assume it is not running.

Quoted 1 line

Who is your spell checker?

vim :)

thanks,

greg k-h

#13 lore raw
Quoted 10 lines · On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote:
Quoted 9 lines · Randy Dunlap
Quoted 8 lines · On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
Quoted 7 lines · Randy Dunlap
Quoted 5 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

But that's the point. It assumes that udev is being used. :(

Yes, kernel developers need to be aware that udev _will_ be used, you can not do things that will assume it is not running.

so are you saying that udev is required now?
I missed that information somehow/somewhere.

---
~Randy

author
#14 lore raw
Quoted 16 lines · Randy Dunlap
Quoted 14 lines · On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote:
Quoted 13 lines · Randy Dunlap
Quoted 11 lines · On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
Quoted 8 lines · Randy Dunlap
Quoted 5 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

Quoted 7 lines
Quoted 4 lines
Quoted 1 line

But that's the point. It assumes that udev is being used. :(

Yes, kernel developers need to be aware that udev _will_ be used, you can not do things that will assume it is not running.

so are you saying that udev is required now?
I missed that information somehow/somewhere.

No, not at all, it's not required.

Just that if you are creating kobjects, you need to be aware that there are programs out there, like udev[1], that expect once the kobject is announced, to have all of the attributes present at the same time.

Does that explain it better?

thanks,

greg k-h

[1] There are at least 2 other programs like udev used by distros these days, udev is not the only player in this area anymore.

Quoted 3 lines

---
~Randy

#15 lore raw
Quoted 20 lines · Greg KH
Quoted 11 lines · Randy Dunlap
Quoted 9 lines · On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote:
Quoted 8 lines · Randy Dunlap
Quoted 7 lines · On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
Quoted 6 lines · Randy Dunlap
Quoted 5 lines · On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
    int kobject_uevent(struct kobject *kobj, enum kobject_action action);

Use the KOBJ_ADD action for when the kobject is first added to the kernel. This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look

Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
Quoted 2 lines
Quoted 1 line
		s/will/may/

No, it's usually a "will", as udev is damm fast these days :)

But that's the point. It assumes that udev is being used. :(

Yes, kernel developers need to be aware that udev _will_ be used, you can not do things that will assume it is not running.

so are you saying that udev is required now?
I missed that information somehow/somewhere.

Quoted 7 lines

No, not at all, it's not required.

Just that if you are creating kobjects, you need to be aware that there are programs out there, like udev[1], that expect once the kobject is announced, to have all of the attributes present at the same time.

Does that explain it better?

Yes. Thanks.

Quoted 6 lines

thanks,

greg k-h

[1] There are at least 2 other programs like udev used by distros these days, udev is not the only player in this area anymore.

Signature · 1 line
~Randy
#16 lore raw
In reply to Greg KH
Quoted 10 lines · Greg KH
Quoted 10 lines
Quoted 4 lines

- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens when a kobject is no longer referenced and the kobject's default representation in sysfs.

I can't quite parse the last sentence above. Is it:

The ktype controls (a) what happens ...
and (b) the kobject's default representation in sysfs.

Quoted 7 lines
Quoted 1 line

?

How about:
- A ktype is the type of object that embeds a kobject. Every structure that embeds a kobject needs a corresponding ktype. The ktype controls what happens to the kobject when it is created and destroyed.

I still don't like it. How about being a little more explicit:

A ktype controls certain operations for structures with embedded kobjects. For example, if struct foo contains an embedded kobject member then there should be a foo_ktype object with pointers to the methods for struct foo's. These methods control what happens when the kobject embedded in a struct foo is added or destroyed. Every time a new struct foo is created, &foo_ktype would be passed as the ktype argument in the kobject_init() call for the structure's embedded kobject. Each type of structure (not just foo!) with an embedded kobject needs to have its own corresponding ktype object.

Alan Stern

#17 lore raw
In reply to Greg KH
Quoted 7 lines · Greg KH

Thanks to everyone for your last round of review comments and changes to the kobject documentation.

I now have over 130 patches reworking the kset/ktype and kobject apis in the kernel tree, and here is the updated documentation and example code that shows how things work now.

Quoted 7 lines

Things different from the last time around are the kobject_add() and kobject_init() functions now take a bunch of required parameters, and the kobject cleanup code is much more forgiving.

I want to drop kobject_unregister() but as this patch series is so big already, I think it's time to let it bake in -mm and push into 2.6.25 before attempting it.

[--snip--]

Hi, greg

How about add a kobject_remove function and temporarily keep the kobject_unregister as below until the 2.6.25:

kobject_unregister(...)

{
       ...
        kobject_remove();
        kobject_uevent();
        ...
}
author
#18 lore raw
Quoted 22 lines · Dave Young
Quoted 7 lines · Greg KH

Thanks to everyone for your last round of review comments and changes to the kobject documentation.

I now have over 130 patches reworking the kset/ktype and kobject apis in the kernel tree, and here is the updated documentation and example code that shows how things work now.

Quoted 7 lines

Things different from the last time around are the kobject_add() and kobject_init() functions now take a bunch of required parameters, and the kobject cleanup code is much more forgiving.

I want to drop kobject_unregister() but as this patch series is so big already, I think it's time to let it bake in -mm and push into 2.6.25 before attempting it.

[--snip--]

Hi, greg

How about add a kobject_remove function and temporarily keep the kobject_unregister as below until the 2.6.25:

Quoted 7 lines

kobject_unregister(...)

{
       ...
        kobject_remove();
        kobject_uevent();
        ...
}

Actually, it's not needed at all. Thanks to Kay's recent changes in the tree, a simple kobject_put() is all that is needed. The proper sysfs cleanup and uevent will happen if necessary, no housekeeping by the caller required.

So I'll just nuke kobject_unregister() as it's a simple replacement with kobject_put() which will clean up the api even more :)

And I'll go update the documentation...

thanks,

greg k-h

#19 lore raw
In reply to Greg KH
Quoted 2 lines · Greg KH

See the example module, samples/kobject/kobject-example.c for an implementation of a simple kobject and attributes.

Should mention here that if simple types are enough and a callback function is not needed, a module_param() could be used instead.

Quoted 6 lines

As a kset contains a kobject within it, it should always be dynamically created and never declared statically or on the stack. To create a new kset use:
struct kset *kset_create_and_add(char *name,

				   struct kset_uevent_ops *u,
				   struct kobject *parent);

Hmm... Not const char *?

Quoted 11 lines

If a kset wishes to control the uevent operations of the kobjects associated with it, it can use the struct kset_uevent_ops to handle it:

struct kset_uevent_ops {
       int (*filter)(struct kset *kset, struct kobject *kobj);
       const char *(*name)(struct kset *kset, struct kobject *kobj);
       int (*uevent)(struct kset *kset, struct kobject *kobj,
                     struct kobj_uevent_env *env);
};
Quoted 4 lines

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.

What about other return values? Should filter perhaps return bool instead?

author
#20 lore raw
Quoted 7 lines · Jan Engelhardt
Quoted 2 lines · Greg KH

See the example module, samples/kobject/kobject-example.c for an implementation of a simple kobject and attributes.

Should mention here that if simple types are enough and a callback function is not needed, a module_param() could be used instead.

Nah, why? module paramaters are pretty well known already :)

Quoted 7 lines
Quoted 6 lines

As a kset contains a kobject within it, it should always be dynamically created and never declared statically or on the stack. To create a new kset use:
struct kset *kset_create_and_add(char *name,

				   struct kset_uevent_ops *u,
				   struct kobject *parent);

Hmm... Not const char *?

good catch, that's what the .h file shows :)

Quoted 11 lines
Quoted 11 lines

If a kset wishes to control the uevent operations of the kobjects associated with it, it can use the struct kset_uevent_ops to handle it:

struct kset_uevent_ops {
       int (*filter)(struct kset *kset, struct kobject *kobj);
       const char *(*name)(struct kset *kset, struct kobject *kobj);
       int (*uevent)(struct kset *kset, struct kobject *kobj,
                     struct kobj_uevent_env *env);
};
Quoted 5 lines
Quoted 4 lines

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.

What about other return values? Should filter perhaps return bool instead?

Probably, it was created before there was a 'bool' in the kernel.

thanks,

greg k-h