blob: 8ee49ee7c9636ad6b16cd0ecf3e98539ff818fee [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;
Linus Torvalds1da177e2005-04-16 15:20:36 -070057 char name[KOBJ_NAME_LEN];
Cornelia Huckf285ea02007-07-27 13:41:10 +020058 struct kref kref;
Linus Torvalds1da177e2005-04-16 15:20:36 -070059 struct list_head entry;
60 struct kobject * parent;
61 struct kset * kset;
62 struct kobj_type * ktype;
Cornelia Huckf285ea02007-07-27 13:41:10 +020063 struct sysfs_dirent * sd;
64 wait_queue_head_t poll;
Linus Torvalds1da177e2005-04-16 15:20:36 -070065};
66
67void kobject_init(struct kobject *);
68int kobject_add(struct kobject *);
69int kobject_register(struct kobject *);
70
71void kobject_del(struct kobject *);
72void kobject_unregister(struct kobject *);
73
74struct kobject * kobject_get(struct kobject *);
75void kobject_put(struct kobject *);
76
77
781.3 kobject Programming Interface
79
80kobjects may be dynamically added and removed from the kobject core
81using kobject_register() and kobject_unregister(). Registration
82includes inserting the kobject in the list of its dominant kset and
83creating a directory for it in sysfs.
84
85Alternatively, one may use a kobject without adding it to its kset's list
86or exporting it via sysfs, by simply calling kobject_init(). An
87initialized kobject may later be added to the object hierarchy by
88calling kobject_add(). An initialized kobject may be used for
89reference counting.
90
91Note: calling kobject_init() then kobject_add() is functionally
92equivalent to calling kobject_register().
93
94When a kobject is unregistered, it is removed from its kset's list,
95removed from the sysfs filesystem, and its reference count is decremented.
96List and sysfs removal happen in kobject_del(), and may be called
97manually. kobject_put() decrements the reference count, and may also
98be called manually.
99
100A kobject's reference count may be incremented with kobject_get(),
101which returns a valid reference to a kobject; and decremented with
102kobject_put(). An object's reference count may only be incremented if
103it is already positive.
104
105When a kobject's reference count reaches 0, the method struct
106kobj_type::release() (which the kobject's kset points to) is called.
107This allows any memory allocated for the object to be freed.
108
109
110NOTE!!!
111
112It is _imperative_ that you supply a destructor for dynamically
113allocated kobjects to free them if you are using kobject reference
114counts. The reference count controls the lifetime of the object.
115If it goes to 0, then it is assumed that the object will
116be freed and cannot be used.
117
118More importantly, you must free the object there, and not immediately
119after an unregister call. If someone else is referencing the object
120(e.g. through a sysfs file), they will obtain a reference to the
121object, assume it's valid and operate on it. If the object is
122unregistered and freed in the meantime, the operation will then
123reference freed memory and go boom.
124
125This can be prevented, in the simplest case, by defining a release
126method and freeing the object from there only. Note that this will not
127secure reference count/object management models that use a dual
128reference count or do other wacky things with the reference count
129(like the networking layer).
130
131
1321.4 sysfs
133
134Each kobject receives a directory in sysfs. This directory is created
135under the kobject's parent directory.
136
137If a kobject does not have a parent when it is registered, its parent
138becomes its dominant kset.
139
140If a kobject does not have a parent nor a dominant kset, its directory
Cornelia Huckf285ea02007-07-27 13:41:10 +0200141is created at the top-level of the sysfs partition.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700142
143
144
1452. ksets
146
1472.1 Description
148
149A kset is a set of kobjects that are embedded in the same type.
150
151
152struct kset {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153 struct kobj_type * ktype;
154 struct list_head list;
155 struct kobject kobj;
Cornelia Huckf285ea02007-07-27 13:41:10 +0200156 struct kset_uevent_ops * uevent_ops;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700157};
158
159
160void kset_init(struct kset * k);
161int kset_add(struct kset * k);
162int kset_register(struct kset * k);
163void kset_unregister(struct kset * k);
164
165struct kset * kset_get(struct kset * k);
166void kset_put(struct kset * k);
167
168struct kobject * kset_find_obj(struct kset *, char *);
169
170
171The type that the kobjects are embedded in is described by the ktype
Cornelia Huckf285ea02007-07-27 13:41:10 +0200172pointer.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700173
174A kset contains a kobject itself, meaning that it may be registered in
175the kobject hierarchy and exported via sysfs. More importantly, the
176kset may be embedded in a larger data type, and may be part of another
177kset (of that object type).
178
179For example, a block device is an object (struct gendisk) that is
180contained in a set of block devices. It may also contain a set of
181partitions (struct hd_struct) that have been found on the device. The
182following 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
2002.2 kset Programming Interface
201
202All kset functions, except kset_find_obj(), eventually forward the
203calls to their embedded kobjects after performing kset-specific
204operations. ksets offer a similar programming model to kobjects: they
205may be used after they are initialized, without registering them in
206the hierarchy.
207
208kset_find_obj() may be used to locate a kobject with a particular
209name. The kobject, if found, is returned.
210
Cornelia Huckf285ea02007-07-27 13:41:10 +0200211There are also some helper functions which names point to the formerly
212existing "struct subsystem", whose functions have been taken over by
213ksets.
214
215
216decl_subsys(name,type,uevent_ops)
217
218Declares a kset named '<name>_subsys' of type <type> with
219uevent_ops <uevent_ops>. For example,
220
221decl_subsys(devices, &ktype_device, &device_uevent_ops);
222
223is equivalent to doing:
224
225struct kset devices_subsys = {
226 .kobj = {
227 .name = "devices",
228 },
229 .ktype = &ktype_devices,
230 .uevent_ops = &device_uevent_ops,
231};
232
233
234The objects that are registered with a subsystem that use the
235subsystem's default list must have their kset ptr set properly. These
236objects may have embedded kobjects or ksets. The
237following helpers make setting the kset easier:
238
239
240kobj_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
246kset_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
251subsys_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
256void subsystem_init(struct kset *s);
257int subsystem_register(struct kset *s);
258void subsystem_unregister(struct kset *s);
259struct kset *subsys_get(struct kset *s);
260void kset_put(struct kset *s);
261
262These are just wrappers around the respective kset_* functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700263
2642.3 sysfs
265
266ksets are represented in sysfs when their embedded kobjects are
267registered. They follow the same rules of parenting, with one
268exception. If a kset does not have a parent, nor is its embedded
269kobject part of another kset, the kset's parent becomes its dominant
270subsystem.
271
272If the kset does not have a parent, its directory is created at the
273sysfs root. This should only happen when the kset registered is
274embedded in a subsystem itself.
275
276
2773. struct ktype
278
2793.1. Description
280
281struct kobj_type {
282 void (*release)(struct kobject *);
283 struct sysfs_ops * sysfs_ops;
284 struct attribute ** default_attrs;
285};
286
287
288Object types require specific functions for converting between the
289generic object and the more complex type. struct kobj_type provides
290the 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
Brandon Philipse9539ee2006-08-01 14:04:17 -0500301 in block/genhd.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700302
303
304Instances of struct kobj_type are not registered; only referenced by
305the kset. A kobj_type may be referenced by an arbitrary number of
306ksets, as there may be disparate sets of identical objects.
307