From: Alan Stern <stern@rowland.harvard.edu>

Here is a suggested amendment to Documentation/kobject.h.  Please check it 
for accuracy and tell me if you think it could be improved at all.



 25-akpm/Documentation/kobject.txt |   66 +++++++++++++++++++++++++++++++++++---
 1 files changed, 62 insertions(+), 4 deletions(-)

diff -puN Documentation/kobject.txt~kobject-docco-additions Documentation/kobject.txt
--- 25/Documentation/kobject.txt~kobject-docco-additions	Wed Nov 12 13:11:00 2003
+++ 25-akpm/Documentation/kobject.txt	Wed Nov 12 13:11:00 2003
@@ -2,7 +2,7 @@ The kobject Infrastructure
 
 Patrick Mochel <mochel@osdl.org>
 
-Updated: 3 June 2003
+Updated: 12 November 2003
 
 
 Copyright (c)  2003 Patrick Mochel
@@ -128,7 +128,33 @@ reference count or do other wacky things
 (like the networking layer). 
 
 
-1.4 sysfs
+1.4 Order dependencies
+
+Fields in a kobject must be initialized before they are used, as
+indicated in this table:
+
+	k_name		Before kobject_add() (1)
+	name		Before kobject_add() (1)
+	refcount	Before kobject_init() (2)
+	entry		Set by kobject_init()
+	parent		Before kobject_add() (3)
+	kset		Before kobject_init() (4)
+	ktype		Before kobject_add() (4)
+	dentry		Set by kobject_add()
+
+(1) If k_name isn't already set when kobject_add() is called,
+it will be set to name.
+
+(2) Although kobject_init() sets refcount to 1, a warning will be logged
+if refcount is not equal to 0 beforehand.
+
+(3) If parent isn't already set when kobject_add() is called,
+it will be set to kset's embedded kobject.
+
+(4) kset and ktype are optional. If they are used, they should be set
+at the times indicated.
+
+1.5 sysfs
 
 Each kobject receives a directory in sysfs. This directory is created
 under the kobject's parent directory. 
@@ -210,7 +236,25 @@ kset_find_obj() may be used to locate a 
 name. The kobject, if found, is returned. 
 
 
-2.3 sysfs
+2.3 Order dependencies
+
+Fields in a kset must be initialized before they are used, as indicated
+in this table:
+
+	subsys		Before kset_add()
+	ktype		Before kset_add() (1)
+	list		Set by kset_init()
+	kobj		Before kset_init() (2)
+	hotplug_ops	Before kset_add() (1)
+
+(1) ktype and hotplug_ops are optional. If they are used, they should
+be set at the times indicated.
+
+(2) kobj is passed to kobject_init() during kset_init() and to
+kobject_add() during kset_add(); it must initialized accordingly.
+
+
+2.4 sysfs
 
 ksets are represented in sysfs when their embedded kobjects are
 registered. They follow the same rules of parenting, with one
@@ -352,7 +396,21 @@ subsys_set_kset(obj,subsys)
 - Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
 
 
-4.4 sysfs
+4.4 Order dependencies
+
+Fields in a subsystem must be initialized before they are used,
+as indicated in this table:
+
+	kset		Before subsystem_register() (1)
+	rwsem		Set by subsystem_register()
+
+(1) kset is minimally initialized by the decl_subsys macro. It is
+passed to kset_init() and kset_add() by subsystem_register(). If its
+subsys member isn't already set, subsystem_register() sets it to the
+containing subsystem.
+
+
+4.5 sysfs
 
 subsystems are represented in sysfs via their embedded kobjects. They
 follow the same rules as previously mentioned with no exceptions. They

_