Re: [PATCH v12 7/8] qmp: add QMP command x-query-virtio-queue-element

[Markus Armbruster <armbru@redhat.com>]

Jonah Palmer <jonah.palmer@oracle.com> writes:

> From: Laurent Vivier <lvivier@redhat.com>
>
> This new command shows the information of a VirtQueue element.
>
> [Note: Up until v10 of this patch series, virtio.json had many (15+)
>  enums defined (e.g. decoded device features, statuses, etc.). In v10
>  most of these enums were removed and replaced with string literals.
>  By doing this we get (1) simpler schema, (2) smaller generated code,
>  and (3) less maintenance burden for when new things are added (e.g.
>  devices, device features, etc.).]
>
> Signed-off-by: Jonah Palmer <jonah.palmer@oracle.com>

[...]

> diff --git a/qapi/virtio.json b/qapi/virtio.json
> index 44cc05c..bb93d6d 100644
> --- a/qapi/virtio.json
> +++ b/qapi/virtio.json
> @@ -656,3 +656,186 @@
>    'data': { 'path': 'str', 'queue': 'uint16' },
>    'returns': 'VirtVhostQueueStatus',
>    'features': [ 'unstable' ] }
> +
> +##
> +# @VirtioRingDesc:
> +#
> +# Information regarding the vring descriptor area
> +#
> +# @addr: Guest physical address of the descriptor area
> +#
> +# @len: Length of the descriptor area
> +#
> +# @flags: List of descriptor flags
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtioRingDesc',
> +  'data': { 'addr': 'uint64',
> +            'len': 'uint32',
> +            'flags': [ 'str' ] } }
> +
> +##
> +# @VirtioRingAvail:
> +#
> +# Information regarding the avail vring (a.k.a. driver area)
> +#
> +# @flags: VRingAvail flags
> +#
> +# @idx: VRingAvail index
> +#
> +# @ring: VRingAvail ring[] entry at provided index
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtioRingAvail',
> +  'data': { 'flags': 'uint16',
> +            'idx': 'uint16',
> +            'ring': 'uint16' } }
> +
> +##
> +# @VirtioRingUsed:
> +#
> +# Information regarding the used vring (a.k.a. device area)
> +#
> +# @flags: VRingUsed flags
> +#
> +# @idx: VRingUsed index
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtioRingUsed',
> +  'data': { 'flags': 'uint16',
> +            'idx': 'uint16' } }
> +
> +##
> +# @VirtioQueueElement:
> +#
> +# Information regarding a VirtQueue's VirtQueueElement including
> +# descriptor, driver, and device areas
> +#
> +# @name: Name of the VirtIODevice that uses this VirtQueue
> +#
> +# @index: Index of the element in the queue
> +#
> +# @descs: List of descriptors (VirtioRingDesc)
> +#
> +# @avail: VRingAvail info
> +#
> +# @used: VRingUsed info
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtioQueueElement',
> +  'data': { 'name': 'str',
> +            'index': 'uint32',
> +            'descs': [ 'VirtioRingDesc' ],
> +            'avail': 'VirtioRingAvail',
> +            'used': 'VirtioRingUsed' } }
> +
> +##
> +# @x-query-virtio-queue-element:
> +#
> +# Return the information about a VirtQueue's VirtQueueElement
> +# (default: head of the queue)

I'd put this line ...

> +#
> +# @path: VirtIODevice canonical QOM path
> +#
> +# @queue: VirtQueue index to examine
> +#
> +# @index: Index of the element in the queue

... here.

> +#
> +# Features:
> +# @unstable: This command is meant for debugging.
> +#
> +# Returns: VirtioQueueElement information
> +#
> +# Since: 7.0
> +#
> +# Examples:
> +#
> +# 1. Introspect on virtio-net's VirtQueue 0 at index 5
> +#
> +# -> { "execute": "x-query-virtio-queue-element",
> +#      "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
> +#                     "queue": 0,
> +#                     "index": 5 }
> +#    }
> +# <- { "return": {
> +#            "index": 5,
> +#            "name": "virtio-net",
> +#            "descs": [
> +#               { "flags": ["write"], "len": 1536, "addr": 5257305600 }
> +#            ],
> +#            "avail": {
> +#               "idx": 256,
> +#               "flags": 0,
> +#               "ring": 5
> +#            },
> +#            "used": {
> +#               "idx": 13,
> +#               "flags": 0
> +#            },
> +#    }
> +#
> +# 2. Introspect on virtio-crypto's VirtQueue 1 at head
> +#
> +# -> { "execute": "x-query-virtio-queue-element",
> +#      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
> +#                     "queue": 1 }
> +#    }
> +# <- { "return": {
> +#            "index": 0,
> +#            "name": "virtio-crypto",
> +#            "descs": [
> +#               { "flags": [], "len": 0, "addr": 8080268923184214134 }
> +#            ],
> +#            "avail": {
> +#               "idx": 280,
> +#               "flags": 0,
> +#               "ring": 0
> +#            },
> +#            "used": {
> +#               "idx": 280,
> +#               "flags": 0
> +#            }
> +#    }
> +#
> +# 3. Introspect on virtio-scsi's VirtQueue 2 at head
> +#
> +# -> { "execute": "x-query-virtio-queue-element",
> +#      "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
> +#                     "queue": 2 }
> +#    }
> +# <- { "return": {
> +#            "index": 19,
> +#            "name": "virtio-scsi",
> +#            "descs": [
> +#               { "flags": ["used", "indirect", "write"], "len": 4099327944,
> +#                 "addr": 12055409292258155293 }
> +#            ],
> +#            "avail": {
> +#               "idx": 1147,
> +#               "flags": 0,
> +#               "ring": 19
> +#            },
> +#            "used": {
> +#               "idx": 280,
> +#               "flags": 0
> +#            }
> +#    }
> +#
> +##
> +
> +{ 'command': 'x-query-virtio-queue-element',
> +  'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
> +  'returns': 'VirtioQueueElement',
> +  'features': [ 'unstable' ] }

Preferably with my doc tweak, QAPI schema
Acked-by: Markus Armbruster <armbru@redhat.com>