Message-ID: <87abtijg4x.wl%takeuchi_satoru@jp.fujitsu.com>
Date:	Fri, 27 Jul 2007 19:27:26 +0900
From:	Satoru Takeuchi <takeuchi_satoru@...fujitsu.com>
To:	mochel@...l.org, linux-kernel@...r.kernel.org
Cc:	Satoru Takeuchi <takeuchi_satoru@...fujitsu.com>
Subject: [PATCH] Fix kobject documentation

Fix kobject documentation as follows.

 - remove trailing spaces.
 - struct device_subsys -> devices_subsys

Signed-off-by: Satoru Takeuchi<takeuchi_satoru@...fujitsu.com>

Index: linux-2.6.23-rc1/Documentation/kobject.txt
===================================================================
--- linux-2.6.23-rc1.orig/Documentation/kobject.txt	2007-07-27 19:11:37.000000000 +0900
+++ linux-2.6.23-rc1/Documentation/kobject.txt	2007-07-27 19:17:16.000000000 +0900
@@ -18,7 +18,7 @@ similar functionality. This functionalit
 - Object reference counting.
 - Maintaining lists (sets) of objects.
 - Object set locking.
-- Userspace representation. 
+- Userspace representation.
 
 The infrastructure consists of a number of object types to support
 this functionality. Their programming interfaces are described below
@@ -26,7 +26,7 @@ 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. 
+- ktype		a set of helpers for objects of a common type.
 - subsystem	a controlling object for a number of ksets.
 
 
@@ -34,11 +34,11 @@ The kobject infrastructure maintains a c
 sysfs filesystem. Each kobject that is registered with the kobject
 core receives a directory in sysfs. Attributes about the kobject can
 then be exported. Please see Documentation/filesystems/sysfs.txt for
-more information. 
+more information.
 
 The kobject infrastructure provides a flexible programming interface,
 and allows kobjects and ksets to be used without being registered
-(i.e. with no sysfs representation). This is also described later. 
+(i.e. with no sysfs representation). This is also described later.
 
 
 1. kobjects
@@ -49,7 +49,7 @@ and allows kobjects and ksets to be used
 struct kobject is a simple data type that provides a foundation for
 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. 
+embedded in larger data structures and replace fields they duplicate.
 
 1.2 Definition
 
@@ -94,51 +94,51 @@ When a kobject is unregistered, it is re
 removed from the sysfs filesystem, and its reference count is decremented.
 List and sysfs removal happen in kobject_del(), and may be called
 manually. kobject_put() decrements the reference count, and may also
-be called manually. 
+be called manually.
 
 A kobject's reference count may be incremented with kobject_get(),
-which returns a valid reference to a kobject; and decremented with 
+which returns a valid reference to a kobject; and decremented with
 kobject_put(). An object's reference count may only be incremented if
-it is already positive. 
+it is already positive.
 
 When a kobject's reference count reaches 0, the method struct
 kobj_type::release() (which the kobject's kset points to) is called.
 This allows any memory allocated for the object to be freed.
 
 
-NOTE!!! 
+NOTE!!!
 
 It is _imperative_ that you supply a destructor for dynamically
 allocated kobjects to free them if you are using kobject reference
 counts. The reference count controls the lifetime of the object.
 If it goes to 0, then it is assumed that the object will
-be freed and cannot be used. 
+be freed and cannot be used.
 
 More importantly, you must free the object there, and not immediately
 after an unregister call. If someone else is referencing the object
 (e.g. through a sysfs file), they will obtain a reference to the
 object, assume it's valid and operate on it. If the object is
 unregistered and freed in the meantime, the operation will then
-reference freed memory and go boom. 
+reference freed memory and go boom.
 
 This can be prevented, in the simplest case, by defining a release
 method and freeing the object from there only. Note that this will not
 secure reference count/object management models that use a dual
 reference count or do other wacky things with the reference count
-(like the networking layer). 
+(like the networking layer).
 
 
 1.4 sysfs
 
 Each kobject receives a directory in sysfs. This directory is created
-under the kobject's parent directory. 
+under the kobject's parent directory.
 
 If a kobject does not have a parent when it is registered, its parent
-becomes its dominant kset. 
+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. 
+happen for kobjects that are embedded in a struct subsystem.
 
 
 
@@ -146,7 +146,7 @@ happen for kobjects that are embedded in
 
 2.1 Description
 
-A kset is a set of kobjects that are embedded in the same type. 
+A kset is a set of kobjects that are embedded in the same type.
 
 
 struct kset {
@@ -170,12 +170,12 @@ struct kobject * kset_find_obj(struct ks
 
 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. 
+subsys pointer.
 
 A kset contains a kobject itself, meaning that it may be registered in
 the kobject hierarchy and exported via sysfs. More importantly, the
 kset may be embedded in a larger data type, and may be part of another
-kset (of that object type). 
+kset (of that object type).
 
 For example, a block device is an object (struct gendisk) that is
 contained in a set of block devices. It may also contain a set of
@@ -189,25 +189,25 @@ following code snippet illustrates how t
 	 kset_register(&disk->kset);
 
 - The kset that the disk's embedded object belongs to is the
-  block_kset, and is pointed to by disk->kset.kobj.kset. 
+  block_kset, and is pointed to by disk->kset.kobj.kset.
 
-- The type of objects on the disk's _subordinate_ list are partitions, 
-  and is set in disk->kset.ktype. 
+- The type of objects on the disk's _subordinate_ list are partitions,
+  and is set in disk->kset.ktype.
 
 - The kset is then registered, which handles initializing and adding
-  the embedded kobject to the hierarchy. 
+  the embedded kobject to the hierarchy.
 
 
-2.2 kset Programming Interface 
+2.2 kset Programming Interface
 
 All kset functions, except kset_find_obj(), eventually forward the
 calls to their embedded kobjects after performing kset-specific
 operations. ksets offer a similar programming model to kobjects: they
 may be used after they are initialized, without registering them in
-the hierarchy. 
+the hierarchy.
 
 kset_find_obj() may be used to locate a kobject with a particular
-name. The kobject, if found, is returned. 
+name. The kobject, if found, is returned.
 
 
 2.3 sysfs
@@ -216,11 +216,11 @@ ksets are represented in sysfs when thei
 registered. They follow the same rules of parenting, with one
 exception. If a kset does not have a parent, nor is its embedded
 kobject part of another kset, the kset's parent becomes its dominant
-subsystem. 
+subsystem.
 
 If the kset does not have a parent, its directory is created at the
 sysfs root. This should only happen when the kset registered is
-embedded in a subsystem itself. 
+embedded in a subsystem itself.
 
 
 3. struct ktype
@@ -239,10 +239,10 @@ generic object and the more complex type
 the object-specific fields, which include:
 
 - release: Called when the kobject's reference count reaches 0. This
-  should convert the object to the more complex type and free it. 
+  should convert the object to the more complex type and free it.
 
 - sysfs_ops: Provides conversion functions for sysfs access. Please
-  see the sysfs documentation for more information. 
+  see the sysfs documentation for more information.
 
 - default_attrs: Default attributes to be exported via sysfs when the
   object is registered.Note that the last attribute has to be
@@ -252,7 +252,7 @@ the object-specific fields, which includ
 
 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. 
+ksets, as there may be disparate sets of identical objects.
 
 
 
@@ -263,7 +263,7 @@ ksets, as there may be disparate sets of
 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. 
+generic representation of a subsystem is minimal.
 
 
 struct subsystem {
@@ -281,17 +281,17 @@ 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. 
+  embedded kobject.
 
-- It can maintain a default list of objects of one type. 
+- 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.) 
+subsystem.)
 
 All ksets that are attached to a subsystem share the subsystem's R/W
-semaphore. 
+semaphore.
 
 
 4.2 subsystem Programming Interface.
@@ -306,45 +306,45 @@ calls to their embedded kobjects).
 4.3 Helpers
 
 A number of macros are available to make dealing with subsystems and
-their embedded objects easier. 
+their embedded objects easier.
 
 
 decl_subsys(name,type)
 
 Declares a subsystem named '<name>_subsys', with an embedded kset of
-type <type>. For example, 
+type <type>. For example,
 
 decl_subsys(devices,&ktype_devices);
 
 is equivalent to doing:
 
-struct subsystem device_subsys = {
+struct subsystem devices_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: 
+following helpers make setting the kset easier:
 
 
 kobj_set_kset_s(obj,subsys)
 
-- Assumes that obj->kobj exists, and is a struct kobject. 
+- 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. 
+- Sets the kset of the embedded kobject to the subsystem's
+  embedded kset.
 
 subsys_set_kset(obj,subsys)
 
@@ -358,10 +358,9 @@ subsystems are represented in sysfs via 
 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. 
+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 linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists