From: Eduardo Habkost <ehabkost@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Daniel P. Berrange" <berrange@redhat.com>,
"John Snow" <jsnow@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Igor Mammedov" <imammedo@redhat.com>,
"Paolo Bonzini" <pbonzini@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>
Subject: [PATCH 36/36] qom: Include static property API reference in documentation
Date: Thu, 29 Oct 2020 18:02:46 -0400 [thread overview]
Message-ID: <20201029220246.472693-37-ehabkost@redhat.com> (raw)
In-Reply-To: <20201029220246.472693-1-ehabkost@redhat.com>
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 <ehabkost@redhat.com>
---
docs/devel/qom.rst | 6 ++
include/qom/static-property.h | 154 ++++++++++++++++++++++++++++++++--
2 files changed, 151 insertions(+), 9 deletions(-)
diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 42d0dc4f4d..0989b4e690 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -379,3 +379,9 @@ API Reference
-------------
.. kernel-doc:: include/qom/object.h
+
+
+Static Property API Reference
+-----------------------------
+
+.. kernel-doc:: include/qom/static-property.h
diff --git a/include/qom/static-property.h b/include/qom/static-property.h
index 779918c947..8339700818 100644
--- a/include/qom/static-property.h
+++ b/include/qom/static-property.h
@@ -8,20 +8,31 @@
#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 static Property
+ *
+ * #Property structs should be always initialized using the
+ * ``DEFINE_PROP`` family of macros.
*/
struct Property {
+ /* private: */
const char *name;
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;
@@ -110,6 +121,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), \
@@ -124,12 +143,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, \
@@ -142,9 +176,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
@@ -171,36 +206,137 @@ 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_UUID: Define UUID property
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ *
+ * The @_f field in struct @_s must be of type ``QemuUUID``.
+ * The default value of the property will be "auto".
+ */
#define DEFINE_PROP_UUID(_name, _state, _field) \
DEFINE_PROP(_name, _state, _field, prop_info_uuid, QemuUUID, \
.set_default = true)
+/**
+ * DEFINE_PROP_UUID_NODEFAULT: Define UUID property with no default
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ *
+ * The @_f field in struct @_s must be of type ``QemuUUID``.
+ * No default value will be set for the property.
+ */
#define DEFINE_PROP_UUID_NODEFAULT(_name, _state, _field) \
DEFINE_PROP(_name, _state, _field, prop_info_uuid, QemuUUID)
+/**
+ * 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
prev parent reply other threads:[~2020-10-29 22:30 UTC|newest]
Thread overview: 99+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-29 22:02 [PATCH 00/36] Make qdev static property API usable by any QOM type Eduardo Habkost
2020-10-29 22:02 ` [PATCH 01/36] cs4231: Get rid of empty property array Eduardo Habkost
2020-10-30 7:42 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 02/36] cpu: Move cpu_common_props to hw/core/cpu.c Eduardo Habkost
2020-10-30 7:42 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 03/36] qdev: Move property code to qdev-properties.[ch] Eduardo Habkost
2020-10-30 7:42 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 04/36] qdev: Check dev->realized at set_size() Eduardo Habkost
2020-10-30 7:11 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 05/36] sparc: Check dev->realized at sparc_set_nwindows() Eduardo Habkost
2020-10-30 7:43 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 06/36] qdev: Don't use dev->id on set_size32() error message Eduardo Habkost
2020-10-30 7:42 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 07/36] qdev: Make PropertyInfo.print method get Object* argument Eduardo Habkost
2020-10-30 7:43 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 08/36] qdev: Make bit_prop_set() " Eduardo Habkost
2020-10-30 7:45 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 09/36] qdev: Make qdev_get_prop_ptr() get Object* arg Eduardo Habkost
2020-10-29 22:02 ` Eduardo Habkost
2020-10-29 22:46 ` Stefan Berger
2020-10-29 22:46 ` Stefan Berger
2020-10-30 7:29 ` Marc-André Lureau
2020-10-30 7:29 ` Marc-André Lureau
2020-10-30 7:34 ` Marc-André Lureau
2020-10-30 7:34 ` Marc-André Lureau
2020-10-30 11:35 ` --enable-xen on gitlab CI? (was Re: [PATCH 09/36] qdev: Make qdev_get_prop_ptr() get Object* arg) Eduardo Habkost
2020-10-30 11:35 ` Eduardo Habkost
2020-10-30 17:13 ` Paolo Bonzini
2020-10-30 17:13 ` Paolo Bonzini
2020-10-31 10:25 ` Thomas Huth
2020-10-31 10:25 ` Thomas Huth
2020-11-08 17:45 ` Philippe Mathieu-Daudé
2020-11-08 17:45 ` Philippe Mathieu-Daudé
2020-10-29 22:02 ` [PATCH 10/36] qdev: Make qdev_find_global_prop() get Object* argument Eduardo Habkost
2020-10-30 7:45 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 11/36] qdev: Make check_prop_still_unset() " Eduardo Habkost
2020-10-30 7:53 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 12/36] qdev: Make error_set_from_qdev_prop_error() " Eduardo Habkost
2020-10-30 8:00 ` Marc-André Lureau
2020-10-30 11:16 ` Eduardo Habkost
2020-10-29 22:02 ` [PATCH 13/36] qdev: Wrap getters and setters in separate helpers Eduardo Habkost
2020-10-30 8:06 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 14/36] qdev: Move dev->realized check to qdev_property_set() Eduardo Habkost
2020-10-29 22:02 ` Eduardo Habkost
2020-10-29 22:43 ` Stefan Berger
2020-10-29 22:43 ` Stefan Berger
2020-10-30 8:05 ` Marc-André Lureau
2020-10-30 8:05 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 15/36] qdev: Make PropertyInfo.create return ObjectProperty* Eduardo Habkost
2020-10-30 16:52 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 16/36] qdev: Make qdev_class_add_property() more flexible Eduardo Habkost
2020-10-30 9:45 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 17/36] qdev: Separate generic and device-specific property registration Eduardo Habkost
2020-10-30 9:56 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 18/36] qdev: Avoid unnecessary DeviceState* variable at set_prop_arraylen() Eduardo Habkost
2020-10-30 9:59 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 19/36] qdev: Move array property creation/registration to separate functions Eduardo Habkost
2020-10-30 10:03 ` Marc-André Lureau
2020-10-30 10:10 ` Marc-André Lureau
2020-10-30 10:12 ` Daniel P. Berrangé
2020-10-30 11:20 ` Eduardo Habkost
2020-10-29 22:02 ` [PATCH 20/36] qdev: Reuse object_property_add_static() when adding array elements Eduardo Habkost
2020-10-30 11:37 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 21/36] qom: Add allow_set callback to ObjectProperty Eduardo Habkost
2020-10-30 16:43 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 22/36] qdev: Make qdev_prop_allow_set() a property allow_set callback Eduardo Habkost
2020-10-30 16:42 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 23/36] qdev: Make qdev_propinfo_get_uint16() static Eduardo Habkost
2020-10-30 16:51 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 24/36] qdev: Rename qdev_propinfo_* to object_propinfo_* Eduardo Habkost
2020-10-30 16:50 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 25/36] qdev: Rename qdev_get_prop_ptr() to object_static_prop_ptr() Eduardo Habkost
2020-10-29 22:02 ` Eduardo Habkost
2020-10-29 22:41 ` Stefan Berger
2020-10-29 22:41 ` Stefan Berger
2020-10-29 22:02 ` [PATCH 26/36] qdev: Move softmmu properties to qdev-properties-system.h Eduardo Habkost
2020-10-30 16:51 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 27/36] qdev: Reuse DEFINE_PROP in all DEFINE_PROP_* macros Eduardo Habkost
2020-10-30 16:53 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 28/36] qdev: Move core static property code to QOM Eduardo Habkost
2020-10-30 16:59 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 29/36] qdev: Move qdev_prop_tpm declaration to tpm_prop.h Eduardo Habkost
2020-10-29 22:40 ` Stefan Berger
2020-10-30 17:02 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 30/36] qdev: Rename qdev_prop_* to prop_info_* Eduardo Habkost
2020-10-30 17:02 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 31/36] qdev: Stop using error_set_from_qdev_prop_error() for UUID property Eduardo Habkost
2020-10-30 17:06 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 32/36] qdev: Move base property types to qom/property-types.c Eduardo Habkost
2020-10-31 7:38 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 33/36] tests: Use static properties at check-qom-proplist test case Eduardo Habkost
2020-10-31 7:53 ` Marc-André Lureau
2020-10-29 22:02 ` [PATCH 34/36] machine: Use DEFINE_PROP_STRING for string properties Eduardo Habkost
2020-10-30 17:10 ` Paolo Bonzini
2020-10-30 20:03 ` Eduardo Habkost
2020-10-30 20:41 ` Paolo Bonzini
2020-10-30 21:00 ` Eduardo Habkost
2020-10-29 22:02 ` [PATCH 35/36] machine: Use DEFINE_PROP_BOOL for boolean properties Eduardo Habkost
2020-10-29 22:02 ` Eduardo Habkost [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201029220246.472693-37-ehabkost@redhat.com \
--to=ehabkost@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=imammedo@redhat.com \
--cc=jsnow@redhat.com \
--cc=pbonzini@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.