Add new doc comments and reformat the existing ones,
and include the static-properties.h API reference in
docs/devel/qom.rst.
Signed-off-by: Eduardo Habkost <ehabk...@redhat.com>
---
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 | 47 ++++++++++++---
include/qom/property-types.h | 111 ++++++++++++++++++++++++++++++++++-
3 files changed, 165 insertions(+), 10 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 bdc89b38a6..bc866e1c93 100644
--- a/include/qom/field-property.h
+++ b/include/qom/field-property.h
@@ -8,15 +8,16 @@
#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 declared using
+ * ``DEFINE_PROP_<type>`` (for property arrays registered using
+ * device_class_set_props()), or using ``PROP_<type>`` (for
+ * object_class_property_add_field() calls).
*/
struct Property {
+ /* private: */
/**
* @qdev_prop_name: qdev property name
*
@@ -28,27 +29,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 75f758e835..a891dffb6e 100644
--- a/include/qom/property-types.h
+++ b/include/qom/property-types.h
@@ -39,6 +39,14 @@ extern const PropertyInfo prop_info_link;
#define DEFINE_PROP_SIGNED_NODEFAULT(_name, _state, _field, _prop, _type) \
DEFINE_PROP(_name, _state, _field, _prop, _type)
+/**
+ * DEFINE_PROP_BIT: Define bit property in uint32_t field
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``uint32_t`` field in @_state
+ * @_bit: bit offset in @_field
+ * @_defval: default value for bit
+ */
#define DEFINE_PROP_BIT(_name, _state, _field, _bit, _defval) \
DEFINE_PROP(_name, _state, _field, prop_info_bit, uint32_t, \
.bitnr = (_bit), \
@@ -53,12 +61,27 @@ extern const PropertyInfo prop_info_link;
#define DEFINE_PROP_UNSIGNED_NODEFAULT(_name, _state, _field, _prop, _type) \
DEFINE_PROP(_name, _state, _field, _prop, _type)
+/**
+ * DEFINE_PROP_BIT64: Define bit property in uint64_t field
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``uint64_t`` field in @_state
+ * @_bit: bit offset in @_field
+ * @_defval: default value for bit
+ */
#define DEFINE_PROP_BIT64(_name, _state, _field, _bit, _defval) \
DEFINE_PROP(_name, _state, _field, prop_info_bit64, uint64_t, \
.bitnr = (_bit), \
.set_default = true, \
.defval.u = (bool)_defval)
+/**
+ * DEFINE_PROP_BOOL:
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``bool`` field in @_state
+ * @_defval: default value of property
+ */
#define DEFINE_PROP_BOOL(_name, _state, _field, _defval) \
DEFINE_PROP(_name, _state, _field, prop_info_bool, bool, \
.set_default = true, \
@@ -71,9 +94,10 @@ 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
+ * @_arrayprop: #PropertyInfo variable defining property type of
+ * array elements
* @_arraytype: C type of the array elements
*
* Define device properties for a variable-length array _name. A
@@ -100,31 +124,114 @@ extern const PropertyInfo prop_info_link;
.arrayfieldsize = sizeof(_arraytype), \
.arrayoffset = offsetof(_state, _arrayfield))
+/**
+ * DEFINE_PROP_LINK: Define object link property
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ * @_type: QOM type name of link target
+ * @_ptr_type: Type of field @_field in struct @_state
+ */
#define DEFINE_PROP_LINK(_name, _state, _field, _type, _ptr_type) \
DEFINE_PROP(_name, _state, _field, prop_info_link, _ptr_type, \
.link_type = _type)
+/**
+ * DEFINE_PROP_UINT8: Define uint8 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint8_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_UINT8(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint8, uint8_t)
+/**
+ * DEFINE_PROP_UINT16: Define uint16 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint16_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_UINT16(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint16, uint16_t)
+/**
+ * DEFINE_PROP_UINT32: Define uint32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint32_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_UINT32(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint32, uint32_t)
+/**
+ * DEFINE_PROP_INT32: Define int32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``int32_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_INT32(_n, _s, _f, _d) \
DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_int32, int32_t)
+/**
+ * DEFINE_PROP_UINT64: Define uint64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint64_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_UINT64(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint64, uint64_t)
+/**
+ * DEFINE_PROP_INT64: Define int64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``int64_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_INT64(_n, _s, _f, _d) \
DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_int64, int64_t)
+/**
+ * DEFINE_PROP_SIZE: Define uint64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint64_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_SIZE(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_size, uint64_t)
+/**
+ * DEFINE_PROP_STRING:
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``char *`` field in @_state
+ */
#define DEFINE_PROP_STRING(_n, _s, _f) \
DEFINE_PROP(_n, _s, _f, prop_info_string, char*)
+/**
+ * DEFINE_PROP_ON_OFF_AUTO: Define OnOffAuto property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``OnOffAuto`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_ON_OFF_AUTO(_n, _s, _f, _d) \
DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_on_off_auto, OnOffAuto)
+/**
+ * DEFINE_PROP_SIZE32: Define uint32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint32_t`` field in @_s
+ * @_d: default value of property
+ */
#define DEFINE_PROP_SIZE32(_n, _s, _f, _d) \
DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_size32, uint32_t)
+/**
+ * DEFINE_PROP_END_OF_LIST: Mark end of property array
+ *
+ * This must be the last entry in #Property arrays when calling
+ * object_class_add_static_props().
+ */
#define DEFINE_PROP_END_OF_LIST() \
{}
--
2.28.0
