Commit 5008743dc7f98dd1ad4f20f4d7ff0b479e78895d
1 parent
af5ca3f4ec
Exists in
master
and in
4 other branches
kobject: remove old, outdated documentation.
As we are replacing the documentation, it's easier to do this in a two stage pass, delete the old file and add the new one. Cc: Kay Sievers <kay.sievers@vrfy.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Showing 1 changed file with 0 additions and 289 deletions Side-by-side Diff
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 | - struct kref kref; | |
| 58 | - struct list_head entry; | |
| 59 | - struct kobject * parent; | |
| 60 | - struct kset * kset; | |
| 61 | - struct kobj_type * ktype; | |
| 62 | - struct sysfs_dirent * sd; | |
| 63 | - wait_queue_head_t poll; | |
| 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 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. | |
| 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. | |
| 141 | - | |
| 142 | - | |
| 143 | - | |
| 144 | -2. ksets | |
| 145 | - | |
| 146 | -2.1 Description | |
| 147 | - | |
| 148 | -A kset is a set of kobjects that are embedded in the same type. | |
| 149 | - | |
| 150 | - | |
| 151 | -struct kset { | |
| 152 | - struct kobj_type * ktype; | |
| 153 | - struct list_head list; | |
| 154 | - struct kobject kobj; | |
| 155 | - struct kset_uevent_ops * uevent_ops; | |
| 156 | -}; | |
| 157 | - | |
| 158 | - | |
| 159 | -void kset_init(struct kset * k); | |
| 160 | -int kset_add(struct kset * k); | |
| 161 | -int kset_register(struct kset * k); | |
| 162 | -void kset_unregister(struct kset * k); | |
| 163 | - | |
| 164 | -struct kset * kset_get(struct kset * k); | |
| 165 | -void kset_put(struct kset * k); | |
| 166 | - | |
| 167 | -struct kobject * kset_find_obj(struct kset *, char *); | |
| 168 | - | |
| 169 | - | |
| 170 | -The type that the kobjects are embedded in is described by the ktype | |
| 171 | -pointer. | |
| 172 | - | |
| 173 | -A kset contains a kobject itself, meaning that it may be registered in | |
| 174 | -the kobject hierarchy and exported via sysfs. More importantly, the | |
| 175 | -kset may be embedded in a larger data type, and may be part of another | |
| 176 | -kset (of that object type). | |
| 177 | - | |
| 178 | -For example, a block device is an object (struct gendisk) that is | |
| 179 | -contained in a set of block devices. It may also contain a set of | |
| 180 | -partitions (struct hd_struct) that have been found on the device. The | |
| 181 | -following code snippet illustrates how to express this properly. | |
| 182 | - | |
| 183 | - struct gendisk * disk; | |
| 184 | - ... | |
| 185 | - disk->kset.kobj.kset = &block_kset; | |
| 186 | - disk->kset.ktype = &partition_ktype; | |
| 187 | - kset_register(&disk->kset); | |
| 188 | - | |
| 189 | -- The kset that the disk's embedded object belongs to is the | |
| 190 | - block_kset, and is pointed to by disk->kset.kobj.kset. | |
| 191 | - | |
| 192 | -- The type of objects on the disk's _subordinate_ list are partitions, | |
| 193 | - and is set in disk->kset.ktype. | |
| 194 | - | |
| 195 | -- The kset is then registered, which handles initializing and adding | |
| 196 | - the embedded kobject to the hierarchy. | |
| 197 | - | |
| 198 | - | |
| 199 | -2.2 kset Programming Interface | |
| 200 | - | |
| 201 | -All kset functions, except kset_find_obj(), eventually forward the | |
| 202 | -calls to their embedded kobjects after performing kset-specific | |
| 203 | -operations. ksets offer a similar programming model to kobjects: they | |
| 204 | -may be used after they are initialized, without registering them in | |
| 205 | -the hierarchy. | |
| 206 | - | |
| 207 | -kset_find_obj() may be used to locate a kobject with a particular | |
| 208 | -name. The kobject, if found, is returned. | |
| 209 | - | |
| 210 | -There are also some helper functions which names point to the formerly | |
| 211 | -existing "struct subsystem", whose functions have been taken over by | |
| 212 | -ksets. | |
| 213 | - | |
| 214 | - | |
| 215 | -decl_subsys(name,type,uevent_ops) | |
| 216 | - | |
| 217 | -Declares a kset named '<name>_subsys' of type <type> with | |
| 218 | -uevent_ops <uevent_ops>. For example, | |
| 219 | - | |
| 220 | -decl_subsys(devices, &ktype_device, &device_uevent_ops); | |
| 221 | - | |
| 222 | -is equivalent to doing: | |
| 223 | - | |
| 224 | -struct kset devices_subsys = { | |
| 225 | - .ktype = &ktype_devices, | |
| 226 | - .uevent_ops = &device_uevent_ops, | |
| 227 | -}; | |
| 228 | -kobject_set_name(&devices_subsys, name); | |
| 229 | - | |
| 230 | -The objects that are registered with a subsystem that use the | |
| 231 | -subsystem's default list must have their kset ptr set properly. These | |
| 232 | -objects may have embedded kobjects or ksets. The | |
| 233 | -following helper makes setting the kset easier: | |
| 234 | - | |
| 235 | - | |
| 236 | -kobj_set_kset_s(obj,subsys) | |
| 237 | - | |
| 238 | -- Assumes that obj->kobj exists, and is a struct kobject. | |
| 239 | -- Sets the kset of that kobject to the kset <subsys>. | |
| 240 | - | |
| 241 | -int subsystem_register(struct kset *s); | |
| 242 | -void subsystem_unregister(struct kset *s); | |
| 243 | - | |
| 244 | -These are just wrappers around the respective kset_* functions. | |
| 245 | - | |
| 246 | -2.3 sysfs | |
| 247 | - | |
| 248 | -ksets are represented in sysfs when their embedded kobjects are | |
| 249 | -registered. They follow the same rules of parenting, with one | |
| 250 | -exception. If a kset does not have a parent, nor is its embedded | |
| 251 | -kobject part of another kset, the kset's parent becomes its dominant | |
| 252 | -subsystem. | |
| 253 | - | |
| 254 | -If the kset does not have a parent, its directory is created at the | |
| 255 | -sysfs root. This should only happen when the kset registered is | |
| 256 | -embedded in a subsystem itself. | |
| 257 | - | |
| 258 | - | |
| 259 | -3. struct ktype | |
| 260 | - | |
| 261 | -3.1. Description | |
| 262 | - | |
| 263 | -struct kobj_type { | |
| 264 | - void (*release)(struct kobject *); | |
| 265 | - struct sysfs_ops * sysfs_ops; | |
| 266 | - struct attribute ** default_attrs; | |
| 267 | -}; | |
| 268 | - | |
| 269 | - | |
| 270 | -Object types require specific functions for converting between the | |
| 271 | -generic object and the more complex type. struct kobj_type provides | |
| 272 | -the object-specific fields, which include: | |
| 273 | - | |
| 274 | -- release: Called when the kobject's reference count reaches 0. This | |
| 275 | - should convert the object to the more complex type and free it. | |
| 276 | - | |
| 277 | -- sysfs_ops: Provides conversion functions for sysfs access. Please | |
| 278 | - see the sysfs documentation for more information. | |
| 279 | - | |
| 280 | -- default_attrs: Default attributes to be exported via sysfs when the | |
| 281 | - object is registered.Note that the last attribute has to be | |
| 282 | - initialized to NULL ! You can find a complete implementation | |
| 283 | - in block/genhd.c | |
| 284 | - | |
| 285 | - | |
| 286 | -Instances of struct kobj_type are not registered; only referenced by | |
| 287 | -the kset. A kobj_type may be referenced by an arbitrary number of | |
| 288 | -ksets, as there may be disparate sets of identical objects. |