1 |
3 |
xianfeng |
The kobject Infrastructure
|
2 |
|
|
|
3 |
|
|
Patrick Mochel
|
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 '_subsys' of type with
|
218 |
|
|
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 .
|
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.
|
289 |
|
|
|