[PATCH] qom: deprecate use of instance level properties

[PATCH] qom: deprecate use of instance level properties

[Daniel P. Berrangé]

Add API docs to object_property_(add/try_add/del) to recommend
use of class properties instead.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 include/qom/object.h | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/include/qom/object.h b/include/qom/object.h
index 4c0645817a5..d3fddb449f5 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -1171,6 +1171,16 @@ void object_unref(void *obj);
  * @opaque: an opaque pointer to pass to the callbacks for the property
  * @errp: pointer to error object
  *
+ * Further use of this method is deprecated. Properties for an
+ * object should be statically declared against the class, and
+ * not be permitted to vary at runtime. Use the
+ * object_class_property_add() method (and its variants) instead.
+ *
+ * If usage scenarios require differing subsets of properties
+ * to be present, this should be handled by creating further
+ * specialized subclasses instead of dynamically registering
+ * properties against instances.
+ *
  * Returns: The #ObjectProperty; this can be used to set the @resolve
  * callback for child and link properties.
  */
@@ -1183,9 +1193,6 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
 
 /**
  * object_property_add:
- * Same as object_property_try_add() with @errp hardcoded to
- * &error_abort.
- *
  * @obj: the object to add a property to
  * @name: the name of the property.  This can contain any character except for
  *  a forward slash.  In general, you should use hyphens '-' instead of
@@ -1202,6 +1209,12 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
  *   meant to allow a property to free its opaque upon object
  *   destruction.  This may be NULL.
  * @opaque: an opaque pointer to pass to the callbacks for the property
+ *
+ * Same as object_property_try_add() with @errp hardcoded to
+ * &error_abort.
+ *
+ * Further use of this method is deprecated, see
+ * object_property_try_add() for details.
  */
 ObjectProperty *object_property_add(Object *obj, const char *name,
                                     const char *type,
@@ -1210,6 +1223,12 @@ ObjectProperty *object_property_add(Object *obj, const char *name,
                                     ObjectPropertyRelease *release,
                                     void *opaque);
 
+/**
+ * object_property_del:
+ *
+ * Further use of this method is deprecated, see
+ * object_property_try_add() for details.
+ */
 void object_property_del(Object *obj, const char *name);
 
 ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
-- 
2.56.0

Re: [PATCH] qom: deprecate use of instance level properties

[Mark Cave-Ayland]

On 13/10/2026 13:06, Daniel P. Berrangé wrote:

> Add API docs to object_property_(add/try_add/del) to recommend
> use of class properties instead.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   include/qom/object.h | 25 ++++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)
> 
> diff --git a/include/qom/object.h b/include/qom/object.h
> index 4c0645817a5..d3fddb449f5 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -1171,6 +1171,16 @@ void object_unref(void *obj);
>    * @opaque: an opaque pointer to pass to the callbacks for the property
>    * @errp: pointer to error object
>    *
> + * Further use of this method is deprecated. Properties for an
> + * object should be statically declared against the class, and
> + * not be permitted to vary at runtime. Use the
> + * object_class_property_add() method (and its variants) instead.
> + *
> + * If usage scenarios require differing subsets of properties
> + * to be present, this should be handled by creating further
> + * specialized subclasses instead of dynamically registering
> + * properties against instances.
> + *
>    * Returns: The #ObjectProperty; this can be used to set the @resolve
>    * callback for child and link properties.
>    */
> @@ -1183,9 +1193,6 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
>   
>   /**
>    * object_property_add:
> - * Same as object_property_try_add() with @errp hardcoded to
> - * &error_abort.
> - *
>    * @obj: the object to add a property to
>    * @name: the name of the property.  This can contain any character except for
>    *  a forward slash.  In general, you should use hyphens '-' instead of
> @@ -1202,6 +1209,12 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
>    *   meant to allow a property to free its opaque upon object
>    *   destruction.  This may be NULL.
>    * @opaque: an opaque pointer to pass to the callbacks for the property
> + *
> + * Same as object_property_try_add() with @errp hardcoded to
> + * &error_abort.
> + *
> + * Further use of this method is deprecated, see
> + * object_property_try_add() for details.
>    */
>   ObjectProperty *object_property_add(Object *obj, const char *name,
>                                       const char *type,
> @@ -1210,6 +1223,12 @@ ObjectProperty *object_property_add(Object *obj, const char *name,
>                                       ObjectPropertyRelease *release,
>                                       void *opaque);
>   
> +/**
> + * object_property_del:
> + *
> + * Further use of this method is deprecated, see
> + * object_property_try_add() for details.
> + */
>   void object_property_del(Object *obj, const char *name);
>   
>   ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,

Looks good to me, and at least it means LLMs should pick up the 
recommended usage going forward. Do we also want to update checkpatch.pl 
to emit a warning if someone uses these legacy functions so that it gets 
flagged during local testing/CI too?

Anyhow:
Reviewed-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>


ATB,

Mark.

Re: [PATCH] qom: deprecate use of instance level properties

[Daniel P. Berrangé]

On Wed, Oct 14, 2026 at 10:05:01AM +0100, Mark Cave-Ayland wrote:
> On 13/10/2026 13:06, Daniel P. Berrangé wrote:
> 
> > Add API docs to object_property_(add/try_add/del) to recommend
> > use of class properties instead.
> > 
> > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> > ---
> >   include/qom/object.h | 25 ++++++++++++++++++++++---
> >   1 file changed, 22 insertions(+), 3 deletions(-)
> > 
> > diff --git a/include/qom/object.h b/include/qom/object.h
> > index 4c0645817a5..d3fddb449f5 100644
> > --- a/include/qom/object.h
> > +++ b/include/qom/object.h
> > @@ -1171,6 +1171,16 @@ void object_unref(void *obj);
> >    * @opaque: an opaque pointer to pass to the callbacks for the property
> >    * @errp: pointer to error object
> >    *
> > + * Further use of this method is deprecated. Properties for an
> > + * object should be statically declared against the class, and
> > + * not be permitted to vary at runtime. Use the
> > + * object_class_property_add() method (and its variants) instead.
> > + *
> > + * If usage scenarios require differing subsets of properties
> > + * to be present, this should be handled by creating further
> > + * specialized subclasses instead of dynamically registering
> > + * properties against instances.
> > + *
> >    * Returns: The #ObjectProperty; this can be used to set the @resolve
> >    * callback for child and link properties.
> >    */
> > @@ -1183,9 +1193,6 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
> >   /**
> >    * object_property_add:
> > - * Same as object_property_try_add() with @errp hardcoded to
> > - * &error_abort.
> > - *
> >    * @obj: the object to add a property to
> >    * @name: the name of the property.  This can contain any character except for
> >    *  a forward slash.  In general, you should use hyphens '-' instead of
> > @@ -1202,6 +1209,12 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
> >    *   meant to allow a property to free its opaque upon object
> >    *   destruction.  This may be NULL.
> >    * @opaque: an opaque pointer to pass to the callbacks for the property
> > + *
> > + * Same as object_property_try_add() with @errp hardcoded to
> > + * &error_abort.
> > + *
> > + * Further use of this method is deprecated, see
> > + * object_property_try_add() for details.
> >    */
> >   ObjectProperty *object_property_add(Object *obj, const char *name,
> >                                       const char *type,
> > @@ -1210,6 +1223,12 @@ ObjectProperty *object_property_add(Object *obj, const char *name,
> >                                       ObjectPropertyRelease *release,
> >                                       void *opaque);
> > +/**
> > + * object_property_del:
> > + *
> > + * Further use of this method is deprecated, see
> > + * object_property_try_add() for details.
> > + */
> >   void object_property_del(Object *obj, const char *name);
> >   ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
> 
> Looks good to me, and at least it means LLMs should pick up the recommended
> usage going forward. Do we also want to update checkpatch.pl to emit a
> warning if someone uses these legacy functions so that it gets flagged
> during local testing/CI too?

As long as we have piles of code still using the old instance level
APIs remaining to be converted, I think a checkpatch test will be
too annoying.

> Anyhow:
> Reviewed-by: Mark Cave-Ayland <mark.caveayland@nutanix.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] qom: deprecate use of instance level properties

[Mark Cave-Ayland]

On 14/10/2026 10:11, Daniel P. Berrangé wrote:

> On Wed, Oct 14, 2026 at 10:05:01AM +0100, Mark Cave-Ayland wrote:
>> On 13/10/2026 13:06, Daniel P. Berrangé wrote:
>>
>>> Add API docs to object_property_(add/try_add/del) to recommend
>>> use of class properties instead.
>>>
>>> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
>>> ---
>>>    include/qom/object.h | 25 ++++++++++++++++++++++---
>>>    1 file changed, 22 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/include/qom/object.h b/include/qom/object.h
>>> index 4c0645817a5..d3fddb449f5 100644
>>> --- a/include/qom/object.h
>>> +++ b/include/qom/object.h
>>> @@ -1171,6 +1171,16 @@ void object_unref(void *obj);
>>>     * @opaque: an opaque pointer to pass to the callbacks for the property
>>>     * @errp: pointer to error object
>>>     *
>>> + * Further use of this method is deprecated. Properties for an
>>> + * object should be statically declared against the class, and
>>> + * not be permitted to vary at runtime. Use the
>>> + * object_class_property_add() method (and its variants) instead.
>>> + *
>>> + * If usage scenarios require differing subsets of properties
>>> + * to be present, this should be handled by creating further
>>> + * specialized subclasses instead of dynamically registering
>>> + * properties against instances.
>>> + *
>>>     * Returns: The #ObjectProperty; this can be used to set the @resolve
>>>     * callback for child and link properties.
>>>     */
>>> @@ -1183,9 +1193,6 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
>>>    /**
>>>     * object_property_add:
>>> - * Same as object_property_try_add() with @errp hardcoded to
>>> - * &error_abort.
>>> - *
>>>     * @obj: the object to add a property to
>>>     * @name: the name of the property.  This can contain any character except for
>>>     *  a forward slash.  In general, you should use hyphens '-' instead of
>>> @@ -1202,6 +1209,12 @@ ObjectProperty *object_property_try_add(Object *obj, const char *name,
>>>     *   meant to allow a property to free its opaque upon object
>>>     *   destruction.  This may be NULL.
>>>     * @opaque: an opaque pointer to pass to the callbacks for the property
>>> + *
>>> + * Same as object_property_try_add() with @errp hardcoded to
>>> + * &error_abort.
>>> + *
>>> + * Further use of this method is deprecated, see
>>> + * object_property_try_add() for details.
>>>     */
>>>    ObjectProperty *object_property_add(Object *obj, const char *name,
>>>                                        const char *type,
>>> @@ -1210,6 +1223,12 @@ ObjectProperty *object_property_add(Object *obj, const char *name,
>>>                                        ObjectPropertyRelease *release,
>>>                                        void *opaque);
>>> +/**
>>> + * object_property_del:
>>> + *
>>> + * Further use of this method is deprecated, see
>>> + * object_property_try_add() for details.
>>> + */
>>>    void object_property_del(Object *obj, const char *name);
>>>    ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
>>
>> Looks good to me, and at least it means LLMs should pick up the recommended
>> usage going forward. Do we also want to update checkpatch.pl to emit a
>> warning if someone uses these legacy functions so that it gets flagged
>> during local testing/CI too?
> 
> As long as we have piles of code still using the old instance level
> APIs remaining to be converted, I think a checkpatch test will be
> too annoying.
I'll take that as a hint to continue chipping away at converting devices 
under hw/ then ;)


ATB,

Mark.

Re: [PATCH] qom: deprecate use of instance level properties

[Philippe Mathieu-Daudé]

On 13/10/26 14:06, Daniel P. Berrangé wrote:
> Add API docs to object_property_(add/try_add/del) to recommend
> use of class properties instead.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   include/qom/object.h | 25 ++++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>