docs/devel/qom.rst

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