]>
Commit | Line | Data |
---|---|---|
2f28d2ff AL |
1 | /* |
2 | * QEMU Object Model | |
3 | * | |
4 | * Copyright IBM, Corp. 2011 | |
5 | * | |
6 | * Authors: | |
7 | * Anthony Liguori <aliguori@us.ibm.com> | |
8 | * | |
9 | * This work is licensed under the terms of the GNU GPL, version 2 or later. | |
10 | * See the COPYING file in the top-level directory. | |
11 | * | |
12 | */ | |
13 | ||
14 | #ifndef QEMU_OBJECT_H | |
15 | #define QEMU_OBJECT_H | |
16 | ||
17 | #include <glib.h> | |
18 | #include <stdint.h> | |
19 | #include <stdbool.h> | |
20 | ||
21 | struct TypeImpl; | |
22 | typedef struct TypeImpl *Type; | |
23 | ||
24 | typedef struct ObjectClass ObjectClass; | |
25 | typedef struct Object Object; | |
26 | ||
27 | typedef struct TypeInfo TypeInfo; | |
28 | ||
29 | typedef struct InterfaceClass InterfaceClass; | |
30 | typedef struct InterfaceInfo InterfaceInfo; | |
31 | ||
32 | #define TYPE_OBJECT NULL | |
33 | ||
34 | /** | |
35 | * SECTION:object.h | |
36 | * @title:Base Object Type System | |
37 | * @short_description: interfaces for creating new types and objects | |
38 | * | |
39 | * The QEMU Object Model provides a framework for registering user creatable | |
40 | * types and instantiating objects from those types. QOM provides the following | |
41 | * features: | |
42 | * | |
43 | * - System for dynamically registering types | |
44 | * - Support for single-inheritance of types | |
45 | * - Multiple inheritance of stateless interfaces | |
46 | * | |
47 | * <example> | |
48 | * <title>Creating a minimal type</title> | |
49 | * <programlisting> | |
50 | * #include "qdev.h" | |
51 | * | |
52 | * #define TYPE_MY_DEVICE "my-device" | |
53 | * | |
54 | * typedef struct MyDevice | |
55 | * { | |
56 | * DeviceState parent; | |
57 | * | |
58 | * int reg0, reg1, reg2; | |
59 | * } MyDevice; | |
60 | * | |
61 | * static TypeInfo my_device_info = { | |
62 | * .name = TYPE_MY_DEVICE, | |
63 | * .parent = TYPE_DEVICE, | |
64 | * .instance_size = sizeof(MyDevice), | |
65 | * }; | |
66 | * | |
67 | * static void my_device_module_init(void) | |
68 | * { | |
69 | * type_register_static(&my_device_info); | |
70 | * } | |
71 | * | |
72 | * device_init(my_device_module_init); | |
73 | * </programlisting> | |
74 | * </example> | |
75 | * | |
76 | * In the above example, we create a simple type that is described by #TypeInfo. | |
77 | * #TypeInfo describes information about the type including what it inherits | |
78 | * from, the instance and class size, and constructor/destructor hooks. | |
79 | * | |
80 | * Every type has an #ObjectClass associated with it. #ObjectClass derivatives | |
81 | * are instantiated dynamically but there is only ever one instance for any | |
82 | * given type. The #ObjectClass typically holds a table of function pointers | |
83 | * for the virtual methods implemented by this type. | |
84 | * | |
85 | * Using object_new(), a new #Object derivative will be instantiated. You can | |
86 | * cast an #Object to a subclass (or base-class) type using | |
87 | * object_dynamic_cast(). You typically want to define a macro wrapper around | |
88 | * object_dynamic_cast_assert() to make it easier to convert to a specific type. | |
89 | * | |
90 | * # Class Initialization # | |
91 | * | |
92 | * Before an object is initialized, the class for the object must be | |
93 | * initialized. There is only one class object for all instance objects | |
94 | * that is created lazily. | |
95 | * | |
96 | * Classes are initialized by first initializing any parent classes (if | |
97 | * necessary). After the parent class object has initialized, it will be | |
98 | * copied into the current class object and any additional storage in the | |
99 | * class object is zero filled. | |
100 | * | |
101 | * The effect of this is that classes automatically inherit any virtual | |
102 | * function pointers that the parent class has already initialized. All | |
103 | * other fields will be zero filled. | |
104 | * | |
105 | * Once all of the parent classes have been initialized, #TypeInfo::class_init | |
106 | * is called to let the class being instantiated provide default initialize for | |
107 | * it's virtual functions. | |
108 | * | |
109 | * # Interfaces # | |
110 | * | |
111 | * Interfaces allow a limited form of multiple inheritance. Instances are | |
112 | * similar to normal types except for the fact that are only defined by | |
113 | * their classes and never carry any state. You can dynamically cast an object | |
114 | * to one of its #Interface types and vice versa. | |
115 | */ | |
116 | ||
117 | /** | |
118 | * ObjectClass: | |
119 | * | |
120 | * The base for all classes. The only thing that #ObjectClass contains is an | |
121 | * integer type handle. | |
122 | */ | |
123 | struct ObjectClass | |
124 | { | |
125 | /*< private >*/ | |
126 | Type type; | |
127 | }; | |
128 | ||
129 | /** | |
130 | * Object: | |
131 | * | |
132 | * The base for all objects. The first member of this object is a pointer to | |
133 | * a #ObjectClass. Since C guarantees that the first member of a structure | |
134 | * always begins at byte 0 of that structure, as long as any sub-object places | |
135 | * its parent as the first member, we can cast directly to a #Object. | |
136 | * | |
137 | * As a result, #Object contains a reference to the objects type as its | |
138 | * first member. This allows identification of the real type of the object at | |
139 | * run time. | |
140 | * | |
141 | * #Object also contains a list of #Interfaces that this object | |
142 | * implements. | |
143 | */ | |
144 | struct Object | |
145 | { | |
146 | /*< private >*/ | |
147 | ObjectClass *class; | |
148 | ||
149 | GSList *interfaces; | |
150 | }; | |
151 | ||
152 | /** | |
153 | * TypeInfo: | |
154 | * @name: The name of the type. | |
155 | * @parent: The name of the parent type. | |
156 | * @instance_size: The size of the object (derivative of #Object). If | |
157 | * @instance_size is 0, then the size of the object will be the size of the | |
158 | * parent object. | |
159 | * @instance_init: This function is called to initialize an object. The parent | |
160 | * class will have already been initialized so the type is only responsible | |
161 | * for initializing its own members. | |
162 | * @instance_finalize: This function is called during object destruction. This | |
163 | * is called before the parent @instance_finalize function has been called. | |
164 | * An object should only free the members that are unique to its type in this | |
165 | * function. | |
166 | * @abstract: If this field is true, then the class is considered abstract and | |
167 | * cannot be directly instantiated. | |
168 | * @class_size: The size of the class object (derivative of #ObjectClass) | |
169 | * for this object. If @class_size is 0, then the size of the class will be | |
170 | * assumed to be the size of the parent class. This allows a type to avoid | |
171 | * implementing an explicit class type if they are not adding additional | |
172 | * virtual functions. | |
173 | * @class_init: This function is called after all parent class initialization | |
174 | * has occured to allow a class to set its default virtual method pointers. | |
175 | * This is also the function to use to override virtual methods from a parent | |
176 | * class. | |
177 | * @class_finalize: This function is called during class destruction and is | |
178 | * meant to release and dynamic parameters allocated by @class_init. | |
179 | * @class_data: Data to pass to the @class_init and @class_finalize functions. | |
180 | * This can be useful when building dynamic classes. | |
181 | * @interfaces: The list of interfaces associated with this type. This | |
182 | * should point to a static array that's terminated with a zero filled | |
183 | * element. | |
184 | */ | |
185 | struct TypeInfo | |
186 | { | |
187 | const char *name; | |
188 | const char *parent; | |
189 | ||
190 | size_t instance_size; | |
191 | void (*instance_init)(Object *obj); | |
192 | void (*instance_finalize)(Object *obj); | |
193 | ||
194 | bool abstract; | |
195 | size_t class_size; | |
196 | ||
197 | void (*class_init)(ObjectClass *klass, void *data); | |
198 | void (*class_finalize)(ObjectClass *klass, void *data); | |
199 | void *class_data; | |
200 | ||
201 | InterfaceInfo *interfaces; | |
202 | }; | |
203 | ||
204 | /** | |
205 | * OBJECT: | |
206 | * @obj: A derivative of #Object | |
207 | * | |
208 | * Converts an object to a #Object. Since all objects are #Objects, | |
209 | * this function will always succeed. | |
210 | */ | |
211 | #define OBJECT(obj) \ | |
212 | ((Object *)(obj)) | |
213 | ||
214 | /** | |
215 | * OBJECT_CHECK: | |
216 | * @type: The C type to use for the return value. | |
217 | * @obj: A derivative of @type to cast. | |
218 | * @name: The QOM typename of @type | |
219 | * | |
220 | * A type safe version of @object_dynamic_cast_assert. Typically each class | |
221 | * will define a macro based on this type to perform type safe dynamic_casts to | |
222 | * this object type. | |
223 | * | |
224 | * If an invalid object is passed to this function, a run time assert will be | |
225 | * generated. | |
226 | */ | |
227 | #define OBJECT_CHECK(type, obj, name) \ | |
228 | ((type *)object_dynamic_cast_assert((Object *)(obj), (name))) | |
229 | ||
230 | /** | |
231 | * OBJECT_CLASS_CHECK: | |
232 | * @class: The C type to use for the return value. | |
233 | * @obj: A derivative of @type to cast. | |
234 | * @name: the QOM typename of @class. | |
235 | * | |
236 | * A type safe version of @object_check_class. This macro is typically wrapped | |
237 | * by each type to perform type safe casts of a class to a specific class type. | |
238 | */ | |
239 | #define OBJECT_CLASS_CHECK(class, obj, name) \ | |
240 | ((class *)object_class_dynamic_cast_assert((ObjectClass *)(obj), (name))) | |
241 | ||
242 | /** | |
243 | * OBJECT_GET_CLASS: | |
244 | * @class: The C type to use for the return value. | |
245 | * @obj: The object to obtain the class for. | |
246 | * @name: The QOM typename of @obj. | |
247 | * | |
248 | * This function will return a specific class for a given object. Its generally | |
249 | * used by each type to provide a type safe macro to get a specific class type | |
250 | * from an object. | |
251 | */ | |
252 | #define OBJECT_GET_CLASS(class, obj, name) \ | |
253 | OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name) | |
254 | ||
255 | #define OBJECT_CLASS(class) \ | |
256 | ((ObjectClass *)(class)) | |
257 | ||
258 | /** | |
259 | * InterfaceClass: | |
260 | * @parent_class: the base class | |
261 | * | |
262 | * The class for all interfaces. Subclasses of this class should only add | |
263 | * virtual methods. | |
264 | */ | |
265 | struct InterfaceClass | |
266 | { | |
267 | ObjectClass parent_class; | |
268 | }; | |
269 | ||
270 | /** | |
271 | * InterfaceInfo: | |
272 | * @type: The name of the interface. | |
273 | * @interface_initfn: This method is called during class initialization and is | |
274 | * used to initialize an interface associated with a class. This function | |
275 | * should initialize any default virtual functions for a class and/or override | |
276 | * virtual functions in a parent class. | |
277 | * | |
278 | * The information associated with an interface. | |
279 | */ | |
280 | struct InterfaceInfo | |
281 | { | |
282 | const char *type; | |
283 | ||
284 | void (*interface_initfn)(ObjectClass *class, void *data); | |
285 | }; | |
286 | ||
287 | #define TYPE_INTERFACE "interface" | |
288 | ||
289 | /** | |
290 | * object_new: | |
291 | * @typename: The name of the type of the object to instantiate. | |
292 | * | |
293 | * This function will initialize a new object using heap allocated memory. This | |
294 | * function should be paired with object_delete() to free the resources | |
295 | * associated with the object. | |
296 | * | |
297 | * Returns: The newly allocated and instantiated object. | |
298 | */ | |
299 | Object *object_new(const char *typename); | |
300 | ||
301 | /** | |
302 | * object_new_with_type: | |
303 | * @type: The type of the object to instantiate. | |
304 | * | |
305 | * This function will initialize a new object using heap allocated memory. This | |
306 | * function should be paired with object_delete() to free the resources | |
307 | * associated with the object. | |
308 | * | |
309 | * Returns: The newly allocated and instantiated object. | |
310 | */ | |
311 | Object *object_new_with_type(Type type); | |
312 | ||
313 | /** | |
314 | * object_delete: | |
315 | * @obj: The object to free. | |
316 | * | |
317 | * Finalize an object and then free the memory associated with it. This should | |
318 | * be paired with object_new() to free the resources associated with an object. | |
319 | */ | |
320 | void object_delete(Object *obj); | |
321 | ||
322 | /** | |
323 | * object_initialize_with_type: | |
324 | * @obj: A pointer to the memory to be used for the object. | |
325 | * @type: The type of the object to instantiate. | |
326 | * | |
327 | * This function will initialize an object. The memory for the object should | |
328 | * have already been allocated. | |
329 | */ | |
330 | void object_initialize_with_type(void *data, Type type); | |
331 | ||
332 | /** | |
333 | * object_initialize: | |
334 | * @obj: A pointer to the memory to be used for the object. | |
335 | * @typename: The name of the type of the object to instantiate. | |
336 | * | |
337 | * This function will initialize an object. The memory for the object should | |
338 | * have already been allocated. | |
339 | */ | |
340 | void object_initialize(void *obj, const char *typename); | |
341 | ||
342 | /** | |
343 | * object_finalize: | |
344 | * @obj: The object to finalize. | |
345 | * | |
346 | * This function destroys and object without freeing the memory associated with | |
347 | * it. | |
348 | */ | |
349 | void object_finalize(void *obj); | |
350 | ||
351 | /** | |
352 | * object_dynamic_cast: | |
353 | * @obj: The object to cast. | |
354 | * @typename: The @typename to cast to. | |
355 | * | |
356 | * This function will determine if @obj is-a @typename. @obj can refer to an | |
357 | * object or an interface associated with an object. | |
358 | * | |
359 | * Returns: This function returns @obj on success or #NULL on failure. | |
360 | */ | |
361 | Object *object_dynamic_cast(Object *obj, const char *typename); | |
362 | ||
363 | /** | |
364 | * @object_dynamic_cast_assert: | |
365 | * | |
366 | * See object_dynamic_cast() for a description of the parameters of this | |
367 | * function. The only difference in behavior is that this function asserts | |
368 | * instead of returning #NULL on failure. | |
369 | */ | |
370 | Object *object_dynamic_cast_assert(Object *obj, const char *typename); | |
371 | ||
372 | /** | |
373 | * object_get_class: | |
374 | * @obj: A derivative of #Object | |
375 | * | |
376 | * Returns: The #ObjectClass of the type associated with @obj. | |
377 | */ | |
378 | ObjectClass *object_get_class(Object *obj); | |
379 | ||
380 | /** | |
381 | * object_get_typename: | |
382 | * @obj: A derivative of #Object. | |
383 | * | |
384 | * Returns: The QOM typename of @obj. | |
385 | */ | |
386 | const char *object_get_typename(Object *obj); | |
387 | ||
388 | /** | |
389 | * type_register_static: | |
390 | * @info: The #TypeInfo of the new type. | |
391 | * | |
392 | * @info and all of the strings it points to should exist for the life time | |
393 | * that the type is registered. | |
394 | * | |
395 | * Returns: 0 on failure, the new #Type on success. | |
396 | */ | |
397 | Type type_register_static(const TypeInfo *info); | |
398 | ||
399 | /** | |
400 | * type_register: | |
401 | * @info: The #TypeInfo of the new type | |
402 | * | |
403 | * Unlike type_register_static(), this call does not require @info or it's | |
404 | * string members to continue to exist after the call returns. | |
405 | * | |
406 | * Returns: 0 on failure, the new #Type on success. | |
407 | */ | |
408 | Type type_register(const TypeInfo *info); | |
409 | ||
410 | /** | |
411 | * object_class_dynamic_cast_assert: | |
412 | * @klass: The #ObjectClass to attempt to cast. | |
413 | * @typename: The QOM typename of the class to cast to. | |
414 | * | |
415 | * Returns: This function always returns @klass and asserts on failure. | |
416 | */ | |
417 | ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass, | |
418 | const char *typename); | |
419 | ||
420 | ObjectClass *object_class_dynamic_cast(ObjectClass *klass, | |
421 | const char *typename); | |
422 | ||
423 | /** | |
424 | * object_class_get_name: | |
425 | * @klass: The class to obtain the QOM typename for. | |
426 | * | |
427 | * Returns: The QOM typename for @klass. | |
428 | */ | |
429 | const char *object_class_get_name(ObjectClass *klass); | |
430 | ||
431 | ObjectClass *object_class_by_name(const char *typename); | |
432 | ||
433 | void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque), | |
434 | void *opaque); | |
435 | ||
436 | #endif |