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 <cornelia.huck@de.ibm.com> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

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 <cornelia.huck@de.ibm.com> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Cornelia Huck · Greg Kroah-Hartman
1 parent a56156489d
Showing 1 changed file with 59 additions and 119 deletions Side-by-side Diff
Documentation/kobject.txt
@@ -27,7 +27,6 @@
 - 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 @@
 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 @@
 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 @@
  
  
 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 @@
  
  
 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,7 +208,59 @@
 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
  
 ksets are represented in sysfs when their embedded kobjects are
@@ -253,115 +304,4 @@
 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).
...	...	@@ -27,7 +27,6 @@
27	27	- kobjects a simple object.
28	28	- kset a set of objects of a certain type.
29	29	- ktype a set of helpers for objects of a common type.
30		-- subsystem a controlling object for a number of ksets.
31	30
32	31
33	32	The kobject infrastructure maintains a close relationship with the
34	33
35	34
...	...	@@ -54,13 +53,15 @@
54	53	1.2 Definition
55	54
56	55	struct kobject {
	56	+ const char * k_name;
57	57	char name[KOBJ_NAME_LEN];
58		- atomic_t refcount;
	58	+ struct kref kref;
59	59	struct list_head entry;
60	60	struct kobject * parent;
61	61	struct kset * kset;
62	62	struct kobj_type * ktype;
63		- struct dentry * dentry;
	63	+ struct sysfs_dirent * sd;
	64	+ wait_queue_head_t poll;
64	65	};
65	66
66	67	void kobject_init(struct kobject *);
...	...	@@ -137,8 +138,7 @@
137	138	becomes its dominant kset.
138	139
139	140	If a kobject does not have a parent nor a dominant kset, its directory
140		-is created at the top-level of the sysfs partition. This should only
141		-happen for kobjects that are embedded in a struct subsystem.
	141	+is created at the top-level of the sysfs partition.
142	142
143	143
144	144
145	145
...	...	@@ -150,10 +150,10 @@
150	150
151	151
152	152	struct kset {
153		- struct subsystem * subsys;
154	153	struct kobj_type * ktype;
155	154	struct list_head list;
156	155	struct kobject kobj;
	156	+ struct kset_uevent_ops * uevent_ops;
157	157	};
158	158
159	159
...	...	@@ -169,8 +169,7 @@
169	169
170	170
171	171	The type that the kobjects are embedded in is described by the ktype
172		-pointer. The subsystem that the kobject belongs to is pointed to by the
173		-subsys pointer.
	172	+pointer.
174	173
175	174	A kset contains a kobject itself, meaning that it may be registered in
176	175	the kobject hierarchy and exported via sysfs. More importantly, the
177	176
...	...	@@ -209,7 +208,59 @@
209	208	kset_find_obj() may be used to locate a kobject with a particular
210	209	name. The kobject, if found, is returned.
211	210
	211	+There are also some helper functions which names point to the formerly
	212	+existing "struct subsystem", whose functions have been taken over by
	213	+ksets.
212	214
	215	+
	216	+decl_subsys(name,type,uevent_ops)
	217	+
	218	+Declares a kset named '<name>_subsys' of type <type> with
	219	+uevent_ops <uevent_ops>. For example,
	220	+
	221	+decl_subsys(devices, &ktype_device, &device_uevent_ops);
	222	+
	223	+is equivalent to doing:
	224	+
	225	+struct kset devices_subsys = {
	226	+ .kobj = {
	227	+ .name = "devices",
	228	+ },
	229	+ .ktype = &ktype_devices,
	230	+ .uevent_ops = &device_uevent_ops,
	231	+};
	232	+
	233	+
	234	+The objects that are registered with a subsystem that use the
	235	+subsystem's default list must have their kset ptr set properly. These
	236	+objects may have embedded kobjects or ksets. The
	237	+following helpers make setting the kset easier:
	238	+
	239	+
	240	+kobj_set_kset_s(obj,subsys)
	241	+
	242	+- Assumes that obj->kobj exists, and is a struct kobject.
	243	+- Sets the kset of that kobject to the kset <subsys>.
	244	+
	245	+
	246	+kset_set_kset_s(obj,subsys)
	247	+
	248	+- Assumes that obj->kset exists, and is a struct kset.
	249	+- Sets the kset of the embedded kobject to the kset <subsys>.
	250	+
	251	+subsys_set_kset(obj,subsys)
	252	+
	253	+- Assumes obj->subsys exists, and is a struct subsystem.
	254	+- Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
	255	+
	256	+void subsystem_init(struct kset *s);
	257	+int subsystem_register(struct kset *s);
	258	+void subsystem_unregister(struct kset *s);
	259	+struct kset subsys_get(struct kset s);
	260	+void kset_put(struct kset *s);
	261	+
	262	+These are just wrappers around the respective kset_* functions.
	263	+
213	264	2.3 sysfs
214	265
215	266	ksets are represented in sysfs when their embedded kobjects are
...	...	@@ -253,115 +304,4 @@
253	304	Instances of struct kobj_type are not registered; only referenced by
254	305	the kset. A kobj_type may be referenced by an arbitrary number of
255	306	ksets, as there may be disparate sets of identical objects.
256		-
257		-
258		-
259		-4. subsystems
260		-
261		-4.1 Description
262		-
263		-A subsystem represents a significant entity of code that maintains an
264		-arbitrary number of sets of objects of various types. Since the number
265		-of ksets and the type of objects they contain are variable, a
266		-generic representation of a subsystem is minimal.
267		-
268		-
269		-struct subsystem {
270		- struct kset kset;
271		- struct rw_semaphore rwsem;
272		-};
273		-
274		-int subsystem_register(struct subsystem *);
275		-void subsystem_unregister(struct subsystem *);
276		-
277		-struct subsystem * subsys_get(struct subsystem * s);
278		-void subsys_put(struct subsystem * s);
279		-
280		-
281		-A subsystem contains an embedded kset so:
282		-
283		-- It can be represented in the object hierarchy via the kset's
284		- embedded kobject.
285		-
286		-- It can maintain a default list of objects of one type.
287		-
288		-Additional ksets may attach to the subsystem simply by referencing the
289		-subsystem before they are registered. (This one-way reference means
290		-that there is no way to determine the ksets that are attached to the
291		-subsystem.)
292		-
293		-All ksets that are attached to a subsystem share the subsystem's R/W
294		-semaphore.
295		-
296		-
297		-4.2 subsystem Programming Interface.
298		-
299		-The subsystem programming interface is simple and does not offer the
300		-flexibility that the kset and kobject programming interfaces do. They
301		-may be registered and unregistered, as well as reference counted. Each
302		-call forwards the calls to their embedded ksets (which forward the
303		-calls to their embedded kobjects).
304		-
305		-
306		-4.3 Helpers
307		-
308		-A number of macros are available to make dealing with subsystems and
309		-their embedded objects easier.
310		-
311		-
312		-decl_subsys(name,type)
313		-
314		-Declares a subsystem named '<name>_subsys', with an embedded kset of
315		-type <type>. For example,
316		-
317		-decl_subsys(devices,&ktype_devices);
318		-
319		-is equivalent to doing:
320		-
321		-struct subsystem device_subsys = {
322		- .kset = {
323		- .kobj = {
324		- .name = "devices",
325		- },
326		- .ktype = &ktype_devices,
327		- }
328		-};
329		-
330		-
331		-The objects that are registered with a subsystem that use the
332		-subsystem's default list must have their kset ptr set properly. These
333		-objects may have embedded kobjects, ksets, or other subsystems. The
334		-following helpers make setting the kset easier:
335		-
336		-
337		-kobj_set_kset_s(obj,subsys)
338		-
339		-- Assumes that obj->kobj exists, and is a struct kobject.
340		-- Sets the kset of that kobject to the subsystem's embedded kset.
341		-
342		-
343		-kset_set_kset_s(obj,subsys)
344		-
345		-- Assumes that obj->kset exists, and is a struct kset.
346		-- Sets the kset of the embedded kobject to the subsystem's
347		- embedded kset.
348		-
349		-subsys_set_kset(obj,subsys)
350		-
351		-- Assumes obj->subsys exists, and is a struct subsystem.
352		-- Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
353		-
354		-
355		-4.4 sysfs
356		-
357		-subsystems are represented in sysfs via their embedded kobjects. They
358		-follow the same rules as previously mentioned with no exceptions. They
359		-typically receive a top-level directory in sysfs, except when their
360		-embedded kobject is part of another kset, or the parent of the
361		-embedded kobject is explicitly set.
362		-
363		-Note that the subsystem's embedded kset must be 'attached' to the
364		-subsystem itself in order to use its rwsem. This is done after
365		-kset_add() has been called. (Not before, because kset_add() uses its
366		-subsystem for a default parent if it doesn't already have one).