Jonah Palmer <jonah.pal...@oracle.com> writes:
> From: Laurent Vivier <lviv...@redhat.com>
>
> These new commands show the internal status of a VirtIODevice's
> VirtQueue and a vhost device's vhost_virtqueue (if active).
>
> Signed-off-by: Jonah Palmer <jonah.pal...@oracle.com>
> ---
[...]
> diff --git a/qapi/virtio.json b/qapi/virtio.json
> index 7ef1f95..56e56d2 100644
> --- a/qapi/virtio.json
> +++ b/qapi/virtio.json
> @@ -402,3 +402,255 @@
> 'data': { 'transports': [ 'str' ],
> '*dev-features': [ 'str' ],
> '*unknown-dev-features': 'uint64' } }
> +
> +##
> +# @VirtQueueStatus:
> +#
> +# Information of a VirtIODevice VirtQueue, including most members of
> +# the VirtQueue data structure.
> +#
> +# @name: Name of the VirtIODevice that uses this VirtQueue
> +#
> +# @queue-index: VirtQueue queue_index
> +#
> +# @inuse: VirtQueue inuse
> +#
> +# @vring-num: VirtQueue vring.num
> +#
> +# @vring-num-default: VirtQueue vring.num_default
> +#
> +# @vring-align: VirtQueue vring.align
> +#
> +# @vring-desc: VirtQueue vring.desc (descriptor area)
> +#
> +# @vring-avail: VirtQueue vring.avail (driver area)
> +#
> +# @vring-used: VirtQueue vring.used (device area)
> +#
> +# @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
> +# vhost_get_vring_base (if vhost active)
> +#
> +# @shadow-avail-idx: VirtQueue shadow_avail_idx
> +#
> +# @used-idx: VirtQueue used_idx
> +#
> +# @signalled-used: VirtQueue signalled_used
> +#
> +# @signalled-used-valid: VirtQueue signalled_used_valid flag
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtQueueStatus',
> + 'data': { 'name': 'str',
> + 'queue-index': 'uint16',
> + 'inuse': 'uint32',
> + 'vring-num': 'uint32',
> + 'vring-num-default': 'uint32',
> + 'vring-align': 'uint32',
> + 'vring-desc': 'uint64',
> + 'vring-avail': 'uint64',
> + 'vring-used': 'uint64',
> + '*last-avail-idx': 'uint16',
> + '*shadow-avail-idx': 'uint16',
> + 'used-idx': 'uint16',
> + 'signalled-used': 'uint16',
> + 'signalled-used-valid': 'bool' } }
> +
> +##
> +# @x-query-virtio-queue-status:
> +#
> +# Return the status of a given VirtIODevice's VirtQueue
> +#
> +# @path: VirtIODevice canonical QOM path
> +#
> +# @queue: VirtQueue index to examine
> +#
> +# Features:
> +# @unstable: This command is meant for debugging
End with a period for consistency with existing docs, like you did in
v9.
> +#
> +# Returns: VirtQueueStatus of the VirtQueue
> +#
> +# Notes: last_avail_idx will not be displayed in the case where
> +# the selected VirtIODevice has a running vhost device and
> +# the VirtIODevice VirtQueue index (queue) does not exist for
> +# the corresponding vhost device vhost_virtqueue. Also,
> +# shadow_avail_idx will not be displayed in the case where
> +# the selected VirtIODevice has a running vhost device.
> +#
> +# Since: 7.0
> +#
> +# Examples:
> +#
> +# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
> +#
> +# -> { "execute": "x-query-virtio-queue-status",
> +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
> +# "queue": 1 }
> +# }
> +# <- { "return": {
> +# "signalled-used": 0,
> +# "inuse": 0,
> +# "vring-align": 4096,
> +# "vring-desc": 5217370112,
> +# "signalled-used-valid": false,
> +# "vring-num-default": 128,
> +# "vring-avail": 5217372160,
> +# "queue-index": 1,
> +# "last-avail-idx": 0,
> +# "vring-used": 5217372480,
> +# "used-idx": 0,
> +# "name": "vhost-vsock",
> +# "vring-num": 128 }
> +# }
> +#
> +# 2. Get VirtQueueStatus for virtio-serial (no vhost)
> +#
> +# -> { "execute": "x-query-virtio-queue-status",
> +# "arguments": { "path":
> "/machine/peripheral-anon/device[0]/virtio-backend",
> +# "queue": 20 }
> +# }
> +# <- { "return": {
> +# "signalled-used": 0,
> +# "inuse": 0,
> +# "vring-align": 4096,
> +# "vring-desc": 5182074880,
> +# "signalled-used-valid": false,
> +# "vring-num-default": 128,
> +# "vring-avail": 5182076928,
> +# "queue-index": 20,
> +# "last-avail-idx": 0,
> +# "vring-used": 5182077248,
> +# "used-idx": 0,
> +# "name": "virtio-serial",
> +# "shadow-avail-idx": 0,
> +# "vring-num": 128 }
> +# }
> +#
> +##
> +
> +{ 'command': 'x-query-virtio-queue-status',
> + 'data': { 'path': 'str', 'queue': 'uint16' },
> + 'returns': 'VirtQueueStatus',
> + 'features': [ 'unstable' ] }
> +
> +##
> +# @VirtVhostQueueStatus:
> +#
> +# Information of a vhost device's vhost_virtqueue, including most
> +# members of the vhost_dev vhost_virtqueue data structure.
> +#
> +# @name: Name of the VirtIODevice that uses this vhost_virtqueue
> +#
> +# @kick: vhost_virtqueue kick
> +#
> +# @call: vhost_virtqueue call
> +#
> +# @desc: vhost_virtqueue desc
> +#
> +# @avail: vhost_virtqueue avail
> +#
> +# @used: vhost_virtqueue used
> +#
> +# @num: vhost_virtqueue num
> +#
> +# @desc-phys: vhost_virtqueue desc_phys (descriptor area phys. addr.)
> +#
> +# @desc-size: vhost_virtqueue desc_size
> +#
> +# @avail-phys: vhost_virtqueue avail_phys (driver area phys. addr.)
> +#
> +# @avail-size: vhost_virtqueue avail_size
> +#
> +# @used-phys: vhost_virtqueue used_phys (device area phys. addr.)
> +#
> +# @used-size: vhost_virtqueue used_size
> +#
> +# Since: 7.0
> +#
> +##
> +
> +{ 'struct': 'VirtVhostQueueStatus',
> + 'data': { 'name': 'str',
> + 'kick': 'int',
> + 'call': 'int',
> + 'desc': 'uint64',
> + 'avail': 'uint64',
> + 'used': 'uint64',
> + 'num': 'int',
> + 'desc-phys': 'uint64',
> + 'desc-size': 'uint32',
> + 'avail-phys': 'uint64',
> + 'avail-size': 'uint32',
> + 'used-phys': 'uint64',
> + 'used-size': 'uint32' } }
> +
> +##
> +# @x-query-virtio-vhost-queue-status:
> +#
> +# Return information of a given vhost device's vhost_virtqueue
> +#
> +# @path: VirtIODevice canonical QOM path
> +#
> +# @queue: vhost_virtqueue index to examine
> +#
> +# Features:
> +# @unstable: This command ism eant for debugging
Likewise.
"is meant", like in v9.
> +#
> +# Returns: VirtVhostQueueStatus of the vhost_virtqueue
> +#
> +# Since: 7.0
> +#
> +# Examples:
> +#
> +# 1. Get vhost_virtqueue status for vhost-crypto
> +#
> +# -> { "execute": "x-query-virtio-vhost-queue-status",
> +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
> +# "queue": 0 }
> +# }
> +# <- { "return": {
> +# "avail-phys": 5216124928,
> +# "used-phys": 5216127040,
> +# "avail-size": 2054,
> +# "desc-size": 16384,
> +# "used-size": 8198,
> +# "desc": 140141447430144,
> +# "num": 1024,
> +# "name": "virtio-crypto",
> +# "call": 0,
> +# "avail": 140141447446528,
> +# "desc-phys": 5216108544,
> +# "used": 140141447448640,
> +# "kick": 0 }
> +# }
> +#
> +# 2. Get vhost_virtqueue status for vhost-vsock
> +#
> +# -> { "execute": "x-query-virtio-vhost-queue-status",
> +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
> +# "queue": 0 }
> +# }
> +# <- { "return": {
> +# "avail-phys": 5182261248,
> +# "used-phys": 5182261568,
> +# "avail-size": 262,
> +# "desc-size": 2048,
> +# "used-size": 1030,
> +# "desc": 140141413580800,
> +# "num": 128,
> +# "name": "vhost-vsock",
> +# "call": 0,
> +# "avail": 140141413582848,
> +# "desc-phys": 5182259200,
> +# "used": 140141413583168,
> +# "kick": 0 }
> +# }
> +#
> +##
> +
> +{ 'command': 'x-query-virtio-vhost-queue-status',
> + 'data': { 'path': 'str', 'queue': 'uint16' },
> + 'returns': 'VirtVhostQueueStatus',
> + 'features': [ 'unstable' ] }
With my doc remarks addressed, QAPI schema
Acked-by: Markus Armbruster <arm...@redhat.com>
