[MIPS] Alchemy: replace ffs() with __ffs()

[linux-2.6-omap-h63xx.git] / Documentation / kobject.txt

diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index 949f7b5a20538aa3537078d0eafd636df4a5991b..ca86a885ad8f71c6f98647debd50bf293b33de47 100644 (file)
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -27,7 +27,6 @@ in detail, and briefly here:
 - kobjects     a simple object.
 - kset         a set of objects of a certain type.
 - ktype                a set of helpers for objects of a common type. 
 - kobjects     a simple object.
 - kset         a set of objects of a certain type.
 - ktype                a set of helpers for objects of a common type. 

-- subsystem    a controlling object for a number of ksets.

 
 
 The kobject infrastructure maintains a close relationship with the
 
 
 The kobject infrastructure maintains a close relationship with the


@@ -51,16 +50,17 @@ more complex object types. It provides a set of basic fields that
 almost all complex data types share. kobjects are intended to be
 embedded in larger data structures and replace fields they duplicate. 
 
 almost all complex data types share. kobjects are intended to be
 embedded in larger data structures and replace fields they duplicate. 
 

-1.2 Defintion
+1.2 Definition

 
 struct kobject {
 
 struct kobject {

-       char                    name[KOBJ_NAME_LEN];
-       atomic_t                refcount;
+       const char              * k_name;
+       struct kref             kref;

        struct list_head        entry;
        struct kobject          * parent;
        struct kset             * kset;
        struct kobj_type        * ktype;
        struct list_head        entry;
        struct kobject          * parent;
        struct kset             * kset;
        struct kobj_type        * ktype;

-       struct dentry           * dentry;
+       struct sysfs_dirent     * sd;
+       wait_queue_head_t       poll;

 };
 
 void kobject_init(struct kobject *);
 };
 
 void kobject_init(struct kobject *);


@@ -137,8 +137,7 @@ If a kobject does not have a parent when it is registered, its parent
 becomes its dominant kset. 
 
 If a kobject does not have a parent nor a dominant kset, its directory
 becomes its dominant kset. 
 
 If a kobject does not have a parent nor a dominant kset, its directory

-is created at the top-level of the sysfs partition. This should only
-happen for kobjects that are embedded in a struct subsystem. 
+is created at the top-level of the sysfs partition.

 
 
 
 
 
 


@@ -150,10 +149,10 @@ A kset is a set of kobjects that are embedded in the same type.
 
 
 struct kset {
 
 
 struct kset {

-       struct subsystem        * subsys;

        struct kobj_type        * ktype;
        struct list_head        list;
        struct kobject          kobj;
        struct kobj_type        * ktype;
        struct list_head        list;
        struct kobject          kobj;

+       struct kset_uevent_ops  * uevent_ops;

 };
 
 
 };
 
 


@@ -169,8 +168,7 @@ struct kobject * kset_find_obj(struct kset *, char *);
 
 
 The type that the kobjects are embedded in is described by the ktype
 
 
 The type that the kobjects are embedded in is described by the ktype

-pointer. The subsystem that the kobject belongs to is pointed to by the
-subsys pointer. 
+pointer.

 
 A kset contains a kobject itself, meaning that it may be registered in
 the kobject hierarchy and exported via sysfs. More importantly, the
 
 A kset contains a kobject itself, meaning that it may be registered in
 the kobject hierarchy and exported via sysfs. More importantly, the


@@ -209,6 +207,41 @@ the hierarchy.
 kset_find_obj() may be used to locate a kobject with a particular
 name. The kobject, if found, is returned. 
 
 kset_find_obj() may be used to locate a kobject with a particular
 name. The kobject, if found, is returned. 
 

+There are also some helper functions which names point to the formerly
+existing "struct subsystem", whose functions have been taken over by
+ksets.
+
+
+decl_subsys(name,type,uevent_ops)
+
+Declares a kset named '<name>_subsys' of type <type> with
+uevent_ops <uevent_ops>. For example,
+
+decl_subsys(devices, &ktype_device, &device_uevent_ops);
+
+is equivalent to doing:
+
+struct kset devices_subsys = {
+     .ktype = &ktype_devices,
+     .uevent_ops = &device_uevent_ops,
+};
+kobject_set_name(&devices_subsys, name);
+
+The objects that are registered with a subsystem that use the
+subsystem's default list must have their kset ptr set properly. These
+objects may have embedded kobjects or ksets. The
+following helper makes setting the kset easier:
+
+
+kobj_set_kset_s(obj,subsys)
+
+- Assumes that obj->kobj exists, and is a struct kobject.
+- Sets the kset of that kobject to the kset <subsys>.
+
+int subsystem_register(struct kset *s);
+void subsystem_unregister(struct kset *s);
+
+These are just wrappers around the respective kset_* functions.

 
 2.3 sysfs
 
 
 2.3 sysfs
 


@@ -254,114 +287,3 @@ Instances of struct kobj_type are not registered; only referenced by
 the kset. A kobj_type may be referenced by an arbitrary number of
 ksets, as there may be disparate sets of identical objects. 
 
 the kset. A kobj_type may be referenced by an arbitrary number of
 ksets, as there may be disparate sets of identical objects. 
 

-
-
-4. subsystems
-
-4.1 Description
-
-A subsystem represents a significant entity of code that maintains an
-arbitrary number of sets of objects of various types. Since the number
-of ksets and the type of objects they contain are variable, a
-generic representation of a subsystem is minimal. 
-
-
-struct subsystem {
-       struct kset             kset;
-       struct rw_semaphore     rwsem;
-};
-
-int subsystem_register(struct subsystem *);
-void subsystem_unregister(struct subsystem *);
-
-struct subsystem * subsys_get(struct subsystem * s);
-void subsys_put(struct subsystem * s);
-
-
-A subsystem contains an embedded kset so:
-
-- It can be represented in the object hierarchy via the kset's
-  embedded kobject. 
-
-- It can maintain a default list of objects of one type. 
-
-Additional ksets may attach to the subsystem simply by referencing the
-subsystem before they are registered. (This one-way reference means
-that there is no way to determine the ksets that are attached to the
-subsystem.) 
-
-All ksets that are attached to a subsystem share the subsystem's R/W
-semaphore. 
-
-
-4.2 subsystem Programming Interface.
-
-The subsystem programming interface is simple and does not offer the
-flexibility that the kset and kobject programming interfaces do. They
-may be registered and unregistered, as well as reference counted. Each
-call forwards the calls to their embedded ksets (which forward the
-calls to their embedded kobjects).
-
-
-4.3 Helpers
-
-A number of macros are available to make dealing with subsystems and
-their embedded objects easier. 
-
-
-decl_subsys(name,type)
-
-Declares a subsystem named '<name>_subsys', with an embedded kset of
-type <type>. For example, 
-
-decl_subsys(devices,&ktype_devices);
-
-is equivalent to doing:
-
-struct subsystem device_subsys = {
-       .kset = {
-            .kobj = {
-                  .name = "devices",
-            },
-            .ktype = &ktype_devices,
-       }
-}; 
-
-
-The objects that are registered with a subsystem that use the
-subsystem's default list must have their kset ptr set properly. These
-objects may have embedded kobjects, ksets, or other subsystems. The
-following helpers make setting the kset easier: 
-
-
-kobj_set_kset_s(obj,subsys)
-
-- Assumes that obj->kobj exists, and is a struct kobject. 
-- Sets the kset of that kobject to the subsystem's embedded kset.
-
-
-kset_set_kset_s(obj,subsys)
-
-- Assumes that obj->kset exists, and is a struct kset.
-- Sets the kset of the embedded kobject to the subsystem's 
-  embedded kset. 
-
-subsys_set_kset(obj,subsys)
-
-- Assumes obj->subsys exists, and is a struct subsystem.
-- Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
-
-
-4.4 sysfs
-
-subsystems are represented in sysfs via their embedded kobjects. They
-follow the same rules as previously mentioned with no exceptions. They
-typically receive a top-level directory in sysfs, except when their
-embedded kobject is part of another kset, or the parent of the
-embedded kobject is explicitly set. 
-
-Note that the subsystem's embedded kset must be 'attached' to the
-subsystem itself in order to use its rwsem. This is done after
-kset_add() has been called. (Not before, because kset_add() uses its
-subsystem for a default parent if it doesn't already have one).
-