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