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 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 *method* 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 *class method*.
 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 *virtual*. 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,
 288                               MY_DEVICE, DEVICE)
 289
 290 This is equivalent to the following:
 291
 292 .. code-block:: c
 293    :caption: Expansion from declaring a simple type
 294
 295    typedef struct MyDevice MyDevice;
 296    typedef struct MyDeviceClass MyDeviceClass;
 297
 298    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
 299
 300    #define MY_DEVICE_GET_CLASS(void *obj) \
 301            OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
 302    #define MY_DEVICE_CLASS(void *klass) \
 303            OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
 304    #define MY_DEVICE(void *obj)
 305            OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
 306
 307    struct MyDeviceClass {
 308        DeviceClass parent_class;
 309    };
 310
 311 The 'struct MyDevice' needs to be declared separately.
 312 If the type requires virtual functions to be declared in the class
 313 struct, then the alternative OBJECT_DECLARE_TYPE() macro can be
 314 used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without
 315 the 'struct MyDeviceClass' definition.
 316
 317 To implement the type, the OBJECT_DEFINE macro family is available.
 318 In the simple case the OBJECT_DEFINE_TYPE macro is suitable:
 319
 320 .. code-block:: c
 321    :caption: Defining a simple type
 322
 323    OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
 324
 325 This is equivalent to the following:
 326
 327 .. code-block:: c
 328    :caption: Expansion from defining a simple type
 329
 330    static void my_device_finalize(Object *obj);
 331    static void my_device_class_init(ObjectClass *oc, void *data);
 332    static void my_device_init(Object *obj);
 333
 334    static const TypeInfo my_device_info = {
 335        .parent = TYPE_DEVICE,
 336        .name = TYPE_MY_DEVICE,
 337        .instance_size = sizeof(MyDevice),
 338        .instance_init = my_device_init,
 339        .instance_finalize = my_device_finalize,
 340        .class_size = sizeof(MyDeviceClass),
 341        .class_init = my_device_class_init,
 342    };
 343
 344    static void
 345    my_device_register_types(void)
 346    {
 347        type_register_static(&my_device_info);
 348    }
 349    type_init(my_device_register_types);
 350
 351 This is sufficient to get the type registered with the type
 352 system, and the three standard methods now need to be implemented
 353 along with any other logic required for the type.
 354
 355 If the type needs to implement one or more interfaces, then the
 356 OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead.
 357 This accepts an array of interface type names.
 358
 359 .. code-block:: c
 360    :caption: Defining a simple type implementing interfaces
 361
 362    OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
 363                                       MY_DEVICE, DEVICE,
 364                                       { TYPE_USER_CREATABLE },
 365                                       { NULL })
 366
 367 If the type is not intended to be instantiated, then then
 368 the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
 369
 370 .. code-block:: c
 371    :caption: Defining a simple abstract type
 372
 373    OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device,
 374                                MY_DEVICE, DEVICE)
 375
 376
 377
 378 API Reference
 379 -------------
 380
 381 .. kernel-doc:: include/qom/object.h