object.h 43.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/*
 * QEMU Object Model
 *
 * Copyright IBM, Corp. 2011
 *
 * Authors:
 *  Anthony Liguori   <aliguori@us.ibm.com>
 *
 * This work is licensed under the terms of the GNU GPL, version 2 or later.
 * See the COPYING file in the top-level directory.
 *
 */

#ifndef QEMU_OBJECT_H
#define QEMU_OBJECT_H

#include <glib.h>
#include <stdint.h>
#include <stdbool.h>
20
#include "qemu/queue.h"
21
#include "qapi/error.h"
22 23

struct Visitor;
24 25 26 27 28 29 30 31 32 33 34 35

struct TypeImpl;
typedef struct TypeImpl *Type;

typedef struct ObjectClass ObjectClass;
typedef struct Object Object;

typedef struct TypeInfo TypeInfo;

typedef struct InterfaceClass InterfaceClass;
typedef struct InterfaceInfo InterfaceInfo;

Paolo Bonzini's avatar
Paolo Bonzini committed
36
#define TYPE_OBJECT "object"
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

/**
 * SECTION:object.h
 * @title:Base Object Type System
 * @short_description: interfaces for creating new types and objects
 *
 * The QEMU Object Model provides a framework for registering user creatable
 * types and instantiating objects from those types.  QOM provides the following
 * features:
 *
 *  - System for dynamically registering types
 *  - Support for single-inheritance of types
 *  - Multiple inheritance of stateless interfaces
 *
 * <example>
 *   <title>Creating a minimal type</title>
 *   <programlisting>
 * #include "qdev.h"
 *
 * #define TYPE_MY_DEVICE "my-device"
 *
58 59 60
 * // No new virtual functions: we can reuse the typedef for the
 * // superclass.
 * typedef DeviceClass MyDeviceClass;
61 62 63 64 65 66 67
 * typedef struct MyDevice
 * {
 *     DeviceState parent;
 *
 *     int reg0, reg1, reg2;
 * } MyDevice;
 *
68
 * static const TypeInfo my_device_info = {
69 70 71 72 73
 *     .name = TYPE_MY_DEVICE,
 *     .parent = TYPE_DEVICE,
 *     .instance_size = sizeof(MyDevice),
 * };
 *
74
 * static void my_device_register_types(void)
75 76 77 78
 * {
 *     type_register_static(&my_device_info);
 * }
 *
79
 * type_init(my_device_register_types)
80 81 82 83 84 85 86 87 88 89 90 91 92 93
 *   </programlisting>
 * </example>
 *
 * In the above example, we create a simple type that is described by #TypeInfo.
 * #TypeInfo describes information about the type including what it inherits
 * from, the instance and class size, and constructor/destructor hooks.
 *
 * Every type has an #ObjectClass associated with it.  #ObjectClass derivatives
 * are instantiated dynamically but there is only ever one instance for any
 * given type.  The #ObjectClass typically holds a table of function pointers
 * for the virtual methods implemented by this type.
 *
 * Using object_new(), a new #Object derivative will be instantiated.  You can
 * cast an #Object to a subclass (or base-class) type using
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
 * object_dynamic_cast().  You typically want to define macro wrappers around
 * OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a
 * specific type:
 *
 * <example>
 *   <title>Typecasting macros</title>
 *   <programlisting>
 *    #define MY_DEVICE_GET_CLASS(obj) \
 *       OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
 *    #define MY_DEVICE_CLASS(klass) \
 *       OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
 *    #define MY_DEVICE(obj) \
 *       OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
 *   </programlisting>
 * </example>
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
 *
 * # Class Initialization #
 *
 * Before an object is initialized, the class for the object must be
 * initialized.  There is only one class object for all instance objects
 * that is created lazily.
 *
 * Classes are initialized by first initializing any parent classes (if
 * necessary).  After the parent class object has initialized, it will be
 * copied into the current class object and any additional storage in the
 * class object is zero filled.
 *
 * The effect of this is that classes automatically inherit any virtual
 * function pointers that the parent class has already initialized.  All
 * other fields will be zero filled.
 *
 * Once all of the parent classes have been initialized, #TypeInfo::class_init
 * is called to let the class being instantiated provide default initialize for
127
 * its virtual functions.  Here is how the above example might be modified
128 129 130 131 132 133 134 135 136 137 138 139 140
 * to introduce an overridden virtual function:
 *
 * <example>
 *   <title>Overriding a virtual function</title>
 *   <programlisting>
 * #include "qdev.h"
 *
 * void my_device_class_init(ObjectClass *klass, void *class_data)
 * {
 *     DeviceClass *dc = DEVICE_CLASS(klass);
 *     dc->reset = my_device_reset;
 * }
 *
141
 * static const TypeInfo my_device_info = {
142 143 144 145 146 147 148 149
 *     .name = TYPE_MY_DEVICE,
 *     .parent = TYPE_DEVICE,
 *     .instance_size = sizeof(MyDevice),
 *     .class_init = my_device_class_init,
 * };
 *   </programlisting>
 * </example>
 *
150 151 152
 * Introducing new virtual methods requires a class to define its own
 * struct and to add a .class_size member to the #TypeInfo.  Each method
 * will also have a wrapper function to call it easily:
153 154 155 156 157 158 159 160 161 162 163 164 165
 *
 * <example>
 *   <title>Defining an abstract class</title>
 *   <programlisting>
 * #include "qdev.h"
 *
 * typedef struct MyDeviceClass
 * {
 *     DeviceClass parent;
 *
 *     void (*frobnicate) (MyDevice *obj);
 * } MyDeviceClass;
 *
166
 * static const TypeInfo my_device_info = {
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
 *     .name = TYPE_MY_DEVICE,
 *     .parent = TYPE_DEVICE,
 *     .instance_size = sizeof(MyDevice),
 *     .abstract = true, // or set a default in my_device_class_init
 *     .class_size = sizeof(MyDeviceClass),
 * };
 *
 * void my_device_frobnicate(MyDevice *obj)
 * {
 *     MyDeviceClass *klass = MY_DEVICE_GET_CLASS(obj);
 *
 *     klass->frobnicate(obj);
 * }
 *   </programlisting>
 * </example>
182 183 184 185 186 187 188
 *
 * # Interfaces #
 *
 * Interfaces allow a limited form of multiple inheritance.  Instances are
 * similar to normal types except for the fact that are only defined by
 * their classes and never carry any state.  You can dynamically cast an object
 * to one of its #Interface types and vice versa.
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
 *
 * # Methods #
 *
 * A <emphasis>method</emphasis> is a function within the namespace scope of
 * a class. It usually operates on the object instance by passing it as a
 * strongly-typed first argument.
 * If it does not operate on an object instance, it is dubbed
 * <emphasis>class method</emphasis>.
 *
 * Methods cannot be overloaded. That is, the #ObjectClass and method name
 * uniquely identity the function to be called; the signature does not vary
 * except for trailing varargs.
 *
 * Methods are always <emphasis>virtual</emphasis>. Overriding a method in
 * #TypeInfo.class_init of a subclass leads to any user of the class obtained
 * via OBJECT_GET_CLASS() accessing the overridden function.
205
 * The original function is not automatically invoked. It is the responsibility
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
 * of the overriding class to determine whether and when to invoke the method
 * being overridden.
 *
 * To invoke the method being overridden, the preferred solution is to store
 * the original value in the overriding class before overriding the method.
 * This corresponds to |[ {super,base}.method(...) ]| in Java and C#
 * respectively; this frees the overriding class from hardcoding its parent
 * class, which someone might choose to change at some point.
 *
 * <example>
 *   <title>Overriding a virtual method</title>
 *   <programlisting>
 * typedef struct MyState MyState;
 *
 * typedef void (*MyDoSomething)(MyState *obj);
 *
 * typedef struct MyClass {
 *     ObjectClass parent_class;
 *
 *     MyDoSomething do_something;
 * } MyClass;
 *
 * static void my_do_something(MyState *obj)
 * {
 *     // do something
 * }
 *
 * static void my_class_init(ObjectClass *oc, void *data)
 * {
 *     MyClass *mc = MY_CLASS(oc);
 *
 *     mc->do_something = my_do_something;
 * }
 *
 * static const TypeInfo my_type_info = {
 *     .name = TYPE_MY,
 *     .parent = TYPE_OBJECT,
 *     .instance_size = sizeof(MyState),
 *     .class_size = sizeof(MyClass),
 *     .class_init = my_class_init,
 * };
 *
 * typedef struct DerivedClass {
 *     MyClass parent_class;
 *
 *     MyDoSomething parent_do_something;
252
 * } DerivedClass;
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
 *
 * static void derived_do_something(MyState *obj)
 * {
 *     DerivedClass *dc = DERIVED_GET_CLASS(obj);
 *
 *     // do something here
 *     dc->parent_do_something(obj);
 *     // do something else here
 * }
 *
 * static void derived_class_init(ObjectClass *oc, void *data)
 * {
 *     MyClass *mc = MY_CLASS(oc);
 *     DerivedClass *dc = DERIVED_CLASS(oc);
 *
 *     dc->parent_do_something = mc->do_something;
 *     mc->do_something = derived_do_something;
 * }
 *
 * static const TypeInfo derived_type_info = {
 *     .name = TYPE_DERIVED,
 *     .parent = TYPE_MY,
 *     .class_size = sizeof(DerivedClass),
 *     .class_init = my_class_init,
 * };
 *   </programlisting>
 * </example>
 *
 * Alternatively, object_class_by_name() can be used to obtain the class and
 * its non-overridden methods for a specific type. This would correspond to
 * |[ MyClass::method(...) ]| in C++.
 *
 * The first example of such a QOM method was #CPUClass.reset,
 * another example is #DeviceClass.realize.
287 288
 */

289 290 291 292 293 294 295 296 297 298 299 300 301 302 303

/**
 * ObjectPropertyAccessor:
 * @obj: the object that owns the property
 * @v: the visitor that contains the property data
 * @opaque: the object property opaque
 * @name: the name of the property
 * @errp: a pointer to an Error that is filled if getting/setting fails.
 *
 * Called when trying to get/set a property.
 */
typedef void (ObjectPropertyAccessor)(Object *obj,
                                      struct Visitor *v,
                                      void *opaque,
                                      const char *name,
304
                                      Error **errp);
305

306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
/**
 * ObjectPropertyResolve:
 * @obj: the object that owns the property
 * @opaque: the opaque registered with the property
 * @part: the name of the property
 *
 * Resolves the #Object corresponding to property @part.
 *
 * The returned object can also be used as a starting point
 * to resolve a relative path starting with "@part".
 *
 * Returns: If @path is the path that led to @obj, the function
 * returns the #Object corresponding to "@path/@part".
 * If "@path/@part" is not a valid object path, it returns #NULL.
 */
typedef Object *(ObjectPropertyResolve)(Object *obj,
                                        void *opaque,
                                        const char *part);

325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340
/**
 * ObjectPropertyRelease:
 * @obj: the object that owns the property
 * @name: the name of the property
 * @opaque: the opaque registered with the property
 *
 * Called when a property is removed from a object.
 */
typedef void (ObjectPropertyRelease)(Object *obj,
                                     const char *name,
                                     void *opaque);

typedef struct ObjectProperty
{
    gchar *name;
    gchar *type;
341
    gchar *description;
342 343
    ObjectPropertyAccessor *get;
    ObjectPropertyAccessor *set;
344
    ObjectPropertyResolve *resolve;
345 346 347 348 349 350
    ObjectPropertyRelease *release;
    void *opaque;

    QTAILQ_ENTRY(ObjectProperty) node;
} ObjectProperty;

351 352 353 354 355 356 357 358 359
/**
 * ObjectUnparent:
 * @obj: the object that is being removed from the composition tree
 *
 * Called when an object is being removed from the QOM composition tree.
 * The function should remove any backlinks from children objects to @obj.
 */
typedef void (ObjectUnparent)(Object *obj);

360 361 362 363 364 365 366 367
/**
 * ObjectFree:
 * @obj: the object being freed
 *
 * Called when an object's last reference is removed.
 */
typedef void (ObjectFree)(void *obj);

368 369
#define OBJECT_CLASS_CAST_CACHE 4

370 371 372 373 374 375 376 377 378 379
/**
 * ObjectClass:
 *
 * The base for all classes.  The only thing that #ObjectClass contains is an
 * integer type handle.
 */
struct ObjectClass
{
    /*< private >*/
    Type type;
380
    GSList *interfaces;
381

382 383
    const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
    const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
384

385
    ObjectUnparent *unparent;
386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
};

/**
 * Object:
 *
 * The base for all objects.  The first member of this object is a pointer to
 * a #ObjectClass.  Since C guarantees that the first member of a structure
 * always begins at byte 0 of that structure, as long as any sub-object places
 * its parent as the first member, we can cast directly to a #Object.
 *
 * As a result, #Object contains a reference to the objects type as its
 * first member.  This allows identification of the real type of the object at
 * run time.
 *
 * #Object also contains a list of #Interfaces that this object
 * implements.
 */
struct Object
{
    /*< private >*/
    ObjectClass *class;
407
    ObjectFree *free;
408 409 410
    QTAILQ_HEAD(, ObjectProperty) properties;
    uint32_t ref;
    Object *parent;
411 412 413 414 415 416 417 418 419 420 421 422
};

/**
 * TypeInfo:
 * @name: The name of the type.
 * @parent: The name of the parent type.
 * @instance_size: The size of the object (derivative of #Object).  If
 *   @instance_size is 0, then the size of the object will be the size of the
 *   parent object.
 * @instance_init: This function is called to initialize an object.  The parent
 *   class will have already been initialized so the type is only responsible
 *   for initializing its own members.
423 424
 * @instance_post_init: This function is called to finish initialization of
 *   an object, after all @instance_init functions were called.
425 426 427 428 429 430 431 432 433 434 435 436
 * @instance_finalize: This function is called during object destruction.  This
 *   is called before the parent @instance_finalize function has been called.
 *   An object should only free the members that are unique to its type in this
 *   function.
 * @abstract: If this field is true, then the class is considered abstract and
 *   cannot be directly instantiated.
 * @class_size: The size of the class object (derivative of #ObjectClass)
 *   for this object.  If @class_size is 0, then the size of the class will be
 *   assumed to be the size of the parent class.  This allows a type to avoid
 *   implementing an explicit class type if they are not adding additional
 *   virtual functions.
 * @class_init: This function is called after all parent class initialization
437
 *   has occurred to allow a class to set its default virtual method pointers.
438 439
 *   This is also the function to use to override virtual methods from a parent
 *   class.
Paolo Bonzini's avatar
Paolo Bonzini committed
440 441 442 443
 * @class_base_init: This function is called for all base classes after all
 *   parent class initialization has occurred, but before the class itself
 *   is initialized.  This is the function to use to undo the effects of
 *   memcpy from the parent class to the descendents.
444 445
 * @class_finalize: This function is called during class destruction and is
 *   meant to release and dynamic parameters allocated by @class_init.
Paolo Bonzini's avatar
Paolo Bonzini committed
446 447 448
 * @class_data: Data to pass to the @class_init, @class_base_init and
 *   @class_finalize functions.  This can be useful when building dynamic
 *   classes.
449 450 451 452 453 454 455 456 457 458 459
 * @interfaces: The list of interfaces associated with this type.  This
 *   should point to a static array that's terminated with a zero filled
 *   element.
 */
struct TypeInfo
{
    const char *name;
    const char *parent;

    size_t instance_size;
    void (*instance_init)(Object *obj);
460
    void (*instance_post_init)(Object *obj);
461 462 463 464 465 466
    void (*instance_finalize)(Object *obj);

    bool abstract;
    size_t class_size;

    void (*class_init)(ObjectClass *klass, void *data);
Paolo Bonzini's avatar
Paolo Bonzini committed
467
    void (*class_base_init)(ObjectClass *klass, void *data);
468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
    void (*class_finalize)(ObjectClass *klass, void *data);
    void *class_data;

    InterfaceInfo *interfaces;
};

/**
 * OBJECT:
 * @obj: A derivative of #Object
 *
 * Converts an object to a #Object.  Since all objects are #Objects,
 * this function will always succeed.
 */
#define OBJECT(obj) \
    ((Object *)(obj))

484 485
/**
 * OBJECT_CLASS:
486
 * @class: A derivative of #ObjectClass.
487 488 489 490 491 492 493
 *
 * Converts a class to an #ObjectClass.  Since all objects are #Objects,
 * this function will always succeed.
 */
#define OBJECT_CLASS(class) \
    ((ObjectClass *)(class))

494 495 496 497 498 499 500 501 502 503 504 505 506 507
/**
 * OBJECT_CHECK:
 * @type: The C type to use for the return value.
 * @obj: A derivative of @type to cast.
 * @name: The QOM typename of @type
 *
 * A type safe version of @object_dynamic_cast_assert.  Typically each class
 * will define a macro based on this type to perform type safe dynamic_casts to
 * this object type.
 *
 * If an invalid object is passed to this function, a run time assert will be
 * generated.
 */
#define OBJECT_CHECK(type, obj, name) \
508 509
    ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
                                        __FILE__, __LINE__, __func__))
510 511 512 513 514 515 516

/**
 * OBJECT_CLASS_CHECK:
 * @class: The C type to use for the return value.
 * @obj: A derivative of @type to cast.
 * @name: the QOM typename of @class.
 *
517 518 519
 * A type safe version of @object_class_dynamic_cast_assert.  This macro is
 * typically wrapped by each type to perform type safe casts of a class to a
 * specific class type.
520 521
 */
#define OBJECT_CLASS_CHECK(class, obj, name) \
522 523
    ((class *)object_class_dynamic_cast_assert(OBJECT_CLASS(obj), (name), \
                                               __FILE__, __LINE__, __func__))
524 525 526 527 528 529 530 531 532 533 534 535 536 537

/**
 * OBJECT_GET_CLASS:
 * @class: The C type to use for the return value.
 * @obj: The object to obtain the class for.
 * @name: The QOM typename of @obj.
 *
 * This function will return a specific class for a given object.  Its generally
 * used by each type to provide a type safe macro to get a specific class type
 * from an object.
 */
#define OBJECT_GET_CLASS(class, obj, name) \
    OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)

538 539 540 541 542 543 544 545 546 547
/**
 * InterfaceInfo:
 * @type: The name of the interface.
 *
 * The information associated with an interface.
 */
struct InterfaceInfo {
    const char *type;
};

548 549 550 551 552 553 554 555 556 557
/**
 * InterfaceClass:
 * @parent_class: the base class
 *
 * The class for all interfaces.  Subclasses of this class should only add
 * virtual methods.
 */
struct InterfaceClass
{
    ObjectClass parent_class;
558 559
    /*< private >*/
    ObjectClass *concrete_class;
560
    Type interface_type;
561 562
};

563 564
#define TYPE_INTERFACE "interface"

565
/**
566 567 568
 * INTERFACE_CLASS:
 * @klass: class to cast from
 * Returns: An #InterfaceClass or raise an error if cast is invalid
569
 */
570 571
#define INTERFACE_CLASS(klass) \
    OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE)
572

573 574 575 576 577 578 579 580 581
/**
 * INTERFACE_CHECK:
 * @interface: the type to return
 * @obj: the object to convert to an interface
 * @name: the interface type name
 *
 * Returns: @obj casted to @interface if cast is valid, otherwise raise error.
 */
#define INTERFACE_CHECK(interface, obj, name) \
582 583
    ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
                                             __FILE__, __LINE__, __func__))
584 585 586 587 588

/**
 * object_new:
 * @typename: The name of the type of the object to instantiate.
 *
589 590 591
 * This function will initialize a new object using heap allocated memory.
 * The returned object has a reference count of 1, and will be freed when
 * the last reference is dropped.
592 593 594 595 596 597 598 599 600
 *
 * Returns: The newly allocated and instantiated object.
 */
Object *object_new(const char *typename);

/**
 * object_new_with_type:
 * @type: The type of the object to instantiate.
 *
601 602 603
 * This function will initialize a new object using heap allocated memory.
 * The returned object has a reference count of 1, and will be freed when
 * the last reference is dropped.
604 605 606 607 608 609 610
 *
 * Returns: The newly allocated and instantiated object.
 */
Object *object_new_with_type(Type type);

/**
 * object_initialize_with_type:
611
 * @data: A pointer to the memory to be used for the object.
612
 * @size: The maximum size available at @data for the object.
613 614 615
 * @type: The type of the object to instantiate.
 *
 * This function will initialize an object.  The memory for the object should
616 617
 * have already been allocated.  The returned object has a reference count of 1,
 * and will be finalized when the last reference is dropped.
618
 */
619
void object_initialize_with_type(void *data, size_t size, Type type);
620 621 622 623

/**
 * object_initialize:
 * @obj: A pointer to the memory to be used for the object.
624
 * @size: The maximum size available at @obj for the object.
625 626 627
 * @typename: The name of the type of the object to instantiate.
 *
 * This function will initialize an object.  The memory for the object should
628 629
 * have already been allocated.  The returned object has a reference count of 1,
 * and will be finalized when the last reference is dropped.
630
 */
631
void object_initialize(void *obj, size_t size, const char *typename);
632 633 634 635 636 637 638 639 640 641 642 643 644 645

/**
 * object_dynamic_cast:
 * @obj: The object to cast.
 * @typename: The @typename to cast to.
 *
 * This function will determine if @obj is-a @typename.  @obj can refer to an
 * object or an interface associated with an object.
 *
 * Returns: This function returns @obj on success or #NULL on failure.
 */
Object *object_dynamic_cast(Object *obj, const char *typename);

/**
646
 * object_dynamic_cast_assert:
647 648 649
 *
 * See object_dynamic_cast() for a description of the parameters of this
 * function.  The only difference in behavior is that this function asserts
650 651 652
 * instead of returning #NULL on failure if QOM cast debugging is enabled.
 * This function is not meant to be called directly, but only through
 * the wrapper macro OBJECT_CHECK.
653
 */
654 655
Object *object_dynamic_cast_assert(Object *obj, const char *typename,
                                   const char *file, int line, const char *func);
656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687

/**
 * object_get_class:
 * @obj: A derivative of #Object
 *
 * Returns: The #ObjectClass of the type associated with @obj.
 */
ObjectClass *object_get_class(Object *obj);

/**
 * object_get_typename:
 * @obj: A derivative of #Object.
 *
 * Returns: The QOM typename of @obj.
 */
const char *object_get_typename(Object *obj);

/**
 * type_register_static:
 * @info: The #TypeInfo of the new type.
 *
 * @info and all of the strings it points to should exist for the life time
 * that the type is registered.
 *
 * Returns: 0 on failure, the new #Type on success.
 */
Type type_register_static(const TypeInfo *info);

/**
 * type_register:
 * @info: The #TypeInfo of the new type
 *
688
 * Unlike type_register_static(), this call does not require @info or its
689 690 691 692 693 694 695 696 697 698 699
 * string members to continue to exist after the call returns.
 *
 * Returns: 0 on failure, the new #Type on success.
 */
Type type_register(const TypeInfo *info);

/**
 * object_class_dynamic_cast_assert:
 * @klass: The #ObjectClass to attempt to cast.
 * @typename: The QOM typename of the class to cast to.
 *
700 701
 * See object_class_dynamic_cast() for a description of the parameters
 * of this function.  The only difference in behavior is that this function
702 703 704
 * asserts instead of returning #NULL on failure if QOM cast debugging is
 * enabled.  This function is not meant to be called directly, but only through
 * the wrapper macros OBJECT_CLASS_CHECK and INTERFACE_CHECK.
705 706
 */
ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
707 708 709
                                              const char *typename,
                                              const char *file, int line,
                                              const char *func);
710

711 712 713 714 715 716 717 718 719 720 721 722 723 724
/**
 * object_class_dynamic_cast:
 * @klass: The #ObjectClass to attempt to cast.
 * @typename: The QOM typename of the class to cast to.
 *
 * Returns: If @typename is a class, this function returns @klass if
 * @typename is a subtype of @klass, else returns #NULL.
 *
 * If @typename is an interface, this function returns the interface
 * definition for @klass if @klass implements it unambiguously; #NULL
 * is returned if @klass does not implement the interface or if multiple
 * classes or interfaces on the hierarchy leading to @klass implement
 * it.  (FIXME: perhaps this can be detected at type definition time?)
 */
725 726 727
ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
                                       const char *typename);

728 729 730 731 732 733 734 735
/**
 * object_class_get_parent:
 * @klass: The class to obtain the parent for.
 *
 * Returns: The parent for @klass or %NULL if none.
 */
ObjectClass *object_class_get_parent(ObjectClass *klass);

736 737 738 739 740 741 742 743
/**
 * object_class_get_name:
 * @klass: The class to obtain the QOM typename for.
 *
 * Returns: The QOM typename for @klass.
 */
const char *object_class_get_name(ObjectClass *klass);

744 745 746 747 748 749 750 751
/**
 * object_class_is_abstract:
 * @klass: The class to obtain the abstractness for.
 *
 * Returns: %true if @klass is abstract, %false otherwise.
 */
bool object_class_is_abstract(ObjectClass *klass);

752 753 754 755 756 757
/**
 * object_class_by_name:
 * @typename: The QOM typename to obtain the class for.
 *
 * Returns: The class for @typename or %NULL if not found.
 */
758 759 760
ObjectClass *object_class_by_name(const char *typename);

void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
761
                          const char *implements_type, bool include_abstract,
762
                          void *opaque);
763 764 765 766 767 768 769 770 771 772 773

/**
 * object_class_get_list:
 * @implements_type: The type to filter for, including its derivatives.
 * @include_abstract: Whether to include abstract classes.
 *
 * Returns: A singly-linked list of the classes in reverse hashtable order.
 */
GSList *object_class_get_list(const char *implements_type,
                              bool include_abstract);

774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810
/**
 * object_ref:
 * @obj: the object
 *
 * Increase the reference count of a object.  A object cannot be freed as long
 * as its reference count is greater than zero.
 */
void object_ref(Object *obj);

/**
 * qdef_unref:
 * @obj: the object
 *
 * Decrease the reference count of a object.  A object cannot be freed as long
 * as its reference count is greater than zero.
 */
void object_unref(Object *obj);

/**
 * object_property_add:
 * @obj: the object to add a property to
 * @name: the name of the property.  This can contain any character except for
 *  a forward slash.  In general, you should use hyphens '-' instead of
 *  underscores '_' when naming properties.
 * @type: the type name of the property.  This namespace is pretty loosely
 *   defined.  Sub namespaces are constructed by using a prefix and then
 *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
 *   'link' namespace would be 'link<virtio-net-pci>'.
 * @get: The getter to be called to read a property.  If this is NULL, then
 *   the property cannot be read.
 * @set: the setter to be called to write a property.  If this is NULL,
 *   then the property cannot be written.
 * @release: called when the property is removed from the object.  This is
 *   meant to allow a property to free its opaque upon object
 *   destruction.  This may be NULL.
 * @opaque: an opaque pointer to pass to the callbacks for the property
 * @errp: returns an error if this function fails
811 812 813
 *
 * Returns: The #ObjectProperty; this can be used to set the @resolve
 * callback for child and link properties.
814
 */
815 816 817 818 819 820
ObjectProperty *object_property_add(Object *obj, const char *name,
                                    const char *type,
                                    ObjectPropertyAccessor *get,
                                    ObjectPropertyAccessor *set,
                                    ObjectPropertyRelease *release,
                                    void *opaque, Error **errp);
821

822
void object_property_del(Object *obj, const char *name, Error **errp);
823

824 825 826 827
/**
 * object_property_find:
 * @obj: the object
 * @name: the name of the property
828
 * @errp: returns an error if this function fails
829 830 831
 *
 * Look up a property for an object and return its #ObjectProperty if found.
 */
832
ObjectProperty *object_property_find(Object *obj, const char *name,
833
                                     Error **errp);
834

835 836 837 838 839 840 841 842 843 844 845 846 847
void object_unparent(Object *obj);

/**
 * object_property_get:
 * @obj: the object
 * @v: the visitor that will receive the property value.  This should be an
 *   Output visitor and the data will be written with @name as the name.
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Reads a property from a object.
 */
void object_property_get(Object *obj, struct Visitor *v, const char *name,
848
                         Error **errp);
849

850 851 852 853 854 855 856 857 858
/**
 * object_property_set_str:
 * @value: the value to be written to the property
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Writes a string value to a property.
 */
void object_property_set_str(Object *obj, const char *value,
859
                             const char *name, Error **errp);
860 861 862 863 864 865 866 867 868 869 870 871

/**
 * object_property_get_str:
 * @obj: the object
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, converted to a C string, or NULL if
 * an error occurs (including when the property value is not a string).
 * The caller should free the string.
 */
char *object_property_get_str(Object *obj, const char *name,
872
                              Error **errp);
873

874 875 876 877 878 879 880 881 882
/**
 * object_property_set_link:
 * @value: the value to be written to the property
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Writes an object's canonical path to a property.
 */
void object_property_set_link(Object *obj, Object *value,
883
                              const char *name, Error **errp);
884 885 886 887 888 889 890 891 892 893 894 895

/**
 * object_property_get_link:
 * @obj: the object
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, resolved from a path to an Object,
 * or NULL if an error occurs (including when the property value is not a
 * string or not a valid object path).
 */
Object *object_property_get_link(Object *obj, const char *name,
896
                                 Error **errp);
897

898 899 900 901 902 903 904 905 906
/**
 * object_property_set_bool:
 * @value: the value to be written to the property
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Writes a bool value to a property.
 */
void object_property_set_bool(Object *obj, bool value,
907
                              const char *name, Error **errp);
908 909 910 911 912 913 914 915 916 917 918

/**
 * object_property_get_bool:
 * @obj: the object
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, converted to a boolean, or NULL if
 * an error occurs (including when the property value is not a bool).
 */
bool object_property_get_bool(Object *obj, const char *name,
919
                              Error **errp);
920 921 922 923 924 925 926 927 928 929

/**
 * object_property_set_int:
 * @value: the value to be written to the property
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Writes an integer value to a property.
 */
void object_property_set_int(Object *obj, int64_t value,
930
                             const char *name, Error **errp);
931 932 933 934 935 936 937 938 939 940 941

/**
 * object_property_get_int:
 * @obj: the object
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, converted to an integer, or NULL if
 * an error occurs (including when the property value is not an integer).
 */
int64_t object_property_get_int(Object *obj, const char *name,
942
                                Error **errp);
943

944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971
/**
 * object_property_get_enum:
 * @obj: the object
 * @name: the name of the property
 * @strings: strings corresponding to enums
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, converted to an integer, or
 * undefined if an error occurs (including when the property value is not
 * an enum).
 */
int object_property_get_enum(Object *obj, const char *name,
                             const char *strings[], Error **errp);

/**
 * object_property_get_uint16List:
 * @obj: the object
 * @name: the name of the property
 * @list: the returned int list
 * @errp: returns an error if this function fails
 *
 * Returns: the value of the property, converted to integers, or
 * undefined if an error occurs (including when the property value is not
 * an list of integers).
 */
void object_property_get_uint16List(Object *obj, const char *name,
                                    uint16List **list, Error **errp);

972 973 974 975 976 977 978 979 980 981 982 983
/**
 * object_property_set:
 * @obj: the object
 * @v: the visitor that will be used to write the property value.  This should
 *   be an Input visitor and the data will be first read with @name as the
 *   name and then written as the property value.
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Writes a property to a object.
 */
void object_property_set(Object *obj, struct Visitor *v, const char *name,
984
                         Error **errp);
985

986 987 988 989 990 991 992 993 994 995
/**
 * object_property_parse:
 * @obj: the object
 * @string: the string that will be used to parse the property value.
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Parses a string and writes the result into a property of an object.
 */
void object_property_parse(Object *obj, const char *string,
996
                           const char *name, Error **errp);
997 998 999 1000 1001

/**
 * object_property_print:
 * @obj: the object
 * @name: the name of the property
1002
 * @human: if true, print for human consumption
1003 1004 1005 1006 1007
 * @errp: returns an error if this function fails
 *
 * Returns a string representation of the value of the property.  The
 * caller shall free the string.
 */
1008
char *object_property_print(Object *obj, const char *name, bool human,
1009
                            Error **errp);
1010

1011
/**
1012
 * object_property_get_type:
1013 1014 1015 1016 1017 1018 1019
 * @obj: the object
 * @name: the name of the property
 * @errp: returns an error if this function fails
 *
 * Returns:  The type name of the property.
 */
const char *object_property_get_type(Object *obj, const char *name,
1020
                                     Error **errp);
1021 1022 1023 1024 1025 1026 1027 1028

/**
 * object_get_root:
 *
 * Returns: the root object of the composition tree
 */
Object *object_get_root(void);

1029 1030 1031 1032 1033 1034 1035 1036
/**
 * object_get_canonical_path_component:
 *
 * Returns: The final component in the object's canonical path.  The canonical
 * path is the path within the composition tree starting from the root.
 */
gchar *object_get_canonical_path_component(Object *obj);

1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062
/**
 * object_get_canonical_path:
 *
 * Returns: The canonical path for a object.  This is the path within the
 * composition tree starting from the root.
 */
gchar *object_get_canonical_path(Object *obj);

/**
 * object_resolve_path:
 * @path: the path to resolve
 * @ambiguous: returns true if the path resolution failed because of an
 *   ambiguous match
 *
 * There are two types of supported paths--absolute paths and partial paths.
 * 
 * Absolute paths are derived from the root object and can follow child<> or
 * link<> properties.  Since they can follow link<> properties, they can be
 * arbitrarily long.  Absolute paths look like absolute filenames and are
 * prefixed with a leading slash.
 * 
 * Partial paths look like relative filenames.  They do not begin with a
 * prefix.  The matching rules for partial paths are subtle but designed to make
 * specifying objects easy.  At each level of the composition tree, the partial
 * path is matched as an absolute path.  The first match is not returned.  At
 * least two matches are searched for.  A successful result is only returned if
1063 1064
 * only one match is found.  If more than one match is found, a flag is
 * returned to indicate that the match was ambiguous.
1065 1066 1067 1068 1069
 *
 * Returns: The matched object or NULL on path lookup failure.
 */
Object *object_resolve_path(const char *path, bool *ambiguous);

1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090
/**
 * object_resolve_path_type:
 * @path: the path to resolve
 * @typename: the type to look for.
 * @ambiguous: returns true if the path resolution failed because of an
 *   ambiguous match
 *
 * This is similar to object_resolve_path.  However, when looking for a
 * partial path only matches that implement the given type are considered.
 * This restricts the search and avoids spuriously flagging matches as
 * ambiguous.
 *
 * For both partial and absolute paths, the return value goes through
 * a dynamic cast to @typename.  This is important if either the link,
 * or the typename itself are of interface types.
 *
 * Returns: The matched object or NULL on path lookup failure.
 */
Object *object_resolve_path_type(const char *path, const char *typename,
                                 bool *ambiguous);

Paolo Bonzini's avatar
Paolo Bonzini committed
1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
/**
 * object_resolve_path_component:
 * @parent: the object in which to resolve the path
 * @part: the component to resolve.
 *
 * This is similar to object_resolve_path with an absolute path, but it
 * only resolves one element (@part) and takes the others from @parent.
 *
 * Returns: The resolved object or NULL on path lookup failure.
 */
1101
Object *object_resolve_path_component(Object *parent, const gchar *part);
Paolo Bonzini's avatar
Paolo Bonzini committed
1102

1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114
/**
 * object_property_add_child:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @child: the child object
 * @errp: if an error occurs, a pointer to an area to store the area
 *
 * Child properties form the composition tree.  All objects need to be a child
 * of another object.  Objects can only be a child of one object.
 *
 * There is no way for a child to determine what its parent is.  It is not
 * a bidirectional relationship.  This is by design.
1115 1116 1117 1118
 *
 * The value of a child property as a C string will be the child object's
 * canonical path. It can be retrieved using object_property_get_str().
 * The child object itself can be retrieved using object_property_get_link().
1119 1120
 */
void object_property_add_child(Object *obj, const char *name,
1121
                               Object *child, Error **errp);
1122

1123 1124 1125 1126 1127
typedef enum {
    /* Unref the link pointer when the property is deleted */
    OBJ_PROP_LINK_UNREF_ON_RELEASE = 0x1,
} ObjectPropertyLinkFlags;

1128 1129 1130 1131 1132 1133 1134 1135 1136 1137
/**
 * object_property_allow_set_link:
 *
 * The default implementation of the object_property_add_link() check()
 * callback function.  It allows the link property to be set and never returns
 * an error.
 */
void object_property_allow_set_link(Object *, const char *,
                                    Object *, Error **);

1138 1139 1140 1141 1142 1143
/**
 * object_property_add_link:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @type: the qobj type of the link
 * @child: a pointer to where the link object reference is stored
1144
 * @check: callback to veto setting or NULL if the property is read-only
1145
 * @flags: additional options for the link
1146 1147 1148 1149 1150 1151 1152
 * @errp: if an error occurs, a pointer to an area to store the area
 *
 * Links establish relationships between objects.  Links are unidirectional
 * although two links can be combined to form a bidirectional relationship
 * between objects.
 *
 * Links form the graph in the object model.
1153
 *
1154 1155 1156 1157 1158
 * The <code>@check()</code> callback is invoked when
 * object_property_set_link() is called and can raise an error to prevent the
 * link being set.  If <code>@check</code> is NULL, the property is read-only
 * and cannot be set.
 *
1159 1160 1161
 * Ownership of the pointer that @child points to is transferred to the
 * link property.  The reference count for <code>*@child</code> is
 * managed by the property from after the function returns till the
1162 1163 1164
 * property is deleted with object_property_del().  If the
 * <code>@flags</code> <code>OBJ_PROP_LINK_UNREF_ON_RELEASE</code> bit is set,
 * the reference count is decremented when the property is deleted.
1165 1166 1167
 */
void object_property_add_link(Object *obj, const char *name,
                              const char *type, Object **child,
1168 1169
                              void (*check)(Object *obj, const char *name,
                                            Object *val, Error **errp),
1170
                              ObjectPropertyLinkFlags flags,
1171
                              Error **errp);
1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185

/**
 * object_property_add_str:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @get: the getter or NULL if the property is write-only.  This function must
 *   return a string to be freed by g_free().
 * @set: the setter or NULL if the property is read-only
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add a string property using getters/setters.  This function will add a
 * property of type 'string'.
 */
void object_property_add_str(Object *obj, const char *name,
1186 1187 1188
                             char *(*get)(Object *, Error **),
                             void (*set)(Object *, const char *, Error **),
                             Error **errp);
1189

1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201
/**
 * object_property_add_bool:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @get: the getter or NULL if the property is write-only.
 * @set: the setter or NULL if the property is read-only
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add a bool property using getters/setters.  This function will add a
 * property of type 'bool'.
 */
void object_property_add_bool(Object *obj, const char *name,
1202 1203 1204
                              bool (*get)(Object *, Error **),
                              void (*set)(Object *, bool, Error **),
                              Error **errp);
1205

1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257
/**
 * object_property_add_uint8_ptr:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @v: pointer to value
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add an integer property in memory.  This function will add a
 * property of type 'uint8'.
 */
void object_property_add_uint8_ptr(Object *obj, const char *name,
                                   const uint8_t *v, Error **errp);

/**
 * object_property_add_uint16_ptr:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @v: pointer to value
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add an integer property in memory.  This function will add a
 * property of type 'uint16'.
 */
void object_property_add_uint16_ptr(Object *obj, const char *name,
                                    const uint16_t *v, Error **errp);

/**
 * object_property_add_uint32_ptr:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @v: pointer to value
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add an integer property in memory.  This function will add a
 * property of type 'uint32'.
 */
void object_property_add_uint32_ptr(Object *obj, const char *name,
                                    const uint32_t *v, Error **errp);

/**
 * object_property_add_uint64_ptr:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @v: pointer to value
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add an integer property in memory.  This function will add a
 * property of type 'uint64'.
 */
void object_property_add_uint64_ptr(Object *obj, const char *name,
                                    const uint64_t *v, Error **Errp);

1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277
/**
 * object_property_add_alias:
 * @obj: the object to add a property to
 * @name: the name of the property
 * @target_obj: the object to forward property access to
 * @target_name: the name of the property on the forwarded object
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Add an alias for a property on an object.  This function will add a property
 * of the same type as the forwarded property.
 *
 * The caller must ensure that <code>@target_obj</code> stays alive as long as
 * this property exists.  In the case of a child object or an alias on the same
 * object this will be the case.  For aliases to other objects the caller is
 * responsible for taking a reference.
 */
void object_property_add_alias(Object *obj, const char *name,
                               Object *target_obj, const char *target_name,
                               Error **errp);

1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290
/**
 * object_property_set_description:
 * @obj: the object owning the property
 * @name: the name of the property
 * @description: the description of the property on the object
 * @errp: if an error occurs, a pointer to an area to store the error
 *
 * Set an object property's description.
 *
 */
void object_property_set_description(Object *obj, const char *name,
                                     const char *description, Error **errp);

1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304
/**
 * object_child_foreach:
 * @obj: the object whose children will be navigated
 * @fn: the iterator function to be called
 * @opaque: an opaque value that will be passed to the iterator
 *
 * Call @fn passing each child of @obj and @opaque to it, until @fn returns
 * non-zero.
 *
 * Returns: The last value returned by @fn, or 0 if there is no child.
 */
int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque),
                         void *opaque);

Paolo Bonzini's avatar
Paolo Bonzini committed
1305 1306
/**
 * container_get:
1307
 * @root: root of the #path, e.g., object_get_root()
Paolo Bonzini's avatar
Paolo Bonzini committed
1308 1309 1310 1311 1312 1313 1314
 * @path: path to the container
 *
 * Return a container object whose path is @path.  Create more containers
 * along the path if necessary.
 *
 * Returns: the container object.
 */
1315
Object *container_get(Object *root, const char *path);
Paolo Bonzini's avatar
Paolo Bonzini committed
1316 1317


1318
#endif