xref: /openbmc/qemu/include/qom/object.h (revision 1c8f85d9)
1 /*
2  * QEMU Object Model
3  *
4  * Copyright IBM, Corp. 2011
5  *
6  * Authors:
7  *  Anthony Liguori   <aliguori@us.ibm.com>
8  *
9  * This work is licensed under the terms of the GNU GPL, version 2 or later.
10  * See the COPYING file in the top-level directory.
11  *
12  */
13 
14 #ifndef QEMU_OBJECT_H
15 #define QEMU_OBJECT_H
16 
17 #include "qapi/qapi-builtin-types.h"
18 #include "qemu/module.h"
19 
20 struct TypeImpl;
21 typedef struct TypeImpl *Type;
22 
23 typedef struct Object Object;
24 
25 typedef struct TypeInfo TypeInfo;
26 
27 typedef struct InterfaceClass InterfaceClass;
28 typedef struct InterfaceInfo InterfaceInfo;
29 
30 #define TYPE_OBJECT "object"
31 
32 /**
33  * SECTION:object.h
34  * @title:Base Object Type System
35  * @short_description: interfaces for creating new types and objects
36  *
37  * The QEMU Object Model provides a framework for registering user creatable
38  * types and instantiating objects from those types.  QOM provides the following
39  * features:
40  *
41  *  - System for dynamically registering types
42  *  - Support for single-inheritance of types
43  *  - Multiple inheritance of stateless interfaces
44  *
45  * <example>
46  *   <title>Creating a minimal type</title>
47  *   <programlisting>
48  * #include "qdev.h"
49  *
50  * #define TYPE_MY_DEVICE "my-device"
51  *
52  * // No new virtual functions: we can reuse the typedef for the
53  * // superclass.
54  * typedef DeviceClass MyDeviceClass;
55  * typedef struct MyDevice
56  * {
57  *     DeviceState parent;
58  *
59  *     int reg0, reg1, reg2;
60  * } MyDevice;
61  *
62  * static const TypeInfo my_device_info = {
63  *     .name = TYPE_MY_DEVICE,
64  *     .parent = TYPE_DEVICE,
65  *     .instance_size = sizeof(MyDevice),
66  * };
67  *
68  * static void my_device_register_types(void)
69  * {
70  *     type_register_static(&my_device_info);
71  * }
72  *
73  * type_init(my_device_register_types)
74  *   </programlisting>
75  * </example>
76  *
77  * In the above example, we create a simple type that is described by #TypeInfo.
78  * #TypeInfo describes information about the type including what it inherits
79  * from, the instance and class size, and constructor/destructor hooks.
80  *
81  * Alternatively several static types could be registered using helper macro
82  * DEFINE_TYPES()
83  *
84  * <example>
85  *   <programlisting>
86  * static const TypeInfo device_types_info[] = {
87  *     {
88  *         .name = TYPE_MY_DEVICE_A,
89  *         .parent = TYPE_DEVICE,
90  *         .instance_size = sizeof(MyDeviceA),
91  *     },
92  *     {
93  *         .name = TYPE_MY_DEVICE_B,
94  *         .parent = TYPE_DEVICE,
95  *         .instance_size = sizeof(MyDeviceB),
96  *     },
97  * };
98  *
99  * DEFINE_TYPES(device_types_info)
100  *   </programlisting>
101  * </example>
102  *
103  * Every type has an #ObjectClass associated with it.  #ObjectClass derivatives
104  * are instantiated dynamically but there is only ever one instance for any
105  * given type.  The #ObjectClass typically holds a table of function pointers
106  * for the virtual methods implemented by this type.
107  *
108  * Using object_new(), a new #Object derivative will be instantiated.  You can
109  * cast an #Object to a subclass (or base-class) type using
110  * object_dynamic_cast().  You typically want to define macro wrappers around
111  * OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a
112  * specific type:
113  *
114  * <example>
115  *   <title>Typecasting macros</title>
116  *   <programlisting>
117  *    #define MY_DEVICE_GET_CLASS(obj) \
118  *       OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
119  *    #define MY_DEVICE_CLASS(klass) \
120  *       OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
121  *    #define MY_DEVICE(obj) \
122  *       OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
123  *   </programlisting>
124  * </example>
125  *
126  * # Class Initialization #
127  *
128  * Before an object is initialized, the class for the object must be
129  * initialized.  There is only one class object for all instance objects
130  * that is created lazily.
131  *
132  * Classes are initialized by first initializing any parent classes (if
133  * necessary).  After the parent class object has initialized, it will be
134  * copied into the current class object and any additional storage in the
135  * class object is zero filled.
136  *
137  * The effect of this is that classes automatically inherit any virtual
138  * function pointers that the parent class has already initialized.  All
139  * other fields will be zero filled.
140  *
141  * Once all of the parent classes have been initialized, #TypeInfo::class_init
142  * is called to let the class being instantiated provide default initialize for
143  * its virtual functions.  Here is how the above example might be modified
144  * to introduce an overridden virtual function:
145  *
146  * <example>
147  *   <title>Overriding a virtual function</title>
148  *   <programlisting>
149  * #include "qdev.h"
150  *
151  * void my_device_class_init(ObjectClass *klass, void *class_data)
152  * {
153  *     DeviceClass *dc = DEVICE_CLASS(klass);
154  *     dc->reset = my_device_reset;
155  * }
156  *
157  * static const TypeInfo my_device_info = {
158  *     .name = TYPE_MY_DEVICE,
159  *     .parent = TYPE_DEVICE,
160  *     .instance_size = sizeof(MyDevice),
161  *     .class_init = my_device_class_init,
162  * };
163  *   </programlisting>
164  * </example>
165  *
166  * Introducing new virtual methods requires a class to define its own
167  * struct and to add a .class_size member to the #TypeInfo.  Each method
168  * will also have a wrapper function to call it easily:
169  *
170  * <example>
171  *   <title>Defining an abstract class</title>
172  *   <programlisting>
173  * #include "qdev.h"
174  *
175  * typedef struct MyDeviceClass
176  * {
177  *     DeviceClass parent;
178  *
179  *     void (*frobnicate) (MyDevice *obj);
180  * } MyDeviceClass;
181  *
182  * static const TypeInfo my_device_info = {
183  *     .name = TYPE_MY_DEVICE,
184  *     .parent = TYPE_DEVICE,
185  *     .instance_size = sizeof(MyDevice),
186  *     .abstract = true, // or set a default in my_device_class_init
187  *     .class_size = sizeof(MyDeviceClass),
188  * };
189  *
190  * void my_device_frobnicate(MyDevice *obj)
191  * {
192  *     MyDeviceClass *klass = MY_DEVICE_GET_CLASS(obj);
193  *
194  *     klass->frobnicate(obj);
195  * }
196  *   </programlisting>
197  * </example>
198  *
199  * # Interfaces #
200  *
201  * Interfaces allow a limited form of multiple inheritance.  Instances are
202  * similar to normal types except for the fact that are only defined by
203  * their classes and never carry any state.  As a consequence, a pointer to
204  * an interface instance should always be of incomplete type in order to be
205  * sure it cannot be dereferenced.  That is, you should define the
206  * 'typedef struct SomethingIf SomethingIf' so that you can pass around
207  * 'SomethingIf *si' arguments, but not define a 'struct SomethingIf { ... }'.
208  * The only things you can validly do with a 'SomethingIf *' are to pass it as
209  * an argument to a method on its corresponding SomethingIfClass, or to
210  * dynamically cast it to an object that implements the interface.
211  *
212  * # Methods #
213  *
214  * A <emphasis>method</emphasis> is a function within the namespace scope of
215  * a class. It usually operates on the object instance by passing it as a
216  * strongly-typed first argument.
217  * If it does not operate on an object instance, it is dubbed
218  * <emphasis>class method</emphasis>.
219  *
220  * Methods cannot be overloaded. That is, the #ObjectClass and method name
221  * uniquely identity the function to be called; the signature does not vary
222  * except for trailing varargs.
223  *
224  * Methods are always <emphasis>virtual</emphasis>. Overriding a method in
225  * #TypeInfo.class_init of a subclass leads to any user of the class obtained
226  * via OBJECT_GET_CLASS() accessing the overridden function.
227  * The original function is not automatically invoked. It is the responsibility
228  * of the overriding class to determine whether and when to invoke the method
229  * being overridden.
230  *
231  * To invoke the method being overridden, the preferred solution is to store
232  * the original value in the overriding class before overriding the method.
233  * This corresponds to |[ {super,base}.method(...) ]| in Java and C#
234  * respectively; this frees the overriding class from hardcoding its parent
235  * class, which someone might choose to change at some point.
236  *
237  * <example>
238  *   <title>Overriding a virtual method</title>
239  *   <programlisting>
240  * typedef struct MyState MyState;
241  *
242  * typedef void (*MyDoSomething)(MyState *obj);
243  *
244  * typedef struct MyClass {
245  *     ObjectClass parent_class;
246  *
247  *     MyDoSomething do_something;
248  * } MyClass;
249  *
250  * static void my_do_something(MyState *obj)
251  * {
252  *     // do something
253  * }
254  *
255  * static void my_class_init(ObjectClass *oc, void *data)
256  * {
257  *     MyClass *mc = MY_CLASS(oc);
258  *
259  *     mc->do_something = my_do_something;
260  * }
261  *
262  * static const TypeInfo my_type_info = {
263  *     .name = TYPE_MY,
264  *     .parent = TYPE_OBJECT,
265  *     .instance_size = sizeof(MyState),
266  *     .class_size = sizeof(MyClass),
267  *     .class_init = my_class_init,
268  * };
269  *
270  * typedef struct DerivedClass {
271  *     MyClass parent_class;
272  *
273  *     MyDoSomething parent_do_something;
274  * } DerivedClass;
275  *
276  * static void derived_do_something(MyState *obj)
277  * {
278  *     DerivedClass *dc = DERIVED_GET_CLASS(obj);
279  *
280  *     // do something here
281  *     dc->parent_do_something(obj);
282  *     // do something else here
283  * }
284  *
285  * static void derived_class_init(ObjectClass *oc, void *data)
286  * {
287  *     MyClass *mc = MY_CLASS(oc);
288  *     DerivedClass *dc = DERIVED_CLASS(oc);
289  *
290  *     dc->parent_do_something = mc->do_something;
291  *     mc->do_something = derived_do_something;
292  * }
293  *
294  * static const TypeInfo derived_type_info = {
295  *     .name = TYPE_DERIVED,
296  *     .parent = TYPE_MY,
297  *     .class_size = sizeof(DerivedClass),
298  *     .class_init = derived_class_init,
299  * };
300  *   </programlisting>
301  * </example>
302  *
303  * Alternatively, object_class_by_name() can be used to obtain the class and
304  * its non-overridden methods for a specific type. This would correspond to
305  * |[ MyClass::method(...) ]| in C++.
306  *
307  * The first example of such a QOM method was #CPUClass.reset,
308  * another example is #DeviceClass.realize.
309  */
310 
311 
312 /**
313  * ObjectPropertyAccessor:
314  * @obj: the object that owns the property
315  * @v: the visitor that contains the property data
316  * @name: the name of the property
317  * @opaque: the object property opaque
318  * @errp: a pointer to an Error that is filled if getting/setting fails.
319  *
320  * Called when trying to get/set a property.
321  */
322 typedef void (ObjectPropertyAccessor)(Object *obj,
323                                       Visitor *v,
324                                       const char *name,
325                                       void *opaque,
326                                       Error **errp);
327 
328 /**
329  * ObjectPropertyResolve:
330  * @obj: the object that owns the property
331  * @opaque: the opaque registered with the property
332  * @part: the name of the property
333  *
334  * Resolves the #Object corresponding to property @part.
335  *
336  * The returned object can also be used as a starting point
337  * to resolve a relative path starting with "@part".
338  *
339  * Returns: If @path is the path that led to @obj, the function
340  * returns the #Object corresponding to "@path/@part".
341  * If "@path/@part" is not a valid object path, it returns #NULL.
342  */
343 typedef Object *(ObjectPropertyResolve)(Object *obj,
344                                         void *opaque,
345                                         const char *part);
346 
347 /**
348  * ObjectPropertyRelease:
349  * @obj: the object that owns the property
350  * @name: the name of the property
351  * @opaque: the opaque registered with the property
352  *
353  * Called when a property is removed from a object.
354  */
355 typedef void (ObjectPropertyRelease)(Object *obj,
356                                      const char *name,
357                                      void *opaque);
358 
359 typedef struct ObjectProperty
360 {
361     gchar *name;
362     gchar *type;
363     gchar *description;
364     ObjectPropertyAccessor *get;
365     ObjectPropertyAccessor *set;
366     ObjectPropertyResolve *resolve;
367     ObjectPropertyRelease *release;
368     void *opaque;
369 } ObjectProperty;
370 
371 /**
372  * ObjectUnparent:
373  * @obj: the object that is being removed from the composition tree
374  *
375  * Called when an object is being removed from the QOM composition tree.
376  * The function should remove any backlinks from children objects to @obj.
377  */
378 typedef void (ObjectUnparent)(Object *obj);
379 
380 /**
381  * ObjectFree:
382  * @obj: the object being freed
383  *
384  * Called when an object's last reference is removed.
385  */
386 typedef void (ObjectFree)(void *obj);
387 
388 #define OBJECT_CLASS_CAST_CACHE 4
389 
390 /**
391  * ObjectClass:
392  *
393  * The base for all classes.  The only thing that #ObjectClass contains is an
394  * integer type handle.
395  */
396 struct ObjectClass
397 {
398     /*< private >*/
399     Type type;
400     GSList *interfaces;
401 
402     const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
403     const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
404 
405     ObjectUnparent *unparent;
406 
407     GHashTable *properties;
408 };
409 
410 /**
411  * Object:
412  *
413  * The base for all objects.  The first member of this object is a pointer to
414  * a #ObjectClass.  Since C guarantees that the first member of a structure
415  * always begins at byte 0 of that structure, as long as any sub-object places
416  * its parent as the first member, we can cast directly to a #Object.
417  *
418  * As a result, #Object contains a reference to the objects type as its
419  * first member.  This allows identification of the real type of the object at
420  * run time.
421  */
422 struct Object
423 {
424     /*< private >*/
425     ObjectClass *class;
426     ObjectFree *free;
427     GHashTable *properties;
428     uint32_t ref;
429     Object *parent;
430 };
431 
432 /**
433  * TypeInfo:
434  * @name: The name of the type.
435  * @parent: The name of the parent type.
436  * @instance_size: The size of the object (derivative of #Object).  If
437  *   @instance_size is 0, then the size of the object will be the size of the
438  *   parent object.
439  * @instance_init: This function is called to initialize an object.  The parent
440  *   class will have already been initialized so the type is only responsible
441  *   for initializing its own members.
442  * @instance_post_init: This function is called to finish initialization of
443  *   an object, after all @instance_init functions were called.
444  * @instance_finalize: This function is called during object destruction.  This
445  *   is called before the parent @instance_finalize function has been called.
446  *   An object should only free the members that are unique to its type in this
447  *   function.
448  * @abstract: If this field is true, then the class is considered abstract and
449  *   cannot be directly instantiated.
450  * @class_size: The size of the class object (derivative of #ObjectClass)
451  *   for this object.  If @class_size is 0, then the size of the class will be
452  *   assumed to be the size of the parent class.  This allows a type to avoid
453  *   implementing an explicit class type if they are not adding additional
454  *   virtual functions.
455  * @class_init: This function is called after all parent class initialization
456  *   has occurred to allow a class to set its default virtual method pointers.
457  *   This is also the function to use to override virtual methods from a parent
458  *   class.
459  * @class_base_init: This function is called for all base classes after all
460  *   parent class initialization has occurred, but before the class itself
461  *   is initialized.  This is the function to use to undo the effects of
462  *   memcpy from the parent class to the descendants.
463  * @class_data: Data to pass to the @class_init,
464  *   @class_base_init. This can be useful when building dynamic
465  *   classes.
466  * @interfaces: The list of interfaces associated with this type.  This
467  *   should point to a static array that's terminated with a zero filled
468  *   element.
469  */
470 struct TypeInfo
471 {
472     const char *name;
473     const char *parent;
474 
475     size_t instance_size;
476     void (*instance_init)(Object *obj);
477     void (*instance_post_init)(Object *obj);
478     void (*instance_finalize)(Object *obj);
479 
480     bool abstract;
481     size_t class_size;
482 
483     void (*class_init)(ObjectClass *klass, void *data);
484     void (*class_base_init)(ObjectClass *klass, void *data);
485     void *class_data;
486 
487     InterfaceInfo *interfaces;
488 };
489 
490 /**
491  * OBJECT:
492  * @obj: A derivative of #Object
493  *
494  * Converts an object to a #Object.  Since all objects are #Objects,
495  * this function will always succeed.
496  */
497 #define OBJECT(obj) \
498     ((Object *)(obj))
499 
500 /**
501  * OBJECT_CLASS:
502  * @class: A derivative of #ObjectClass.
503  *
504  * Converts a class to an #ObjectClass.  Since all objects are #Objects,
505  * this function will always succeed.
506  */
507 #define OBJECT_CLASS(class) \
508     ((ObjectClass *)(class))
509 
510 /**
511  * OBJECT_CHECK:
512  * @type: The C type to use for the return value.
513  * @obj: A derivative of @type to cast.
514  * @name: The QOM typename of @type
515  *
516  * A type safe version of @object_dynamic_cast_assert.  Typically each class
517  * will define a macro based on this type to perform type safe dynamic_casts to
518  * this object type.
519  *
520  * If an invalid object is passed to this function, a run time assert will be
521  * generated.
522  */
523 #define OBJECT_CHECK(type, obj, name) \
524     ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
525                                         __FILE__, __LINE__, __func__))
526 
527 /**
528  * OBJECT_CLASS_CHECK:
529  * @class_type: The C type to use for the return value.
530  * @class: A derivative class of @class_type to cast.
531  * @name: the QOM typename of @class_type.
532  *
533  * A type safe version of @object_class_dynamic_cast_assert.  This macro is
534  * typically wrapped by each type to perform type safe casts of a class to a
535  * specific class type.
536  */
537 #define OBJECT_CLASS_CHECK(class_type, class, name) \
538     ((class_type *)object_class_dynamic_cast_assert(OBJECT_CLASS(class), (name), \
539                                                __FILE__, __LINE__, __func__))
540 
541 /**
542  * OBJECT_GET_CLASS:
543  * @class: The C type to use for the return value.
544  * @obj: The object to obtain the class for.
545  * @name: The QOM typename of @obj.
546  *
547  * This function will return a specific class for a given object.  Its generally
548  * used by each type to provide a type safe macro to get a specific class type
549  * from an object.
550  */
551 #define OBJECT_GET_CLASS(class, obj, name) \
552     OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)
553 
554 /**
555  * InterfaceInfo:
556  * @type: The name of the interface.
557  *
558  * The information associated with an interface.
559  */
560 struct InterfaceInfo {
561     const char *type;
562 };
563 
564 /**
565  * InterfaceClass:
566  * @parent_class: the base class
567  *
568  * The class for all interfaces.  Subclasses of this class should only add
569  * virtual methods.
570  */
571 struct InterfaceClass
572 {
573     ObjectClass parent_class;
574     /*< private >*/
575     ObjectClass *concrete_class;
576     Type interface_type;
577 };
578 
579 #define TYPE_INTERFACE "interface"
580 
581 /**
582  * INTERFACE_CLASS:
583  * @klass: class to cast from
584  * Returns: An #InterfaceClass or raise an error if cast is invalid
585  */
586 #define INTERFACE_CLASS(klass) \
587     OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE)
588 
589 /**
590  * INTERFACE_CHECK:
591  * @interface: the type to return
592  * @obj: the object to convert to an interface
593  * @name: the interface type name
594  *
595  * Returns: @obj casted to @interface if cast is valid, otherwise raise error.
596  */
597 #define INTERFACE_CHECK(interface, obj, name) \
598     ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
599                                              __FILE__, __LINE__, __func__))
600 
601 /**
602  * object_new_with_class:
603  * @klass: The class to instantiate.
604  *
605  * This function will initialize a new object using heap allocated memory.
606  * The returned object has a reference count of 1, and will be freed when
607  * the last reference is dropped.
608  *
609  * Returns: The newly allocated and instantiated object.
610  */
611 Object *object_new_with_class(ObjectClass *klass);
612 
613 /**
614  * object_new:
615  * @typename: The name of the type of the object to instantiate.
616  *
617  * This function will initialize a new object using heap allocated memory.
618  * The returned object has a reference count of 1, and will be freed when
619  * the last reference is dropped.
620  *
621  * Returns: The newly allocated and instantiated object.
622  */
623 Object *object_new(const char *typename);
624 
625 /**
626  * object_new_with_props:
627  * @typename:  The name of the type of the object to instantiate.
628  * @parent: the parent object
629  * @id: The unique ID of the object
630  * @errp: pointer to error object
631  * @...: list of property names and values
632  *
633  * This function will initialize a new object using heap allocated memory.
634  * The returned object has a reference count of 1, and will be freed when
635  * the last reference is dropped.
636  *
637  * The @id parameter will be used when registering the object as a
638  * child of @parent in the composition tree.
639  *
640  * The variadic parameters are a list of pairs of (propname, propvalue)
641  * strings. The propname of %NULL indicates the end of the property
642  * list. If the object implements the user creatable interface, the
643  * object will be marked complete once all the properties have been
644  * processed.
645  *
646  * <example>
647  *   <title>Creating an object with properties</title>
648  *   <programlisting>
649  *   Error *err = NULL;
650  *   Object *obj;
651  *
652  *   obj = object_new_with_props(TYPE_MEMORY_BACKEND_FILE,
653  *                               object_get_objects_root(),
654  *                               "hostmem0",
655  *                               &err,
656  *                               "share", "yes",
657  *                               "mem-path", "/dev/shm/somefile",
658  *                               "prealloc", "yes",
659  *                               "size", "1048576",
660  *                               NULL);
661  *
662  *   if (!obj) {
663  *     g_printerr("Cannot create memory backend: %s\n",
664  *                error_get_pretty(err));
665  *   }
666  *   </programlisting>
667  * </example>
668  *
669  * The returned object will have one stable reference maintained
670  * for as long as it is present in the object hierarchy.
671  *
672  * Returns: The newly allocated, instantiated & initialized object.
673  */
674 Object *object_new_with_props(const char *typename,
675                               Object *parent,
676                               const char *id,
677                               Error **errp,
678                               ...) QEMU_SENTINEL;
679 
680 /**
681  * object_new_with_propv:
682  * @typename:  The name of the type of the object to instantiate.
683  * @parent: the parent object
684  * @id: The unique ID of the object
685  * @errp: pointer to error object
686  * @vargs: list of property names and values
687  *
688  * See object_new_with_props() for documentation.
689  */
690 Object *object_new_with_propv(const char *typename,
691                               Object *parent,
692                               const char *id,
693                               Error **errp,
694                               va_list vargs);
695 
696 void object_apply_global_props(Object *obj, const GPtrArray *props,
697                                Error **errp);
698 void object_set_machine_compat_props(GPtrArray *compat_props);
699 void object_set_accelerator_compat_props(GPtrArray *compat_props);
700 void object_register_sugar_prop(const char *driver, const char *prop, const char *value);
701 void object_apply_compat_props(Object *obj);
702 
703 /**
704  * object_set_props:
705  * @obj: the object instance to set properties on
706  * @errp: pointer to error object
707  * @...: list of property names and values
708  *
709  * This function will set a list of properties on an existing object
710  * instance.
711  *
712  * The variadic parameters are a list of pairs of (propname, propvalue)
713  * strings. The propname of %NULL indicates the end of the property
714  * list.
715  *
716  * <example>
717  *   <title>Update an object's properties</title>
718  *   <programlisting>
719  *   Error *err = NULL;
720  *   Object *obj = ...get / create object...;
721  *
722  *   obj = object_set_props(obj,
723  *                          &err,
724  *                          "share", "yes",
725  *                          "mem-path", "/dev/shm/somefile",
726  *                          "prealloc", "yes",
727  *                          "size", "1048576",
728  *                          NULL);
729  *
730  *   if (!obj) {
731  *     g_printerr("Cannot set properties: %s\n",
732  *                error_get_pretty(err));
733  *   }
734  *   </programlisting>
735  * </example>
736  *
737  * The returned object will have one stable reference maintained
738  * for as long as it is present in the object hierarchy.
739  *
740  * Returns: -1 on error, 0 on success
741  */
742 int object_set_props(Object *obj,
743                      Error **errp,
744                      ...) QEMU_SENTINEL;
745 
746 /**
747  * object_set_propv:
748  * @obj: the object instance to set properties on
749  * @errp: pointer to error object
750  * @vargs: list of property names and values
751  *
752  * See object_set_props() for documentation.
753  *
754  * Returns: -1 on error, 0 on success
755  */
756 int object_set_propv(Object *obj,
757                      Error **errp,
758                      va_list vargs);
759 
760 /**
761  * object_initialize:
762  * @obj: A pointer to the memory to be used for the object.
763  * @size: The maximum size available at @obj for the object.
764  * @typename: The name of the type of the object to instantiate.
765  *
766  * This function will initialize an object.  The memory for the object should
767  * have already been allocated.  The returned object has a reference count of 1,
768  * and will be finalized when the last reference is dropped.
769  */
770 void object_initialize(void *obj, size_t size, const char *typename);
771 
772 /**
773  * object_initialize_child:
774  * @parentobj: The parent object to add a property to
775  * @propname: The name of the property
776  * @childobj: A pointer to the memory to be used for the object.
777  * @size: The maximum size available at @childobj for the object.
778  * @type: The name of the type of the object to instantiate.
779  * @errp: If an error occurs, a pointer to an area to store the error
780  * @...: list of property names and values
781  *
782  * This function will initialize an object. The memory for the object should
783  * have already been allocated. The object will then be added as child property
784  * to a parent with object_property_add_child() function. The returned object
785  * has a reference count of 1 (for the "child<...>" property from the parent),
786  * so the object will be finalized automatically when the parent gets removed.
787  *
788  * The variadic parameters are a list of pairs of (propname, propvalue)
789  * strings. The propname of %NULL indicates the end of the property list.
790  * If the object implements the user creatable interface, the object will
791  * be marked complete once all the properties have been processed.
792  */
793 void object_initialize_child(Object *parentobj, const char *propname,
794                              void *childobj, size_t size, const char *type,
795                              Error **errp, ...) QEMU_SENTINEL;
796 
797 /**
798  * object_initialize_childv:
799  * @parentobj: The parent object to add a property to
800  * @propname: The name of the property
801  * @childobj: A pointer to the memory to be used for the object.
802  * @size: The maximum size available at @childobj for the object.
803  * @type: The name of the type of the object to instantiate.
804  * @errp: If an error occurs, a pointer to an area to store the error
805  * @vargs: list of property names and values
806  *
807  * See object_initialize_child() for documentation.
808  */
809 void object_initialize_childv(Object *parentobj, const char *propname,
810                               void *childobj, size_t size, const char *type,
811                               Error **errp, va_list vargs);
812 
813 /**
814  * object_dynamic_cast:
815  * @obj: The object to cast.
816  * @typename: The @typename to cast to.
817  *
818  * This function will determine if @obj is-a @typename.  @obj can refer to an
819  * object or an interface associated with an object.
820  *
821  * Returns: This function returns @obj on success or #NULL on failure.
822  */
823 Object *object_dynamic_cast(Object *obj, const char *typename);
824 
825 /**
826  * object_dynamic_cast_assert:
827  *
828  * See object_dynamic_cast() for a description of the parameters of this
829  * function.  The only difference in behavior is that this function asserts
830  * instead of returning #NULL on failure if QOM cast debugging is enabled.
831  * This function is not meant to be called directly, but only through
832  * the wrapper macro OBJECT_CHECK.
833  */
834 Object *object_dynamic_cast_assert(Object *obj, const char *typename,
835                                    const char *file, int line, const char *func);
836 
837 /**
838  * object_get_class:
839  * @obj: A derivative of #Object
840  *
841  * Returns: The #ObjectClass of the type associated with @obj.
842  */
843 ObjectClass *object_get_class(Object *obj);
844 
845 /**
846  * object_get_typename:
847  * @obj: A derivative of #Object.
848  *
849  * Returns: The QOM typename of @obj.
850  */
851 const char *object_get_typename(const Object *obj);
852 
853 /**
854  * type_register_static:
855  * @info: The #TypeInfo of the new type.
856  *
857  * @info and all of the strings it points to should exist for the life time
858  * that the type is registered.
859  *
860  * Returns: the new #Type.
861  */
862 Type type_register_static(const TypeInfo *info);
863 
864 /**
865  * type_register:
866  * @info: The #TypeInfo of the new type
867  *
868  * Unlike type_register_static(), this call does not require @info or its
869  * string members to continue to exist after the call returns.
870  *
871  * Returns: the new #Type.
872  */
873 Type type_register(const TypeInfo *info);
874 
875 /**
876  * type_register_static_array:
877  * @infos: The array of the new type #TypeInfo structures.
878  * @nr_infos: number of entries in @infos
879  *
880  * @infos and all of the strings it points to should exist for the life time
881  * that the type is registered.
882  */
883 void type_register_static_array(const TypeInfo *infos, int nr_infos);
884 
885 /**
886  * DEFINE_TYPES:
887  * @type_array: The array containing #TypeInfo structures to register
888  *
889  * @type_array should be static constant that exists for the life time
890  * that the type is registered.
891  */
892 #define DEFINE_TYPES(type_array)                                            \
893 static void do_qemu_init_ ## type_array(void)                               \
894 {                                                                           \
895     type_register_static_array(type_array, ARRAY_SIZE(type_array));         \
896 }                                                                           \
897 type_init(do_qemu_init_ ## type_array)
898 
899 /**
900  * object_class_dynamic_cast_assert:
901  * @klass: The #ObjectClass to attempt to cast.
902  * @typename: The QOM typename of the class to cast to.
903  *
904  * See object_class_dynamic_cast() for a description of the parameters
905  * of this function.  The only difference in behavior is that this function
906  * asserts instead of returning #NULL on failure if QOM cast debugging is
907  * enabled.  This function is not meant to be called directly, but only through
908  * the wrapper macros OBJECT_CLASS_CHECK and INTERFACE_CHECK.
909  */
910 ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
911                                               const char *typename,
912                                               const char *file, int line,
913                                               const char *func);
914 
915 /**
916  * object_class_dynamic_cast:
917  * @klass: The #ObjectClass to attempt to cast.
918  * @typename: The QOM typename of the class to cast to.
919  *
920  * Returns: If @typename is a class, this function returns @klass if
921  * @typename is a subtype of @klass, else returns #NULL.
922  *
923  * If @typename is an interface, this function returns the interface
924  * definition for @klass if @klass implements it unambiguously; #NULL
925  * is returned if @klass does not implement the interface or if multiple
926  * classes or interfaces on the hierarchy leading to @klass implement
927  * it.  (FIXME: perhaps this can be detected at type definition time?)
928  */
929 ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
930                                        const char *typename);
931 
932 /**
933  * object_class_get_parent:
934  * @klass: The class to obtain the parent for.
935  *
936  * Returns: The parent for @klass or %NULL if none.
937  */
938 ObjectClass *object_class_get_parent(ObjectClass *klass);
939 
940 /**
941  * object_class_get_name:
942  * @klass: The class to obtain the QOM typename for.
943  *
944  * Returns: The QOM typename for @klass.
945  */
946 const char *object_class_get_name(ObjectClass *klass);
947 
948 /**
949  * object_class_is_abstract:
950  * @klass: The class to obtain the abstractness for.
951  *
952  * Returns: %true if @klass is abstract, %false otherwise.
953  */
954 bool object_class_is_abstract(ObjectClass *klass);
955 
956 /**
957  * object_class_by_name:
958  * @typename: The QOM typename to obtain the class for.
959  *
960  * Returns: The class for @typename or %NULL if not found.
961  */
962 ObjectClass *object_class_by_name(const char *typename);
963 
964 void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
965                           const char *implements_type, bool include_abstract,
966                           void *opaque);
967 
968 /**
969  * object_class_get_list:
970  * @implements_type: The type to filter for, including its derivatives.
971  * @include_abstract: Whether to include abstract classes.
972  *
973  * Returns: A singly-linked list of the classes in reverse hashtable order.
974  */
975 GSList *object_class_get_list(const char *implements_type,
976                               bool include_abstract);
977 
978 /**
979  * object_class_get_list_sorted:
980  * @implements_type: The type to filter for, including its derivatives.
981  * @include_abstract: Whether to include abstract classes.
982  *
983  * Returns: A singly-linked list of the classes in alphabetical
984  * case-insensitive order.
985  */
986 GSList *object_class_get_list_sorted(const char *implements_type,
987                               bool include_abstract);
988 
989 /**
990  * object_ref:
991  * @obj: the object
992  *
993  * Increase the reference count of a object.  A object cannot be freed as long
994  * as its reference count is greater than zero.
995  */
996 void object_ref(Object *obj);
997 
998 /**
999  * object_unref:
1000  * @obj: the object
1001  *
1002  * Decrease the reference count of a object.  A object cannot be freed as long
1003  * as its reference count is greater than zero.
1004  */
1005 void object_unref(Object *obj);
1006 
1007 /**
1008  * object_property_add:
1009  * @obj: the object to add a property to
1010  * @name: the name of the property.  This can contain any character except for
1011  *  a forward slash.  In general, you should use hyphens '-' instead of
1012  *  underscores '_' when naming properties.
1013  * @type: the type name of the property.  This namespace is pretty loosely
1014  *   defined.  Sub namespaces are constructed by using a prefix and then
1015  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1016  *   'link' namespace would be 'link<virtio-net-pci>'.
1017  * @get: The getter to be called to read a property.  If this is NULL, then
1018  *   the property cannot be read.
1019  * @set: the setter to be called to write a property.  If this is NULL,
1020  *   then the property cannot be written.
1021  * @release: called when the property is removed from the object.  This is
1022  *   meant to allow a property to free its opaque upon object
1023  *   destruction.  This may be NULL.
1024  * @opaque: an opaque pointer to pass to the callbacks for the property
1025  * @errp: returns an error if this function fails
1026  *
1027  * Returns: The #ObjectProperty; this can be used to set the @resolve
1028  * callback for child and link properties.
1029  */
1030 ObjectProperty *object_property_add(Object *obj, const char *name,
1031                                     const char *type,
1032                                     ObjectPropertyAccessor *get,
1033                                     ObjectPropertyAccessor *set,
1034                                     ObjectPropertyRelease *release,
1035                                     void *opaque, Error **errp);
1036 
1037 void object_property_del(Object *obj, const char *name, Error **errp);
1038 
1039 ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
1040                                           const char *type,
1041                                           ObjectPropertyAccessor *get,
1042                                           ObjectPropertyAccessor *set,
1043                                           ObjectPropertyRelease *release,
1044                                           void *opaque, Error **errp);
1045 
1046 /**
1047  * object_property_find:
1048  * @obj: the object
1049  * @name: the name of the property
1050  * @errp: returns an error if this function fails
1051  *
1052  * Look up a property for an object and return its #ObjectProperty if found.
1053  */
1054 ObjectProperty *object_property_find(Object *obj, const char *name,
1055                                      Error **errp);
1056 ObjectProperty *object_class_property_find(ObjectClass *klass, const char *name,
1057                                            Error **errp);
1058 
1059 typedef struct ObjectPropertyIterator {
1060     ObjectClass *nextclass;
1061     GHashTableIter iter;
1062 } ObjectPropertyIterator;
1063 
1064 /**
1065  * object_property_iter_init:
1066  * @obj: the object
1067  *
1068  * Initializes an iterator for traversing all properties
1069  * registered against an object instance, its class and all parent classes.
1070  *
1071  * It is forbidden to modify the property list while iterating,
1072  * whether removing or adding properties.
1073  *
1074  * Typical usage pattern would be
1075  *
1076  * <example>
1077  *   <title>Using object property iterators</title>
1078  *   <programlisting>
1079  *   ObjectProperty *prop;
1080  *   ObjectPropertyIterator iter;
1081  *
1082  *   object_property_iter_init(&iter, obj);
1083  *   while ((prop = object_property_iter_next(&iter))) {
1084  *     ... do something with prop ...
1085  *   }
1086  *   </programlisting>
1087  * </example>
1088  */
1089 void object_property_iter_init(ObjectPropertyIterator *iter,
1090                                Object *obj);
1091 
1092 /**
1093  * object_class_property_iter_init:
1094  * @klass: the class
1095  *
1096  * Initializes an iterator for traversing all properties
1097  * registered against an object class and all parent classes.
1098  *
1099  * It is forbidden to modify the property list while iterating,
1100  * whether removing or adding properties.
1101  *
1102  * This can be used on abstract classes as it does not create a temporary
1103  * instance.
1104  */
1105 void object_class_property_iter_init(ObjectPropertyIterator *iter,
1106                                      ObjectClass *klass);
1107 
1108 /**
1109  * object_property_iter_next:
1110  * @iter: the iterator instance
1111  *
1112  * Return the next available property. If no further properties
1113  * are available, a %NULL value will be returned and the @iter
1114  * pointer should not be used again after this point without
1115  * re-initializing it.
1116  *
1117  * Returns: the next property, or %NULL when all properties
1118  * have been traversed.
1119  */
1120 ObjectProperty *object_property_iter_next(ObjectPropertyIterator *iter);
1121 
1122 void object_unparent(Object *obj);
1123 
1124 /**
1125  * object_property_get:
1126  * @obj: the object
1127  * @v: the visitor that will receive the property value.  This should be an
1128  *   Output visitor and the data will be written with @name as the name.
1129  * @name: the name of the property
1130  * @errp: returns an error if this function fails
1131  *
1132  * Reads a property from a object.
1133  */
1134 void object_property_get(Object *obj, Visitor *v, const char *name,
1135                          Error **errp);
1136 
1137 /**
1138  * object_property_set_str:
1139  * @value: the value to be written to the property
1140  * @name: the name of the property
1141  * @errp: returns an error if this function fails
1142  *
1143  * Writes a string value to a property.
1144  */
1145 void object_property_set_str(Object *obj, const char *value,
1146                              const char *name, Error **errp);
1147 
1148 /**
1149  * object_property_get_str:
1150  * @obj: the object
1151  * @name: the name of the property
1152  * @errp: returns an error if this function fails
1153  *
1154  * Returns: the value of the property, converted to a C string, or NULL if
1155  * an error occurs (including when the property value is not a string).
1156  * The caller should free the string.
1157  */
1158 char *object_property_get_str(Object *obj, const char *name,
1159                               Error **errp);
1160 
1161 /**
1162  * object_property_set_link:
1163  * @value: the value to be written to the property
1164  * @name: the name of the property
1165  * @errp: returns an error if this function fails
1166  *
1167  * Writes an object's canonical path to a property.
1168  *
1169  * If the link property was created with
1170  * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is
1171  * unreferenced, and a reference is added to the new target object.
1172  *
1173  */
1174 void object_property_set_link(Object *obj, Object *value,
1175                               const char *name, Error **errp);
1176 
1177 /**
1178  * object_property_get_link:
1179  * @obj: the object
1180  * @name: the name of the property
1181  * @errp: returns an error if this function fails
1182  *
1183  * Returns: the value of the property, resolved from a path to an Object,
1184  * or NULL if an error occurs (including when the property value is not a
1185  * string or not a valid object path).
1186  */
1187 Object *object_property_get_link(Object *obj, const char *name,
1188                                  Error **errp);
1189 
1190 /**
1191  * object_property_set_bool:
1192  * @value: the value to be written to the property
1193  * @name: the name of the property
1194  * @errp: returns an error if this function fails
1195  *
1196  * Writes a bool value to a property.
1197  */
1198 void object_property_set_bool(Object *obj, bool value,
1199                               const char *name, Error **errp);
1200 
1201 /**
1202  * object_property_get_bool:
1203  * @obj: the object
1204  * @name: the name of the property
1205  * @errp: returns an error if this function fails
1206  *
1207  * Returns: the value of the property, converted to a boolean, or NULL if
1208  * an error occurs (including when the property value is not a bool).
1209  */
1210 bool object_property_get_bool(Object *obj, const char *name,
1211                               Error **errp);
1212 
1213 /**
1214  * object_property_set_int:
1215  * @value: the value to be written to the property
1216  * @name: the name of the property
1217  * @errp: returns an error if this function fails
1218  *
1219  * Writes an integer value to a property.
1220  */
1221 void object_property_set_int(Object *obj, int64_t value,
1222                              const char *name, Error **errp);
1223 
1224 /**
1225  * object_property_get_int:
1226  * @obj: the object
1227  * @name: the name of the property
1228  * @errp: returns an error if this function fails
1229  *
1230  * Returns: the value of the property, converted to an integer, or negative if
1231  * an error occurs (including when the property value is not an integer).
1232  */
1233 int64_t object_property_get_int(Object *obj, const char *name,
1234                                 Error **errp);
1235 
1236 /**
1237  * object_property_set_uint:
1238  * @value: the value to be written to the property
1239  * @name: the name of the property
1240  * @errp: returns an error if this function fails
1241  *
1242  * Writes an unsigned integer value to a property.
1243  */
1244 void object_property_set_uint(Object *obj, uint64_t value,
1245                               const char *name, Error **errp);
1246 
1247 /**
1248  * object_property_get_uint:
1249  * @obj: the object
1250  * @name: the name of the property
1251  * @errp: returns an error if this function fails
1252  *
1253  * Returns: the value of the property, converted to an unsigned integer, or 0
1254  * an error occurs (including when the property value is not an integer).
1255  */
1256 uint64_t object_property_get_uint(Object *obj, const char *name,
1257                                   Error **errp);
1258 
1259 /**
1260  * object_property_get_enum:
1261  * @obj: the object
1262  * @name: the name of the property
1263  * @typename: the name of the enum data type
1264  * @errp: returns an error if this function fails
1265  *
1266  * Returns: the value of the property, converted to an integer, or
1267  * undefined if an error occurs (including when the property value is not
1268  * an enum).
1269  */
1270 int object_property_get_enum(Object *obj, const char *name,
1271                              const char *typename, Error **errp);
1272 
1273 /**
1274  * object_property_get_uint16List:
1275  * @obj: the object
1276  * @name: the name of the property
1277  * @list: the returned int list
1278  * @errp: returns an error if this function fails
1279  *
1280  * Returns: the value of the property, converted to integers, or
1281  * undefined if an error occurs (including when the property value is not
1282  * an list of integers).
1283  */
1284 void object_property_get_uint16List(Object *obj, const char *name,
1285                                     uint16List **list, Error **errp);
1286 
1287 /**
1288  * object_property_set:
1289  * @obj: the object
1290  * @v: the visitor that will be used to write the property value.  This should
1291  *   be an Input visitor and the data will be first read with @name as the
1292  *   name and then written as the property value.
1293  * @name: the name of the property
1294  * @errp: returns an error if this function fails
1295  *
1296  * Writes a property to a object.
1297  */
1298 void object_property_set(Object *obj, Visitor *v, const char *name,
1299                          Error **errp);
1300 
1301 /**
1302  * object_property_parse:
1303  * @obj: the object
1304  * @string: the string that will be used to parse the property value.
1305  * @name: the name of the property
1306  * @errp: returns an error if this function fails
1307  *
1308  * Parses a string and writes the result into a property of an object.
1309  */
1310 void object_property_parse(Object *obj, const char *string,
1311                            const char *name, Error **errp);
1312 
1313 /**
1314  * object_property_print:
1315  * @obj: the object
1316  * @name: the name of the property
1317  * @human: if true, print for human consumption
1318  * @errp: returns an error if this function fails
1319  *
1320  * Returns a string representation of the value of the property.  The
1321  * caller shall free the string.
1322  */
1323 char *object_property_print(Object *obj, const char *name, bool human,
1324                             Error **errp);
1325 
1326 /**
1327  * object_property_get_type:
1328  * @obj: the object
1329  * @name: the name of the property
1330  * @errp: returns an error if this function fails
1331  *
1332  * Returns:  The type name of the property.
1333  */
1334 const char *object_property_get_type(Object *obj, const char *name,
1335                                      Error **errp);
1336 
1337 /**
1338  * object_get_root:
1339  *
1340  * Returns: the root object of the composition tree
1341  */
1342 Object *object_get_root(void);
1343 
1344 
1345 /**
1346  * object_get_objects_root:
1347  *
1348  * Get the container object that holds user created
1349  * object instances. This is the object at path
1350  * "/objects"
1351  *
1352  * Returns: the user object container
1353  */
1354 Object *object_get_objects_root(void);
1355 
1356 /**
1357  * object_get_internal_root:
1358  *
1359  * Get the container object that holds internally used object
1360  * instances.  Any object which is put into this container must not be
1361  * user visible, and it will not be exposed in the QOM tree.
1362  *
1363  * Returns: the internal object container
1364  */
1365 Object *object_get_internal_root(void);
1366 
1367 /**
1368  * object_get_canonical_path_component:
1369  *
1370  * Returns: The final component in the object's canonical path.  The canonical
1371  * path is the path within the composition tree starting from the root.
1372  * %NULL if the object doesn't have a parent (and thus a canonical path).
1373  */
1374 gchar *object_get_canonical_path_component(Object *obj);
1375 
1376 /**
1377  * object_get_canonical_path:
1378  *
1379  * Returns: The canonical path for a object.  This is the path within the
1380  * composition tree starting from the root.
1381  */
1382 gchar *object_get_canonical_path(Object *obj);
1383 
1384 /**
1385  * object_resolve_path:
1386  * @path: the path to resolve
1387  * @ambiguous: returns true if the path resolution failed because of an
1388  *   ambiguous match
1389  *
1390  * There are two types of supported paths--absolute paths and partial paths.
1391  *
1392  * Absolute paths are derived from the root object and can follow child<> or
1393  * link<> properties.  Since they can follow link<> properties, they can be
1394  * arbitrarily long.  Absolute paths look like absolute filenames and are
1395  * prefixed with a leading slash.
1396  *
1397  * Partial paths look like relative filenames.  They do not begin with a
1398  * prefix.  The matching rules for partial paths are subtle but designed to make
1399  * specifying objects easy.  At each level of the composition tree, the partial
1400  * path is matched as an absolute path.  The first match is not returned.  At
1401  * least two matches are searched for.  A successful result is only returned if
1402  * only one match is found.  If more than one match is found, a flag is
1403  * returned to indicate that the match was ambiguous.
1404  *
1405  * Returns: The matched object or NULL on path lookup failure.
1406  */
1407 Object *object_resolve_path(const char *path, bool *ambiguous);
1408 
1409 /**
1410  * object_resolve_path_type:
1411  * @path: the path to resolve
1412  * @typename: the type to look for.
1413  * @ambiguous: returns true if the path resolution failed because of an
1414  *   ambiguous match
1415  *
1416  * This is similar to object_resolve_path.  However, when looking for a
1417  * partial path only matches that implement the given type are considered.
1418  * This restricts the search and avoids spuriously flagging matches as
1419  * ambiguous.
1420  *
1421  * For both partial and absolute paths, the return value goes through
1422  * a dynamic cast to @typename.  This is important if either the link,
1423  * or the typename itself are of interface types.
1424  *
1425  * Returns: The matched object or NULL on path lookup failure.
1426  */
1427 Object *object_resolve_path_type(const char *path, const char *typename,
1428                                  bool *ambiguous);
1429 
1430 /**
1431  * object_resolve_path_component:
1432  * @parent: the object in which to resolve the path
1433  * @part: the component to resolve.
1434  *
1435  * This is similar to object_resolve_path with an absolute path, but it
1436  * only resolves one element (@part) and takes the others from @parent.
1437  *
1438  * Returns: The resolved object or NULL on path lookup failure.
1439  */
1440 Object *object_resolve_path_component(Object *parent, const gchar *part);
1441 
1442 /**
1443  * object_property_add_child:
1444  * @obj: the object to add a property to
1445  * @name: the name of the property
1446  * @child: the child object
1447  * @errp: if an error occurs, a pointer to an area to store the error
1448  *
1449  * Child properties form the composition tree.  All objects need to be a child
1450  * of another object.  Objects can only be a child of one object.
1451  *
1452  * There is no way for a child to determine what its parent is.  It is not
1453  * a bidirectional relationship.  This is by design.
1454  *
1455  * The value of a child property as a C string will be the child object's
1456  * canonical path. It can be retrieved using object_property_get_str().
1457  * The child object itself can be retrieved using object_property_get_link().
1458  */
1459 void object_property_add_child(Object *obj, const char *name,
1460                                Object *child, Error **errp);
1461 
1462 typedef enum {
1463     /* Unref the link pointer when the property is deleted */
1464     OBJ_PROP_LINK_STRONG = 0x1,
1465 } ObjectPropertyLinkFlags;
1466 
1467 /**
1468  * object_property_allow_set_link:
1469  *
1470  * The default implementation of the object_property_add_link() check()
1471  * callback function.  It allows the link property to be set and never returns
1472  * an error.
1473  */
1474 void object_property_allow_set_link(const Object *, const char *,
1475                                     Object *, Error **);
1476 
1477 /**
1478  * object_property_add_link:
1479  * @obj: the object to add a property to
1480  * @name: the name of the property
1481  * @type: the qobj type of the link
1482  * @child: a pointer to where the link object reference is stored
1483  * @check: callback to veto setting or NULL if the property is read-only
1484  * @flags: additional options for the link
1485  * @errp: if an error occurs, a pointer to an area to store the error
1486  *
1487  * Links establish relationships between objects.  Links are unidirectional
1488  * although two links can be combined to form a bidirectional relationship
1489  * between objects.
1490  *
1491  * Links form the graph in the object model.
1492  *
1493  * The <code>@check()</code> callback is invoked when
1494  * object_property_set_link() is called and can raise an error to prevent the
1495  * link being set.  If <code>@check</code> is NULL, the property is read-only
1496  * and cannot be set.
1497  *
1498  * Ownership of the pointer that @child points to is transferred to the
1499  * link property.  The reference count for <code>*@child</code> is
1500  * managed by the property from after the function returns till the
1501  * property is deleted with object_property_del().  If the
1502  * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set,
1503  * the reference count is decremented when the property is deleted or
1504  * modified.
1505  */
1506 void object_property_add_link(Object *obj, const char *name,
1507                               const char *type, Object **child,
1508                               void (*check)(const Object *obj, const char *name,
1509                                             Object *val, Error **errp),
1510                               ObjectPropertyLinkFlags flags,
1511                               Error **errp);
1512 
1513 /**
1514  * object_property_add_str:
1515  * @obj: the object to add a property to
1516  * @name: the name of the property
1517  * @get: the getter or NULL if the property is write-only.  This function must
1518  *   return a string to be freed by g_free().
1519  * @set: the setter or NULL if the property is read-only
1520  * @errp: if an error occurs, a pointer to an area to store the error
1521  *
1522  * Add a string property using getters/setters.  This function will add a
1523  * property of type 'string'.
1524  */
1525 void object_property_add_str(Object *obj, const char *name,
1526                              char *(*get)(Object *, Error **),
1527                              void (*set)(Object *, const char *, Error **),
1528                              Error **errp);
1529 
1530 void object_class_property_add_str(ObjectClass *klass, const char *name,
1531                                    char *(*get)(Object *, Error **),
1532                                    void (*set)(Object *, const char *,
1533                                                Error **),
1534                                    Error **errp);
1535 
1536 /**
1537  * object_property_add_bool:
1538  * @obj: the object to add a property to
1539  * @name: the name of the property
1540  * @get: the getter or NULL if the property is write-only.
1541  * @set: the setter or NULL if the property is read-only
1542  * @errp: if an error occurs, a pointer to an area to store the error
1543  *
1544  * Add a bool property using getters/setters.  This function will add a
1545  * property of type 'bool'.
1546  */
1547 void object_property_add_bool(Object *obj, const char *name,
1548                               bool (*get)(Object *, Error **),
1549                               void (*set)(Object *, bool, Error **),
1550                               Error **errp);
1551 
1552 void object_class_property_add_bool(ObjectClass *klass, const char *name,
1553                                     bool (*get)(Object *, Error **),
1554                                     void (*set)(Object *, bool, Error **),
1555                                     Error **errp);
1556 
1557 /**
1558  * object_property_add_enum:
1559  * @obj: the object to add a property to
1560  * @name: the name of the property
1561  * @typename: the name of the enum data type
1562  * @get: the getter or %NULL if the property is write-only.
1563  * @set: the setter or %NULL if the property is read-only
1564  * @errp: if an error occurs, a pointer to an area to store the error
1565  *
1566  * Add an enum property using getters/setters.  This function will add a
1567  * property of type '@typename'.
1568  */
1569 void object_property_add_enum(Object *obj, const char *name,
1570                               const char *typename,
1571                               const QEnumLookup *lookup,
1572                               int (*get)(Object *, Error **),
1573                               void (*set)(Object *, int, Error **),
1574                               Error **errp);
1575 
1576 void object_class_property_add_enum(ObjectClass *klass, const char *name,
1577                                     const char *typename,
1578                                     const QEnumLookup *lookup,
1579                                     int (*get)(Object *, Error **),
1580                                     void (*set)(Object *, int, Error **),
1581                                     Error **errp);
1582 
1583 /**
1584  * object_property_add_tm:
1585  * @obj: the object to add a property to
1586  * @name: the name of the property
1587  * @get: the getter or NULL if the property is write-only.
1588  * @errp: if an error occurs, a pointer to an area to store the error
1589  *
1590  * Add a read-only struct tm valued property using a getter function.
1591  * This function will add a property of type 'struct tm'.
1592  */
1593 void object_property_add_tm(Object *obj, const char *name,
1594                             void (*get)(Object *, struct tm *, Error **),
1595                             Error **errp);
1596 
1597 void object_class_property_add_tm(ObjectClass *klass, const char *name,
1598                                   void (*get)(Object *, struct tm *, Error **),
1599                                   Error **errp);
1600 
1601 /**
1602  * object_property_add_uint8_ptr:
1603  * @obj: the object to add a property to
1604  * @name: the name of the property
1605  * @v: pointer to value
1606  * @errp: if an error occurs, a pointer to an area to store the error
1607  *
1608  * Add an integer property in memory.  This function will add a
1609  * property of type 'uint8'.
1610  */
1611 void object_property_add_uint8_ptr(Object *obj, const char *name,
1612                                    const uint8_t *v, Error **errp);
1613 void object_class_property_add_uint8_ptr(ObjectClass *klass, const char *name,
1614                                          const uint8_t *v, Error **errp);
1615 
1616 /**
1617  * object_property_add_uint16_ptr:
1618  * @obj: the object to add a property to
1619  * @name: the name of the property
1620  * @v: pointer to value
1621  * @errp: if an error occurs, a pointer to an area to store the error
1622  *
1623  * Add an integer property in memory.  This function will add a
1624  * property of type 'uint16'.
1625  */
1626 void object_property_add_uint16_ptr(Object *obj, const char *name,
1627                                     const uint16_t *v, Error **errp);
1628 void object_class_property_add_uint16_ptr(ObjectClass *klass, const char *name,
1629                                           const uint16_t *v, Error **errp);
1630 
1631 /**
1632  * object_property_add_uint32_ptr:
1633  * @obj: the object to add a property to
1634  * @name: the name of the property
1635  * @v: pointer to value
1636  * @errp: if an error occurs, a pointer to an area to store the error
1637  *
1638  * Add an integer property in memory.  This function will add a
1639  * property of type 'uint32'.
1640  */
1641 void object_property_add_uint32_ptr(Object *obj, const char *name,
1642                                     const uint32_t *v, Error **errp);
1643 void object_class_property_add_uint32_ptr(ObjectClass *klass, const char *name,
1644                                           const uint32_t *v, Error **errp);
1645 
1646 /**
1647  * object_property_add_uint64_ptr:
1648  * @obj: the object to add a property to
1649  * @name: the name of the property
1650  * @v: pointer to value
1651  * @errp: if an error occurs, a pointer to an area to store the error
1652  *
1653  * Add an integer property in memory.  This function will add a
1654  * property of type 'uint64'.
1655  */
1656 void object_property_add_uint64_ptr(Object *obj, const char *name,
1657                                     const uint64_t *v, Error **errp);
1658 void object_class_property_add_uint64_ptr(ObjectClass *klass, const char *name,
1659                                           const uint64_t *v, Error **errp);
1660 
1661 /**
1662  * object_property_add_alias:
1663  * @obj: the object to add a property to
1664  * @name: the name of the property
1665  * @target_obj: the object to forward property access to
1666  * @target_name: the name of the property on the forwarded object
1667  * @errp: if an error occurs, a pointer to an area to store the error
1668  *
1669  * Add an alias for a property on an object.  This function will add a property
1670  * of the same type as the forwarded property.
1671  *
1672  * The caller must ensure that <code>@target_obj</code> stays alive as long as
1673  * this property exists.  In the case of a child object or an alias on the same
1674  * object this will be the case.  For aliases to other objects the caller is
1675  * responsible for taking a reference.
1676  */
1677 void object_property_add_alias(Object *obj, const char *name,
1678                                Object *target_obj, const char *target_name,
1679                                Error **errp);
1680 
1681 /**
1682  * object_property_add_const_link:
1683  * @obj: the object to add a property to
1684  * @name: the name of the property
1685  * @target: the object to be referred by the link
1686  * @errp: if an error occurs, a pointer to an area to store the error
1687  *
1688  * Add an unmodifiable link for a property on an object.  This function will
1689  * add a property of type link<TYPE> where TYPE is the type of @target.
1690  *
1691  * The caller must ensure that @target stays alive as long as
1692  * this property exists.  In the case @target is a child of @obj,
1693  * this will be the case.  Otherwise, the caller is responsible for
1694  * taking a reference.
1695  */
1696 void object_property_add_const_link(Object *obj, const char *name,
1697                                     Object *target, Error **errp);
1698 
1699 /**
1700  * object_property_set_description:
1701  * @obj: the object owning the property
1702  * @name: the name of the property
1703  * @description: the description of the property on the object
1704  * @errp: if an error occurs, a pointer to an area to store the error
1705  *
1706  * Set an object property's description.
1707  *
1708  */
1709 void object_property_set_description(Object *obj, const char *name,
1710                                      const char *description, Error **errp);
1711 void object_class_property_set_description(ObjectClass *klass, const char *name,
1712                                            const char *description,
1713                                            Error **errp);
1714 
1715 /**
1716  * object_child_foreach:
1717  * @obj: the object whose children will be navigated
1718  * @fn: the iterator function to be called
1719  * @opaque: an opaque value that will be passed to the iterator
1720  *
1721  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
1722  * non-zero.
1723  *
1724  * It is forbidden to add or remove children from @obj from the @fn
1725  * callback.
1726  *
1727  * Returns: The last value returned by @fn, or 0 if there is no child.
1728  */
1729 int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque),
1730                          void *opaque);
1731 
1732 /**
1733  * object_child_foreach_recursive:
1734  * @obj: the object whose children will be navigated
1735  * @fn: the iterator function to be called
1736  * @opaque: an opaque value that will be passed to the iterator
1737  *
1738  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
1739  * non-zero. Calls recursively, all child nodes of @obj will also be passed
1740  * all the way down to the leaf nodes of the tree. Depth first ordering.
1741  *
1742  * It is forbidden to add or remove children from @obj (or its
1743  * child nodes) from the @fn callback.
1744  *
1745  * Returns: The last value returned by @fn, or 0 if there is no child.
1746  */
1747 int object_child_foreach_recursive(Object *obj,
1748                                    int (*fn)(Object *child, void *opaque),
1749                                    void *opaque);
1750 /**
1751  * container_get:
1752  * @root: root of the #path, e.g., object_get_root()
1753  * @path: path to the container
1754  *
1755  * Return a container object whose path is @path.  Create more containers
1756  * along the path if necessary.
1757  *
1758  * Returns: the container object.
1759  */
1760 Object *container_get(Object *root, const char *path);
1761 
1762 /**
1763  * object_type_get_instance_size:
1764  * @typename: Name of the Type whose instance_size is required
1765  *
1766  * Returns the instance_size of the given @typename.
1767  */
1768 size_t object_type_get_instance_size(const char *typename);
1769 #endif
1770