Re: [PATCH for-9.0] qapi: Add 'recurse-children' option to qom-list

[Markus Armbruster <armbru@redhat.com>]

Alberto Garcia <berto@igalia.com> writes:

> This allows returning a tree of all object properties under a given
> path, in a way similar to scripts/qmp/qom-tree.

Use case?  We already have that script, and also HMP info qom-tree.

> Signed-off-by: Alberto Garcia <berto@igalia.com>
> ---
>  qapi/qom.json      | 10 +++++++++-
>  qom/qom-hmp-cmds.c |  4 ++--
>  qom/qom-qmp-cmds.c | 22 +++++++++++++++++++++-
>  3 files changed, 32 insertions(+), 4 deletions(-)
>
> diff --git a/qapi/qom.json b/qapi/qom.json
> index c53ef978ff..dfe3a20725 100644
> --- a/qapi/qom.json
> +++ b/qapi/qom.json
> @@ -33,6 +33,10 @@
>  #        qdev device type name.  Link properties form the device model
>  #        graph.
>  #
> +# @children: if specified, a list of @ObjectPropertyInfo describing

Suggest "if present".

> +#     the child properties. This requires that this property's @type
> +#     is of the form 'child<subtype>' (since 9.0)

But when will it be present?

In qom-list-properties's return value: never.

In qom-list's return value: if and only if passed recurse-children=true.

Awkward to document.

> +#
>  # @description: if specified, the description of the property.
>  #
>  # @default-value: the default value, if any (since 5.0)
> @@ -42,6 +46,7 @@
>  { 'struct': 'ObjectPropertyInfo',
>    'data': { 'name': 'str',
>              'type': 'str',
> +            '*children' :  [ 'ObjectPropertyInfo' ],
>              '*description': 'str',
>              '*default-value': 'any' } }
>  
> @@ -54,6 +59,9 @@
>  # @path: the path within the object model.  See @qom-get for a
>  #     description of this parameter.
>  #
> +# @recurse-children: if true, include the child properties recursively
> +#     in the return value (default: false) (since 9.0)

Insufficiently clear on the connection to ObjectPropertyInfo member
@children, I'm afraid.

> +#
>  # Returns: a list of @ObjectPropertyInfo that describe the properties
>  #     of the object.
>  #
> @@ -69,7 +77,7 @@
>  #                  { "name": "mon0", "type": "child<chardev-stdio>" } ] }
>  ##
>  { 'command': 'qom-list',
> -  'data': { 'path': 'str' },
> +  'data': { 'path': 'str', '*recurse-children': 'bool' },
>    'returns': [ 'ObjectPropertyInfo' ],
>    'allow-preconfig': true }
>  

[...]