From: Greg Kroah-Hartman <gregkh@suse.de>
To: linux-kernel@vger.kernel.org
Cc: Greg Kroah-Hartman <gregkh@suse.de>, Kay Sievers <kay.sievers@vrfy.org>
Subject: [PATCH 177/196] kobject: remove old, outdated documentation.
Date: Thu, 24 Jan 2008 23:33:26 -0800
Message-Id: <1201246425-5058-98-git-send-email-gregkh@suse.de>
In-Reply-To: <20080125071127.GA4860@kroah.com>
References: <20080125071127.GA4860@kroah.com>
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 10432
Lines: 313

As we are replacing the documentation, it's easier to do this in a two
stage pass, delete the old file and add the new one.

Cc: Kay Sievers <kay.sievers@vrfy.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
---
 Documentation/kobject.txt |  289 ---------------------------------------------
 1 files changed, 0 insertions(+), 289 deletions(-)
 delete mode 100644 Documentation/kobject.txt

diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
deleted file mode 100644
index ca86a88..0000000
--- a/Documentation/kobject.txt
+++ /dev/null
@@ -1,289 +0,0 @@
-The kobject Infrastructure
-
-Patrick Mochel <mochel@osdl.org>
-
-Updated: 3 June 2003
-
-
-Copyright (c)  2003 Patrick Mochel
-Copyright (c)  2003 Open Source Development Labs
-
-
-0. Introduction
-
-The kobject infrastructure performs basic object management that larger
-data structures and subsystems can leverage, rather than reimplement
-similar functionality. This functionality primarily concerns:
-
-- Object reference counting.
-- Maintaining lists (sets) of objects.
-- Object set locking.
-- Userspace representation. 
-
-The infrastructure consists of a number of object types to support
-this functionality. Their programming interfaces are described below
-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. 
-
-
-The kobject infrastructure maintains a close relationship with the
-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. 
-
-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. 
-
-
-1. kobjects
-
-1.1 Description
-
-
-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. 
-
-1.2 Definition
-
-struct kobject {
-	const char		* k_name;
-	struct kref		kref;
-	struct list_head	entry;
-	struct kobject		* parent;
-	struct kset		* kset;
-	struct kobj_type	* ktype;
-	struct sysfs_dirent	* sd;
-	wait_queue_head_t	poll;
-};
-
-void kobject_init(struct kobject *);
-int kobject_add(struct kobject *);
-int kobject_register(struct kobject *);
-
-void kobject_del(struct kobject *);
-void kobject_unregister(struct kobject *);
-
-struct kobject * kobject_get(struct kobject *);
-void kobject_put(struct kobject *);
-
-
-1.3 kobject Programming Interface
-
-kobjects may be dynamically added and removed from the kobject core
-using kobject_register() and kobject_unregister(). Registration
-includes inserting the kobject in the list of its dominant kset and
-creating a directory for it in sysfs.
-
-Alternatively, one may use a kobject without adding it to its kset's list
-or exporting it via sysfs, by simply calling kobject_init(). An
-initialized kobject may later be added to the object hierarchy by
-calling kobject_add(). An initialized kobject may be used for
-reference counting.
-
-Note: calling kobject_init() then kobject_add() is functionally
-equivalent to calling kobject_register().
-
-When a kobject is unregistered, it is removed from its kset's list,
-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. 
-
-A kobject's reference count may be incremented with kobject_get(),
-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. 
-
-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!!! 
-
-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. 
-
-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. 
-
-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). 
-
-
-1.4 sysfs
-
-Each kobject receives a directory in sysfs. This directory is created
-under the kobject's parent directory. 
-
-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.
-
-
-
-2. ksets
-
-2.1 Description
-
-A kset is a set of kobjects that are embedded in the same type. 
-
-
-struct kset {
-	struct kobj_type	* ktype;
-	struct list_head	list;
-	struct kobject		kobj;
-	struct kset_uevent_ops	* uevent_ops;
-};
-
-
-void kset_init(struct kset * k);
-int kset_add(struct kset * k);
-int kset_register(struct kset * k);
-void kset_unregister(struct kset * k);
-
-struct kset * kset_get(struct kset * k);
-void kset_put(struct kset * k);
-
-struct kobject * kset_find_obj(struct kset *, char *);
-
-
-The type that the kobjects are embedded in is described by the ktype
-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). 
-
-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
-partitions (struct hd_struct) that have been found on the device. The
-following code snippet illustrates how to express this properly.
-
-	 struct gendisk * disk;
-	 ...
-	 disk->kset.kobj.kset = &block_kset;
-	 disk->kset.ktype = &partition_ktype;
-	 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. 
-
-- 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. 
-
-
-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. 
-
-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
-
-ksets are represented in sysfs when their embedded kobjects are
-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. 
-
-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. 
-
-
-3. struct ktype
-
-3.1. Description
-
-struct kobj_type {
-	void (*release)(struct kobject *);
-	struct sysfs_ops	* sysfs_ops;
-	struct attribute	** default_attrs;
-};
-
-
-Object types require specific functions for converting between the
-generic object and the more complex type. struct kobj_type provides
-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. 
-
-- sysfs_ops: Provides conversion functions for sysfs access. Please
-  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
-  initialized to NULL ! You can find a complete implementation
-  in block/genhd.c
-
-
-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. 
-
-- 
1.5.3.8

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/