Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/kobject.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 11613 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 11613 byte(s)
Tag kernel26-2.6.12-alx-r9
1 | The kobject Infrastructure |
2 | |
3 | Patrick Mochel <mochel@osdl.org> |
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 | - subsystem a controlling object for a number of ksets. |
31 | |
32 | |
33 | The kobject infrastructure maintains a close relationship with the |
34 | sysfs filesystem. Each kobject that is registered with the kobject |
35 | core receives a directory in sysfs. Attributes about the kobject can |
36 | then be exported. Please see Documentation/filesystems/sysfs.txt for |
37 | more information. |
38 | |
39 | The kobject infrastructure provides a flexible programming interface, |
40 | and allows kobjects and ksets to be used without being registered |
41 | (i.e. with no sysfs representation). This is also described later. |
42 | |
43 | |
44 | 1. kobjects |
45 | |
46 | 1.1 Description |
47 | |
48 | |
49 | struct kobject is a simple data type that provides a foundation for |
50 | more complex object types. It provides a set of basic fields that |
51 | almost all complex data types share. kobjects are intended to be |
52 | embedded in larger data structures and replace fields they duplicate. |
53 | |
54 | 1.2 Defintion |
55 | |
56 | struct kobject { |
57 | char name[KOBJ_NAME_LEN]; |
58 | atomic_t refcount; |
59 | struct list_head entry; |
60 | struct kobject * parent; |
61 | struct kset * kset; |
62 | struct kobj_type * ktype; |
63 | struct dentry * dentry; |
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. This should only |
141 | happen for kobjects that are embedded in a struct subsystem. |
142 | |
143 | |
144 | |
145 | 2. ksets |
146 | |
147 | 2.1 Description |
148 | |
149 | A kset is a set of kobjects that are embedded in the same type. |
150 | |
151 | |
152 | struct kset { |
153 | struct subsystem * subsys; |
154 | struct kobj_type * ktype; |
155 | struct list_head list; |
156 | struct kobject kobj; |
157 | }; |
158 | |
159 | |
160 | void kset_init(struct kset * k); |
161 | int kset_add(struct kset * k); |
162 | int kset_register(struct kset * k); |
163 | void kset_unregister(struct kset * k); |
164 | |
165 | struct kset * kset_get(struct kset * k); |
166 | void kset_put(struct kset * k); |
167 | |
168 | struct kobject * kset_find_obj(struct kset *, char *); |
169 | |
170 | |
171 | The type that the kobjects are embedded in is described by the ktype |
172 | pointer. The subsystem that the kobject belongs to is pointed to by the |
173 | subsys pointer. |
174 | |
175 | A kset contains a kobject itself, meaning that it may be registered in |
176 | the kobject hierarchy and exported via sysfs. More importantly, the |
177 | kset may be embedded in a larger data type, and may be part of another |
178 | kset (of that object type). |
179 | |
180 | For example, a block device is an object (struct gendisk) that is |
181 | contained in a set of block devices. It may also contain a set of |
182 | partitions (struct hd_struct) that have been found on the device. The |
183 | following code snippet illustrates how to express this properly. |
184 | |
185 | struct gendisk * disk; |
186 | ... |
187 | disk->kset.kobj.kset = &block_kset; |
188 | disk->kset.ktype = &partition_ktype; |
189 | kset_register(&disk->kset); |
190 | |
191 | - The kset that the disk's embedded object belongs to is the |
192 | block_kset, and is pointed to by disk->kset.kobj.kset. |
193 | |
194 | - The type of objects on the disk's _subordinate_ list are partitions, |
195 | and is set in disk->kset.ktype. |
196 | |
197 | - The kset is then registered, which handles initializing and adding |
198 | the embedded kobject to the hierarchy. |
199 | |
200 | |
201 | 2.2 kset Programming Interface |
202 | |
203 | All kset functions, except kset_find_obj(), eventually forward the |
204 | calls to their embedded kobjects after performing kset-specific |
205 | operations. ksets offer a similar programming model to kobjects: they |
206 | may be used after they are initialized, without registering them in |
207 | the hierarchy. |
208 | |
209 | kset_find_obj() may be used to locate a kobject with a particular |
210 | name. The kobject, if found, is returned. |
211 | |
212 | |
213 | 2.3 sysfs |
214 | |
215 | ksets are represented in sysfs when their embedded kobjects are |
216 | registered. They follow the same rules of parenting, with one |
217 | exception. If a kset does not have a parent, nor is its embedded |
218 | kobject part of another kset, the kset's parent becomes its dominant |
219 | subsystem. |
220 | |
221 | If the kset does not have a parent, its directory is created at the |
222 | sysfs root. This should only happen when the kset registered is |
223 | embedded in a subsystem itself. |
224 | |
225 | |
226 | 3. struct ktype |
227 | |
228 | 3.1. Description |
229 | |
230 | struct kobj_type { |
231 | void (*release)(struct kobject *); |
232 | struct sysfs_ops * sysfs_ops; |
233 | struct attribute ** default_attrs; |
234 | }; |
235 | |
236 | |
237 | Object types require specific functions for converting between the |
238 | generic object and the more complex type. struct kobj_type provides |
239 | the object-specific fields, which include: |
240 | |
241 | - release: Called when the kobject's reference count reaches 0. This |
242 | should convert the object to the more complex type and free it. |
243 | |
244 | - sysfs_ops: Provides conversion functions for sysfs access. Please |
245 | see the sysfs documentation for more information. |
246 | |
247 | - default_attrs: Default attributes to be exported via sysfs when the |
248 | object is registered.Note that the last attribute has to be |
249 | initialized to NULL ! You can find a complete implementation |
250 | in drivers/block/genhd.c |
251 | |
252 | |
253 | Instances of struct kobj_type are not registered; only referenced by |
254 | the kset. A kobj_type may be referenced by an arbitrary number of |
255 | ksets, as there may be disparate sets of identical objects. |
256 | |
257 | |
258 | |
259 | 4. subsystems |
260 | |
261 | 4.1 Description |
262 | |
263 | A subsystem represents a significant entity of code that maintains an |
264 | arbitrary number of sets of objects of various types. Since the number |
265 | of ksets and the type of objects they contain are variable, a |
266 | generic representation of a subsystem is minimal. |
267 | |
268 | |
269 | struct subsystem { |
270 | struct kset kset; |
271 | struct rw_semaphore rwsem; |
272 | }; |
273 | |
274 | int subsystem_register(struct subsystem *); |
275 | void subsystem_unregister(struct subsystem *); |
276 | |
277 | struct subsystem * subsys_get(struct subsystem * s); |
278 | void subsys_put(struct subsystem * s); |
279 | |
280 | |
281 | A subsystem contains an embedded kset so: |
282 | |
283 | - It can be represented in the object hierarchy via the kset's |
284 | embedded kobject. |
285 | |
286 | - It can maintain a default list of objects of one type. |
287 | |
288 | Additional ksets may attach to the subsystem simply by referencing the |
289 | subsystem before they are registered. (This one-way reference means |
290 | that there is no way to determine the ksets that are attached to the |
291 | subsystem.) |
292 | |
293 | All ksets that are attached to a subsystem share the subsystem's R/W |
294 | semaphore. |
295 | |
296 | |
297 | 4.2 subsystem Programming Interface. |
298 | |
299 | The subsystem programming interface is simple and does not offer the |
300 | flexibility that the kset and kobject programming interfaces do. They |
301 | may be registered and unregistered, as well as reference counted. Each |
302 | call forwards the calls to their embedded ksets (which forward the |
303 | calls to their embedded kobjects). |
304 | |
305 | |
306 | 4.3 Helpers |
307 | |
308 | A number of macros are available to make dealing with subsystems and |
309 | their embedded objects easier. |
310 | |
311 | |
312 | decl_subsys(name,type) |
313 | |
314 | Declares a subsystem named '<name>_subsys', with an embedded kset of |
315 | type <type>. For example, |
316 | |
317 | decl_subsys(devices,&ktype_devices); |
318 | |
319 | is equivalent to doing: |
320 | |
321 | struct subsystem device_subsys = { |
322 | .kset = { |
323 | .kobj = { |
324 | .name = "devices", |
325 | }, |
326 | .ktype = &ktype_devices, |
327 | } |
328 | }; |
329 | |
330 | |
331 | The objects that are registered with a subsystem that use the |
332 | subsystem's default list must have their kset ptr set properly. These |
333 | objects may have embedded kobjects, ksets, or other subsystems. The |
334 | following helpers make setting the kset easier: |
335 | |
336 | |
337 | kobj_set_kset_s(obj,subsys) |
338 | |
339 | - Assumes that obj->kobj exists, and is a struct kobject. |
340 | - Sets the kset of that kobject to the subsystem's embedded kset. |
341 | |
342 | |
343 | kset_set_kset_s(obj,subsys) |
344 | |
345 | - Assumes that obj->kset exists, and is a struct kset. |
346 | - Sets the kset of the embedded kobject to the subsystem's |
347 | embedded kset. |
348 | |
349 | subsys_set_kset(obj,subsys) |
350 | |
351 | - Assumes obj->subsys exists, and is a struct subsystem. |
352 | - Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset. |
353 | |
354 | |
355 | 4.4 sysfs |
356 | |
357 | subsystems are represented in sysfs via their embedded kobjects. They |
358 | follow the same rules as previously mentioned with no exceptions. They |
359 | typically receive a top-level directory in sysfs, except when their |
360 | embedded kobject is part of another kset, or the parent of the |
361 | embedded kobject is explicitly set. |
362 | |
363 | Note that the subsystem's embedded kset must be 'attached' to the |
364 | subsystem itself in order to use its rwsem. This is done after |
365 | kset_add() has been called. (Not before, because kset_add() uses its |
366 | subsystem for a default parent if it doesn't already have one). |
367 |