docs/devel/qom.rst

   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