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; |
f285ea05 | 57 | struct kref kref; |
1da177e4 LT |
58 | struct list_head entry; |
59 | struct kobject * parent; | |
60 | struct kset * kset; | |
61 | struct kobj_type * ktype; | |
f285ea05 CH |
62 | struct sysfs_dirent * sd; |
63 | wait_queue_head_t poll; | |
1da177e4 LT |
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 | |
f285ea05 | 140 | is created at the top-level of the sysfs partition. |
1da177e4 LT |
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 { | |
1da177e4 LT |
152 | struct kobj_type * ktype; |
153 | struct list_head list; | |
154 | struct kobject kobj; | |
f285ea05 | 155 | struct kset_uevent_ops * uevent_ops; |
1da177e4 LT |
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 | |
f285ea05 | 171 | pointer. |
1da177e4 LT |
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 | ||
f285ea05 CH |
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 '<name>_subsys' of type <type> with | |
218 | uevent_ops <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 = { | |
f285ea05 CH |
225 | .ktype = &ktype_devices, |
226 | .uevent_ops = &device_uevent_ops, | |
227 | }; | |
d716551e | 228 | kobject_set_name(&devices_subsys, name); |
f285ea05 CH |
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 | |
d716551e | 233 | following helper makes setting the kset easier: |
f285ea05 CH |
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 <subsys>. | |
240 | ||
f285ea05 CH |
241 | int subsystem_register(struct kset *s); |
242 | void subsystem_unregister(struct kset *s); | |
f285ea05 CH |
243 | |
244 | These are just wrappers around the respective kset_* functions. | |
1da177e4 LT |
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 | |
e9539ee7 | 283 | in block/genhd.c |
1da177e4 LT |
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 |