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

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

[Kashyap Chamarthy]

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?

-- 
/kashyap

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

[Philippe Mathieu-Daudé]

Hi Kashyap,

On 1/9/19 9:51 AM, 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?

IMHO the 1:1 mapping is only obvious for developpers who implement such
commands and for 3rd party libs using QMP.
For end-users, a command-line comment is helpful.

This remind me of this patch:

https://lists.gnu.org/archive/html/qemu-devel/2018-11/msg06623.html

+/**
+ * QAuthZSimple:
+ *
+ * This authorization driver provides a simple mechanism
+ * for granting access based on an exact matched username.
+ *
+ * To create an instance of this class via QMP:
+ *
+ *  {
+ *    "execute": "object-add",
+ *    "arguments": {
+ *      "qom-type": "authz-simple",
+ *      "id": "authz0",
+ *      "parameters": {
+ *        "identity": "fred"
+ *      }
+ *    }
+ *  }
+ *
+ * Or via the command line
+ *
+ *   -object authz-simple,id=authz0,identity=fred
+ *
+ */

Regards,

Phil.

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

[Kashyap Chamarthy]

On Wed, Jan 09, 2019 at 11:31:18AM +0100, Philippe Mathieu-Daudé wrote:
> Hi Kashyap,

Hi,

> On 1/9/19 9:51 AM, Kashyap Chamarthy wrote:

[...]

> > 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?
> 
> IMHO the 1:1 mapping is only obvious for developpers who implement such
> commands and for 3rd party libs using QMP.

Even for developers who use QMP to implement higher layer tools, it
might take non-trivial amount of squinting to realize that it's a 1:1
mapping.  It should at least be mentioned in the relevant QMP doc
("explicit is better than implicit").  I'll submit a patch and see if it
flies. :-)

> For end-users, a command-line comment is helpful.
> 
> This remind me of this patch:
> 
> https://lists.gnu.org/archive/html/qemu-devel/2018-11/msg06623.html
> 
> +/**
> + * QAuthZSimple:
> + *
> + * This authorization driver provides a simple mechanism
> + * for granting access based on an exact matched username.
> + *
> + * To create an instance of this class via QMP:
> + *
> + *  {
> + *    "execute": "object-add",
> + *    "arguments": {
> + *      "qom-type": "authz-simple",
> + *      "id": "authz0",
> + *      "parameters": {
> + *        "identity": "fred"
> + *      }
> + *    }
> + *  }
> + *
> + * Or via the command line
> + *
> + *   -object authz-simple,id=authz0,identity=fred

Yeah, that's a convenient example.  And in this specific case, it is
useful for those reading the code.

-- 
/kashyap

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

[Daniel P. Berrangé]

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.

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...


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Kashyap Chamarthy]

On Wed, Jan 09, 2019 at 11:02:08AM +0000, Daniel P. Berrangé wrote:
> On Wed, Jan 09, 2019 at 09:51:13AM +0100, Kashyap Chamarthy wrote:

[...]

> > 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.
> 
> 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. 

Didn't know about this; thanks for the background.  Then, I'll hold off
submitting any patch to qapi/misc.json.

> That's basically lacking dev resources to work on it though...

Noted.

[...]

-- 
/kashyap

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

[Markus Armbruster]

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