ia64/linux-2.6.18-xen.hg

view Documentation/kobject.txt @ 912:dd42cdb0ab89

[IA64] Build blktap2 driver by default in x86 builds.

add CONFIG_XEN_BLKDEV_TAP2=y to buildconfigs/linux-defconfig_xen_ia64.

Signed-off-by: Isaku Yamahata <yamahata@valinux.co.jp>
author Isaku Yamahata <yamahata@valinux.co.jp>
date Mon Jun 29 12:09:16 2009 +0900 (2009-06-29)
parents 831230e53067
children
line source
1 The kobject Infrastructure
3 Patrick Mochel <mochel@osdl.org>
5 Updated: 3 June 2003
8 Copyright (c) 2003 Patrick Mochel
9 Copyright (c) 2003 Open Source Development Labs
12 0. Introduction
14 The kobject infrastructure performs basic object management that larger
15 data structures and subsystems can leverage, rather than reimplement
16 similar functionality. This functionality primarily concerns:
18 - Object reference counting.
19 - Maintaining lists (sets) of objects.
20 - Object set locking.
21 - Userspace representation.
23 The infrastructure consists of a number of object types to support
24 this functionality. Their programming interfaces are described below
25 in detail, and briefly here:
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.
33 The kobject infrastructure maintains a close relationship with the
34 sysfs filesystem. Each kobject that is registered with the kobject
35 core receives a directory in sysfs. Attributes about the kobject can
36 then be exported. Please see Documentation/filesystems/sysfs.txt for
37 more information.
39 The kobject infrastructure provides a flexible programming interface,
40 and allows kobjects and ksets to be used without being registered
41 (i.e. with no sysfs representation). This is also described later.
44 1. kobjects
46 1.1 Description
49 struct kobject is a simple data type that provides a foundation for
50 more complex object types. It provides a set of basic fields that
51 almost all complex data types share. kobjects are intended to be
52 embedded in larger data structures and replace fields they duplicate.
54 1.2 Defintion
56 struct 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 };
66 void kobject_init(struct kobject *);
67 int kobject_add(struct kobject *);
68 int kobject_register(struct kobject *);
70 void kobject_del(struct kobject *);
71 void kobject_unregister(struct kobject *);
73 struct kobject * kobject_get(struct kobject *);
74 void kobject_put(struct kobject *);
77 1.3 kobject Programming Interface
79 kobjects may be dynamically added and removed from the kobject core
80 using kobject_register() and kobject_unregister(). Registration
81 includes inserting the kobject in the list of its dominant kset and
82 creating a directory for it in sysfs.
84 Alternatively, one may use a kobject without adding it to its kset's list
85 or exporting it via sysfs, by simply calling kobject_init(). An
86 initialized kobject may later be added to the object hierarchy by
87 calling kobject_add(). An initialized kobject may be used for
88 reference counting.
90 Note: calling kobject_init() then kobject_add() is functionally
91 equivalent to calling kobject_register().
93 When a kobject is unregistered, it is removed from its kset's list,
94 removed from the sysfs filesystem, and its reference count is decremented.
95 List and sysfs removal happen in kobject_del(), and may be called
96 manually. kobject_put() decrements the reference count, and may also
97 be called manually.
99 A kobject's reference count may be incremented with kobject_get(),
100 which returns a valid reference to a kobject; and decremented with
101 kobject_put(). An object's reference count may only be incremented if
102 it is already positive.
104 When a kobject's reference count reaches 0, the method struct
105 kobj_type::release() (which the kobject's kset points to) is called.
106 This allows any memory allocated for the object to be freed.
109 NOTE!!!
111 It is _imperative_ that you supply a destructor for dynamically
112 allocated kobjects to free them if you are using kobject reference
113 counts. The reference count controls the lifetime of the object.
114 If it goes to 0, then it is assumed that the object will
115 be freed and cannot be used.
117 More importantly, you must free the object there, and not immediately
118 after an unregister call. If someone else is referencing the object
119 (e.g. through a sysfs file), they will obtain a reference to the
120 object, assume it's valid and operate on it. If the object is
121 unregistered and freed in the meantime, the operation will then
122 reference freed memory and go boom.
124 This can be prevented, in the simplest case, by defining a release
125 method and freeing the object from there only. Note that this will not
126 secure reference count/object management models that use a dual
127 reference count or do other wacky things with the reference count
128 (like the networking layer).
131 1.4 sysfs
133 Each kobject receives a directory in sysfs. This directory is created
134 under the kobject's parent directory.
136 If a kobject does not have a parent when it is registered, its parent
137 becomes its dominant kset.
139 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.
145 2. ksets
147 2.1 Description
149 A kset is a set of kobjects that are embedded in the same type.
152 struct kset {
153 struct subsystem * subsys;
154 struct kobj_type * ktype;
155 struct list_head list;
156 struct kobject kobj;
157 };
160 void kset_init(struct kset * k);
161 int kset_add(struct kset * k);
162 int kset_register(struct kset * k);
163 void kset_unregister(struct kset * k);
165 struct kset * kset_get(struct kset * k);
166 void kset_put(struct kset * k);
168 struct kobject * kset_find_obj(struct kset *, char *);
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.
175 A kset contains a kobject itself, meaning that it may be registered in
176 the kobject hierarchy and exported via sysfs. More importantly, the
177 kset may be embedded in a larger data type, and may be part of another
178 kset (of that object type).
180 For example, a block device is an object (struct gendisk) that is
181 contained in a set of block devices. It may also contain a set of
182 partitions (struct hd_struct) that have been found on the device. The
183 following code snippet illustrates how to express this properly.
185 struct gendisk * disk;
186 ...
187 disk->kset.kobj.kset = &block_kset;
188 disk->kset.ktype = &partition_ktype;
189 kset_register(&disk->kset);
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.
194 - The type of objects on the disk's _subordinate_ list are partitions,
195 and is set in disk->kset.ktype.
197 - The kset is then registered, which handles initializing and adding
198 the embedded kobject to the hierarchy.
201 2.2 kset Programming Interface
203 All kset functions, except kset_find_obj(), eventually forward the
204 calls to their embedded kobjects after performing kset-specific
205 operations. ksets offer a similar programming model to kobjects: they
206 may be used after they are initialized, without registering them in
207 the hierarchy.
209 kset_find_obj() may be used to locate a kobject with a particular
210 name. The kobject, if found, is returned.
213 2.3 sysfs
215 ksets are represented in sysfs when their embedded kobjects are
216 registered. They follow the same rules of parenting, with one
217 exception. If a kset does not have a parent, nor is its embedded
218 kobject part of another kset, the kset's parent becomes its dominant
219 subsystem.
221 If the kset does not have a parent, its directory is created at the
222 sysfs root. This should only happen when the kset registered is
223 embedded in a subsystem itself.
226 3. struct ktype
228 3.1. Description
230 struct kobj_type {
231 void (*release)(struct kobject *);
232 struct sysfs_ops * sysfs_ops;
233 struct attribute ** default_attrs;
234 };
237 Object types require specific functions for converting between the
238 generic object and the more complex type. struct kobj_type provides
239 the object-specific fields, which include:
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.
244 - sysfs_ops: Provides conversion functions for sysfs access. Please
245 see the sysfs documentation for more information.
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 block/genhd.c
253 Instances of struct kobj_type are not registered; only referenced by
254 the kset. A kobj_type may be referenced by an arbitrary number of
255 ksets, as there may be disparate sets of identical objects.
259 4. subsystems
261 4.1 Description
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.
269 struct subsystem {
270 struct kset kset;
271 struct rw_semaphore rwsem;
272 };
274 int subsystem_register(struct subsystem *);
275 void subsystem_unregister(struct subsystem *);
277 struct subsystem * subsys_get(struct subsystem * s);
278 void subsys_put(struct subsystem * s);
281 A subsystem contains an embedded kset so:
283 - It can be represented in the object hierarchy via the kset's
284 embedded kobject.
286 - It can maintain a default list of objects of one type.
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.)
293 All ksets that are attached to a subsystem share the subsystem's R/W
294 semaphore.
297 4.2 subsystem Programming Interface.
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).
306 4.3 Helpers
308 A number of macros are available to make dealing with subsystems and
309 their embedded objects easier.
312 decl_subsys(name,type)
314 Declares a subsystem named '<name>_subsys', with an embedded kset of
315 type <type>. For example,
317 decl_subsys(devices,&ktype_devices);
319 is equivalent to doing:
321 struct subsystem device_subsys = {
322 .kset = {
323 .kobj = {
324 .name = "devices",
325 },
326 .ktype = &ktype_devices,
327 }
328 };
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:
337 kobj_set_kset_s(obj,subsys)
339 - Assumes that obj->kobj exists, and is a struct kobject.
340 - Sets the kset of that kobject to the subsystem's embedded kset.
343 kset_set_kset_s(obj,subsys)
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.
349 subsys_set_kset(obj,subsys)
351 - Assumes obj->subsys exists, and is a struct subsystem.
352 - Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
355 4.4 sysfs
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.
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).