aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kobject.txt
diff options
context:
space:
mode:
authorCornelia Huck <cornelia.huck@de.ibm.com>2007-07-27 07:41:10 -0400
committerGreg Kroah-Hartman <gregkh@suse.de>2007-07-30 17:25:13 -0400
commitf285ea058001ef534f9e53a21aad42c2952bbad5 (patch)
treed3e4df63f49fc10c599d9fd123812ac297c226ce /Documentation/kobject.txt
parenta56156489dbdc60ac39a77b8a988d375b2f273a0 (diff)
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>
Diffstat (limited to 'Documentation/kobject.txt')
-rw-r--r--Documentation/kobject.txt178
1 files changed, 59 insertions, 119 deletions
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index e44855513b3d..8ee49ee7c963 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -27,7 +27,6 @@ in detail, and briefly here:
27- kobjects a simple object. 27- kobjects a simple object.
28- kset a set of objects of a certain type. 28- kset a set of objects of a certain type.
29- ktype a set of helpers for objects of a common type. 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
33The kobject infrastructure maintains a close relationship with the 32The kobject infrastructure maintains a close relationship with the
@@ -54,13 +53,15 @@ embedded in larger data structures and replace fields they duplicate.
541.2 Definition 531.2 Definition
55 54
56struct kobject { 55struct kobject {
56 const char * k_name;
57 char name[KOBJ_NAME_LEN]; 57 char name[KOBJ_NAME_LEN];
58 atomic_t refcount; 58 struct kref kref;
59 struct list_head entry; 59 struct list_head entry;
60 struct kobject * parent; 60 struct kobject * parent;
61 struct kset * kset; 61 struct kset * kset;
62 struct kobj_type * ktype; 62 struct kobj_type * ktype;
63 struct dentry * dentry; 63 struct sysfs_dirent * sd;
64 wait_queue_head_t poll;
64}; 65};
65 66
66void kobject_init(struct kobject *); 67void kobject_init(struct kobject *);
@@ -137,8 +138,7 @@ If a kobject does not have a parent when it is registered, its parent
137becomes its dominant kset. 138becomes its dominant kset.
138 139
139If a kobject does not have a parent nor a dominant kset, its directory 140If a kobject does not have a parent nor a dominant kset, its directory
140is created at the top-level of the sysfs partition. This should only 141is created at the top-level of the sysfs partition.
141happen for kobjects that are embedded in a struct subsystem.
142 142
143 143
144 144
@@ -150,10 +150,10 @@ A kset is a set of kobjects that are embedded in the same type.
150 150
151 151
152struct kset { 152struct kset {
153 struct subsystem * subsys;
154 struct kobj_type * ktype; 153 struct kobj_type * ktype;
155 struct list_head list; 154 struct list_head list;
156 struct kobject kobj; 155 struct kobject kobj;
156 struct kset_uevent_ops * uevent_ops;
157}; 157};
158 158
159 159
@@ -169,8 +169,7 @@ struct kobject * kset_find_obj(struct kset *, char *);
169 169
170 170
171The type that the kobjects are embedded in is described by the ktype 171The type that the kobjects are embedded in is described by the ktype
172pointer. The subsystem that the kobject belongs to is pointed to by the 172pointer.
173subsys pointer.
174 173
175A kset contains a kobject itself, meaning that it may be registered in 174A kset contains a kobject itself, meaning that it may be registered in
176the kobject hierarchy and exported via sysfs. More importantly, the 175the kobject hierarchy and exported via sysfs. More importantly, the
@@ -209,6 +208,58 @@ the hierarchy.
209kset_find_obj() may be used to locate a kobject with a particular 208kset_find_obj() may be used to locate a kobject with a particular
210name. The kobject, if found, is returned. 209name. The kobject, if found, is returned.
211 210
211There are also some helper functions which names point to the formerly
212existing "struct subsystem", whose functions have been taken over by
213ksets.
214
215
216decl_subsys(name,type,uevent_ops)
217
218Declares a kset named '<name>_subsys' of type <type> with
219uevent_ops <uevent_ops>. For example,
220
221decl_subsys(devices, &ktype_device, &device_uevent_ops);
222
223is equivalent to doing:
224
225struct kset devices_subsys = {
226 .kobj = {
227 .name = "devices",
228 },
229 .ktype = &ktype_devices,
230 .uevent_ops = &device_uevent_ops,
231};
232
233
234The objects that are registered with a subsystem that use the
235subsystem's default list must have their kset ptr set properly. These
236objects may have embedded kobjects or ksets. The
237following helpers make setting the kset easier:
238
239
240kobj_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
246kset_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
251subsys_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
256void subsystem_init(struct kset *s);
257int subsystem_register(struct kset *s);
258void subsystem_unregister(struct kset *s);
259struct kset *subsys_get(struct kset *s);
260void kset_put(struct kset *s);
261
262These are just wrappers around the respective kset_* functions.
212 263
2132.3 sysfs 2642.3 sysfs
214 265
@@ -254,114 +305,3 @@ Instances of struct kobj_type are not registered; only referenced by
254the kset. A kobj_type may be referenced by an arbitrary number of 305the kset. A kobj_type may be referenced by an arbitrary number of
255ksets, as there may be disparate sets of identical objects. 306ksets, as there may be disparate sets of identical objects.
256 307
257
258
2594. subsystems
260
2614.1 Description
262
263A subsystem represents a significant entity of code that maintains an
264arbitrary number of sets of objects of various types. Since the number
265of ksets and the type of objects they contain are variable, a
266generic representation of a subsystem is minimal.
267
268
269struct subsystem {
270 struct kset kset;
271 struct rw_semaphore rwsem;
272};
273
274int subsystem_register(struct subsystem *);
275void subsystem_unregister(struct subsystem *);
276
277struct subsystem * subsys_get(struct subsystem * s);
278void subsys_put(struct subsystem * s);
279
280
281A 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
288Additional ksets may attach to the subsystem simply by referencing the
289subsystem before they are registered. (This one-way reference means
290that there is no way to determine the ksets that are attached to the
291subsystem.)
292
293All ksets that are attached to a subsystem share the subsystem's R/W
294semaphore.
295
296
2974.2 subsystem Programming Interface.
298
299The subsystem programming interface is simple and does not offer the
300flexibility that the kset and kobject programming interfaces do. They
301may be registered and unregistered, as well as reference counted. Each
302call forwards the calls to their embedded ksets (which forward the
303calls to their embedded kobjects).
304
305
3064.3 Helpers
307
308A number of macros are available to make dealing with subsystems and
309their embedded objects easier.
310
311
312decl_subsys(name,type)
313
314Declares a subsystem named '<name>_subsys', with an embedded kset of
315type <type>. For example,
316
317decl_subsys(devices,&ktype_devices);
318
319is equivalent to doing:
320
321struct subsystem device_subsys = {
322 .kset = {
323 .kobj = {
324 .name = "devices",
325 },
326 .ktype = &ktype_devices,
327 }
328};
329
330
331The objects that are registered with a subsystem that use the
332subsystem's default list must have their kset ptr set properly. These
333objects may have embedded kobjects, ksets, or other subsystems. The
334following helpers make setting the kset easier:
335
336
337kobj_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
343kset_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
349subsys_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
3554.4 sysfs
356
357subsystems are represented in sysfs via their embedded kobjects. They
358follow the same rules as previously mentioned with no exceptions. They
359typically receive a top-level directory in sysfs, except when their
360embedded kobject is part of another kset, or the parent of the
361embedded kobject is explicitly set.
362
363Note that the subsystem's embedded kset must be 'attached' to the
364subsystem itself in order to use its rwsem. This is done after
365kset_add() has been called. (Not before, because kset_add() uses its
366subsystem for a default parent if it doesn't already have one).
367