Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007, Greg KH wrote: > > > - 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. > > > > ? > > 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, _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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
Greg KH wrote: On Thu, Dec 20, 2007 at 02:29:52PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: 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 :) 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? Yes. Thanks. 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. -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 02:29:52PM -0800, Randy Dunlap wrote: > On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: > > > On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: > > > On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: > > > > On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: > > > > > 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 :) > > > > > > 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. > > --- > ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: > On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: > > On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: > > > On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: > > > > 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 :) > > > > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: > On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: > > On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: > > > 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 :) > > 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. > Who is your spell checker? vim :) thanks, greg k-h -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 05:03:35PM -0500, Robert P. J. Day wrote: > On Thu, 20 Dec 2007, Greg KH wrote: > > > 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 :) > > 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... > > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
> On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote:
> > On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
> >
> > ...
> > > - 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.
> >
> > ?
>
> 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.
> > > 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
> > > :
> > >
> > > 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"?
>
> 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.
> > > 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. :(
> > > 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?
I'm lost in the twisty maze. I suppose that will do until someone
can make it better. ;)
Who is your spell checker?
---
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007, Greg KH wrote: > 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"? > 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. > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, Dec 19, 2007 at 11:26:19PM -0500, Alan Stern wrote: > On Wed, 19 Dec 2007, Greg KH wrote: > > - 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 :) > > > > It is rare for kernel code to create a standalone kobject; with one major > > The ';' should be a ','. fixed. > > 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. > > 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. > > 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. > > 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. > > 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. > > 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. > > 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. > > - 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. > > - 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. > > 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. > > 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. > > In the future, the kobject_unregister() call will be going away to help
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 10:04:26AM +0100, Jan Engelhardt wrote:
>
> On Dec 19 2007 16:30, Greg KH wrote:
> >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 :)
> >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 :)
> >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.
> >
> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote:
> 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
> >
> >
> ...
> > - 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.
>
> ?
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.
> > 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
> > :
> >
> > 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"?
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:
> > 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.
> > 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.
> > 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.
>
> 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
:)
> > 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.
> > 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 :)
> >
> > Because kobjects are dynamic, they must not be declared
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Dec 19 2007 16:30, Greg KH wrote:
>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.
>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 *?
>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.
>
What about other return values? Should filter perhaps return bool instead?
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 03:54:40PM +0800, Dave Young wrote:
> On Dec 20, 2007 8:30 AM, Greg KH <[EMAIL PROTECTED]> wrote:
> > 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.
> [--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();
> ...
> }
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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 03:54:40PM +0800, Dave Young wrote:
On Dec 20, 2007 8:30 AM, Greg KH [EMAIL PROTECTED] wrote:
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.
[--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();
...
}
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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Dec 19 2007 16:30, Greg KH wrote:
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.
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 *?
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.
What about other return values? Should filter perhaps return bool instead?
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 10:04:26AM +0100, Jan Engelhardt wrote:
On Dec 19 2007 16:30, Greg KH wrote:
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 :)
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 :)
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.
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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote:
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
...
- 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.
?
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.
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
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:
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.
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.
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.
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
:)
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.
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 :)
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.
the kernel will contain a run-time check
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, Dec 19, 2007 at 11:26:19PM -0500, Alan Stern wrote: On Wed, 19 Dec 2007, Greg KH wrote: - 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 :) It is rare for kernel code to create a standalone kobject; with one major The ';' should be a ','. fixed. 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. 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. 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. 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. 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. 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. 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. - 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. - 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. 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. 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. 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
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007, Greg KH wrote: 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? 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. 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 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote:
On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote:
On Wed, 19 Dec 2007 16:30:31 -0800 Greg KH wrote:
...
- 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.
?
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.
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
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.
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. :(
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?
I'm lost in the twisty maze. I suppose that will do until someone
can make it better. ;)
Who is your spell checker?
---
~Randy
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: 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 :) 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. Who is your spell checker? vim :) thanks, greg k-h -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 05:03:35PM -0500, Robert P. J. Day wrote: On Thu, 20 Dec 2007, Greg KH wrote: 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 :) 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... 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 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: 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 :) 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 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, Dec 20, 2007 at 02:29:52PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: 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 :) 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. --- ~Randy -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
Greg KH wrote: On Thu, Dec 20, 2007 at 02:29:52PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 14:12:52 -0800 Greg KH wrote: On Thu, Dec 20, 2007 at 02:06:59PM -0800, Randy Dunlap wrote: On Thu, 20 Dec 2007 13:27:00 -0800 Greg KH wrote: On Wed, Dec 19, 2007 at 10:32:06PM -0800, Randy Dunlap wrote: 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 :) 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? Yes. Thanks. 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. -- ~Randy -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Thu, 20 Dec 2007, Greg KH wrote: - 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. ? 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 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Dec 20, 2007 8:30 AM, Greg KH <[EMAIL PROTECTED]> wrote:
> 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.
[--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();
...
}
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, 2007-12-19 at 23:26 -0500, Alan Stern wrote:
> On Wed, 19 Dec 2007, Greg KH wrote:
> > 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(>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.
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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
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
>
>
...
> - 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.
?
> 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
> :
>
> 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"?
> 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".
> 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.
> 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.
Is kobject_set_name() marked as __deprecated ?
> 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 ...
>
> 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/
> for them when this call happens.
>
> When the kobject is removed from the kernel (details on how to do that is
are
> 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
>
...
>
> 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?
> 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
> 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
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, 19 Dec 2007, Greg KH wrote:
> 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:
> 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
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.
>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
The ';' should be a ','.
> 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
"using the kobj member."
> 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
> :
>
> 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);
>
>
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, 19 Dec 2007, Greg KH wrote:
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:
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
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.
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
The ';' should be a ','.
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
using the kobj member.
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
Re: [RFC] kobject/kset/ktype documentation and example code updated
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
...
- 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.
?
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
This is (still) confusing to me. Is it:
a pointer kp to a ...
or is struct uio_mem the kp?
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.
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.
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.
Is kobject_set_name() marked as __deprecated ?
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 ...
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/
for them when this call happens.
When the kobject is removed from the kernel (details on how to do that is
are
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
...
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?
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
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.
Creating simple kobjects
Sometimes all that a developer wants is a way to create a simple
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Wed, 2007-12-19 at 23:26 -0500, Alan Stern wrote:
On Wed, 19 Dec 2007, Greg KH wrote:
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.
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
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC] kobject/kset/ktype documentation and example code updated
On Dec 20, 2007 8:30 AM, Greg KH [EMAIL PROTECTED] wrote:
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.
[--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();
...
}
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
