annotate Documentation/kobject.txt @ 0:831230e53067

Import 2.6.18 from kernel.org tarball.
author Ian Campbell <ian.campbell@xensource.com>
date Wed Apr 11 14:15:44 2007 +0100 (2007-04-11)
rev   line source
ian@0 1 The kobject Infrastructure
ian@0 2
ian@0 3 Patrick Mochel <mochel@osdl.org>
ian@0 4
ian@0 5 Updated: 3 June 2003
ian@0 6
ian@0 7
ian@0 8 Copyright (c) 2003 Patrick Mochel
ian@0 9 Copyright (c) 2003 Open Source Development Labs
ian@0 10
ian@0 11
ian@0 12 0. Introduction
ian@0 13
ian@0 14 The kobject infrastructure performs basic object management that larger
ian@0 15 data structures and subsystems can leverage, rather than reimplement
ian@0 16 similar functionality. This functionality primarily concerns:
ian@0 17
ian@0 18 - Object reference counting.
ian@0 19 - Maintaining lists (sets) of objects.
ian@0 20 - Object set locking.
ian@0 21 - Userspace representation.
ian@0 22
ian@0 23 The infrastructure consists of a number of object types to support
ian@0 24 this functionality. Their programming interfaces are described below
ian@0 25 in detail, and briefly here:
ian@0 26
ian@0 27 - kobjects a simple object.
ian@0 28 - kset a set of objects of a certain type.
ian@0 29 - ktype a set of helpers for objects of a common type.
ian@0 30 - subsystem a controlling object for a number of ksets.
ian@0 31
ian@0 32
ian@0 33 The kobject infrastructure maintains a close relationship with the
ian@0 34 sysfs filesystem. Each kobject that is registered with the kobject
ian@0 35 core receives a directory in sysfs. Attributes about the kobject can
ian@0 36 then be exported. Please see Documentation/filesystems/sysfs.txt for
ian@0 37 more information.
ian@0 38
ian@0 39 The kobject infrastructure provides a flexible programming interface,
ian@0 40 and allows kobjects and ksets to be used without being registered
ian@0 41 (i.e. with no sysfs representation). This is also described later.
ian@0 42
ian@0 43
ian@0 44 1. kobjects
ian@0 45
ian@0 46 1.1 Description
ian@0 47
ian@0 48
ian@0 49 struct kobject is a simple data type that provides a foundation for
ian@0 50 more complex object types. It provides a set of basic fields that
ian@0 51 almost all complex data types share. kobjects are intended to be
ian@0 52 embedded in larger data structures and replace fields they duplicate.
ian@0 53
ian@0 54 1.2 Defintion
ian@0 55
ian@0 56 struct kobject {
ian@0 57 char name[KOBJ_NAME_LEN];
ian@0 58 atomic_t refcount;
ian@0 59 struct list_head entry;
ian@0 60 struct kobject * parent;
ian@0 61 struct kset * kset;
ian@0 62 struct kobj_type * ktype;
ian@0 63 struct dentry * dentry;
ian@0 64 };
ian@0 65
ian@0 66 void kobject_init(struct kobject *);
ian@0 67 int kobject_add(struct kobject *);
ian@0 68 int kobject_register(struct kobject *);
ian@0 69
ian@0 70 void kobject_del(struct kobject *);
ian@0 71 void kobject_unregister(struct kobject *);
ian@0 72
ian@0 73 struct kobject * kobject_get(struct kobject *);
ian@0 74 void kobject_put(struct kobject *);
ian@0 75
ian@0 76
ian@0 77 1.3 kobject Programming Interface
ian@0 78
ian@0 79 kobjects may be dynamically added and removed from the kobject core
ian@0 80 using kobject_register() and kobject_unregister(). Registration
ian@0 81 includes inserting the kobject in the list of its dominant kset and
ian@0 82 creating a directory for it in sysfs.
ian@0 83
ian@0 84 Alternatively, one may use a kobject without adding it to its kset's list
ian@0 85 or exporting it via sysfs, by simply calling kobject_init(). An
ian@0 86 initialized kobject may later be added to the object hierarchy by
ian@0 87 calling kobject_add(). An initialized kobject may be used for
ian@0 88 reference counting.
ian@0 89
ian@0 90 Note: calling kobject_init() then kobject_add() is functionally
ian@0 91 equivalent to calling kobject_register().
ian@0 92
ian@0 93 When a kobject is unregistered, it is removed from its kset's list,
ian@0 94 removed from the sysfs filesystem, and its reference count is decremented.
ian@0 95 List and sysfs removal happen in kobject_del(), and may be called
ian@0 96 manually. kobject_put() decrements the reference count, and may also
ian@0 97 be called manually.
ian@0 98
ian@0 99 A kobject's reference count may be incremented with kobject_get(),
ian@0 100 which returns a valid reference to a kobject; and decremented with
ian@0 101 kobject_put(). An object's reference count may only be incremented if
ian@0 102 it is already positive.
ian@0 103
ian@0 104 When a kobject's reference count reaches 0, the method struct
ian@0 105 kobj_type::release() (which the kobject's kset points to) is called.
ian@0 106 This allows any memory allocated for the object to be freed.
ian@0 107
ian@0 108
ian@0 109 NOTE!!!
ian@0 110
ian@0 111 It is _imperative_ that you supply a destructor for dynamically
ian@0 112 allocated kobjects to free them if you are using kobject reference
ian@0 113 counts. The reference count controls the lifetime of the object.
ian@0 114 If it goes to 0, then it is assumed that the object will
ian@0 115 be freed and cannot be used.
ian@0 116
ian@0 117 More importantly, you must free the object there, and not immediately
ian@0 118 after an unregister call. If someone else is referencing the object
ian@0 119 (e.g. through a sysfs file), they will obtain a reference to the
ian@0 120 object, assume it's valid and operate on it. If the object is
ian@0 121 unregistered and freed in the meantime, the operation will then
ian@0 122 reference freed memory and go boom.
ian@0 123
ian@0 124 This can be prevented, in the simplest case, by defining a release
ian@0 125 method and freeing the object from there only. Note that this will not
ian@0 126 secure reference count/object management models that use a dual
ian@0 127 reference count or do other wacky things with the reference count
ian@0 128 (like the networking layer).
ian@0 129
ian@0 130
ian@0 131 1.4 sysfs
ian@0 132
ian@0 133 Each kobject receives a directory in sysfs. This directory is created
ian@0 134 under the kobject's parent directory.
ian@0 135
ian@0 136 If a kobject does not have a parent when it is registered, its parent
ian@0 137 becomes its dominant kset.
ian@0 138
ian@0 139 If a kobject does not have a parent nor a dominant kset, its directory
ian@0 140 is created at the top-level of the sysfs partition. This should only
ian@0 141 happen for kobjects that are embedded in a struct subsystem.
ian@0 142
ian@0 143
ian@0 144
ian@0 145 2. ksets
ian@0 146
ian@0 147 2.1 Description
ian@0 148
ian@0 149 A kset is a set of kobjects that are embedded in the same type.
ian@0 150
ian@0 151
ian@0 152 struct kset {
ian@0 153 struct subsystem * subsys;
ian@0 154 struct kobj_type * ktype;
ian@0 155 struct list_head list;
ian@0 156 struct kobject kobj;
ian@0 157 };
ian@0 158
ian@0 159
ian@0 160 void kset_init(struct kset * k);
ian@0 161 int kset_add(struct kset * k);
ian@0 162 int kset_register(struct kset * k);
ian@0 163 void kset_unregister(struct kset * k);
ian@0 164
ian@0 165 struct kset * kset_get(struct kset * k);
ian@0 166 void kset_put(struct kset * k);
ian@0 167
ian@0 168 struct kobject * kset_find_obj(struct kset *, char *);
ian@0 169
ian@0 170
ian@0 171 The type that the kobjects are embedded in is described by the ktype
ian@0 172 pointer. The subsystem that the kobject belongs to is pointed to by the
ian@0 173 subsys pointer.
ian@0 174
ian@0 175 A kset contains a kobject itself, meaning that it may be registered in
ian@0 176 the kobject hierarchy and exported via sysfs. More importantly, the
ian@0 177 kset may be embedded in a larger data type, and may be part of another
ian@0 178 kset (of that object type).
ian@0 179
ian@0 180 For example, a block device is an object (struct gendisk) that is
ian@0 181 contained in a set of block devices. It may also contain a set of
ian@0 182 partitions (struct hd_struct) that have been found on the device. The
ian@0 183 following code snippet illustrates how to express this properly.
ian@0 184
ian@0 185 struct gendisk * disk;
ian@0 186 ...
ian@0 187 disk->kset.kobj.kset = &block_kset;
ian@0 188 disk->kset.ktype = &partition_ktype;
ian@0 189 kset_register(&disk->kset);
ian@0 190
ian@0 191 - The kset that the disk's embedded object belongs to is the
ian@0 192 block_kset, and is pointed to by disk->kset.kobj.kset.
ian@0 193
ian@0 194 - The type of objects on the disk's _subordinate_ list are partitions,
ian@0 195 and is set in disk->kset.ktype.
ian@0 196
ian@0 197 - The kset is then registered, which handles initializing and adding
ian@0 198 the embedded kobject to the hierarchy.
ian@0 199
ian@0 200
ian@0 201 2.2 kset Programming Interface
ian@0 202
ian@0 203 All kset functions, except kset_find_obj(), eventually forward the
ian@0 204 calls to their embedded kobjects after performing kset-specific
ian@0 205 operations. ksets offer a similar programming model to kobjects: they
ian@0 206 may be used after they are initialized, without registering them in
ian@0 207 the hierarchy.
ian@0 208
ian@0 209 kset_find_obj() may be used to locate a kobject with a particular
ian@0 210 name. The kobject, if found, is returned.
ian@0 211
ian@0 212
ian@0 213 2.3 sysfs
ian@0 214
ian@0 215 ksets are represented in sysfs when their embedded kobjects are
ian@0 216 registered. They follow the same rules of parenting, with one
ian@0 217 exception. If a kset does not have a parent, nor is its embedded
ian@0 218 kobject part of another kset, the kset's parent becomes its dominant
ian@0 219 subsystem.
ian@0 220
ian@0 221 If the kset does not have a parent, its directory is created at the
ian@0 222 sysfs root. This should only happen when the kset registered is
ian@0 223 embedded in a subsystem itself.
ian@0 224
ian@0 225
ian@0 226 3. struct ktype
ian@0 227
ian@0 228 3.1. Description
ian@0 229
ian@0 230 struct kobj_type {
ian@0 231 void (*release)(struct kobject *);
ian@0 232 struct sysfs_ops * sysfs_ops;
ian@0 233 struct attribute ** default_attrs;
ian@0 234 };
ian@0 235
ian@0 236
ian@0 237 Object types require specific functions for converting between the
ian@0 238 generic object and the more complex type. struct kobj_type provides
ian@0 239 the object-specific fields, which include:
ian@0 240
ian@0 241 - release: Called when the kobject's reference count reaches 0. This
ian@0 242 should convert the object to the more complex type and free it.
ian@0 243
ian@0 244 - sysfs_ops: Provides conversion functions for sysfs access. Please
ian@0 245 see the sysfs documentation for more information.
ian@0 246
ian@0 247 - default_attrs: Default attributes to be exported via sysfs when the
ian@0 248 object is registered.Note that the last attribute has to be
ian@0 249 initialized to NULL ! You can find a complete implementation
ian@0 250 in block/genhd.c
ian@0 251
ian@0 252
ian@0 253 Instances of struct kobj_type are not registered; only referenced by
ian@0 254 the kset. A kobj_type may be referenced by an arbitrary number of
ian@0 255 ksets, as there may be disparate sets of identical objects.
ian@0 256
ian@0 257
ian@0 258
ian@0 259 4. subsystems
ian@0 260
ian@0 261 4.1 Description
ian@0 262
ian@0 263 A subsystem represents a significant entity of code that maintains an
ian@0 264 arbitrary number of sets of objects of various types. Since the number
ian@0 265 of ksets and the type of objects they contain are variable, a
ian@0 266 generic representation of a subsystem is minimal.
ian@0 267
ian@0 268
ian@0 269 struct subsystem {
ian@0 270 struct kset kset;
ian@0 271 struct rw_semaphore rwsem;
ian@0 272 };
ian@0 273
ian@0 274 int subsystem_register(struct subsystem *);
ian@0 275 void subsystem_unregister(struct subsystem *);
ian@0 276
ian@0 277 struct subsystem * subsys_get(struct subsystem * s);
ian@0 278 void subsys_put(struct subsystem * s);
ian@0 279
ian@0 280
ian@0 281 A subsystem contains an embedded kset so:
ian@0 282
ian@0 283 - It can be represented in the object hierarchy via the kset's
ian@0 284 embedded kobject.
ian@0 285
ian@0 286 - It can maintain a default list of objects of one type.
ian@0 287
ian@0 288 Additional ksets may attach to the subsystem simply by referencing the
ian@0 289 subsystem before they are registered. (This one-way reference means
ian@0 290 that there is no way to determine the ksets that are attached to the
ian@0 291 subsystem.)
ian@0 292
ian@0 293 All ksets that are attached to a subsystem share the subsystem's R/W
ian@0 294 semaphore.
ian@0 295
ian@0 296
ian@0 297 4.2 subsystem Programming Interface.
ian@0 298
ian@0 299 The subsystem programming interface is simple and does not offer the
ian@0 300 flexibility that the kset and kobject programming interfaces do. They
ian@0 301 may be registered and unregistered, as well as reference counted. Each
ian@0 302 call forwards the calls to their embedded ksets (which forward the
ian@0 303 calls to their embedded kobjects).
ian@0 304
ian@0 305
ian@0 306 4.3 Helpers
ian@0 307
ian@0 308 A number of macros are available to make dealing with subsystems and
ian@0 309 their embedded objects easier.
ian@0 310
ian@0 311
ian@0 312 decl_subsys(name,type)
ian@0 313
ian@0 314 Declares a subsystem named '<name>_subsys', with an embedded kset of
ian@0 315 type <type>. For example,
ian@0 316
ian@0 317 decl_subsys(devices,&ktype_devices);
ian@0 318
ian@0 319 is equivalent to doing:
ian@0 320
ian@0 321 struct subsystem device_subsys = {
ian@0 322 .kset = {
ian@0 323 .kobj = {
ian@0 324 .name = "devices",
ian@0 325 },
ian@0 326 .ktype = &ktype_devices,
ian@0 327 }
ian@0 328 };
ian@0 329
ian@0 330
ian@0 331 The objects that are registered with a subsystem that use the
ian@0 332 subsystem's default list must have their kset ptr set properly. These
ian@0 333 objects may have embedded kobjects, ksets, or other subsystems. The
ian@0 334 following helpers make setting the kset easier:
ian@0 335
ian@0 336
ian@0 337 kobj_set_kset_s(obj,subsys)
ian@0 338
ian@0 339 - Assumes that obj->kobj exists, and is a struct kobject.
ian@0 340 - Sets the kset of that kobject to the subsystem's embedded kset.
ian@0 341
ian@0 342
ian@0 343 kset_set_kset_s(obj,subsys)
ian@0 344
ian@0 345 - Assumes that obj->kset exists, and is a struct kset.
ian@0 346 - Sets the kset of the embedded kobject to the subsystem's
ian@0 347 embedded kset.
ian@0 348
ian@0 349 subsys_set_kset(obj,subsys)
ian@0 350
ian@0 351 - Assumes obj->subsys exists, and is a struct subsystem.
ian@0 352 - Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
ian@0 353
ian@0 354
ian@0 355 4.4 sysfs
ian@0 356
ian@0 357 subsystems are represented in sysfs via their embedded kobjects. They
ian@0 358 follow the same rules as previously mentioned with no exceptions. They
ian@0 359 typically receive a top-level directory in sysfs, except when their
ian@0 360 embedded kobject is part of another kset, or the parent of the
ian@0 361 embedded kobject is explicitly set.
ian@0 362
ian@0 363 Note that the subsystem's embedded kset must be 'attached' to the
ian@0 364 subsystem itself in order to use its rwsem. This is done after
ian@0 365 kset_add() has been called. (Not before, because kset_add() uses its
ian@0 366 subsystem for a default parent if it doesn't already have one).
ian@0 367