[PATCH v2 0/6] qom: tidy-ups and preparation for class property conversion

[PATCH v2 0/6] qom: tidy-ups and preparation for class property conversion

[Mark Cave-Ayland]

Based upon feedback from my existing efforts to start converting from object
properties to class properties, here is an initial preparation series which
I hope can be applied soon after 11.1 is released.

Patches 1-3 introduce macros to generate the QOM scalar get/set functions for scalar
memory-based properties as suggested by Daniel. This makes it trivial to add any
additional scalar types as required in future, and a similar pattern will be used
when introducing proper class properties.

Patch 4 fixes an error in the existing documentation for object_property_add_link().

Patch 5 adds missing documentation for the current object_class_* property functions
since if we're looking to deprecate object properties, it seems only fair to include
the replacement class property functions in our documentation. Again once class
propeties are added, the new functions will be documented in a similar way.

Finally patch 6 renames the existing object_class_property_uint*_ptr() functions to
object_class_static_property_uint*_ptr() to both confirm that the property is shared
amongst all instances, and also clears the object_class_property_*() prefix ready
for the introduction of class properties in subsequent patch series. This is taken
from one of my existing series to convert object properties to class properties, but
it seems convenient to include it here.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>

v2:
- Add R-B tags from Daniel for patches 1-3
- Add patch 4 to fix up the existing documentation for object_property_add_link()
- Fix up the object_class_property_add_link() documentation in patch 5
- Add Daniel's description of when to use static properties in patch 6


Mark Cave-Ayland (6):
  qom/object.c: introduce OBJECT_PROPERTY_SCALAR_GETTER(type) macro
  qom/object.c: introduce OBJECT_PROPERTY_SCALAR_SETTER(type) macro
  qom/object.c: introduce DEFINE_OBJECT_PROPERTY_SCALAR_METHODS() macro
  qom/object.h: rename @child to @targetp in object_property_add_link()
    documentation
  qom/object.h: add missing documentation for object_class_* property
    functions
  qom/object.c: rename object_class_property_uint*_ptr() to
    object_class_static_property_uint*_ptr()

 include/qom/object.h | 172 +++++++++++++++++++++++++++++++++++++++++--
 hw/riscv/spike.c     |   5 +-
 qom/object.c         | 126 ++++++++++++-------------------
 3 files changed, 215 insertions(+), 88 deletions(-)

-- 
2.43.0

[PATCH v2 1/6] qom/object.c: introduce OBJECT_PROPERTY_SCALAR_GETTER(type) macro

[Mark Cave-Ayland]

This macro can be used to generate the boilerplate property_get_type_ptr()
QOM get function for the specified scalar type. Replace the existing scaler get
functions with the new macro.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qom/object.c | 41 ++++++++++++++---------------------------
 1 file changed, 14 insertions(+), 27 deletions(-)

diff --git a/qom/object.c b/qom/object.c
index f79b2cf361..34aef7ca9f 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -2661,12 +2661,20 @@ static char *object_get_type(Object *obj, Error **errp)
     return g_strdup(object_get_typename(obj));
 }
 
-static void property_get_uint8_ptr(Object *obj, Visitor *v, const char *name,
-                                   void *opaque, Error **errp)
-{
-    uint8_t value = *(uint8_t *)opaque;
-    visit_type_uint8(v, name, &value, errp);
-}
+
+#define OBJECT_PROPERTY_SCALAR_GETTER(type) \
+    static void property_get_##type##_ptr(Object *obj, Visitor *v, \
+                                          const char *name, \
+                                          void *opaque, Error **errp) \
+    { \
+        type##_t value = *(type##_t *)opaque; \
+        visit_type_##type(v, name, &value, errp); \
+    }
+
+OBJECT_PROPERTY_SCALAR_GETTER(uint8)
+OBJECT_PROPERTY_SCALAR_GETTER(uint16)
+OBJECT_PROPERTY_SCALAR_GETTER(uint32)
+OBJECT_PROPERTY_SCALAR_GETTER(uint64)
 
 static void property_set_uint8_ptr(Object *obj, Visitor *v, const char *name,
                                    void *opaque, Error **errp)
@@ -2681,13 +2689,6 @@ static void property_set_uint8_ptr(Object *obj, Visitor *v, const char *name,
     *field = value;
 }
 
-static void property_get_uint16_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint16_t value = *(uint16_t *)opaque;
-    visit_type_uint16(v, name, &value, errp);
-}
-
 static void property_set_uint16_ptr(Object *obj, Visitor *v, const char *name,
                                     void *opaque, Error **errp)
 {
@@ -2701,13 +2702,6 @@ static void property_set_uint16_ptr(Object *obj, Visitor *v, const char *name,
     *field = value;
 }
 
-static void property_get_uint32_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint32_t value = *(uint32_t *)opaque;
-    visit_type_uint32(v, name, &value, errp);
-}
-
 static void property_set_uint32_ptr(Object *obj, Visitor *v, const char *name,
                                     void *opaque, Error **errp)
 {
@@ -2721,13 +2715,6 @@ static void property_set_uint32_ptr(Object *obj, Visitor *v, const char *name,
     *field = value;
 }
 
-static void property_get_uint64_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint64_t value = *(uint64_t *)opaque;
-    visit_type_uint64(v, name, &value, errp);
-}
-
 static void property_set_uint64_ptr(Object *obj, Visitor *v, const char *name,
                                     void *opaque, Error **errp)
 {
-- 
2.43.0

[PATCH v2 2/6] qom/object.c: introduce OBJECT_PROPERTY_SCALAR_SETTER(type) macro

[Mark Cave-Ayland]

This macro can be used to generate the boilerplate property_set_type_ptr()
QOM set function for the specified scalar type. Replace the existing scaler set
functions with the new macro.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qom/object.c | 72 ++++++++++++++++------------------------------------
 1 file changed, 22 insertions(+), 50 deletions(-)

diff --git a/qom/object.c b/qom/object.c
index 34aef7ca9f..8a1f80f613 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -2671,62 +2671,34 @@ static char *object_get_type(Object *obj, Error **errp)
         visit_type_##type(v, name, &value, errp); \
     }
 
+
+#define OBJECT_PROPERTY_SCALAR_SETTER(type) \
+    static void property_set_##type##_ptr(Object *obj, Visitor *v, \
+                                          const char *name, \
+                                          void *opaque, Error **errp) \
+    { \
+        type##_t *field = opaque; \
+        type##_t value; \
+        \
+        if (!visit_type_##type(v, name, &value, errp)) { \
+            return; \
+        } \
+        \
+        *field = value; \
+    }
+
 OBJECT_PROPERTY_SCALAR_GETTER(uint8)
+OBJECT_PROPERTY_SCALAR_SETTER(uint8)
 OBJECT_PROPERTY_SCALAR_GETTER(uint16)
+OBJECT_PROPERTY_SCALAR_SETTER(uint16)
 OBJECT_PROPERTY_SCALAR_GETTER(uint32)
+OBJECT_PROPERTY_SCALAR_SETTER(uint32)
 OBJECT_PROPERTY_SCALAR_GETTER(uint64)
+OBJECT_PROPERTY_SCALAR_SETTER(uint64)
 
-static void property_set_uint8_ptr(Object *obj, Visitor *v, const char *name,
-                                   void *opaque, Error **errp)
-{
-    uint8_t *field = opaque;
-    uint8_t value;
-
-    if (!visit_type_uint8(v, name, &value, errp)) {
-        return;
-    }
-
-    *field = value;
-}
-
-static void property_set_uint16_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint16_t *field = opaque;
-    uint16_t value;
-
-    if (!visit_type_uint16(v, name, &value, errp)) {
-        return;
-    }
-
-    *field = value;
-}
-
-static void property_set_uint32_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint32_t *field = opaque;
-    uint32_t value;
-
-    if (!visit_type_uint32(v, name, &value, errp)) {
-        return;
-    }
-
-    *field = value;
-}
-
-static void property_set_uint64_ptr(Object *obj, Visitor *v, const char *name,
-                                    void *opaque, Error **errp)
-{
-    uint64_t *field = opaque;
-    uint64_t value;
-
-    if (!visit_type_uint64(v, name, &value, errp)) {
-        return;
-    }
+#undef OBJECT_PROPERTY_SCALAR_GETTER
+#undef OBJECT_PROPERTY_SCALAR_SETTER
 
-    *field = value;
-}
 
 ObjectProperty *
 object_property_add_uint8_ptr(Object *obj, const char *name,
-- 
2.43.0

[PATCH v2 3/6] qom/object.c: introduce DEFINE_OBJECT_PROPERTY_SCALAR_METHODS() macro

[Mark Cave-Ayland]

This macro defines both the QOM get and set functions for the given scaler
type. Replace the combined use of OBJECT_PROPERTY_SCALAR_GETTER() and
OBJECT_PROPERTY_SCALAR_SETTER() with the new macro.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qom/object.c | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/qom/object.c b/qom/object.c
index 8a1f80f613..622840f9f8 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -2687,17 +2687,20 @@ static char *object_get_type(Object *obj, Error **errp)
         *field = value; \
     }
 
-OBJECT_PROPERTY_SCALAR_GETTER(uint8)
-OBJECT_PROPERTY_SCALAR_SETTER(uint8)
-OBJECT_PROPERTY_SCALAR_GETTER(uint16)
-OBJECT_PROPERTY_SCALAR_SETTER(uint16)
-OBJECT_PROPERTY_SCALAR_GETTER(uint32)
-OBJECT_PROPERTY_SCALAR_SETTER(uint32)
-OBJECT_PROPERTY_SCALAR_GETTER(uint64)
-OBJECT_PROPERTY_SCALAR_SETTER(uint64)
+
+#define DEFINE_OBJECT_PROPERTY_SCALAR_METHODS(type) \
+    OBJECT_PROPERTY_SCALAR_GETTER(type) \
+    OBJECT_PROPERTY_SCALAR_SETTER(type)
+
+
+DEFINE_OBJECT_PROPERTY_SCALAR_METHODS(uint8)
+DEFINE_OBJECT_PROPERTY_SCALAR_METHODS(uint16)
+DEFINE_OBJECT_PROPERTY_SCALAR_METHODS(uint32)
+DEFINE_OBJECT_PROPERTY_SCALAR_METHODS(uint64)
 
 #undef OBJECT_PROPERTY_SCALAR_GETTER
 #undef OBJECT_PROPERTY_SCALAR_SETTER
+#undef DEFINE_OBJECT_PROPERTY_SCALAR_METHODS
 
 
 ObjectProperty *
-- 
2.43.0

[PATCH v2 4/6] qom/object.h: rename @child to @targetp in object_property_add_link() documentation

[Mark Cave-Ayland]

This was missed when updating the parameter name in commit 36854207f0 ("object:
rename link "child" to "target"").

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
Fixes: 36854207f0 ("object: rename link "child" to "target"")
---
 include/qom/object.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/qom/object.h b/include/qom/object.h
index 11f55613fc..4e7fe2af7c 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -1802,8 +1802,8 @@ void object_property_allow_set_link(const Object *obj, const char *name,
  * property is read-only and cannot be set. Care must be taken to handle NULL
  * values for @val.
  *
- * Ownership of the pointer that @child points to is transferred to the
- * link property.  The reference count for *@child is
+ * Ownership of the pointer that @targetp points to is transferred to the
+ * link property.  The reference count for *@targetp is
  * managed by the property from after the function returns till the
  * property is deleted with object_property_del().  If the
  * @flags %OBJ_PROP_LINK_STRONG bit is set,
-- 
2.43.0

[PATCH v2 5/6] qom/object.h: add missing documentation for object_class_* property functions

[Mark Cave-Ayland]

This is so that the object_class_* property functions appear in the generated
QOM documentation at devel/qom-api.html.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
---
 include/qom/object.h | 136 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)

diff --git a/include/qom/object.h b/include/qom/object.h
index 4e7fe2af7c..272c41cac7 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -1818,6 +1818,33 @@ ObjectProperty *object_property_add_link(Object *obj, const char *name,
                                             Object *val, Error **errp),
                               ObjectPropertyLinkFlags flags);
 
+/**
+ * object_class_property_add_link:
+ * @oc: the object class to add a property to
+ * @name: the name of the property
+ * @type: the qobj type of the link
+ * @offset: the offset from the object instance where the link object reference
+ *   is stored
+ * @check: callback to veto setting or NULL if the property is read-only
+ * @flags: additional options for the link
+ *
+ * Links establish relationships between objects.  Links are unidirectional
+ * although two links can be combined to form a bidirectional relationship
+ * between objects.
+ *
+ * Links form the graph in the object model.
+ *
+ * The @check() callback is invoked when object_property_set_link() is called
+ * and can raise an error to prevent the link being set. If @check is NULL, the
+ * property is read-only and cannot be set. Care must be taken to handle NULL
+ * values for @val.
+ *
+ * If the @flags %OBJ_PROP_LINK_STRONG bit is set, the reference count of the
+ * linked object is incremented when the property is set, and decremented again
+ * when the property is modified.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_link(ObjectClass *oc,
                               const char *name,
                               const char *type, ptrdiff_t offset,
@@ -1859,6 +1886,19 @@ ObjectProperty *object_property_add_str(Object *obj, const char *name,
                              char *(*get)(Object *, Error **),
                              void (*set)(Object *, const char *, Error **));
 
+/**
+ * object_class_property_add_str:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @get: the getter or NULL if the property is write-only.  This function must
+ *   return a string to be freed by g_free().
+ * @set: the setter or NULL if the property is read-only
+ *
+ * Add a string property using getters/setters.  This function will add a
+ * property of type 'string'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_str(ObjectClass *klass,
                                    const char *name,
                                    char *(*get)(Object *, Error **),
@@ -1881,6 +1921,18 @@ ObjectProperty *object_property_add_bool(Object *obj, const char *name,
                               bool (*get)(Object *, Error **),
                               void (*set)(Object *, bool, Error **));
 
+/**
+ * object_class_property_add_bool:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @get: the getter or NULL if the property is write-only.
+ * @set: the setter or NULL if the property is read-only
+ *
+ * Add a bool property using getters/setters.  This function will add a
+ * property of type 'bool'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_bool(ObjectClass *klass,
                                     const char *name,
                                     bool (*get)(Object *, Error **),
@@ -1906,6 +1958,20 @@ ObjectProperty *object_property_add_enum(Object *obj, const char *name,
                               int (*get)(Object *, Error **),
                               void (*set)(Object *, int, Error **));
 
+/**
+ * object_class_property_add_enum:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @typename: the name of the enum data type
+ * @lookup: enum value namelookup table
+ * @get: the getter or %NULL if the property is write-only.
+ * @set: the setter or %NULL if the property is read-only
+ *
+ * Add an enum property using getters/setters.  This function will add a
+ * property of type '@typename'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
                                     const char *name,
                                     const char *typename,
@@ -1927,6 +1993,17 @@ ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
 ObjectProperty *object_property_add_tm(Object *obj, const char *name,
                             void (*get)(Object *, struct tm *, Error **));
 
+/**
+ * object_class_property_add_tm:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @get: the getter or NULL if the property is write-only.
+ *
+ * Add a read-only struct tm valued property using a getter function.
+ * This function will add a property of type 'struct tm'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_tm(ObjectClass *klass,
                             const char *name,
                             void (*get)(Object *, struct tm *, Error **));
@@ -1956,6 +2033,18 @@ ObjectProperty *object_property_add_uint8_ptr(Object *obj, const char *name,
                                               const uint8_t *v,
                                               ObjectPropertyFlags flags);
 
+/**
+ * object_class_property_add_uint8_ptr:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @flags: bitwise-or'd ObjectPropertyFlags
+ *
+ * Add an integer property in memory.  This function will add a
+ * property of type 'uint8'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
                                          const char *name,
                                          const uint8_t *v,
@@ -1977,6 +2066,18 @@ ObjectProperty *object_property_add_uint16_ptr(Object *obj, const char *name,
                                     const uint16_t *v,
                                     ObjectPropertyFlags flags);
 
+/**
+ * object_class_property_add_uint16_ptr:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @flags: bitwise-or'd ObjectPropertyFlags
+ *
+ * Add an integer property in memory.  This function will add a
+ * property of type 'uint16'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint16_t *v,
@@ -1998,6 +2099,18 @@ ObjectProperty *object_property_add_uint32_ptr(Object *obj, const char *name,
                                     const uint32_t *v,
                                     ObjectPropertyFlags flags);
 
+/**
+ * object_class_property_add_uint32_ptr:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @flags: bitwise-or'd ObjectPropertyFlags
+ *
+ * Add an integer property in memory.  This function will add a
+ * property of type 'uint32'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint32_t *v,
@@ -2019,6 +2132,18 @@ ObjectProperty *object_property_add_uint64_ptr(Object *obj, const char *name,
                                     const uint64_t *v,
                                     ObjectPropertyFlags flags);
 
+/**
+ * object_class_property_add_uint64_ptr:
+ * @klass: the object class to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @flags: bitwise-or'd ObjectPropertyFlags
+ *
+ * Add an integer property in memory.  This function will add a
+ * property of type 'uint64'.
+ *
+ * Returns: The newly added property on success, or %NULL on failure.
+ */
 ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint64_t *v,
@@ -2075,6 +2200,17 @@ ObjectProperty *object_property_add_const_link(Object *obj, const char *name,
  */
 void object_property_set_description(Object *obj, const char *name,
                                      const char *description);
+
+/**
+ * object_class_property_set_description:
+ * @klass: the object class owning the property
+ * @name: the name of the property
+ * @description: the description of the property on the object
+ *
+ * Set an object property's description.
+ *
+ * Returns: %true on success, %false on failure.
+ */
 void object_class_property_set_description(ObjectClass *klass, const char *name,
                                            const char *description);
 
-- 
2.43.0

[PATCH v2 6/6] qom/object.c: rename object_class_property_uint*_ptr() to object_class_static_property_uint*_ptr()

[Mark Cave-Ayland]

This more accurately reflects that these properties are held within the class and
not the object. Update the documentation to describe the few cases where static
properties should be used.

Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
---
 include/qom/object.h | 56 +++++++++++++++++++++++++++++++-------------
 hw/riscv/spike.c     |  5 ++--
 qom/object.c         | 28 ++++++++++++----------
 3 files changed, 59 insertions(+), 30 deletions(-)

diff --git a/include/qom/object.h b/include/qom/object.h
index 272c41cac7..11b1c9d2dc 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -2034,18 +2034,24 @@ ObjectProperty *object_property_add_uint8_ptr(Object *obj, const char *name,
                                               ObjectPropertyFlags flags);
 
 /**
- * object_class_property_add_uint8_ptr:
- * @klass: the object class to add a property to
+ * object_class_static_property_add_uint8_ptr:
+ * @klass: the object class to add a static property to
  * @name: the name of the property
  * @v: pointer to value
  * @flags: bitwise-or'd ObjectPropertyFlags
  *
- * Add an integer property in memory.  This function will add a
+ * Add a static integer property in memory.  This function will add a
  * property of type 'uint8'.
  *
+ * A static property is one which is stored outside of the object instance,
+ * typically in global variables. It is only appropriate to use static
+ * properties when the class is designed as a singleton. If there is a
+ * possibility of multiple instances, then properties must be stored
+ * per-instance.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
-ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
+ObjectProperty *object_class_static_property_add_uint8_ptr(ObjectClass *klass,
                                          const char *name,
                                          const uint8_t *v,
                                          ObjectPropertyFlags flags);
@@ -2067,18 +2073,24 @@ ObjectProperty *object_property_add_uint16_ptr(Object *obj, const char *name,
                                     ObjectPropertyFlags flags);
 
 /**
- * object_class_property_add_uint16_ptr:
- * @klass: the object class to add a property to
+ * object_class_static_property_add_uint16_ptr:
+ * @klass: the object class to add a static property to
  * @name: the name of the property
  * @v: pointer to value
  * @flags: bitwise-or'd ObjectPropertyFlags
  *
- * Add an integer property in memory.  This function will add a
+ * Add a static integer property in memory.  This function will add a
  * property of type 'uint16'.
  *
+ * A static property is one which is stored outside of the object instance,
+ * typically in global variables. It is only appropriate to use static
+ * properties when the class is designed as a singleton. If there is a
+ * possibility of multiple instances, then properties must be stored
+ * per-instance.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
-ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
+ObjectProperty *object_class_static_property_add_uint16_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint16_t *v,
                                           ObjectPropertyFlags flags);
@@ -2100,18 +2112,24 @@ ObjectProperty *object_property_add_uint32_ptr(Object *obj, const char *name,
                                     ObjectPropertyFlags flags);
 
 /**
- * object_class_property_add_uint32_ptr:
- * @klass: the object class to add a property to
+ * object_class_static_property_add_uint32_ptr:
+ * @klass: the object class to add a static property to
  * @name: the name of the property
  * @v: pointer to value
  * @flags: bitwise-or'd ObjectPropertyFlags
  *
- * Add an integer property in memory.  This function will add a
+ * Add a static integer property in memory.  This function will add a
  * property of type 'uint32'.
  *
+ * A static property is one which is stored outside of the object instance,
+ * typically in global variables. It is only appropriate to use static
+ * properties when the class is designed as a singleton. If there is a
+ * possibility of multiple instances, then properties must be stored
+ * per-instance.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
-ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
+ObjectProperty *object_class_static_property_add_uint32_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint32_t *v,
                                           ObjectPropertyFlags flags);
@@ -2133,18 +2151,24 @@ ObjectProperty *object_property_add_uint64_ptr(Object *obj, const char *name,
                                     ObjectPropertyFlags flags);
 
 /**
- * object_class_property_add_uint64_ptr:
- * @klass: the object class to add a property to
+ * object_class_static_property_add_uint64_ptr:
+ * @klass: the object class to add a static property to
  * @name: the name of the property
  * @v: pointer to value
  * @flags: bitwise-or'd ObjectPropertyFlags
  *
- * Add an integer property in memory.  This function will add a
+ * Add a static integer property in memory.  This function will add a
  * property of type 'uint64'.
  *
+ * A static property is one which is stored outside of the object instance,
+ * typically in global variables. It is only appropriate to use static
+ * properties when the class is designed as a singleton. If there is a
+ * possibility of multiple instances, then properties must be stored
+ * per-instance.
+ *
  * Returns: The newly added property on success, or %NULL on failure.
  */
-ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
+ObjectProperty *object_class_static_property_add_uint64_ptr(ObjectClass *klass,
                                           const char *name,
                                           const uint64_t *v,
                                           ObjectPropertyFlags flags);
diff --git a/hw/riscv/spike.c b/hw/riscv/spike.c
index 9fde0faf39..630b65f569 100644
--- a/hw/riscv/spike.c
+++ b/hw/riscv/spike.c
@@ -278,8 +278,9 @@ static void spike_machine_class_init(ObjectClass *oc, const void *data)
     object_class_property_add_str(oc, "signature", NULL, spike_set_signature);
     object_class_property_set_description(oc, "signature",
                                           "File to write ACT test signature");
-    object_class_property_add_uint8_ptr(oc, "signature-granularity",
-                                        &line_size, OBJ_PROP_FLAG_WRITE);
+    object_class_static_property_add_uint8_ptr(oc, "signature-granularity",
+                                               &line_size,
+                                               OBJ_PROP_FLAG_WRITE);
     object_class_property_set_description(oc, "signature-granularity",
                                           "Size of each line in ACT signature "
                                           "file");
diff --git a/qom/object.c b/qom/object.c
index 622840f9f8..47977b1f44 100644
--- a/qom/object.c
+++ b/qom/object.c
@@ -2724,9 +2724,10 @@ object_property_add_uint8_ptr(Object *obj, const char *name,
 }
 
 ObjectProperty *
-object_class_property_add_uint8_ptr(ObjectClass *klass, const char *name,
-                                    const uint8_t *v,
-                                    ObjectPropertyFlags flags)
+object_class_static_property_add_uint8_ptr(ObjectClass *klass,
+                                           const char *name,
+                                           const uint8_t *v,
+                                           ObjectPropertyFlags flags)
 {
     ObjectPropertyAccessor *getter = NULL;
     ObjectPropertyAccessor *setter = NULL;
@@ -2764,9 +2765,10 @@ object_property_add_uint16_ptr(Object *obj, const char *name,
 }
 
 ObjectProperty *
-object_class_property_add_uint16_ptr(ObjectClass *klass, const char *name,
-                                     const uint16_t *v,
-                                     ObjectPropertyFlags flags)
+object_class_static_property_add_uint16_ptr(ObjectClass *klass,
+                                            const char *name,
+                                            const uint16_t *v,
+                                            ObjectPropertyFlags flags)
 {
     ObjectPropertyAccessor *getter = NULL;
     ObjectPropertyAccessor *setter = NULL;
@@ -2804,9 +2806,10 @@ object_property_add_uint32_ptr(Object *obj, const char *name,
 }
 
 ObjectProperty *
-object_class_property_add_uint32_ptr(ObjectClass *klass, const char *name,
-                                     const uint32_t *v,
-                                     ObjectPropertyFlags flags)
+object_class_static_property_add_uint32_ptr(ObjectClass *klass,
+                                            const char *name,
+                                            const uint32_t *v,
+                                            ObjectPropertyFlags flags)
 {
     ObjectPropertyAccessor *getter = NULL;
     ObjectPropertyAccessor *setter = NULL;
@@ -2844,9 +2847,10 @@ object_property_add_uint64_ptr(Object *obj, const char *name,
 }
 
 ObjectProperty *
-object_class_property_add_uint64_ptr(ObjectClass *klass, const char *name,
-                                     const uint64_t *v,
-                                     ObjectPropertyFlags flags)
+object_class_static_property_add_uint64_ptr(ObjectClass *klass,
+                                            const char *name,
+                                            const uint64_t *v,
+                                            ObjectPropertyFlags flags)
 {
     ObjectPropertyAccessor *getter = NULL;
     ObjectPropertyAccessor *setter = NULL;
-- 
2.43.0

Re: [PATCH v2 4/6] qom/object.h: rename @child to @targetp in object_property_add_link() documentation

[Daniel P. Berrangé]

On Fri, Jul 17, 2026 at 02:51:44PM +0100, Mark Cave-Ayland wrote:
> This was missed when updating the parameter name in commit 36854207f0 ("object:
> rename link "child" to "target"").
> 
> Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
> Fixes: 36854207f0 ("object: rename link "child" to "target"")
> ---
>  include/qom/object.h | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: [PATCH v2 5/6] qom/object.h: add missing documentation for object_class_* property functions

[Daniel P. Berrangé]

On Fri, Jul 17, 2026 at 02:51:45PM +0100, Mark Cave-Ayland wrote:
> This is so that the object_class_* property functions appear in the generated
> QOM documentation at devel/qom-api.html.
> 
> Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
> ---
>  include/qom/object.h | 136 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 136 insertions(+)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: [PATCH v2 6/6] qom/object.c: rename object_class_property_uint*_ptr() to object_class_static_property_uint*_ptr()

[Daniel P. Berrangé]

On Fri, Jul 17, 2026 at 02:51:46PM +0100, Mark Cave-Ayland wrote:
> This more accurately reflects that these properties are held within the class and
> not the object. Update the documentation to describe the few cases where static
> properties should be used.
> 
> Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
> ---
>  include/qom/object.h | 56 +++++++++++++++++++++++++++++++-------------
>  hw/riscv/spike.c     |  5 ++--
>  qom/object.c         | 28 ++++++++++++----------
>  3 files changed, 59 insertions(+), 30 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|