Re: [PATCH v9 4/8] qmp: add QMP command x-query-virtio-status

[Markus Armbruster <armbru@redhat.com>]

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

> From: Laurent Vivier <lvivier@redhat.com>
>
> This new command shows the status of a VirtIODevice, including
> its corresponding vhost device status (if active).
>
> Next patch will improve output by decoding feature bits, including
> vhost device's feature bits (backend, protocol, acked, and features).
> Also will decode status bits of a VirtIODevice.
>
> Next patch will also suppress the vhost device field from displaying
> if no vhost device is active for a given VirtIODevice.
>
> Signed-off-by: Jonah Palmer <jonah.palmer@oracle.com>

[...]

> diff --git a/qapi/virtio.json b/qapi/virtio.json
> index 324ba8c..54212f2 100644
> --- a/qapi/virtio.json
> +++ b/qapi/virtio.json
> @@ -53,3 +53,249 @@
>  
>  { 'command': 'x-query-virtio', 'returns': ['VirtioInfo'],
>    'features': [ 'unstable' ] }
> +
> +##
> +# @VirtioStatusEndianness:
> +#
> +# Enumeration of endianness for VirtioDevice
> +#
> +# Since: 6.3
> +##
> +
> +{ 'enum': 'VirtioStatusEndianness',
> +  'data': [ 'unknown', 'little', 'big' ]
> +}
> +
> +##
> +# @VhostStatus:
> +#
> +# Information about a vhost device. This information will only be
> +# displayed if the vhost device is active.
> +#
> +# @n-mem-sections: vhost_dev n_mem_sections
> +#
> +# @n-tmp-sections: vhost_dev n_tmp_sections
> +#
> +# @nvqs: vhost_dev nvqs. This is the number of virtqueues being used
> +#        by the vhost device.
> +#
> +# @vq-index: vhost_dev vq_index
> +#
> +# @features: vhost_dev features
> +#
> +# @acked-features: vhost_dev acked_features
> +#
> +# @backend-features: vhost_dev backend_features
> +#
> +# @protocol-features: vhost_dev protocol_features
> +#
> +# @max-queues: vhost_dev max_queues
> +#
> +# @backend-cap: vhost_dev backend_cap
> +#
> +# @log-enabled: vhost_dev log_enabled flag
> +#
> +# @log-size: vhost_dev log_size
> +#
> +# Since: 6.3
> +#
> +##
> +
> +{ 'struct': 'VhostStatus',
> +  'data': { 'n-mem-sections': 'int',
> +            'n-tmp-sections': 'int',
> +            'nvqs': 'uint32',
> +            'vq-index': 'int',
> +            'features': 'uint64',
> +            'acked-features': 'uint64',
> +            'backend-features': 'uint64',
> +            'protocol-features': 'uint64',
> +            'max-queues': 'uint64',
> +            'backend-cap': 'uint64',
> +            'log-enabled': 'bool',
> +            'log-size': 'uint64' } }
> +
> +##
> +# @VirtioStatus:
> +#
> +# Full status of the virtio device with most VirtIODevice members.
> +# Also includes the full status of the corresponding vhost device
> +# if the vhost device is active.
> +#
> +# @name: VirtIODevice name
> +#
> +# @device-id: VirtIODevice ID
> +#
> +# @vhost-started: VirtIODevice vhost_started flag
> +#
> +# @guest-features: VirtIODevice guest_features
> +#
> +# @host-features: VirtIODevice host_features
> +#
> +# @backend-features: VirtIODevice backend_features
> +#
> +# @device-endian: VirtIODevice device_endian
> +#
> +# @num-vqs: VirtIODevice virtqueue count. This is the number of active
> +#           virtqueues being used by the VirtIODevice.
> +#
> +# @status: VirtIODevice configuration status (e.g. DRIVER_OK,
> +#          FEATURES_OK, DRIVER, etc.)
> +#
> +# @isr: VirtIODevice ISR
> +#
> +# @queue-sel: VirtIODevice queue_sel
> +#
> +# @vm-running: VirtIODevice vm_running flag
> +#
> +# @broken: VirtIODevice broken flag
> +#
> +# @disabled: VirtIODevice disabled flag
> +#
> +# @use-started: VirtIODevice use_started flag
> +#
> +# @started: VirtIODevice started flag
> +#
> +# @start-on-kick: VirtIODevice start_on_kick flag
> +#
> +# @disable-legacy-check: VirtIODevice disabled_legacy_check flag
> +#
> +# @bus-name: VirtIODevice bus_name
> +#
> +# @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag
> +#
> +# @vhost-dev: corresponding vhost device info for a given VirtIODevice
> +#
> +# Since: 6.3
> +#
> +##
> +
> +{ 'struct': 'VirtioStatus',
> +  'data': { 'name': 'str',
> +            'device-id': 'uint16',
> +            'vhost-started': 'bool',
> +            'guest-features': 'uint64',
> +            'host-features': 'uint64',
> +            'backend-features': 'uint64',
> +            'device-endian': 'VirtioStatusEndianness',
> +            'num-vqs': 'int',
> +            'status': 'uint8',
> +            'isr': 'uint8',
> +            'queue-sel': 'uint16',
> +            'vm-running': 'bool',
> +            'broken': 'bool',
> +            'disabled': 'bool',
> +            'use-started': 'bool',
> +            'started': 'bool',
> +            'start-on-kick': 'bool',
> +            'disable-legacy-check': 'bool',
> +            'bus-name': 'str',
> +            'use-guest-notifier-mask': 'bool',
> +            'vhost-dev': 'VhostStatus' } }
> +
> +##
> +# @x-query-virtio-status:
> +#
> +# Poll for a comprehensive status of a given virtio device
> +#
> +# @path: Canonical QOM path of the VirtIODevice
> +#
> +# Features:
> +# @unstable: This command is meant for debugging.
> +#
> +# Returns: VirtioStatus of the virtio device
> +#
> +# Since: 6.3
> +#
> +# Examples:
> +#
> +# 1. Poll for the status of virtio-crypto (no vhost-crypto active)
> +#
> +# -> { "execute": "x-query-virtio-status",
> +#      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
> +#    }
> +# <- { "return": {
> +#          "device-endian": "little",
> +#          "bus-name": "",
> +#          "disable-legacy-check": false,
> +#          "name": "virtio-crypto",
> +#          "started": true,
> +#          "device-id": 20,
> +#          "vhost-dev": {
> +#               "n-tmp-sections": 0,
> +#               "n-mem-sections": 0,
> +#               "max-queues": 0,
> +#               "backend-cap": 0,
> +#               "log-size": 0,
> +#               "backend-features": 0,
> +#               "nvqs": 0,
> +#               "protocol-features": 0,
> +#               "vq-index": 0,
> +#               "log-enabled": false,
> +#               "acked-features": 0,
> +#               "features": 0
> +#          },
> +#          "backend-features": 0,
> +#          "start-on-kick": false,
> +#          "isr": 1,
> +#          "broken": false,
> +#          "status": 15,
> +#          "num-vqs": 2,
> +#          "guest-features": 5100273664,
> +#          "host-features": 6325010432,
> +#          "use-guest-notifier-mask": true,
> +#          "vm-running": true,
> +#          "queue-sel": 1,
> +#          "disabled": false,
> +#          "vhost-started": false,
> +#          "use-started": true
> +#      }
> +#    }
> +#
> +# 2. Poll for the status of virtio-net (vhost-net is active)
> +#
> +# -> { "execute": "x-query-virtio-status",
> +#      "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
> +#    }
> +# <- { "return": {
> +#          "device-endian": "little",
> +#          "bus-name": "",
> +#          "disabled-legacy-check": false,
> +#          "name": "virtio-net",
> +#          "started": true,
> +#          "device-id": 1,
> +#          "vhost-dev": {
> +#               "n-tmp-sections": 4,
> +#               "n-mem-sections": 4,
> +#               "max-queues": 1,
> +#               "backend-cap": 2,
> +#               "log-size": 0,
> +#               "backend-features": 0,
> +#               "nvqs": 2,
> +#               "protocol-features": 0,
> +#               "vq-index": 0,
> +#               "log-enabled": false,
> +#               "acked-features": 5100306432,
> +#               "features": 13908344832
> +#          },
> +#          "backend-features": 6337593319,
> +#          "start-on-kick": false,
> +#          "isr": 1,
> +#          "broken": false,
> +#          "status": 15,
> +#          "num-vqs": 3,
> +#          "guest-features": 5111807911,
> +#          "host-features": 6337593319,
> +#          "use-guest-notifier-mask": true,
> +#          "vm-running": true,
> +#          "queue-sel": 2,
> +#          "disabled": false,
> +#          "vhost-started": true,
> +#          "use-started": true
> +#      }
> +#    }
> +#
> +##
> +
> +{ 'command': 'x-query-virtio-status', 'data': { 'path': 'str' },
> +  'returns': 'VirtioStatus', 'features': [ 'unstable' ] }

There's precedence for this style, but I find

   { 'command': 'x-query-virtio-status',
     'data': { 'path': 'str' },
     'returns': 'VirtioStatus',
     'features': [ 'unstable' ] }

easier to read.