Documentation/kobject.txt

   1 The kobject Infrastructure
   2
   3 Patrick Mochel <mochel@osdl.org>
   4
   5 Updated: 3 June 2003
   6
   7
   8 Copyright (c)  2003 Patrick Mochel
   9 Copyright (c)  2003 Open Source Development Labs
  10
  11
  12 0. Introduction
  13
  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:
  17
  18 - Object reference counting.
  19 - Maintaining lists (sets) of objects.
  20 - Object set locking.
  21 - Userspace representation.
  22
  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:
  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
  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.
  38
  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.
  42
  43
  44 1. kobjects
  45
  46 1.1 Description
  47
  48
  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.
  53
  54 1.2 Defintion
  55
  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 };
  65
  66 void kobject_init(struct kobject *);
  67 int kobject_add(struct kobject *);
  68 int kobject_register(struct kobject *);
  69
  70 void kobject_del(struct kobject *);
  71 void kobject_unregister(struct kobject *);
  72
  73 struct kobject * kobject_get(struct kobject *);
  74 void kobject_put(struct kobject *);
  75
  76
  77 1.3 kobject Programming Interface
  78
  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.
  83
  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.
  89
  90 Note: calling kobject_init(), then kobject_add() is functionally
  91 equivalent to calling kobject_register().
  92
  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.
  98
  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.
 103
 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.
 107
 108
 109 NOTE!!!
 110
 111 It is _imperative_ that you supply a desctructor for dynamically
 112 allocated kobjects to free them if you are using kobject reference
 113 counts. The reference count controls the duration of the lifetime of
 114 the object. If it goes to 0, then it is assumed that the object  will
 115 be freed and cannot be used.
 116
 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.
 123
 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).
 129
 130
 131 1.4 sysfs
 132
 133 Each kobject receives a directory in sysfs. This directory is created
 134 under the kobject's parent directory.
 135
 136 If a kobject does not have a parent when it is registered, its parent
 137 becomes its dominant kset.
 138
 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.
 142
 143
 144
 145 2. ksets
 146
 147 2.1 Description
 148
 149 A kset is a set of kobjects that are embedded in the same type.
 150
 151
 152 struct kset {
 153         struct subsystem        * subsys;
 154         struct kobj_type        * ktype;
 155         struct list_head        list;
 156         struct kobject          kobj;
 157 };
 158
 159
 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);
 164
 165 struct kset * kset_get(struct kset * k);
 166 void kset_put(struct kset * k);
 167
 168 struct kobject * kset_find_obj(struct kset *, char *);
 169
 170
 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
 173 subsys pointer.
 174
 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).
 179
 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 properly express this.
 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
 201 2.2 kset Programming Interface
 202
 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.
 208
 209 kset_find_obj() may be used to locate a kobject with a particular
 210 name. The kobject, if found, is returned.
 211
 212
 213 2.3 sysfs
 214
 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 it's dominant
 219 subsystem.
 220
 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.
 224
 225
 226 3. struct ktype
 227
 228 3.1. Description
 229
 230 struct kobj_type {
 231         void (*release)(struct kobject *);
 232         struct sysfs_ops        * sysfs_ops;
 233         struct attribute        ** default_attrs;
 234 };
 235
 236
 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:
 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.
 249
 250
 251 Instances of struct kobj_type are not registered; only referenced by
 252 the kset. A kobj_type may be referenced by an arbitrary number of
 253 ksets, as there may be disparate sets of identical objects.
 254
 255
 256
 257 4. subsystems
 258
 259 4.1 Description
 260
 261 A subsystem represents a significant entity of code that maintains an
 262 arbitrary number of sets of objects of various types. Since the number
 263 of ksets, and the type of objects they contain, are variable, a
 264 generic representation of a subsystem is minimal.
 265
 266
 267 struct subsystem {
 268         struct kset             kset;
 269         struct rw_semaphore     rwsem;
 270 };
 271
 272 int subsystem_register(struct subsystem *);
 273 void subsystem_unregister(struct subsystem *);
 274
 275 struct subsystem * subsys_get(struct subsystem * s);
 276 void subsys_put(struct subsystem * s);
 277
 278
 279 A subsystem contains an embedded kset so:
 280
 281 - It can be represented in the object hierarchy via the kset's
 282   embedded kobject.
 283
 284 - It can maintain a default list of objects of one type.
 285
 286 Additional ksets may attach to the subsystem simply by referencing the
 287 subsystem before they are registered. (This one-way reference means
 288 that there is no way to determine the ksets that are attached to the
 289 subsystem.)
 290
 291 All ksets that are attached to a subsystem share the subsystem's R/W
 292 semaphore.
 293
 294
 295 4.2 Programming Interface.
 296
 297 The subsystem programming interface is simple and does not offer the
 298 flexibility that the kset and kobject programming interfaces do. They
 299 may be registered and unregistered, as well as reference counted. Each
 300 call forwards the calls to their embedded ksets (which forward the
 301 calls to their embedded kobjects).
 302
 303
 304 4.3 Helpers
 305
 306 A number of macros are available to make dealing with subsystems, and
 307 their embedded objects easier.
 308
 309
 310 decl_subsys(name,type)
 311
 312 Declares a subsystem named '<name>_subsys', with an embedded kset of
 313 type <type>. For example,
 314
 315 decl_subsys(devices,&ktype_devices);
 316
 317 is equivalent to doing:
 318
 319 struct subsystem device_subsys = {
 320        .kset = {
 321              .kobj = {
 322                    .name = "devices",
 323              },
 324              .ktype = &ktype_devices,
 325         }
 326 };
 327
 328
 329 The objects that are registered with a subsystem that use the
 330 subsystem's default list must have their kset ptr set properly. These
 331 objects may have embedded kobjects, ksets, or other subsystems. The
 332 following helpers make setting the kset easier:
 333
 334
 335 kobj_set_kset_s(obj,subsys)
 336
 337 - Assumes that obj->kobj exists, and is a struct kobject.
 338 - Sets the kset of that kobject to the subsystem's embedded kset.
 339
 340
 341 kset_set_kset_s(obj,subsys)
 342
 343 - Assumes that obj->kset exists, and is a struct kset.
 344 - Sets the kset of the embedded kobject to the subsystem's
 345   embedded kset.
 346
 347 subsys_set_kset(obj,subsys)
 348
 349 - Assumes obj->subsys exists, and is a struct subsystem.
 350 - Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
 351
 352
 353 4.4 sysfs
 354
 355 subsystems are represented in sysfs via their embedded kobjects. They
 356 follow the same rules as previously mentioned with no exceptions. They
 357 typically receive a top-level directory in sysfs, except when their
 358 embedded kobject is part of another kset, or the parent of the
 359 embedded kobject is explicitly set.
 360
 361 Note that the subsystem's embedded kset must be 'attached' to the
 362 subsystem itself in order to use its rwsem. This is done after
 363 kset_add() has been called. (Not before, because kset_add() uses its
 364 subsystem for a default parent if it doesn't already have one).
 365