Re: [Qemu-devel] Should the "props" be documented for QMP `object-add`?

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Wed, Jan 09, 2019 at 09:51:13AM +0100, Kashyap Chamarthy wrote:
>> I notice that the following QMP command:
>> 
>>     {
>>       "execute":"object-add",
>>       "arguments":{
>>         "qom-type":"tls-creds-x509",
>>         "id":"objlibvirt_migrate_tls0",
>>         "props":{
>>           "dir":"/etc/pki/qemu",
>>           "endpoint":"server",
>>           "verify-peer":true
>>         }
>>       }
>>     }
>> 
>> ... is the same as its command-line equivalent:
>> 
>>     -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes
>> 
>> That said, in qapi/misc.json "@object-add" doesn't document any of the
>> "props".  Is it on purpose?  Maybe because it is a 1:1 mapping of the
>> command-line `-object` (which _is_ documented in qemu-doc.texi).
>> 
>> Is it a good idea to send a patch to document the "props" in
>> qapi/misc.json?  Or would it be needless duplication?
>
> It is not practical at this time because object_add uses QOM object
> properties and these are exclusively defined in code, not QAPI schema.

Correct.  Same for netdev_add and device_add.

Eric posted patches to fix that netdev_add back in 2016[*], but it got
stuck due to (excessive, in my opinion) concern for staying compabile
with incorrectly typed usage.

device_add and object add are harder.

See also my KVM Forum 2015 talk "QEMU interface introspection: From
hacks to solutions", part IV "Future work".

> There's a long term todo item to use QAPI schema to define QOM objects,
> which would then auto-generate the boilerplate QOM code, at which point
> it all becomes self-documenting. That's basically lacking dev resources
> to work on it though...

I'm not sure moving QOM object specification to the QAPI schema is
practical.  Fortunately, it's not the only way to provide introspection.


[*] Subject: [Qemu-devel] [PATCH for-2.7 v9 00/17] qapi netdev_add
     introspection (post-introspection cleanups subset F)
    Message-Id: <1468468228-27827-1-git-send-email-eblake@redhat.com>
    Date: Wed, 13 Jul 2016 21:50:11 -0600 (2 years, 25 weeks, 3 days ago)
[**] http://www.linux-kvm.org/images/7/7a/02x05-Aspen-Markus_Armbruster-QEMU_interface_introspection.pdf