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
  31
  32 The kobject infrastructure maintains a close relationship with the
  33 sysfs filesystem. Each kobject that is registered with the kobject
  34 core receives a directory in sysfs. Attributes about the kobject can
  35 then be exported. Please see Documentation/filesystems/sysfs.txt for
  36 more information.
  37
  38 The kobject infrastructure provides a flexible programming interface,
  39 and allows kobjects and ksets to be used without being registered
  40 (i.e. with no sysfs representation). This is also described later.
  41
  42
  43 1. kobjects
  44
  45 1.1 Description
  46
  47
  48 struct kobject is a simple data type that provides a foundation for
  49 more complex object types. It provides a set of basic fields that
  50 almost all complex data types share. kobjects are intended to be
  51 embedded in larger data structures and replace fields they duplicate.
  52
  53 1.2 Definition
  54
  55 struct kobject {
  56         const char              * k_name;
  57         char                    name[KOBJ_NAME_LEN];
  58         struct kref             kref;
  59         struct list_head        entry;
  60         struct kobject          * parent;
  61         struct kset             * kset;
  62         struct kobj_type        * ktype;
  63         struct sysfs_dirent     * sd;
  64         wait_queue_head_t       poll;
  65 };
  66
  67 void kobject_init(struct kobject *);
  68 int kobject_add(struct kobject *);
  69 int kobject_register(struct kobject *);
  70
  71 void kobject_del(struct kobject *);
  72 void kobject_unregister(struct kobject *);
  73
  74 struct kobject * kobject_get(struct kobject *);
  75 void kobject_put(struct kobject *);
  76
  77
  78 1.3 kobject Programming Interface
  79
  80 kobjects may be dynamically added and removed from the kobject core
  81 using kobject_register() and kobject_unregister(). Registration
  82 includes inserting the kobject in the list of its dominant kset and
  83 creating a directory for it in sysfs.
  84
  85 Alternatively, one may use a kobject without adding it to its kset's list
  86 or exporting it via sysfs, by simply calling kobject_init(). An
  87 initialized kobject may later be added to the object hierarchy by
  88 calling kobject_add(). An initialized kobject may be used for
  89 reference counting.
  90
  91 Note: calling kobject_init() then kobject_add() is functionally
  92 equivalent to calling kobject_register().
  93
  94 When a kobject is unregistered, it is removed from its kset's list,
  95 removed from the sysfs filesystem, and its reference count is decremented.
  96 List and sysfs removal happen in kobject_del(), and may be called
  97 manually. kobject_put() decrements the reference count, and may also
  98 be called manually.
  99
 100 A kobject's reference count may be incremented with kobject_get(),
 101 which returns a valid reference to a kobject; and decremented with
 102 kobject_put(). An object's reference count may only be incremented if
 103 it is already positive.
 104
 105 When a kobject's reference count reaches 0, the method struct
 106 kobj_type::release() (which the kobject's kset points to) is called.
 107 This allows any memory allocated for the object to be freed.
 108
 109
 110 NOTE!!!
 111
 112 It is _imperative_ that you supply a destructor for dynamically
 113 allocated kobjects to free them if you are using kobject reference
 114 counts. The reference count controls the lifetime of the object.
 115 If it goes to 0, then it is assumed that the object will
 116 be freed and cannot be used.
 117
 118 More importantly, you must free the object there, and not immediately
 119 after an unregister call. If someone else is referencing the object
 120 (e.g. through a sysfs file), they will obtain a reference to the
 121 object, assume it's valid and operate on it. If the object is
 122 unregistered and freed in the meantime, the operation will then
 123 reference freed memory and go boom.
 124
 125 This can be prevented, in the simplest case, by defining a release
 126 method and freeing the object from there only. Note that this will not
 127 secure reference count/object management models that use a dual
 128 reference count or do other wacky things with the reference count
 129 (like the networking layer).
 130
 131
 132 1.4 sysfs
 133
 134 Each kobject receives a directory in sysfs. This directory is created
 135 under the kobject's parent directory.
 136
 137 If a kobject does not have a parent when it is registered, its parent
 138 becomes its dominant kset.
 139
 140 If a kobject does not have a parent nor a dominant kset, its directory
 141 is created at the top-level of the sysfs partition.
 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 kobj_type        * ktype;
 154         struct list_head        list;
 155         struct kobject          kobj;
 156         struct kset_uevent_ops  * uevent_ops;
 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.
 173
 174 A kset contains a kobject itself, meaning that it may be registered in
 175 the kobject hierarchy and exported via sysfs. More importantly, the
 176 kset may be embedded in a larger data type, and may be part of another
 177 kset (of that object type).
 178
 179 For example, a block device is an object (struct gendisk) that is
 180 contained in a set of block devices. It may also contain a set of
 181 partitions (struct hd_struct) that have been found on the device. The
 182 following code snippet illustrates how to express this properly.
 183
 184          struct gendisk * disk;
 185          ...
 186          disk->kset.kobj.kset = &block_kset;
 187          disk->kset.ktype = &partition_ktype;
 188          kset_register(&disk->kset);
 189
 190 - The kset that the disk's embedded object belongs to is the
 191   block_kset, and is pointed to by disk->kset.kobj.kset.
 192
 193 - The type of objects on the disk's _subordinate_ list are partitions,
 194   and is set in disk->kset.ktype.
 195
 196 - The kset is then registered, which handles initializing and adding
 197   the embedded kobject to the hierarchy.
 198
 199
 200 2.2 kset Programming Interface
 201
 202 All kset functions, except kset_find_obj(), eventually forward the
 203 calls to their embedded kobjects after performing kset-specific
 204 operations. ksets offer a similar programming model to kobjects: they
 205 may be used after they are initialized, without registering them in
 206 the hierarchy.
 207
 208 kset_find_obj() may be used to locate a kobject with a particular
 209 name. The kobject, if found, is returned.
 210
 211 There are also some helper functions which names point to the formerly
 212 existing "struct subsystem", whose functions have been taken over by
 213 ksets.
 214
 215
 216 decl_subsys(name,type,uevent_ops)
 217
 218 Declares a kset named '<name>_subsys' of type <type> with
 219 uevent_ops <uevent_ops>. For example,
 220
 221 decl_subsys(devices, &ktype_device, &device_uevent_ops);
 222
 223 is equivalent to doing:
 224
 225 struct kset devices_subsys = {
 226      .kobj = {
 227            .name = "devices",
 228      },
 229      .ktype = &ktype_devices,
 230      .uevent_ops = &device_uevent_ops,
 231 };
 232
 233
 234 The objects that are registered with a subsystem that use the
 235 subsystem's default list must have their kset ptr set properly. These
 236 objects may have embedded kobjects or ksets. The
 237 following helpers make setting the kset easier:
 238
 239
 240 kobj_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
 246 kset_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
 251 subsys_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
 256 void subsystem_init(struct kset *s);
 257 int subsystem_register(struct kset *s);
 258 void subsystem_unregister(struct kset *s);
 259 struct kset *subsys_get(struct kset *s);
 260 void kset_put(struct kset *s);
 261
 262 These are just wrappers around the respective kset_* functions.
 263
 264 2.3 sysfs
 265
 266 ksets are represented in sysfs when their embedded kobjects are
 267 registered. They follow the same rules of parenting, with one
 268 exception. If a kset does not have a parent, nor is its embedded
 269 kobject part of another kset, the kset's parent becomes its dominant
 270 subsystem.
 271
 272 If the kset does not have a parent, its directory is created at the
 273 sysfs root. This should only happen when the kset registered is
 274 embedded in a subsystem itself.
 275
 276
 277 3. struct ktype
 278
 279 3.1. Description
 280
 281 struct kobj_type {
 282         void (*release)(struct kobject *);
 283         struct sysfs_ops        * sysfs_ops;
 284         struct attribute        ** default_attrs;
 285 };
 286
 287
 288 Object types require specific functions for converting between the
 289 generic object and the more complex type. struct kobj_type provides
 290 the object-specific fields, which include:
 291
 292 - release: Called when the kobject's reference count reaches 0. This
 293   should convert the object to the more complex type and free it.
 294
 295 - sysfs_ops: Provides conversion functions for sysfs access. Please
 296   see the sysfs documentation for more information.
 297
 298 - default_attrs: Default attributes to be exported via sysfs when the
 299   object is registered.Note that the last attribute has to be
 300   initialized to NULL ! You can find a complete implementation
 301   in block/genhd.c
 302
 303
 304 Instances of struct kobj_type are not registered; only referenced by
 305 the kset. A kobj_type may be referenced by an arbitrary number of
 306 ksets, as there may be disparate sets of identical objects.
 307