diff options
| -rw-r--r-- | Documentation/kobject.txt | 289 |
1 files changed, 0 insertions, 289 deletions
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt deleted file mode 100644 index ca86a885ad8f..000000000000 --- a/Documentation/kobject.txt +++ /dev/null @@ -1,289 +0,0 @@ -The kobject Infrastructure - -Patrick Mochel <mochel@osdl.org> - -Updated: 3 June 2003 - - -Copyright (c) 2003 Patrick Mochel -Copyright (c) 2003 Open Source Development Labs - - -0. Introduction - -The kobject infrastructure performs basic object management that larger -data structures and subsystems can leverage, rather than reimplement -similar functionality. This functionality primarily concerns: - -- Object reference counting. -- Maintaining lists (sets) of objects. -- Object set locking. -- Userspace representation. - -The infrastructure consists of a number of object types to support -this functionality. Their programming interfaces are described below -in detail, and briefly here: - -- kobjects a simple object. -- kset a set of objects of a certain type. -- ktype a set of helpers for objects of a common type. - - -The kobject infrastructure maintains a close relationship with the -sysfs filesystem. Each kobject that is registered with the kobject -core receives a directory in sysfs. Attributes about the kobject can -then be exported. Please see Documentation/filesystems/sysfs.txt for -more information. - -The kobject infrastructure provides a flexible programming interface, -and allows kobjects and ksets to be used without being registered -(i.e. with no sysfs representation). This is also described later. - - -1. kobjects - -1.1 Description - - -struct kobject is a simple data type that provides a foundation for -more complex object types. It provides a set of basic fields that -almost all complex data types share. kobjects are intended to be -embedded in larger data structures and replace fields they duplicate. - -1.2 Definition - -struct kobject { - const char * k_name; - struct kref kref; - struct list_head entry; - struct kobject * parent; - struct kset * kset; - struct kobj_type * ktype; - struct sysfs_dirent * sd; - wait_queue_head_t poll; -}; - -void kobject_init(struct kobject *); -int kobject_add(struct kobject *); -int kobject_register(struct kobject *); - -void kobject_del(struct kobject *); -void kobject_unregister(struct kobject *); - -struct kobject * kobject_get(struct kobject *); -void kobject_put(struct kobject *); - - -1.3 kobject Programming Interface - -kobjects may be dynamically added and removed from the kobject core -using kobject_register() and kobject_unregister(). Registration -includes inserting the kobject in the list of its dominant kset and -creating a directory for it in sysfs. - -Alternatively, one may use a kobject without adding it to its kset's list -or exporting it via sysfs, by simply calling kobject_init(). An -initialized kobject may later be added to the object hierarchy by -calling kobject_add(). An initialized kobject may be used for -reference counting. - -Note: calling kobject_init() then kobject_add() is functionally -equivalent to calling kobject_register(). - -When a kobject is unregistered, it is removed from its kset's list, -removed from the sysfs filesystem, and its reference count is decremented. -List and sysfs removal happen in kobject_del(), and may be called -manually. kobject_put() decrements the reference count, and may also -be called manually. - -A kobject's reference count may be incremented with kobject_get(), -which returns a valid reference to a kobject; and decremented with -kobject_put(). An object's reference count may only be incremented if -it is already positive. - -When a kobject's reference count reaches 0, the method struct -kobj_type::release() (which the kobject's kset points to) is called. -This allows any memory allocated for the object to be freed. - - -NOTE!!! - -It is _imperative_ that you supply a destructor for dynamically -allocated kobjects to free them if you are using kobject reference -counts. The reference count controls the lifetime of the object. -If it goes to 0, then it is assumed that the object will -be freed and cannot be used. - -More importantly, you must free the object there, and not immediately -after an unregister call. If someone else is referencing the object -(e.g. through a sysfs file), they will obtain a reference to the -object, assume it's valid and operate on it. If the object is -unregistered and freed in the meantime, the operation will then -reference freed memory and go boom. - -This can be prevented, in the simplest case, by defining a release -method and freeing the object from there only. Note that this will not -secure reference count/object management models that use a dual -reference count or do other wacky things with the reference count -(like the networking layer). - - -1.4 sysfs - -Each kobject receives a directory in sysfs. This directory is created -under the kobject's parent directory. - -If a kobject does not have a parent when it is registered, its parent -becomes its dominant kset. - -If a kobject does not have a parent nor a dominant kset, its directory -is created at the top-level of the sysfs partition. - - - -2. ksets - -2.1 Description - -A kset is a set of kobjects that are embedded in the same type. - - -struct kset { - struct kobj_type * ktype; - struct list_head list; - struct kobject kobj; - struct kset_uevent_ops * uevent_ops; -}; - - -void kset_init(struct kset * k); -int kset_add(struct kset * k); -int kset_register(struct kset * k); -void kset_unregister(struct kset * k); - -struct kset * kset_get(struct kset * k); -void kset_put(struct kset * k); - -struct kobject * kset_find_obj(struct kset *, char *); - - -The type that the kobjects are embedded in is described by the ktype -pointer. - -A kset contains a kobject itself, meaning that it may be registered in -the kobject hierarchy and exported via sysfs. More importantly, the -kset may be embedded in a larger data type, and may be part of another -kset (of that object type). - -For example, a block device is an object (struct gendisk) that is -contained in a set of block devices. It may also contain a set of -partitions (struct hd_struct) that have been found on the device. The -following code snippet illustrates how to express this properly. - - struct gendisk * disk; - ... - disk->kset.kobj.kset = &block_kset; - disk->kset.ktype = &partition_ktype; - kset_register(&disk->kset); - -- The kset that the disk's embedded object belongs to is the - block_kset, and is pointed to by disk->kset.kobj.kset. - -- The type of objects on the disk's _subordinate_ list are partitions, - and is set in disk->kset.ktype. - -- The kset is then registered, which handles initializing and adding - the embedded kobject to the hierarchy. - - -2.2 kset Programming Interface - -All kset functions, except kset_find_obj(), eventually forward the -calls to their embedded kobjects after performing kset-specific -operations. ksets offer a similar programming model to kobjects: they -may be used after they are initialized, without registering them in -the hierarchy. - -kset_find_obj() may be used to locate a kobject with a particular -name. The kobject, if found, is returned. - -There are also some helper functions which names point to the formerly -existing "struct subsystem", whose functions have been taken over by -ksets. - - -decl_subsys(name,type,uevent_ops) - -Declares a kset named '<name>_subsys' of type <type> with -uevent_ops <uevent_ops>. For example, - -decl_subsys(devices, &ktype_device, &device_uevent_ops); - -is equivalent to doing: - -struct kset devices_subsys = { - .ktype = &ktype_devices, - .uevent_ops = &device_uevent_ops, -}; -kobject_set_name(&devices_subsys, name); - -The objects that are registered with a subsystem that use the -subsystem's default list must have their kset ptr set properly. These -objects may have embedded kobjects or ksets. The -following helper makes setting the kset easier: - - -kobj_set_kset_s(obj,subsys) - -- Assumes that obj->kobj exists, and is a struct kobject. -- Sets the kset of that kobject to the kset <subsys>. - -int subsystem_register(struct kset *s); -void subsystem_unregister(struct kset *s); - -These are just wrappers around the respective kset_* functions. - -2.3 sysfs - -ksets are represented in sysfs when their embedded kobjects are -registered. They follow the same rules of parenting, with one -exception. If a kset does not have a parent, nor is its embedded -kobject part of another kset, the kset's parent becomes its dominant -subsystem. - -If the kset does not have a parent, its directory is created at the -sysfs root. This should only happen when the kset registered is -embedded in a subsystem itself. - - -3. struct ktype - -3.1. Description - -struct kobj_type { - void (*release)(struct kobject *); - struct sysfs_ops * sysfs_ops; - struct attribute ** default_attrs; -}; - - -Object types require specific functions for converting between the -generic object and the more complex type. struct kobj_type provides -the object-specific fields, which include: - -- release: Called when the kobject's reference count reaches 0. This - should convert the object to the more complex type and free it. - -- sysfs_ops: Provides conversion functions for sysfs access. Please - see the sysfs documentation for more information. - -- default_attrs: Default attributes to be exported via sysfs when the - object is registered.Note that the last attribute has to be - initialized to NULL ! You can find a complete implementation - in block/genhd.c - - -Instances of struct kobj_type are not registered; only referenced by -the kset. A kobj_type may be referenced by an arbitrary number of -ksets, as there may be disparate sets of identical objects. - |