Merge bk://ldm.bkbits.net/linux-2.5-kobject

into penguin.transmeta.com:/home/penguin/torvalds/repositories/kernel/linux

Documentation/kobject.txt

+kobjects - Simple, Generic Kernel Objects
+
+Patrick Mochel <mochel@osdl.org>
+
+30 October 2002
+
+
+kobjects
+
+struct kobject introduces a simple, intregral datatype and a simple
+set of semantics for operating on the device. kobjects are intended to
+be embedded in larger data structures and replace fields it
+duplicates. A set of library functions has been developed to assist in
+the manipulation of kobjects.
+
+struct kobject looks like this:
+
+
+struct kobject {
+	char			name[16];
+	atomic_t		refcount;
+	struct list_head	entry;
+	struct kobject		* parent;
+	struct subsystem	* subsys;
+	struct dentry		* dentry;
+};
+
+void kobject_init(struct kobject *);
+int kobject_register(struct kobject *);
+void kobject_unregister(struct kobject *);
+struct kobject * kobject_get(struct kobject *);
+void kobject_put(struct kobject *);
+
+
+
+subsystems
+
+struct subsystem is introduced to describe a collection of objects of
+a certain type. subsystems are kobjects themselves, though they
+contain lists of kobjects that belong to that subsystem. Objects of a
+subsystem (the embedder objects in which kobjects live) are all of the
+same type. The interface looks like:
+
+
+struct subsystem {
+	struct kobject		kobj;
+	struct list_head	list;
+	struct rw_semaphore	rwsem;
+	struct subsystem	* parent;
+	void (*release)(struct kobject *);
+	struct sysfs_ops	* sysfs_ops;
+	struct attribute	** default_attrs;
+};
+
+void subsystem_init(struct subsystem *);
+int subsystem_register(struct subsystem *);
+void subsystem_unregister(struct subsystem *);
+
+struct subsystem * subsys_get(struct subsystem * s);
+void subsys_put(struct subsystem * s);
+
+
+
+Familial Relations
+
+kobjects and subsystems intersect and intertwine in several ways. Each
+is well-defined (though maybe they could be made simpler). Each kobject
+belongs to a subsystem. Since subsystems are kobjects themselves, they
+also belong to a controlling subsystem. This implies that subsystems
+are hierarchial. 
+
+Many kobjects are hierarchial in nature, which is represented by
+including a pointer to its parent kobject in struct kobject. Many
+different types of kobject-embedding objects may all point to the same
+parent. 
+
+The ancestral hierarchy of kobjects should not be confused with
+membership in a subsystem, or the ancestral relationship of
+subsystems. A set of kobjects may all belong to a subsystem, but all
+have different parents. 
+
+kobjects may be orphans and have no explicit parent. In that case, the
+subsystem to which the object belongs becomes its parent. 
+
+
+Sysfs
+
+These rules force a complete kobject hierarchy, which Suprise! maps
+very well onto a filesystem.
+
+driverfs was recently cloned, and there now exists sysfs. All driverfs
+operations operate on a separate data type: struct driver_dir_entry,
+which all objects that are represented in driverfs must have. driverfs
+also allowed rogue directory creation that had no explicit objects
+associated with them.
+
+struct kobject is intended to be the common data type which sysfs
+operates on. This gives the filesystem the ability to directly access
+more fields of the object, including the reference count. This also
+forces each directory in the filesystem to be tied directly to a
+kobject. 
+
+
+Directory Placement
+
+Parental relationships are determined in the kobject/subsystem layer,
+and the kobject is then passed off to the sysfs layer. kobjects with
+no parent have directories created for them in the sysfs root
+directory. Per the rules above, the only kobjects that remain orphans
+are subsystems without parent subsystems (since leaf objects either
+have an explicit parent, or are assigned their controlling subsystem
+as their foster parent). 
+
+
+File Callbacks
+
+Previously, each driverfs directory contained a pointer to a list of file
+operations for reading and writing driverfs files. These callbacks
+received a struct driver_dir_entry, when they performed a
+container_of() transform on to receive the specific object type for
+which the call was meant. 
+
+These callbacks have been converted to accept a struct kobject instead
+of struct driver_dir_entry. Since all kobjects belong to a subsystem
+that contains kobjects all of the same type, the sysfs operations
+have been moved to reside in the subsystem, since they are common for
+all kobjects.
+
+
+Default Attributes
+
+Most subsystems have a set of default attributes associated with an
+object that registers with them. A subsystem definition may contain a
+NULL-terminated array of attributes that will be exported when an
+object is registered with the subsystem. 
+
+
+Reference Counting
+
+All objects contain reference counts. All functions accessing objects
+should increment the reference count until they are finished, and
+decrement the reference count. When an object is initialized, it
+receives a reference count of 1. When a device is unregistered, the
+reference is decremented. When the reference counts reaches 0, the
+subsystem's ->release() callback for that object type (remember
+subsystems control only one type of device each) is called; and the
+reference counts of the kobject's subsystem and parent are
+decremented. 
+
+The ->release() callback is the opportunity for the subsystem to free
+memory allocated for the object. It is the notification that
+absolutely no one is using the structure any more (and can't acquire a
+reference to it), so it is safe to free it.
+

include/linux/kobject.h

+/*
+ * kobject.h - generic kernel object infrastructure.
+ *
+ */
+
+#ifndef _KOBJECT_H_
+#define _KOBJECT_H_
+
+#include <linux/types.h>
+#include <linux/list.h>
+#include <linux/sysfs.h>
+#include <linux/rwsem.h>
+#include <asm/atomic.h>
+
+struct kobject {
+	char			name[16];
+	atomic_t		refcount;
+	struct list_head	entry;
+	struct kobject		* parent;
+	struct subsystem	* subsys;
+	struct dentry		* dentry;
+};
+
+extern void kobject_init(struct kobject *);
+
+extern int kobject_register(struct kobject *);
+extern void kobject_unregister(struct kobject *);
+
+extern struct kobject * kobject_get(struct kobject *);
+extern void kobject_put(struct kobject *);
+
+
+struct subsystem {
+	struct kobject		kobj;
+	struct list_head	list;
+	struct rw_semaphore	rwsem;
+	struct subsystem	* parent;
+	void (*release)(struct kobject *);
+	struct sysfs_ops	* sysfs_ops;
+	struct attribute	** default_attrs;
+};
+
+extern void subsystem_init(struct subsystem *);
+extern int subsystem_register(struct subsystem *);
+extern void subsystem_unregister(struct subsystem *);
+
+static inline struct subsystem * subsys_get(struct subsystem * s)
+{
+	return container_of(kobject_get(&s->kobj),struct subsystem,kobj);
+}
+
+static inline void subsys_put(struct subsystem * s)
+{
+	kobject_put(&s->kobj);
+}
+
+#endif /* _KOBJECT_H_ */

include/linux/sysfs.h

@@ -11,19 +11,11 @@
 
 struct driver_dir_entry;
 struct attribute;
+struct kobject;
 
 struct sysfs_ops {
-	int	(*open)(struct driver_dir_entry *);
-	int	(*close)(struct driver_dir_entry *);
-	ssize_t	(*show)(struct driver_dir_entry *, struct attribute *,char *, size_t, loff_t);
-	ssize_t	(*store)(struct driver_dir_entry *,struct attribute *,const char *, size_t, loff_t);
-};
-
-struct driver_dir_entry {
-	char			* name;
-	struct dentry		* dentry;
-	mode_t			mode;
-	struct sysfs_ops	* ops;
+	ssize_t	(*show)(struct kobject *, struct attribute *,char *, size_t, loff_t);
+	ssize_t	(*store)(struct kobject *,struct attribute *,const char *, size_t, loff_t);
 };
 
 struct attribute {
@@ -32,20 +24,21 @@ struct attribute {
 };
 
 extern int
-sysfs_create_dir(struct driver_dir_entry *, struct driver_dir_entry *);
+sysfs_create_dir(struct kobject *);
 
 extern void
-sysfs_remove_dir(struct driver_dir_entry * entry);
+sysfs_remove_dir(struct kobject *);
 
 extern int
-sysfs_create_file(struct attribute * attr,
-		     struct driver_dir_entry * parent);
+sysfs_create_file(struct kobject *, struct attribute *);
+
+extern void
+sysfs_remove_file(struct kobject *, struct attribute *);
 
 extern int 
-sysfs_create_symlink(struct driver_dir_entry * parent, 
-			char * name, char * target);
+sysfs_create_link(struct kobject * kobj, struct kobject * target, char * name);
 
 extern void
-sysfs_remove_file(struct driver_dir_entry *, const char * name);
+sysfs_remove_link(struct kobject *, char * name);
 
 #endif /* _SYSFS_H_ */

lib/Makefile

@@ -9,10 +9,11 @@
 L_TARGET := lib.a
 
 export-objs := cmdline.o dec_and_lock.o rwsem-spinlock.o rwsem.o \
-	       crc32.o rbtree.o radix-tree.o
+	       crc32.o rbtree.o radix-tree.o kobject.o
 
 obj-y := errno.o ctype.o string.o vsprintf.o brlock.o cmdline.o \
-	 bust_spinlocks.o rbtree.o radix-tree.o dump_stack.o
+	 bust_spinlocks.o rbtree.o radix-tree.o dump_stack.o \
+	 kobject.o
 
 obj-$(CONFIG_RWSEM_GENERIC_SPINLOCK) += rwsem-spinlock.o
 obj-$(CONFIG_RWSEM_XCHGADD_ALGORITHM) += rwsem.o

lib/kobject.c

+/*
+ * kobject.c - library routines for handling generic kernel objects
+ */
+
+#define DEBUG 1
+
+#include <linux/kobject.h>
+#include <linux/module.h>
+#include <linux/stat.h>
+
+/**
+ *	kobject_populate_dir - populate directory with attributes.
+ *	@kobj:	object we're working on.
+ *
+ *	Most subsystems have a set of default attributes that 
+ *	are associated with an object that registers with them.
+ *	This is a helper called during object registration that 
+ *	loops through the default attributes of the subsystem 
+ *	and creates attributes files for them in sysfs.
+ *
+ */
+
+static int kobject_populate_dir(struct kobject * kobj)
+{
+	struct subsystem * s = kobj->subsys;
+	struct attribute * attr;
+	int error = 0;
+	int i;
+	
+	if (s && s->default_attrs) {
+		for (i = 0; (attr = s->default_attrs[i]); i++) {
+			if ((error = sysfs_create_file(kobj,attr)))
+				break;
+		}
+	}
+	return error;
+}
+
+/**
+ *	kobject_init - initialize object.
+ *	@kobj:	object in question.
+ */
+
+void kobject_init(struct kobject * kobj)
+{
+	atomic_set(&kobj->refcount,1);
+	INIT_LIST_HEAD(&kobj->entry);
+}
+
+/**
+ *	kobject_register - register an object.
+ *	@kobj:	object in question.
+ *
+ *	For now, fill in the replicated fields in the object's
+ *	directory entry, and create a dir in sysfs. 
+ *	This stuff should go away in the future, as we move
+ *	more implicit things to sysfs.
+ */
+
+int kobject_register(struct kobject * kobj)
+{
+	int error = 0;
+	struct subsystem * s = subsys_get(kobj->subsys);
+	struct kobject * parent = kobject_get(kobj->parent);
+
+	pr_debug("kobject %s: registering\n",kobj->name);
+	if (parent)
+		pr_debug("  parent is %s\n",parent->name);
+	if (s) {
+		down_write(&s->rwsem);
+		if (parent) 
+			list_add_tail(&kobj->entry,&parent->entry);
+		else {
+			list_add_tail(&kobj->entry,&s->list);
+			kobj->parent = &s->kobj;
+		}
+		up_write(&s->rwsem);
+	}
+	error = sysfs_create_dir(kobj);
+	if (!error) {
+		error = kobject_populate_dir(kobj);
+		if (error)
+			sysfs_remove_dir(kobj);
+	}
+	return error;
+}
+
+/**
+ *	kobject_unregister - unlink an object.
+ *	@kobj:	object going away.
+ *
+ *	The device has been told to be removed, but may
+ *	not necessarily be disappearing from the kernel.
+ *	So, we remove the directory and decrement the refcount
+ *	that we set with kobject_register().
+ *
+ *	Eventually (maybe now), the refcount will hit 0, and 
+ *	put_device() will clean the device up.
+ */
+
+void kobject_unregister(struct kobject * kobj)
+{
+	pr_debug("kobject %s: unregistering\n",kobj->name);
+	sysfs_remove_dir(kobj);
+	if (kobj->subsys) {
+		down_write(&kobj->subsys->rwsem);
+		list_del_init(&kobj->entry);
+		up_write(&kobj->subsys->rwsem);
+	}
+	kobject_put(kobj);
+}
+
+/**
+ *	kobject_get - increment refcount for object.
+ *	@kobj:	object.
+ */
+
+struct kobject * kobject_get(struct kobject * kobj)
+{
+	struct kobject * ret = kobj;
+	if (kobj && atomic_read(&kobj->refcount) > 0)
+		atomic_inc(&kobj->refcount);
+	else
+		ret = NULL;
+	return ret;
+}
+
+/**
+ *	kobject_put - decrement refcount for object.
+ *	@kobj:	object.
+ *
+ *	Decrement the refcount, and check if 0. If it is, then 
+ *	we're gonna need to clean it up, and decrement the refcount
+ *	of its parent.
+ *
+ *	@kobj->parent could point to its subsystem, which we also 
+ *	want to decrement the reference count for. We always dec 
+ *	the refcount for the parent, but only do so for the subsystem
+ *	if it points to a different place than the parent.
+ */
+
+void kobject_put(struct kobject * kobj)
+{
+	struct kobject * parent = kobj->parent;
+	struct subsystem * s = kobj->subsys;
+
+	if (!atomic_dec_and_test(&kobj->refcount))
+		return;
+
+	pr_debug("kobject %s: cleaning up\n",kobj->name);
+	if (s) {
+		if (s->release)
+			s->release(kobj);
+		if (&s->kobj != parent)
+			subsys_put(s);
+	} 
+
+	if (parent) 
+		kobject_put(parent);
+}
+
+
+void subsystem_init(struct subsystem * s)
+{
+	kobject_init(&s->kobj);
+	init_rwsem(&s->rwsem);
+	INIT_LIST_HEAD(&s->list);
+}
+
+/**
+ *	subsystem_register - register a subsystem.
+ *	@s:	the subsystem we're registering.
+ */
+
+int subsystem_register(struct subsystem * s)
+{
+	subsystem_init(s);
+	if (s->parent)
+		s->kobj.parent = &s->parent->kobj;
+	pr_debug("subsystem %s: registering\n",s->kobj.name);
+	if (s->parent)
+		pr_debug("  parent is %s\n",s->parent->kobj.name);
+	return kobject_register(&s->kobj);
+}
+
+void subsystem_unregister(struct subsystem * s)
+{
+	pr_debug("subsystem %s: unregistering\n",s->kobj.name);
+	kobject_unregister(&s->kobj);
+}
+
+
+EXPORT_SYMBOL(kobject_init);
+EXPORT_SYMBOL(kobject_register);
+EXPORT_SYMBOL(kobject_unregister);
+EXPORT_SYMBOL(kobject_get);
+EXPORT_SYMBOL(kobject_put);
+
+EXPORT_SYMBOL(subsystem_init);
+EXPORT_SYMBOL(subsystem_register);
+EXPORT_SYMBOL(subsystem_unregister);