d461c27973
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly. Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives. Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply: .. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ... ... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs. See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use. These are rendered in orange: .. Attention:: ... .. Caution:: ... .. WARNING:: ... These are rendered in red: .. DANGER:: ... .. Error:: ... These are rendered in green: .. Hint:: ... .. Important:: ... .. Tip:: ... These are rendered in blue: .. Note:: ... .. admonition:: custom title admonition body text This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example. NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes *may change* as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>
982 lines
32 KiB
Python
982 lines
32 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
|
|
##
|
|
# = Virtio devices
|
|
##
|
|
|
|
##
|
|
# @VirtioInfo:
|
|
#
|
|
# Basic information about a given VirtIODevice
|
|
#
|
|
# @path: The VirtIODevice's canonical QOM path
|
|
#
|
|
# @name: Name of the VirtIODevice
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'VirtioInfo',
|
|
'data': { 'path': 'str',
|
|
'name': 'str' } }
|
|
|
|
##
|
|
# @x-query-virtio:
|
|
#
|
|
# Returns a list of all realized VirtIODevices
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This command is meant for debugging.
|
|
#
|
|
# Returns: List of gathered VirtIODevices
|
|
#
|
|
# Since: 7.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "x-query-virtio" }
|
|
# <- { "return": [
|
|
# {
|
|
# "name": "virtio-input",
|
|
# "path": "/machine/peripheral-anon/device[4]/virtio-backend"
|
|
# },
|
|
# {
|
|
# "name": "virtio-crypto",
|
|
# "path": "/machine/peripheral/crypto0/virtio-backend"
|
|
# },
|
|
# {
|
|
# "name": "virtio-scsi",
|
|
# "path": "/machine/peripheral-anon/device[2]/virtio-backend"
|
|
# },
|
|
# {
|
|
# "name": "virtio-net",
|
|
# "path": "/machine/peripheral-anon/device[1]/virtio-backend"
|
|
# },
|
|
# {
|
|
# "name": "virtio-serial",
|
|
# "path": "/machine/peripheral-anon/device[0]/virtio-backend"
|
|
# }
|
|
# ]
|
|
# }
|
|
##
|
|
{ 'command': 'x-query-virtio',
|
|
'returns': [ 'VirtioInfo' ],
|
|
'features': [ 'unstable' ] }
|
|
|
|
##
|
|
# @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 (number of virtqueues being used)
|
|
#
|
|
# @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: 7.2
|
|
##
|
|
{ 'struct': 'VhostStatus',
|
|
'data': { 'n-mem-sections': 'int',
|
|
'n-tmp-sections': 'int',
|
|
'nvqs': 'uint32',
|
|
'vq-index': 'int',
|
|
'features': 'VirtioDeviceFeatures',
|
|
'acked-features': 'VirtioDeviceFeatures',
|
|
'backend-features': 'VirtioDeviceFeatures',
|
|
'protocol-features': 'VhostDeviceProtocols',
|
|
'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 (VirtioDeviceStatus)
|
|
#
|
|
# @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. Present if the given VirtIODevice has an active
|
|
# vhost device.
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'VirtioStatus',
|
|
'data': { 'name': 'str',
|
|
'device-id': 'uint16',
|
|
'vhost-started': 'bool',
|
|
'device-endian': 'str',
|
|
'guest-features': 'VirtioDeviceFeatures',
|
|
'host-features': 'VirtioDeviceFeatures',
|
|
'backend-features': 'VirtioDeviceFeatures',
|
|
'num-vqs': 'int',
|
|
'status': 'VirtioDeviceStatus',
|
|
'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: 7.2
|
|
#
|
|
# 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,
|
|
# "backend-features": {
|
|
# "transports": [],
|
|
# "dev-features": []
|
|
# },
|
|
# "start-on-kick": false,
|
|
# "isr": 1,
|
|
# "broken": false,
|
|
# "status": {
|
|
# "statuses": [
|
|
# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
|
|
# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
|
|
# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
|
|
# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
|
|
# ]
|
|
# },
|
|
# "num-vqs": 2,
|
|
# "guest-features": {
|
|
# "dev-features": [],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
|
|
# ]
|
|
# },
|
|
# "host-features": {
|
|
# "unknown-dev-features": 1073741824,
|
|
# "dev-features": [],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
|
|
# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
|
|
# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
|
|
# ]
|
|
# },
|
|
# "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": {
|
|
# "dev-features": [],
|
|
# "transports": []
|
|
# },
|
|
# "nvqs": 2,
|
|
# "protocol-features": {
|
|
# "protocols": []
|
|
# },
|
|
# "vq-index": 0,
|
|
# "log-enabled": false,
|
|
# "acked-features": {
|
|
# "dev-features": [
|
|
# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
|
|
# ],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
|
|
# ]
|
|
# },
|
|
# "features": {
|
|
# "dev-features": [
|
|
# "VHOST_F_LOG_ALL: Logging write descriptors supported",
|
|
# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
|
|
# ],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
|
|
# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
|
|
# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
|
|
# ]
|
|
# }
|
|
# },
|
|
# "backend-features": {
|
|
# "dev-features": [
|
|
# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
|
|
# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
|
|
# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
|
|
# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
|
|
# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
|
|
# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
|
|
# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
|
|
# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
|
|
# "VIRTIO_NET_F_STATUS: Configuration status field available",
|
|
# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
|
|
# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
|
|
# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
|
|
# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
|
|
# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
|
|
# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
|
|
# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
|
|
# "VIRTIO_NET_F_MAC: Device has given MAC address",
|
|
# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
|
|
# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
|
|
# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
|
|
# ],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
|
|
# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
|
|
# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
|
|
# ]
|
|
# },
|
|
# "start-on-kick": false,
|
|
# "isr": 1,
|
|
# "broken": false,
|
|
# "status": {
|
|
# "statuses": [
|
|
# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
|
|
# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
|
|
# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
|
|
# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
|
|
# ]
|
|
# },
|
|
# "num-vqs": 3,
|
|
# "guest-features": {
|
|
# "dev-features": [
|
|
# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
|
|
# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
|
|
# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
|
|
# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
|
|
# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
|
|
# "VIRTIO_NET_F_STATUS: Configuration status field available",
|
|
# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
|
|
# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
|
|
# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
|
|
# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
|
|
# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
|
|
# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
|
|
# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
|
|
# "VIRTIO_NET_F_MAC: Device has given MAC address",
|
|
# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
|
|
# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
|
|
# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
|
|
# ],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
|
|
# ]
|
|
# },
|
|
# "host-features": {
|
|
# "dev-features": [
|
|
# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
|
|
# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
|
|
# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
|
|
# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
|
|
# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
|
|
# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
|
|
# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
|
|
# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
|
|
# "VIRTIO_NET_F_STATUS: Configuration status field available",
|
|
# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
|
|
# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
|
|
# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
|
|
# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
|
|
# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
|
|
# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
|
|
# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
|
|
# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
|
|
# "VIRTIO_NET_F_MAC: Device has given MAC address",
|
|
# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
|
|
# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
|
|
# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
|
|
# ],
|
|
# "transports": [
|
|
# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
|
|
# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
|
|
# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
|
|
# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
|
|
# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
|
|
# ]
|
|
# },
|
|
# "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' ] }
|
|
|
|
##
|
|
# @VirtioDeviceStatus:
|
|
#
|
|
# A structure defined to list the configuration statuses of a virtio
|
|
# device
|
|
#
|
|
# @statuses: List of decoded configuration statuses of the virtio
|
|
# device
|
|
#
|
|
# @unknown-statuses: Virtio device statuses bitmap that have not been
|
|
# decoded
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'VirtioDeviceStatus',
|
|
'data': { 'statuses': [ 'str' ],
|
|
'*unknown-statuses': 'uint8' } }
|
|
|
|
##
|
|
# @VhostDeviceProtocols:
|
|
#
|
|
# A structure defined to list the vhost user protocol features of a
|
|
# Vhost User device
|
|
#
|
|
# @protocols: List of decoded vhost user protocol features of a vhost
|
|
# user device
|
|
#
|
|
# @unknown-protocols: Vhost user device protocol features bitmap that
|
|
# have not been decoded
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'VhostDeviceProtocols',
|
|
'data': { 'protocols': [ 'str' ],
|
|
'*unknown-protocols': 'uint64' } }
|
|
|
|
##
|
|
# @VirtioDeviceFeatures:
|
|
#
|
|
# The common fields that apply to most Virtio devices. Some devices
|
|
# may not have their own device-specific features (e.g. virtio-rng).
|
|
#
|
|
# @transports: List of transport features of the virtio device
|
|
#
|
|
# @dev-features: List of device-specific features (if the device has
|
|
# unique features)
|
|
#
|
|
# @unknown-dev-features: Virtio device features bitmap that have not
|
|
# been decoded
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'VirtioDeviceFeatures',
|
|
'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.2
|
|
##
|
|
{ '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.
|
|
#
|
|
# Returns: VirtQueueStatus of the VirtQueue
|
|
#
|
|
# .. note:: 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.2
|
|
#
|
|
# 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,
|
|
# "name": "vhost-vsock",
|
|
# "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,
|
|
# "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,
|
|
# "name": "virtio-serial",
|
|
# "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,
|
|
# "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 physical
|
|
# address)
|
|
#
|
|
# @desc-size: vhost_virtqueue desc_size
|
|
#
|
|
# @avail-phys: vhost_virtqueue avail_phys (driver area physical
|
|
# address)
|
|
#
|
|
# @avail-size: vhost_virtqueue avail_size
|
|
#
|
|
# @used-phys: vhost_virtqueue used_phys (device area physical address)
|
|
#
|
|
# @used-size: vhost_virtqueue used_size
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ '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 is meant for debugging.
|
|
#
|
|
# Returns: VirtVhostQueueStatus of the vhost_virtqueue
|
|
#
|
|
# Since: 7.2
|
|
#
|
|
# 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,
|
|
# "name": "virtio-crypto",
|
|
# "used-phys": 5216127040,
|
|
# "avail-size": 2054,
|
|
# "desc-size": 16384,
|
|
# "used-size": 8198,
|
|
# "desc": 140141447430144,
|
|
# "num": 1024,
|
|
# "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,
|
|
# "name": "vhost-vsock",
|
|
# "used-phys": 5182261568,
|
|
# "avail-size": 262,
|
|
# "desc-size": 2048,
|
|
# "used-size": 1030,
|
|
# "desc": 140141413580800,
|
|
# "num": 128,
|
|
# "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' ] }
|
|
|
|
##
|
|
# @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.2
|
|
##
|
|
{ '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.2
|
|
##
|
|
{ '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.2
|
|
##
|
|
{ '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.2
|
|
##
|
|
{ '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
|
|
#
|
|
# @path: VirtIODevice canonical QOM path
|
|
#
|
|
# @queue: VirtQueue index to examine
|
|
#
|
|
# @index: Index of the element in the queue (default: head of the
|
|
# queue)
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This command is meant for debugging.
|
|
#
|
|
# Returns: VirtioQueueElement information
|
|
#
|
|
# Since: 7.2
|
|
#
|
|
# 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' ] }
|
|
|
|
##
|
|
# @IOThreadVirtQueueMapping:
|
|
#
|
|
# Describes the subset of virtqueues assigned to an IOThread.
|
|
#
|
|
# @iothread: the id of IOThread object
|
|
#
|
|
# @vqs: an optional array of virtqueue indices that will be handled by
|
|
# this IOThread. When absent, virtqueues are assigned round-robin
|
|
# across all IOThreadVirtQueueMappings provided. Either all
|
|
# IOThreadVirtQueueMappings must have @vqs or none of them must
|
|
# have it.
|
|
#
|
|
# Since: 9.0
|
|
##
|
|
|
|
{ 'struct': 'IOThreadVirtQueueMapping',
|
|
'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
|
|
|
|
##
|
|
# @DummyVirtioForceArrays:
|
|
#
|
|
# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
|
|
# internally
|
|
#
|
|
# Since: 9.0
|
|
##
|
|
|
|
{ 'struct': 'DummyVirtioForceArrays',
|
|
'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } }
|
|
|
|
##
|
|
# @GranuleMode:
|
|
#
|
|
# @4k: granule page size of 4KiB
|
|
#
|
|
# @8k: granule page size of 8KiB
|
|
#
|
|
# @16k: granule page size of 16KiB
|
|
#
|
|
# @64k: granule page size of 64KiB
|
|
#
|
|
# @host: granule matches the host page size
|
|
#
|
|
# Since: 9.0
|
|
##
|
|
{ 'enum': 'GranuleMode',
|
|
'data': [ '4k', '8k', '16k', '64k', 'host' ] }
|