]>
Commit | Line | Data |
---|---|---|
cd442a45 EH |
1 | =========================== |
2 | The QEMU Object Model (QOM) | |
3 | =========================== | |
4 | ||
9cb54b18 PB |
5 | .. highlight:: c |
6 | ||
7 | The QEMU Object Model provides a framework for registering user creatable | |
8 | types and instantiating objects from those types. QOM provides the following | |
9 | features: | |
10 | ||
258c7327 EH |
11 | - System for dynamically registering types |
12 | - Support for single-inheritance of types | |
13 | - Multiple inheritance of stateless interfaces | |
9cb54b18 PB |
14 | |
15 | .. code-block:: c | |
16 | :caption: Creating a minimal type | |
17 | ||
18 | #include "qdev.h" | |
19 | ||
20 | #define TYPE_MY_DEVICE "my-device" | |
21 | ||
22 | // No new virtual functions: we can reuse the typedef for the | |
23 | // superclass. | |
24 | typedef DeviceClass MyDeviceClass; | |
25 | typedef struct MyDevice | |
26 | { | |
27 | DeviceState parent; | |
28 | ||
29 | int reg0, reg1, reg2; | |
30 | } MyDevice; | |
31 | ||
32 | static const TypeInfo my_device_info = { | |
33 | .name = TYPE_MY_DEVICE, | |
34 | .parent = TYPE_DEVICE, | |
35 | .instance_size = sizeof(MyDevice), | |
36 | }; | |
37 | ||
38 | static void my_device_register_types(void) | |
39 | { | |
40 | type_register_static(&my_device_info); | |
41 | } | |
42 | ||
43 | type_init(my_device_register_types) | |
44 | ||
45 | In the above example, we create a simple type that is described by #TypeInfo. | |
46 | #TypeInfo describes information about the type including what it inherits | |
47 | from, the instance and class size, and constructor/destructor hooks. | |
48 | ||
49 | Alternatively several static types could be registered using helper macro | |
50 | DEFINE_TYPES() | |
51 | ||
52 | .. code-block:: c | |
53 | ||
54 | static const TypeInfo device_types_info[] = { | |
55 | { | |
56 | .name = TYPE_MY_DEVICE_A, | |
57 | .parent = TYPE_DEVICE, | |
58 | .instance_size = sizeof(MyDeviceA), | |
59 | }, | |
60 | { | |
61 | .name = TYPE_MY_DEVICE_B, | |
62 | .parent = TYPE_DEVICE, | |
63 | .instance_size = sizeof(MyDeviceB), | |
64 | }, | |
65 | }; | |
66 | ||
67 | DEFINE_TYPES(device_types_info) | |
68 | ||
69 | Every type has an #ObjectClass associated with it. #ObjectClass derivatives | |
70 | are instantiated dynamically but there is only ever one instance for any | |
71 | given type. The #ObjectClass typically holds a table of function pointers | |
72 | for the virtual methods implemented by this type. | |
73 | ||
74 | Using object_new(), a new #Object derivative will be instantiated. You can | |
75 | cast an #Object to a subclass (or base-class) type using | |
76 | object_dynamic_cast(). You typically want to define macro wrappers around | |
77 | OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a | |
78 | specific type: | |
79 | ||
80 | .. code-block:: c | |
81 | :caption: Typecasting macros | |
82 | ||
83 | #define MY_DEVICE_GET_CLASS(obj) \ | |
84 | OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) | |
85 | #define MY_DEVICE_CLASS(klass) \ | |
86 | OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) | |
87 | #define MY_DEVICE(obj) \ | |
88 | OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) | |
89 | ||
90 | Class Initialization | |
91 | ==================== | |
92 | ||
93 | Before an object is initialized, the class for the object must be | |
94 | initialized. There is only one class object for all instance objects | |
95 | that is created lazily. | |
96 | ||
97 | Classes are initialized by first initializing any parent classes (if | |
98 | necessary). After the parent class object has initialized, it will be | |
99 | copied into the current class object and any additional storage in the | |
100 | class object is zero filled. | |
101 | ||
102 | The effect of this is that classes automatically inherit any virtual | |
103 | function pointers that the parent class has already initialized. All | |
104 | other fields will be zero filled. | |
105 | ||
106 | Once all of the parent classes have been initialized, #TypeInfo::class_init | |
107 | is called to let the class being instantiated provide default initialize for | |
108 | its virtual functions. Here is how the above example might be modified | |
109 | to introduce an overridden virtual function: | |
110 | ||
111 | .. code-block:: c | |
112 | :caption: Overriding a virtual function | |
113 | ||
114 | #include "qdev.h" | |
115 | ||
116 | void my_device_class_init(ObjectClass *klass, void *class_data) | |
117 | { | |
118 | DeviceClass *dc = DEVICE_CLASS(klass); | |
119 | dc->reset = my_device_reset; | |
120 | } | |
121 | ||
122 | static const TypeInfo my_device_info = { | |
123 | .name = TYPE_MY_DEVICE, | |
124 | .parent = TYPE_DEVICE, | |
125 | .instance_size = sizeof(MyDevice), | |
126 | .class_init = my_device_class_init, | |
127 | }; | |
128 | ||
129 | Introducing new virtual methods requires a class to define its own | |
130 | struct and to add a .class_size member to the #TypeInfo. Each method | |
131 | will also have a wrapper function to call it easily: | |
132 | ||
133 | .. code-block:: c | |
134 | :caption: Defining an abstract class | |
135 | ||
136 | #include "qdev.h" | |
137 | ||
138 | typedef struct MyDeviceClass | |
139 | { | |
140 | DeviceClass parent; | |
141 | ||
142 | void (*frobnicate) (MyDevice *obj); | |
143 | } MyDeviceClass; | |
144 | ||
145 | static const TypeInfo my_device_info = { | |
146 | .name = TYPE_MY_DEVICE, | |
147 | .parent = TYPE_DEVICE, | |
148 | .instance_size = sizeof(MyDevice), | |
149 | .abstract = true, // or set a default in my_device_class_init | |
150 | .class_size = sizeof(MyDeviceClass), | |
151 | }; | |
152 | ||
153 | void my_device_frobnicate(MyDevice *obj) | |
154 | { | |
155 | MyDeviceClass *klass = MY_DEVICE_GET_CLASS(obj); | |
156 | ||
157 | klass->frobnicate(obj); | |
158 | } | |
159 | ||
160 | Interfaces | |
161 | ========== | |
162 | ||
163 | Interfaces allow a limited form of multiple inheritance. Instances are | |
164 | similar to normal types except for the fact that are only defined by | |
165 | their classes and never carry any state. As a consequence, a pointer to | |
166 | an interface instance should always be of incomplete type in order to be | |
167 | sure it cannot be dereferenced. That is, you should define the | |
168 | 'typedef struct SomethingIf SomethingIf' so that you can pass around | |
169 | ``SomethingIf *si`` arguments, but not define a ``struct SomethingIf { ... }``. | |
170 | The only things you can validly do with a ``SomethingIf *`` are to pass it as | |
171 | an argument to a method on its corresponding SomethingIfClass, or to | |
172 | dynamically cast it to an object that implements the interface. | |
173 | ||
174 | Methods | |
175 | ======= | |
176 | ||
177 | A <emphasis>method</emphasis> is a function within the namespace scope of | |
178 | a class. It usually operates on the object instance by passing it as a | |
179 | strongly-typed first argument. | |
180 | If it does not operate on an object instance, it is dubbed | |
181 | <emphasis>class method</emphasis>. | |
182 | ||
183 | Methods cannot be overloaded. That is, the #ObjectClass and method name | |
184 | uniquely identity the function to be called; the signature does not vary | |
185 | except for trailing varargs. | |
186 | ||
187 | Methods are always <emphasis>virtual</emphasis>. Overriding a method in | |
188 | #TypeInfo.class_init of a subclass leads to any user of the class obtained | |
189 | via OBJECT_GET_CLASS() accessing the overridden function. | |
190 | The original function is not automatically invoked. It is the responsibility | |
191 | of the overriding class to determine whether and when to invoke the method | |
192 | being overridden. | |
193 | ||
194 | To invoke the method being overridden, the preferred solution is to store | |
195 | the original value in the overriding class before overriding the method. | |
196 | This corresponds to ``{super,base}.method(...)`` in Java and C# | |
197 | respectively; this frees the overriding class from hardcoding its parent | |
198 | class, which someone might choose to change at some point. | |
199 | ||
200 | .. code-block:: c | |
201 | :caption: Overriding a virtual method | |
202 | ||
203 | typedef struct MyState MyState; | |
204 | ||
205 | typedef void (*MyDoSomething)(MyState *obj); | |
206 | ||
207 | typedef struct MyClass { | |
208 | ObjectClass parent_class; | |
209 | ||
210 | MyDoSomething do_something; | |
211 | } MyClass; | |
212 | ||
213 | static void my_do_something(MyState *obj) | |
214 | { | |
215 | // do something | |
216 | } | |
217 | ||
218 | static void my_class_init(ObjectClass *oc, void *data) | |
219 | { | |
220 | MyClass *mc = MY_CLASS(oc); | |
221 | ||
222 | mc->do_something = my_do_something; | |
223 | } | |
224 | ||
225 | static const TypeInfo my_type_info = { | |
226 | .name = TYPE_MY, | |
227 | .parent = TYPE_OBJECT, | |
228 | .instance_size = sizeof(MyState), | |
229 | .class_size = sizeof(MyClass), | |
230 | .class_init = my_class_init, | |
231 | }; | |
232 | ||
233 | typedef struct DerivedClass { | |
234 | MyClass parent_class; | |
235 | ||
236 | MyDoSomething parent_do_something; | |
237 | } DerivedClass; | |
238 | ||
239 | static void derived_do_something(MyState *obj) | |
240 | { | |
241 | DerivedClass *dc = DERIVED_GET_CLASS(obj); | |
242 | ||
243 | // do something here | |
244 | dc->parent_do_something(obj); | |
245 | // do something else here | |
246 | } | |
247 | ||
248 | static void derived_class_init(ObjectClass *oc, void *data) | |
249 | { | |
250 | MyClass *mc = MY_CLASS(oc); | |
251 | DerivedClass *dc = DERIVED_CLASS(oc); | |
252 | ||
253 | dc->parent_do_something = mc->do_something; | |
254 | mc->do_something = derived_do_something; | |
255 | } | |
256 | ||
257 | static const TypeInfo derived_type_info = { | |
258 | .name = TYPE_DERIVED, | |
259 | .parent = TYPE_MY, | |
260 | .class_size = sizeof(DerivedClass), | |
261 | .class_init = derived_class_init, | |
262 | }; | |
263 | ||
264 | Alternatively, object_class_by_name() can be used to obtain the class and | |
265 | its non-overridden methods for a specific type. This would correspond to | |
266 | ``MyClass::method(...)`` in C++. | |
267 | ||
268 | The first example of such a QOM method was #CPUClass.reset, | |
269 | another example is #DeviceClass.realize. | |
270 | ||
271 | Standard type declaration and definition macros | |
272 | =============================================== | |
273 | ||
274 | A lot of the code outlined above follows a standard pattern and naming | |
275 | convention. To reduce the amount of boilerplate code that needs to be | |
276 | written for a new type there are two sets of macros to generate the | |
277 | common parts in a standard format. | |
278 | ||
279 | A type is declared using the OBJECT_DECLARE macro family. In types | |
280 | which do not require any virtual functions in the class, the | |
281 | OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed | |
282 | in the header file: | |
283 | ||
284 | .. code-block:: c | |
285 | :caption: Declaring a simple type | |
286 | ||
287 | OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) | |
288 | ||
289 | This is equivalent to the following: | |
290 | ||
291 | .. code-block:: c | |
292 | :caption: Expansion from declaring a simple type | |
293 | ||
294 | typedef struct MyDevice MyDevice; | |
295 | typedef struct MyDeviceClass MyDeviceClass; | |
296 | ||
297 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref) | |
298 | ||
299 | #define MY_DEVICE_GET_CLASS(void *obj) \ | |
300 | OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) | |
301 | #define MY_DEVICE_CLASS(void *klass) \ | |
302 | OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) | |
303 | #define MY_DEVICE(void *obj) | |
304 | OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) | |
305 | ||
306 | struct MyDeviceClass { | |
307 | DeviceClass parent_class; | |
308 | }; | |
309 | ||
310 | The 'struct MyDevice' needs to be declared separately. | |
311 | If the type requires virtual functions to be declared in the class | |
312 | struct, then the alternative OBJECT_DECLARE_TYPE() macro can be | |
313 | used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without | |
314 | the 'struct MyDeviceClass' definition. | |
315 | ||
316 | To implement the type, the OBJECT_DEFINE macro family is available. | |
317 | In the simple case the OBJECT_DEFINE_TYPE macro is suitable: | |
318 | ||
319 | .. code-block:: c | |
320 | :caption: Defining a simple type | |
321 | ||
322 | OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) | |
323 | ||
324 | This is equivalent to the following: | |
325 | ||
326 | .. code-block:: c | |
327 | :caption: Expansion from defining a simple type | |
328 | ||
329 | static void my_device_finalize(Object *obj); | |
330 | static void my_device_class_init(ObjectClass *oc, void *data); | |
331 | static void my_device_init(Object *obj); | |
332 | ||
333 | static const TypeInfo my_device_info = { | |
334 | .parent = TYPE_DEVICE, | |
335 | .name = TYPE_MY_DEVICE, | |
336 | .instance_size = sizeof(MyDevice), | |
337 | .instance_init = my_device_init, | |
338 | .instance_finalize = my_device_finalize, | |
339 | .class_size = sizeof(MyDeviceClass), | |
340 | .class_init = my_device_class_init, | |
341 | }; | |
342 | ||
343 | static void | |
344 | my_device_register_types(void) | |
345 | { | |
346 | type_register_static(&my_device_info); | |
347 | } | |
348 | type_init(my_device_register_types); | |
349 | ||
350 | This is sufficient to get the type registered with the type | |
351 | system, and the three standard methods now need to be implemented | |
352 | along with any other logic required for the type. | |
353 | ||
354 | If the type needs to implement one or more interfaces, then the | |
355 | OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead. | |
356 | This accepts an array of interface type names. | |
357 | ||
358 | .. code-block:: c | |
359 | :caption: Defining a simple type implementing interfaces | |
360 | ||
361 | OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device, | |
362 | MY_DEVICE, DEVICE, | |
363 | { TYPE_USER_CREATABLE }, { NULL }) | |
364 | ||
365 | If the type is not intended to be instantiated, then then | |
366 | the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: | |
367 | ||
368 | .. code-block:: c | |
369 | :caption: Defining a simple abstract type | |
370 | ||
371 | OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) | |
372 | ||
373 | ||
374 | ||
375 | API Reference | |
376 | ------------- | |
377 | ||
cd442a45 | 378 | .. kernel-doc:: include/qom/object.h |