[Qemu-devel] qdev properties vs qom object properties

[Qemu-devel] qdev properties vs qom object properties

[Peter Maydell]

I perpetually get confused about qdev properties vs QOM object
properties.

Why do we have both of these APIs?
How do they interact?
Which is the recommended one for new device code?
Do we have a transition plan for old code?
Where should I be looking for the documentation on this?

For a specific example, I see that target/arm is the only code
using qdev_property_add_static(), but there's no indication
that the function is deprecated or what the right thing to be
doing instead is. Any suggestions?

thanks
-- PMM

Re: [Qemu-devel] qdev properties vs qom object properties

[Paolo Bonzini]

On 05/06/2017 15:10, Peter Maydell wrote:
> I perpetually get confused about qdev properties vs QOM object
> properties.
> 
> Why do we have both of these APIs?
> How do they interact?

qdev properties are just a wrapper around QOM object properties, taking
care of:

- not allowing to set the property after realize

- providing default values

- letting people use the familiar DEFINE_PROP_* array syntax

- pretty printing for "info qtree" (which right now is only used by PCI
devfn and vlan properties)

> Which is the recommended one for new device code?
> Do we have a transition plan for old code?
> Where should I be looking for the documentation on this?

There is no transition plan, qdev properties are not going to go away
soon unless someone actually makes a plan.

Now that there are QOM class properties, it would actually be feasible
to make qdev_property_add_static define QOM properties on the class
rather than the object.  In other words, instead of

    dc->props = virtio_serial_pci_properties;

you'd have something like:

    qdev_add_class_properties(klass, usb_tablet_properties);

or even inlined calls like the following:

    QDEV_DEFINE_CLASS_PROP_UINT32(klass, "usb_version", USBHIDState,
                                  usb_version, 2);
    QDEV_DEFINE_CLASS_PROP_STRING(klass, "display", USBHIDState,
                                  display);
    QDEV_DEFINE_CLASS_PROP_UINT32(klass, "head", USBHIDState, head, 0);

> For a specific example, I see that target/arm is the only code
> using qdev_property_add_static(), but there's no indication
> that the function is deprecated or what the right thing to be
> doing instead is. Any suggestions?

The weird thing in ARM code is that the set of properties depends on the
CPU model.  That's the only reason why it uses
qdev_property_add_static() as far as I can see.

Paolo

Re: [Qemu-devel] qdev properties vs qom object properties

[Eduardo Habkost]

On Mon, Jun 05, 2017 at 02:10:06PM +0100, Peter Maydell wrote:
> I perpetually get confused about qdev properties vs QOM object
> properties.

You are not alone.  :)

> 
> Why do we have both of these APIs?

I don't know.  Probably because the QOM property API was
introduced, it was just a subset of of the features provided by
qdev properties, so the qdev API had to be kept.


> How do they interact?

qdev properties are implemented on top of the QOM property APIs.
After the properties are registered by qdev code, we can simply
use the QOM APIs to interact with them (to get/set/enumerate
properties).

But qdev provide some extra features[1], that's why we can't
simply replace all code using qdev properties to use the QOM APIs
directly.

[1] Some of the differences I remember:
* qdev properties can be defined declaratively using
  using Property arrays.
* qdev properties allows you to set a default value more clearly
  in the code.
* qdev properties don't require custom getters/setters to be
  written.  You just need to provide the field name (which is
  saved as a field offset by the DEFINE_PROP_* macros).
* qdev setters automatically check if "realized" is true, and
  refuse to change a property after the device is realized.
* some existing code (mostly monitor code, I think) looks for
  qdev properties only, but will ignore other QOM properties.
* A few data types (and their corresponding parsers) are only
  defined as qdev types (PropertyInfo structs), not on the QAPI
  schema.


> Which is the recommended one for new device code?

qdev properties are easier to use, so I recommend using them
unless you need custom getters/setters.


> Do we have a transition plan for old code?

We don't.  I believe we should first make the QOM API as powerful
as the qdev property API.  Then we can replace qdev-specific code
with equivalent QOM code.


> Where should I be looking for the documentation on this?

Good question.  The QOM API is well documented, but the way the
qdev property code interacts with the QOM API is not.


> 
> For a specific example, I see that target/arm is the only code
> using qdev_property_add_static(), but there's no indication
> that the function is deprecated or what the right thing to be
> doing instead is. Any suggestions?

qdev_property_static() is still easier to use than writing custom
getters/setters for object_property_add(), so I don't think we
should deprecate it yet.

-- 
Eduardo

Re: [Qemu-devel] qdev properties vs qom object properties

[Eduardo Habkost]

On Mon, Jun 05, 2017 at 03:32:56PM +0200, Paolo Bonzini wrote:
[...]
> > Which is the recommended one for new device code?
> > Do we have a transition plan for old code?
> > Where should I be looking for the documentation on this?
> 
> There is no transition plan, qdev properties are not going to go away
> soon unless someone actually makes a plan.
> 
> Now that there are QOM class properties, it would actually be feasible
> to make qdev_property_add_static define QOM properties on the class
> rather than the object.  In other words, instead of
> 
>     dc->props = virtio_serial_pci_properties;
> 
> you'd have something like:
> 
>     qdev_add_class_properties(klass, usb_tablet_properties);

I have an old branch that does that.  I don't remember if I
submitted it to qemu-devel.  I will try to rebase and (re)submit
it.

-- 
Eduardo

Re: [Qemu-devel] qdev properties vs qom object properties

[Paolo Bonzini]

On 05/06/2017 15:36, Eduardo Habkost wrote:
> On Mon, Jun 05, 2017 at 02:10:06PM +0100, Peter Maydell wrote:
>> Why do we have both of these APIs?
> 
> I don't know.  Probably because the QOM property API was
> introduced, it was just a subset of of the features provided by
> qdev properties, so the qdev API had to be kept.

Indeed---especially there were no QOM class properties (and there are
still no default values, which is the other place where we walk the
props array).

Paolo

Re: [Qemu-devel] qdev properties vs qom object properties

[Markus Armbruster]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 05/06/2017 15:10, Peter Maydell wrote:
>> I perpetually get confused about qdev properties vs QOM object
>> properties.
>> 
>> Why do we have both of these APIs?
>> How do they interact?
>
> qdev properties are just a wrapper around QOM object properties, taking
> care of:
>
> - not allowing to set the property after realize
>
> - providing default values
>
> - letting people use the familiar DEFINE_PROP_* array syntax

It's not just familiar, it's also much easier to reason about, because
it's *data*, not code.  For instance, when I see DEFINE_PROP_UINT8(), I
immediately know it's uint8_t.  With QOM, I commonly have to figure out
WTF the getter and setter will do at run time.  I spent a few hours last
week doing just that, and it sure feels like a severe case of OOPitis to
me.

Message-ID: <877f1ep4xv.fsf@dusky.pond.sub.org>
https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg04353.html

> - pretty printing for "info qtree" (which right now is only used by PCI
> devfn and vlan properties)
>
>> Which is the recommended one for new device code?
>> Do we have a transition plan for old code?
>> Where should I be looking for the documentation on this?
>
> There is no transition plan, qdev properties are not going to go away
> soon unless someone actually makes a plan.

Any plan to replace properties defined as data by properties defined in
code will be a hard sell with me.  I think we should go back to data
unless the problem at hand *requires* code.

> Now that there are QOM class properties, it would actually be feasible
> to make qdev_property_add_static define QOM properties on the class
> rather than the object.  In other words, instead of
>
>     dc->props = virtio_serial_pci_properties;
>
> you'd have something like:
>
>     qdev_add_class_properties(klass, usb_tablet_properties);
>
> or even inlined calls like the following:
>
>     QDEV_DEFINE_CLASS_PROP_UINT32(klass, "usb_version", USBHIDState,
>                                   usb_version, 2);
>     QDEV_DEFINE_CLASS_PROP_STRING(klass, "display", USBHIDState,
>                                   display);
>     QDEV_DEFINE_CLASS_PROP_UINT32(klass, "head", USBHIDState, head, 0);

Sufficiently restricted code can be almost as simple as data.  Still,
why not make it data?  Your examples scream to be data.

>> For a specific example, I see that target/arm is the only code
>> using qdev_property_add_static(), but there's no indication
>> that the function is deprecated or what the right thing to be
>> doing instead is. Any suggestions?
>
> The weird thing in ARM code is that the set of properties depends on the
> CPU model.  That's the only reason why it uses
> qdev_property_add_static() as far as I can see.
>
> Paolo

Re: [Qemu-devel] qdev properties vs qom object properties

[Gerd Hoffmann]

  Hi,

> Any plan to replace properties defined as data by properties defined
> in
> code will be a hard sell with me.  I think we should go back to data
> unless the problem at hand *requires* code.

There *are* some cases which require code, specifically QOM properties
which are writable after realize as they typically need some code to
apply the changes.

But, yes, the majority of properties we have in tree doesn't need that
(realize callback will handle them) and qdev properties are a perfect
fit for those.

cheers,
  Gerd