blob: ca86a885ad8f71c6f98647debd50bf293b33de47 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001The kobject Infrastructure
2
3Patrick Mochel <mochel@osdl.org>
4
5Updated: 3 June 2003
6
7
8Copyright (c) 2003 Patrick Mochel
9Copyright (c) 2003 Open Source Development Labs
10
11
120. Introduction
13
14The kobject infrastructure performs basic object management that larger
15data structures and subsystems can leverage, rather than reimplement
16similar functionality. This functionality primarily concerns:
17
18- Object reference counting.
19- Maintaining lists (sets) of objects.
20- Object set locking.
21- Userspace representation.
22
23The infrastructure consists of a number of object types to support
24this functionality. Their programming interfaces are described below
25in 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070030
31
32The kobject infrastructure maintains a close relationship with the
33sysfs filesystem. Each kobject that is registered with the kobject
34core receives a directory in sysfs. Attributes about the kobject can
35then be exported. Please see Documentation/filesystems/sysfs.txt for
36more information.
37
38The kobject infrastructure provides a flexible programming interface,
39and allows kobjects and ksets to be used without being registered
40(i.e. with no sysfs representation). This is also described later.
41
42
431. kobjects
44
451.1 Description
46
47
48struct kobject is a simple data type that provides a foundation for
49more complex object types. It provides a set of basic fields that
50almost all complex data types share. kobjects are intended to be
51embedded in larger data structures and replace fields they duplicate.
52
Matt LaPlantefff92892006-10-03 22:47:42 +0200531.2 Definition
Linus Torvalds1da177e2005-04-16 15:20:36 -070054
55struct kobject {
Cornelia Huckf285ea02007-07-27 13:41:10 +020056 const char * k_name;
Cornelia Huckf285ea02007-07-27 13:41:10 +020057 struct kref kref;
Linus Torvalds1da177e2005-04-16 15:20:36 -070058 struct list_head entry;
59 struct kobject * parent;
60 struct kset * kset;
61 struct kobj_type * ktype;
Cornelia Huckf285ea02007-07-27 13:41:10 +020062 struct sysfs_dirent * sd;
63 wait_queue_head_t poll;
Linus Torvalds1da177e2005-04-16 15:20:36 -070064};
65
66void kobject_init(struct kobject *);
67int kobject_add(struct kobject *);
68int kobject_register(struct kobject *);
69
70void kobject_del(struct kobject *);
71void kobject_unregister(struct kobject *);
72
73struct kobject * kobject_get(struct kobject *);
74void kobject_put(struct kobject *);
75
76
771.3 kobject Programming Interface
78
79kobjects may be dynamically added and removed from the kobject core
80using kobject_register() and kobject_unregister(). Registration
81includes inserting the kobject in the list of its dominant kset and
82creating a directory for it in sysfs.
83
84Alternatively, one may use a kobject without adding it to its kset's list
85or exporting it via sysfs, by simply calling kobject_init(). An
86initialized kobject may later be added to the object hierarchy by
87calling kobject_add(). An initialized kobject may be used for
88reference counting.
89
90Note: calling kobject_init() then kobject_add() is functionally
91equivalent to calling kobject_register().
92
93When a kobject is unregistered, it is removed from its kset's list,
94removed from the sysfs filesystem, and its reference count is decremented.
95List and sysfs removal happen in kobject_del(), and may be called
96manually. kobject_put() decrements the reference count, and may also
97be called manually.
98
99A kobject's reference count may be incremented with kobject_get(),
100which returns a valid reference to a kobject; and decremented with
101kobject_put(). An object's reference count may only be incremented if
102it is already positive.
103
104When a kobject's reference count reaches 0, the method struct
105kobj_type::release() (which the kobject's kset points to) is called.
106This allows any memory allocated for the object to be freed.
107
108
109NOTE!!!
110
111It is _imperative_ that you supply a destructor for dynamically
112allocated kobjects to free them if you are using kobject reference
113counts. The reference count controls the lifetime of the object.
114If it goes to 0, then it is assumed that the object will
115be freed and cannot be used.
116
117More importantly, you must free the object there, and not immediately
118after an unregister call. If someone else is referencing the object
119(e.g. through a sysfs file), they will obtain a reference to the
120object, assume it's valid and operate on it. If the object is
121unregistered and freed in the meantime, the operation will then
122reference freed memory and go boom.
123
124This can be prevented, in the simplest case, by defining a release
125method and freeing the object from there only. Note that this will not
126secure reference count/object management models that use a dual
127reference count or do other wacky things with the reference count
128(like the networking layer).
129
130
1311.4 sysfs
132
133Each kobject receives a directory in sysfs. This directory is created
134under the kobject's parent directory.
135
136If a kobject does not have a parent when it is registered, its parent
137becomes its dominant kset.
138
139If a kobject does not have a parent nor a dominant kset, its directory
Cornelia Huckf285ea02007-07-27 13:41:10 +0200140is created at the top-level of the sysfs partition.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141
142
143
1442. ksets
145
1462.1 Description
147
148A kset is a set of kobjects that are embedded in the same type.
149
150
151struct kset {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152 struct kobj_type * ktype;
153 struct list_head list;
154 struct kobject kobj;
Cornelia Huckf285ea02007-07-27 13:41:10 +0200155 struct kset_uevent_ops * uevent_ops;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700156};
157
158
159void kset_init(struct kset * k);
160int kset_add(struct kset * k);
161int kset_register(struct kset * k);
162void kset_unregister(struct kset * k);
163
164struct kset * kset_get(struct kset * k);
165void kset_put(struct kset * k);
166
167struct kobject * kset_find_obj(struct kset *, char *);
168
169
170The type that the kobjects are embedded in is described by the ktype
Cornelia Huckf285ea02007-07-27 13:41:10 +0200171pointer.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172
173A kset contains a kobject itself, meaning that it may be registered in
174the kobject hierarchy and exported via sysfs. More importantly, the
175kset may be embedded in a larger data type, and may be part of another
176kset (of that object type).
177
178For example, a block device is an object (struct gendisk) that is
179contained in a set of block devices. It may also contain a set of
180partitions (struct hd_struct) that have been found on the device. The
181following 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
1992.2 kset Programming Interface
200
201All kset functions, except kset_find_obj(), eventually forward the
202calls to their embedded kobjects after performing kset-specific
203operations. ksets offer a similar programming model to kobjects: they
204may be used after they are initialized, without registering them in
205the hierarchy.
206
207kset_find_obj() may be used to locate a kobject with a particular
208name. The kobject, if found, is returned.
209
Cornelia Huckf285ea02007-07-27 13:41:10 +0200210There are also some helper functions which names point to the formerly
211existing "struct subsystem", whose functions have been taken over by
212ksets.
213
214
215decl_subsys(name,type,uevent_ops)
216
217Declares a kset named '<name>_subsys' of type <type> with
218uevent_ops <uevent_ops>. For example,
219
220decl_subsys(devices, &ktype_device, &device_uevent_ops);
221
222is equivalent to doing:
223
224struct kset devices_subsys = {
Cornelia Huckf285ea02007-07-27 13:41:10 +0200225 .ktype = &ktype_devices,
226 .uevent_ops = &device_uevent_ops,
227};
Cornelia Huckd7165512007-09-14 13:25:19 +0200228kobject_set_name(&devices_subsys, name);
Cornelia Huckf285ea02007-07-27 13:41:10 +0200229
230The objects that are registered with a subsystem that use the
231subsystem's default list must have their kset ptr set properly. These
232objects may have embedded kobjects or ksets. The
Cornelia Huckd7165512007-09-14 13:25:19 +0200233following helper makes setting the kset easier:
Cornelia Huckf285ea02007-07-27 13:41:10 +0200234
235
236kobj_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
Cornelia Huckf285ea02007-07-27 13:41:10 +0200241int subsystem_register(struct kset *s);
242void subsystem_unregister(struct kset *s);
Cornelia Huckf285ea02007-07-27 13:41:10 +0200243
244These are just wrappers around the respective kset_* functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700245
2462.3 sysfs
247
248ksets are represented in sysfs when their embedded kobjects are
249registered. They follow the same rules of parenting, with one
250exception. If a kset does not have a parent, nor is its embedded
251kobject part of another kset, the kset's parent becomes its dominant
252subsystem.
253
254If the kset does not have a parent, its directory is created at the
255sysfs root. This should only happen when the kset registered is
256embedded in a subsystem itself.
257
258
2593. struct ktype
260
2613.1. Description
262
263struct kobj_type {
264 void (*release)(struct kobject *);
265 struct sysfs_ops * sysfs_ops;
266 struct attribute ** default_attrs;
267};
268
269
270Object types require specific functions for converting between the
271generic object and the more complex type. struct kobj_type provides
272the 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
Brandon Philipse9539ee2006-08-01 14:04:17 -0500283 in block/genhd.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700284
285
286Instances of struct kobj_type are not registered; only referenced by
287the kset. A kobj_type may be referenced by an arbitrary number of
288ksets, as there may be disparate sets of identical objects.
289