Gitweb:
http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=f285ea058001ef534f9e53a21aad42c2952bbad5
Commit: f285ea058001ef534f9e53a21aad42c2952bbad5
Parent: a56156489dbdc60ac39a77b8a988d375b2f273a0
Author: Cornelia Huck <[EMAIL PROTECTED]>
AuthorDate: Fri Jul 27 13:41:10 2007 +0200
Committer: Greg Kroah-Hartman <[EMAIL PROTECTED]>
CommitDate: Mon Jul 30 14:25:13 2007 -0700
kobject: update documentation
Update kobject documentation:
- Update structure definitions.
- Remove documentation of removed struct subsystem.
(First shot, uevent_ops probably need some documentation as well.)
Signed-off-by: Cornelia Huck <[EMAIL PROTECTED]>
Signed-off-by: Greg Kroah-Hartman <[EMAIL PROTECTED]>
---
Documentation/kobject.txt | 178 +++++++++++++++------------------------------
1 files changed, 59 insertions(+), 119 deletions(-)
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index e448555..8ee49ee 100644
--- 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.
-- subsystem a controlling object for a number of ksets.
The kobject infrastructure maintains a close relationship with the
@@ -54,13 +53,15 @@ embedded in larger data structures and replace fields they
duplicate.
1.2 Definition
struct kobject {
+ const char * k_name;
char name[KOBJ_NAME_LEN];
- atomic_t refcount;
+ struct kref kref;
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 *);
@@ -137,8 +138,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
-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 +150,10 @@ A kset is a set of kobjects that are embedded in the same
type.
struct kset {
- struct subsystem * subsys;
struct kobj_type * ktype;
struct list_head list;
struct kobject kobj;
+ struct kset_uevent_ops * uevent_ops;
};
@@ -169,8 +169,7 @@ struct kobject * kset_find_obj(struct kset *, char *);
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
@@ -209,6 +208,58 @@ the hierarchy.
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 = {
+ .kobj = {
+ .name = "devices",
+ },
+ .ktype = &ktype_devices,
+ .uevent_ops = &device_uevent_ops,
+};
+
+
+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 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 kset <subsys>.
+
+
+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 kset <subsys>.
+
+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.
+
+void subsystem_init(struct kset *s);
+int subsystem_register(struct kset *s);
+void subsystem_unregister(struct kset *s);
+struct kset *subsys_get(struct kset *s);
+void kset_put(struct kset *s);
+
+These are just wrappers around the respective kset_* functions.
2.3 sysfs
@@ -254,114 +305,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.
-
-
-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).
-
-
To unsubscribe from this list: send the line "unsubscribe git-commits-head" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
