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

[Jonah Palmer <jonah.palmer@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 10001 bytes --]


On 11/4/21 11:37, Markus Armbruster wrote:
> 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 4490c2c..656a26f 100644
>> --- a/qapi/virtio.json
>> +++ b/qapi/virtio.json
>> @@ -65,3 +65,258 @@
>>   ##
>>   
>>   { 'command': 'x-debug-query-virtio', 'returns': ['VirtioInfo'] }
>> +
>> +##
>> +# @VirtioStatusEndianness:
>> +#
>> +# Enumeration of endianness for VirtioDevice
>> +#
>> +# Since: 6.2
>> +##
>> +
>> +{ '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.2
>> +#
>> +##
>> +
>> +{ 'struct': 'VhostStatus',
>> +    'data': {
>> +        'n-mem-sections': 'int',
>> +        'n-tmp-sections': 'int',
> Odd indentation.  Better
>
>     { 'struct': 'VhostStatus',
>       'data': {
>           'n-mem-sections': 'int',
>           'n-tmp-sections': 'int',
>
> or
>
>     { 'struct': 'VhostStatus',
>       'data': { 'n-mem-sections': 'int',
>                 'n-tmp-sections': 'int',
>
> More of the same below, and possibly in other patches.  I'm not going to
> point it out again.

Gotcha, I'll use this format in the .json file. Will change it to this for
all relevant patches.

>
>> +        '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'
>> +    }
>> +}
> I can't tell whether these are all needed.  Got to trust virtio experts
> there.

Not sure either, I just included whatever I could include.

>
> I'm not checking the schema types match the data sources' C types.  I
> hope you did :)

Yes c:

>
> More of the same below, and possibly in other patches.  I'm not going to
> point it out again.
>
>> +
>> +##
>> +# @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.2
>> +#
>> +##
>> +
>> +{ '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-debug-virtio-status:
>> +#
>> +# Poll for a comprehensive status of a given virtio device
>> +#
>> +# @path: Canonical QOM path of the VirtIODevice
>> +#
>> +# Returns: VirtioStatus of the virtio device
>> +#
>> +# Since: 6.2
>> +#
>> +# Examples:
>> +#
>> +# 1. Poll for the status of virtio-crypto (no vhost-crypto active)
>> +#
>> +# -> { "execute": "x-debug-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-debug-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-debug-virtio-status',
>> +  'data': { 'path': 'str' },
>> +  'returns': 'VirtioStatus'
>> +}
> Unstable commands now need to be marked with
>
>       'features': [ 'unstable' ]
>
> If you do that, the QAPI generator will demand documentation.  So add
>     
>     # Features:
>     # @unstable: This command is meant for debugging.
>
> You may want to grep for examples.  See also commit 9fb49daabf "qapi:
> Mark unstable QMP parts with feature 'unstable'".

Got it. I will add this in for all 'x-' related commands.

>
> Hmm, this command starts with x-debug-virtio-, wheras the one added in
> the previous commit starts with x-debug-query-virtio-.
>
> By conventions, commands that just return information on FOO are named
> query-FOO.  I recommend an x-query-virtio- prefix for your query
> commands.  We can leave their purpose (debug) to documentation.

Sure thing! I'll make this change.

>
Jonah

[-- Attachment #2: Type: text/html, Size: 11892 bytes --]