aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kobject.txt
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/kobject.txt
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/kobject.txt')
-rw-r--r--Documentation/kobject.txt367
1 files changed, 367 insertions, 0 deletions
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
new file mode 100644
index 000000000000..8d9bffbd192c
--- /dev/null
+++ b/Documentation/kobject.txt
@@ -0,0 +1,367 @@
1The kobject Infrastructure
2
3Patrick Mochel <mochel@osdl.org>
4
5Updated: 3 June 2003
6
7
8Copyright (c) 2003 Patrick Mochel
9Copyright (c) 2003 Open Source Development Labs
10
11
120. Introduction
13
14The kobject infrastructure performs basic object management that larger
15data structures and subsystems can leverage, rather than reimplement
16similar functionality. This functionality primarily concerns:
17
18- Object reference counting.
19- Maintaining lists (sets) of objects.
20- Object set locking.
21- Userspace representation.
22
23The infrastructure consists of a number of object types to support
24this functionality. Their programming interfaces are described below
25in detail, and briefly here:
26
27- kobjects a simple object.
28- kset a set of objects of a certain type.
29- ktype a set of helpers for objects of a common type.
30- subsystem a controlling object for a number of ksets.
31
32
33The kobject infrastructure maintains a close relationship with the
34sysfs filesystem. Each kobject that is registered with the kobject
35core receives a directory in sysfs. Attributes about the kobject can
36then be exported. Please see Documentation/filesystems/sysfs.txt for
37more information.
38
39The kobject infrastructure provides a flexible programming interface,
40and allows kobjects and ksets to be used without being registered
41(i.e. with no sysfs representation). This is also described later.
42
43
441. kobjects
45
461.1 Description
47
48
49struct kobject is a simple data type that provides a foundation for
50more complex object types. It provides a set of basic fields that
51almost all complex data types share. kobjects are intended to be
52embedded in larger data structures and replace fields they duplicate.
53
541.2 Defintion
55
56struct kobject {
57 char name[KOBJ_NAME_LEN];
58 atomic_t refcount;
59 struct list_head entry;
60 struct kobject * parent;
61 struct kset * kset;
62 struct kobj_type * ktype;
63 struct dentry * dentry;
64};
65
66void kobject_init(struct kobject *);
67int kobject_add(struct kobject *);
68int kobject_register(struct kobject *);
69
70void kobject_del(struct kobject *);
71void kobject_unregister(struct kobject *);
72
73struct kobject * kobject_get(struct kobject *);
74void kobject_put(struct kobject *);
75
76
771.3 kobject Programming Interface
78
79kobjects may be dynamically added and removed from the kobject core
80using kobject_register() and kobject_unregister(). Registration
81includes inserting the kobject in the list of its dominant kset and
82creating a directory for it in sysfs.
83
84Alternatively, one may use a kobject without adding it to its kset's list
85or exporting it via sysfs, by simply calling kobject_init(). An
86initialized kobject may later be added to the object hierarchy by
87calling kobject_add(). An initialized kobject may be used for
88reference counting.
89
90Note: calling kobject_init() then kobject_add() is functionally
91equivalent to calling kobject_register().
92
93When a kobject is unregistered, it is removed from its kset's list,
94removed from the sysfs filesystem, and its reference count is decremented.
95List and sysfs removal happen in kobject_del(), and may be called
96manually. kobject_put() decrements the reference count, and may also
97be called manually.
98
99A kobject's reference count may be incremented with kobject_get(),
100which returns a valid reference to a kobject; and decremented with
101kobject_put(). An object's reference count may only be incremented if
102it is already positive.
103
104When a kobject's reference count reaches 0, the method struct
105kobj_type::release() (which the kobject's kset points to) is called.
106This allows any memory allocated for the object to be freed.
107
108
109NOTE!!!
110
111It is _imperative_ that you supply a destructor for dynamically
112allocated kobjects to free them if you are using kobject reference
113counts. The reference count controls the lifetime of the object.
114If it goes to 0, then it is assumed that the object will
115be freed and cannot be used.
116
117More importantly, you must free the object there, and not immediately
118after an unregister call. If someone else is referencing the object
119(e.g. through a sysfs file), they will obtain a reference to the
120object, assume it's valid and operate on it. If the object is
121unregistered and freed in the meantime, the operation will then
122reference freed memory and go boom.
123
124This can be prevented, in the simplest case, by defining a release
125method and freeing the object from there only. Note that this will not
126secure reference count/object management models that use a dual
127reference count or do other wacky things with the reference count
128(like the networking layer).
129
130
1311.4 sysfs
132
133Each kobject receives a directory in sysfs. This directory is created
134under the kobject's parent directory.
135
136If a kobject does not have a parent when it is registered, its parent
137becomes its dominant kset.
138
139If 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
141happen for kobjects that are embedded in a struct subsystem.
142
143
144
1452. ksets
146
1472.1 Description
148
149A kset is a set of kobjects that are embedded in the same type.
150
151
152struct kset {
153 struct subsystem * subsys;
154 struct kobj_type * ktype;
155 struct list_head list;
156 struct kobject kobj;
157};
158
159
160void kset_init(struct kset * k);
161int kset_add(struct kset * k);
162int kset_register(struct kset * k);
163void kset_unregister(struct kset * k);
164
165struct kset * kset_get(struct kset * k);
166void kset_put(struct kset * k);
167
168struct kobject * kset_find_obj(struct kset *, char *);
169
170
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
173subsys pointer.
174
175A kset contains a kobject itself, meaning that it may be registered in
176the kobject hierarchy and exported via sysfs. More importantly, the
177kset may be embedded in a larger data type, and may be part of another
178kset (of that object type).
179
180For example, a block device is an object (struct gendisk) that is
181contained in a set of block devices. It may also contain a set of
182partitions (struct hd_struct) that have been found on the device. The
183following code snippet illustrates how to express this properly.
184
185 struct gendisk * disk;
186 ...
187 disk->kset.kobj.kset = &block_kset;
188 disk->kset.ktype = &partition_ktype;
189 kset_register(&disk->kset);
190
191- The kset that the disk's embedded object belongs to is the
192 block_kset, and is pointed to by disk->kset.kobj.kset.
193
194- The type of objects on the disk's _subordinate_ list are partitions,
195 and is set in disk->kset.ktype.
196
197- The kset is then registered, which handles initializing and adding
198 the embedded kobject to the hierarchy.
199
200
2012.2 kset Programming Interface
202
203All kset functions, except kset_find_obj(), eventually forward the
204calls to their embedded kobjects after performing kset-specific
205operations. ksets offer a similar programming model to kobjects: they
206may be used after they are initialized, without registering them in
207the hierarchy.
208
209kset_find_obj() may be used to locate a kobject with a particular
210name. The kobject, if found, is returned.
211
212
2132.3 sysfs
214
215ksets are represented in sysfs when their embedded kobjects are
216registered. They follow the same rules of parenting, with one
217exception. If a kset does not have a parent, nor is its embedded
218kobject part of another kset, the kset's parent becomes its dominant
219subsystem.
220
221If the kset does not have a parent, its directory is created at the
222sysfs root. This should only happen when the kset registered is
223embedded in a subsystem itself.
224
225
2263. struct ktype
227
2283.1. Description
229
230struct kobj_type {
231 void (*release)(struct kobject *);
232 struct sysfs_ops * sysfs_ops;
233 struct attribute ** default_attrs;
234};
235
236
237Object types require specific functions for converting between the
238generic object and the more complex type. struct kobj_type provides
239the object-specific fields, which include:
240
241- release: Called when the kobject's reference count reaches 0. This
242 should convert the object to the more complex type and free it.
243
244- sysfs_ops: Provides conversion functions for sysfs access. Please
245 see the sysfs documentation for more information.
246
247- default_attrs: Default attributes to be exported via sysfs when the
248 object is registered.Note that the last attribute has to be
249 initialized to NULL ! You can find a complete implementation
250 in drivers/block/genhd.c
251
252
253Instances of struct kobj_type are not registered; only referenced by
254the kset. A kobj_type may be referenced by an arbitrary number of
255ksets, as there may be disparate sets of identical objects.
256
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