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