Include the static-properties.h API reference in docs/devel/qom.rst. Signed-off-by: Eduardo Habkost <ehabk...@redhat.com> --- Changes v2 -> v3: * Redone patch after changes in previous patches in the series * Split into separate patches. This one only adds the file to qom.rst and Property/PropertyInfo doc comments. Another patch will add the documentation for DEFINE_PROP_* and PROP_*.
Changes v1 -> v2: * Redone patch after changes in previous patches in the series --- Cc: Paolo Bonzini <pbonz...@redhat.com> Cc: "Daniel P. Berrangé" <berra...@redhat.com> Cc: Eduardo Habkost <ehabk...@redhat.com> Cc: qemu-devel@nongnu.org --- docs/devel/qom.rst | 17 +++++++++++++- include/qom/field-property.h | 45 ++++++++++++++++++++++++++++++------ include/qom/property-types.h | 2 +- 3 files changed, 55 insertions(+), 9 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 42d0dc4f4d..9e43aa46f2 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -376,6 +376,21 @@ the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: API Reference -------------- +============= + +Core QOM API Reference +---------------------- .. kernel-doc:: include/qom/object.h + + +Field Property API Reference +---------------------------- + +.. kernel-doc:: include/qom/field-property.h + + +Property Types Reference +------------------------ + +.. kernel-doc:: include/qom/property-types.h diff --git a/include/qom/field-property.h b/include/qom/field-property.h index 91e7a43165..419e5eef75 100644 --- a/include/qom/field-property.h +++ b/include/qom/field-property.h @@ -8,15 +8,14 @@ #include "qapi/util.h" /** - * Property: - * @set_default: true if the default value should be set from @defval, - * in which case @info->set_default_value must not be NULL - * (if false then no default value is set by the property system - * and the field retains whatever value it was given by instance_init). - * @defval: default value for the property. This is used only if @set_default - * is true. + * struct Property: definition of a field property + * + * Field properties are used to read and write fields in object + * instance structs. Field properties are defined using + * ``PROP_<type>`` or ``DEFINE_PROP_<type>``. */ struct Property { + /* private: */ /** * @name_template: Property name template * @@ -28,27 +27,59 @@ struct Property { const PropertyInfo *info; ptrdiff_t offset; uint8_t bitnr; + /** + * @set_default: true if the default value should be set from @defval, + * in which case @info->set_default_value must not be NULL + * (if false then no default value is set by the property system + * and the field retains whatever value it was given by instance_init). + */ bool set_default; + /** + * @defval: default value for the property. This is used only if @set_default + * is true. + */ union { int64_t i; uint64_t u; } defval; + /* private: */ int arrayoffset; const PropertyInfo *arrayinfo; int arrayfieldsize; const char *link_type; }; +/** + * struct PropertyInfo: information on a specific QOM property type + */ struct PropertyInfo { + /** @name: property type name */ const char *name; + /** @description: Description for help text */ const char *description; + /** @enum_table: Used by field_prop_get_enum() and field_prop_set_enum() */ const QEnumLookup *enum_table; + /** @print: String formatting function, for the human monitor */ int (*print)(Object *obj, Property *prop, char *dest, size_t len); + /** @set_default_value: Callback for initializing the default value */ void (*set_default_value)(ObjectProperty *op, const Property *prop); + /** @create: Optional callback for creation of property */ ObjectProperty *(*create)(ObjectClass *oc, const char *name, Property *prop); + /** + * @get: Property getter. The opaque parameter will point to + * the &Property struct for the property. + */ ObjectPropertyAccessor *get; + /** + * @set: Property setter. The opaque parameter will point to + * the &Property struct for the property. + */ ObjectPropertyAccessor *set; + /** + * @release: Optional release function, called when the object + * is destroyed + */ ObjectPropertyRelease *release; }; diff --git a/include/qom/property-types.h b/include/qom/property-types.h index 0aff0d9474..46c82da4e3 100644 --- a/include/qom/property-types.h +++ b/include/qom/property-types.h @@ -71,7 +71,7 @@ extern const PropertyInfo prop_info_link; * @_name: name of the array * @_state: name of the device state structure type * @_field: uint32_t field in @_state to hold the array length - * @_arrayfield: field in @_state (of type '@_arraytype *') which + * @_arrayfield: field in @_state (of type ``_arraytype *``) which * will point to the array * @_arrayprop: PropertyInfo defining what property the array elements have * @_arraytype: C type of the array elements -- 2.28.0