ia64/linux-2.6.18-xen.hg

diff 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)
parents
children
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Documentation/kobject.txt	Wed Apr 11 14:15:44 2007 +0100
     1.3 @@ -0,0 +1,367 @@
     1.4 +The kobject Infrastructure
     1.5 +
     1.6 +Patrick Mochel <mochel@osdl.org>
     1.7 +
     1.8 +Updated: 3 June 2003
     1.9 +
    1.10 +
    1.11 +Copyright (c)  2003 Patrick Mochel
    1.12 +Copyright (c)  2003 Open Source Development Labs
    1.13 +
    1.14 +
    1.15 +0. Introduction
    1.16 +
    1.17 +The kobject infrastructure performs basic object management that larger
    1.18 +data structures and subsystems can leverage, rather than reimplement
    1.19 +similar functionality. This functionality primarily concerns:
    1.20 +
    1.21 +- Object reference counting.
    1.22 +- Maintaining lists (sets) of objects.
    1.23 +- Object set locking.
    1.24 +- Userspace representation. 
    1.25 +
    1.26 +The infrastructure consists of a number of object types to support
    1.27 +this functionality. Their programming interfaces are described below
    1.28 +in detail, and briefly here:
    1.29 +
    1.30 +- kobjects	a simple object.
    1.31 +- kset		a set of objects of a certain type.
    1.32 +- ktype		a set of helpers for objects of a common type. 
    1.33 +- subsystem	a controlling object for a number of ksets.
    1.34 +
    1.35 +
    1.36 +The kobject infrastructure maintains a close relationship with the
    1.37 +sysfs filesystem. Each kobject that is registered with the kobject
    1.38 +core receives a directory in sysfs. Attributes about the kobject can
    1.39 +then be exported. Please see Documentation/filesystems/sysfs.txt for
    1.40 +more information. 
    1.41 +
    1.42 +The kobject infrastructure provides a flexible programming interface,
    1.43 +and allows kobjects and ksets to be used without being registered
    1.44 +(i.e. with no sysfs representation). This is also described later. 
    1.45 +
    1.46 +
    1.47 +1. kobjects
    1.48 +
    1.49 +1.1 Description
    1.50 +
    1.51 +
    1.52 +struct kobject is a simple data type that provides a foundation for
    1.53 +more complex object types. It provides a set of basic fields that
    1.54 +almost all complex data types share. kobjects are intended to be
    1.55 +embedded in larger data structures and replace fields they duplicate. 
    1.56 +
    1.57 +1.2 Defintion
    1.58 +
    1.59 +struct kobject {
    1.60 +	char			name[KOBJ_NAME_LEN];
    1.61 +	atomic_t		refcount;
    1.62 +	struct list_head	entry;
    1.63 +	struct kobject		* parent;
    1.64 +	struct kset		* kset;
    1.65 +	struct kobj_type	* ktype;
    1.66 +	struct dentry		* dentry;
    1.67 +};
    1.68 +
    1.69 +void kobject_init(struct kobject *);
    1.70 +int kobject_add(struct kobject *);
    1.71 +int kobject_register(struct kobject *);
    1.72 +
    1.73 +void kobject_del(struct kobject *);
    1.74 +void kobject_unregister(struct kobject *);
    1.75 +
    1.76 +struct kobject * kobject_get(struct kobject *);
    1.77 +void kobject_put(struct kobject *);
    1.78 +
    1.79 +
    1.80 +1.3 kobject Programming Interface
    1.81 +
    1.82 +kobjects may be dynamically added and removed from the kobject core
    1.83 +using kobject_register() and kobject_unregister(). Registration
    1.84 +includes inserting the kobject in the list of its dominant kset and
    1.85 +creating a directory for it in sysfs.
    1.86 +
    1.87 +Alternatively, one may use a kobject without adding it to its kset's list
    1.88 +or exporting it via sysfs, by simply calling kobject_init(). An
    1.89 +initialized kobject may later be added to the object hierarchy by
    1.90 +calling kobject_add(). An initialized kobject may be used for
    1.91 +reference counting.
    1.92 +
    1.93 +Note: calling kobject_init() then kobject_add() is functionally
    1.94 +equivalent to calling kobject_register().
    1.95 +
    1.96 +When a kobject is unregistered, it is removed from its kset's list,
    1.97 +removed from the sysfs filesystem, and its reference count is decremented.
    1.98 +List and sysfs removal happen in kobject_del(), and may be called
    1.99 +manually. kobject_put() decrements the reference count, and may also
   1.100 +be called manually. 
   1.101 +
   1.102 +A kobject's reference count may be incremented with kobject_get(),
   1.103 +which returns a valid reference to a kobject; and decremented with 
   1.104 +kobject_put(). An object's reference count may only be incremented if
   1.105 +it is already positive. 
   1.106 +
   1.107 +When a kobject's reference count reaches 0, the method struct
   1.108 +kobj_type::release() (which the kobject's kset points to) is called.
   1.109 +This allows any memory allocated for the object to be freed.
   1.110 +
   1.111 +
   1.112 +NOTE!!! 
   1.113 +
   1.114 +It is _imperative_ that you supply a destructor for dynamically
   1.115 +allocated kobjects to free them if you are using kobject reference
   1.116 +counts. The reference count controls the lifetime of the object.
   1.117 +If it goes to 0, then it is assumed that the object will
   1.118 +be freed and cannot be used. 
   1.119 +
   1.120 +More importantly, you must free the object there, and not immediately
   1.121 +after an unregister call. If someone else is referencing the object
   1.122 +(e.g. through a sysfs file), they will obtain a reference to the
   1.123 +object, assume it's valid and operate on it. If the object is
   1.124 +unregistered and freed in the meantime, the operation will then
   1.125 +reference freed memory and go boom. 
   1.126 +
   1.127 +This can be prevented, in the simplest case, by defining a release
   1.128 +method and freeing the object from there only. Note that this will not
   1.129 +secure reference count/object management models that use a dual
   1.130 +reference count or do other wacky things with the reference count
   1.131 +(like the networking layer). 
   1.132 +
   1.133 +
   1.134 +1.4 sysfs
   1.135 +
   1.136 +Each kobject receives a directory in sysfs. This directory is created
   1.137 +under the kobject's parent directory. 
   1.138 +
   1.139 +If a kobject does not have a parent when it is registered, its parent
   1.140 +becomes its dominant kset. 
   1.141 +
   1.142 +If a kobject does not have a parent nor a dominant kset, its directory
   1.143 +is created at the top-level of the sysfs partition. This should only
   1.144 +happen for kobjects that are embedded in a struct subsystem. 
   1.145 +
   1.146 +
   1.147 +
   1.148 +2. ksets
   1.149 +
   1.150 +2.1 Description
   1.151 +
   1.152 +A kset is a set of kobjects that are embedded in the same type. 
   1.153 +
   1.154 +
   1.155 +struct kset {
   1.156 +	struct subsystem	* subsys;
   1.157 +	struct kobj_type	* ktype;
   1.158 +	struct list_head	list;
   1.159 +	struct kobject		kobj;
   1.160 +};
   1.161 +
   1.162 +
   1.163 +void kset_init(struct kset * k);
   1.164 +int kset_add(struct kset * k);
   1.165 +int kset_register(struct kset * k);
   1.166 +void kset_unregister(struct kset * k);
   1.167 +
   1.168 +struct kset * kset_get(struct kset * k);
   1.169 +void kset_put(struct kset * k);
   1.170 +
   1.171 +struct kobject * kset_find_obj(struct kset *, char *);
   1.172 +
   1.173 +
   1.174 +The type that the kobjects are embedded in is described by the ktype
   1.175 +pointer. The subsystem that the kobject belongs to is pointed to by the
   1.176 +subsys pointer. 
   1.177 +
   1.178 +A kset contains a kobject itself, meaning that it may be registered in
   1.179 +the kobject hierarchy and exported via sysfs. More importantly, the
   1.180 +kset may be embedded in a larger data type, and may be part of another
   1.181 +kset (of that object type). 
   1.182 +
   1.183 +For example, a block device is an object (struct gendisk) that is
   1.184 +contained in a set of block devices. It may also contain a set of
   1.185 +partitions (struct hd_struct) that have been found on the device. The
   1.186 +following code snippet illustrates how to express this properly.
   1.187 +
   1.188 +	 struct gendisk * disk;
   1.189 +	 ...
   1.190 +	 disk->kset.kobj.kset = &block_kset;
   1.191 +	 disk->kset.ktype = &partition_ktype;
   1.192 +	 kset_register(&disk->kset);
   1.193 +
   1.194 +- The kset that the disk's embedded object belongs to is the
   1.195 +  block_kset, and is pointed to by disk->kset.kobj.kset. 
   1.196 +
   1.197 +- The type of objects on the disk's _subordinate_ list are partitions, 
   1.198 +  and is set in disk->kset.ktype. 
   1.199 +
   1.200 +- The kset is then registered, which handles initializing and adding
   1.201 +  the embedded kobject to the hierarchy. 
   1.202 +
   1.203 +
   1.204 +2.2 kset Programming Interface 
   1.205 +
   1.206 +All kset functions, except kset_find_obj(), eventually forward the
   1.207 +calls to their embedded kobjects after performing kset-specific
   1.208 +operations. ksets offer a similar programming model to kobjects: they
   1.209 +may be used after they are initialized, without registering them in
   1.210 +the hierarchy. 
   1.211 +
   1.212 +kset_find_obj() may be used to locate a kobject with a particular
   1.213 +name. The kobject, if found, is returned. 
   1.214 +
   1.215 +
   1.216 +2.3 sysfs
   1.217 +
   1.218 +ksets are represented in sysfs when their embedded kobjects are
   1.219 +registered. They follow the same rules of parenting, with one
   1.220 +exception. If a kset does not have a parent, nor is its embedded
   1.221 +kobject part of another kset, the kset's parent becomes its dominant
   1.222 +subsystem. 
   1.223 +
   1.224 +If the kset does not have a parent, its directory is created at the
   1.225 +sysfs root. This should only happen when the kset registered is
   1.226 +embedded in a subsystem itself. 
   1.227 +
   1.228 +
   1.229 +3. struct ktype
   1.230 +
   1.231 +3.1. Description
   1.232 +
   1.233 +struct kobj_type {
   1.234 +	void (*release)(struct kobject *);
   1.235 +	struct sysfs_ops	* sysfs_ops;
   1.236 +	struct attribute	** default_attrs;
   1.237 +};
   1.238 +
   1.239 +
   1.240 +Object types require specific functions for converting between the
   1.241 +generic object and the more complex type. struct kobj_type provides
   1.242 +the object-specific fields, which include:
   1.243 +
   1.244 +- release: Called when the kobject's reference count reaches 0. This
   1.245 +  should convert the object to the more complex type and free it. 
   1.246 +
   1.247 +- sysfs_ops: Provides conversion functions for sysfs access. Please
   1.248 +  see the sysfs documentation for more information. 
   1.249 +
   1.250 +- default_attrs: Default attributes to be exported via sysfs when the
   1.251 +  object is registered.Note that the last attribute has to be
   1.252 +  initialized to NULL ! You can find a complete implementation
   1.253 +  in block/genhd.c
   1.254 +
   1.255 +
   1.256 +Instances of struct kobj_type are not registered; only referenced by
   1.257 +the kset. A kobj_type may be referenced by an arbitrary number of
   1.258 +ksets, as there may be disparate sets of identical objects. 
   1.259 +
   1.260 +
   1.261 +
   1.262 +4. subsystems
   1.263 +
   1.264 +4.1 Description
   1.265 +
   1.266 +A subsystem represents a significant entity of code that maintains an
   1.267 +arbitrary number of sets of objects of various types. Since the number
   1.268 +of ksets and the type of objects they contain are variable, a
   1.269 +generic representation of a subsystem is minimal. 
   1.270 +
   1.271 +
   1.272 +struct subsystem {
   1.273 +	struct kset		kset;
   1.274 +	struct rw_semaphore	rwsem;
   1.275 +};
   1.276 +
   1.277 +int subsystem_register(struct subsystem *);
   1.278 +void subsystem_unregister(struct subsystem *);
   1.279 +
   1.280 +struct subsystem * subsys_get(struct subsystem * s);
   1.281 +void subsys_put(struct subsystem * s);
   1.282 +
   1.283 +
   1.284 +A subsystem contains an embedded kset so:
   1.285 +
   1.286 +- It can be represented in the object hierarchy via the kset's
   1.287 +  embedded kobject. 
   1.288 +
   1.289 +- It can maintain a default list of objects of one type. 
   1.290 +
   1.291 +Additional ksets may attach to the subsystem simply by referencing the
   1.292 +subsystem before they are registered. (This one-way reference means
   1.293 +that there is no way to determine the ksets that are attached to the
   1.294 +subsystem.) 
   1.295 +
   1.296 +All ksets that are attached to a subsystem share the subsystem's R/W
   1.297 +semaphore. 
   1.298 +
   1.299 +
   1.300 +4.2 subsystem Programming Interface.
   1.301 +
   1.302 +The subsystem programming interface is simple and does not offer the
   1.303 +flexibility that the kset and kobject programming interfaces do. They
   1.304 +may be registered and unregistered, as well as reference counted. Each
   1.305 +call forwards the calls to their embedded ksets (which forward the
   1.306 +calls to their embedded kobjects).
   1.307 +
   1.308 +
   1.309 +4.3 Helpers
   1.310 +
   1.311 +A number of macros are available to make dealing with subsystems and
   1.312 +their embedded objects easier. 
   1.313 +
   1.314 +
   1.315 +decl_subsys(name,type)
   1.316 +
   1.317 +Declares a subsystem named '<name>_subsys', with an embedded kset of
   1.318 +type <type>. For example, 
   1.319 +
   1.320 +decl_subsys(devices,&ktype_devices);
   1.321 +
   1.322 +is equivalent to doing:
   1.323 +
   1.324 +struct subsystem device_subsys = {
   1.325 +       .kset = {
   1.326 +	     .kobj = {
   1.327 +		   .name = "devices",
   1.328 +	     },
   1.329 +	     .ktype = &ktype_devices,
   1.330 +	}
   1.331 +}; 
   1.332 +
   1.333 +
   1.334 +The objects that are registered with a subsystem that use the
   1.335 +subsystem's default list must have their kset ptr set properly. These
   1.336 +objects may have embedded kobjects, ksets, or other subsystems. The
   1.337 +following helpers make setting the kset easier: 
   1.338 +
   1.339 +
   1.340 +kobj_set_kset_s(obj,subsys)
   1.341 +
   1.342 +- Assumes that obj->kobj exists, and is a struct kobject. 
   1.343 +- Sets the kset of that kobject to the subsystem's embedded kset.
   1.344 +
   1.345 +
   1.346 +kset_set_kset_s(obj,subsys)
   1.347 +
   1.348 +- Assumes that obj->kset exists, and is a struct kset.
   1.349 +- Sets the kset of the embedded kobject to the subsystem's 
   1.350 +  embedded kset. 
   1.351 +
   1.352 +subsys_set_kset(obj,subsys)
   1.353 +
   1.354 +- Assumes obj->subsys exists, and is a struct subsystem.
   1.355 +- Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.
   1.356 +
   1.357 +
   1.358 +4.4 sysfs
   1.359 +
   1.360 +subsystems are represented in sysfs via their embedded kobjects. They
   1.361 +follow the same rules as previously mentioned with no exceptions. They
   1.362 +typically receive a top-level directory in sysfs, except when their
   1.363 +embedded kobject is part of another kset, or the parent of the
   1.364 +embedded kobject is explicitly set. 
   1.365 +
   1.366 +Note that the subsystem's embedded kset must be 'attached' to the
   1.367 +subsystem itself in order to use its rwsem. This is done after
   1.368 +kset_add() has been called. (Not before, because kset_add() uses its
   1.369 +subsystem for a default parent if it doesn't already have one).
   1.370 +