qemu/qapi/virtio.json

# -*- 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.1
#
##
{ '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.1
#
# 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.1
#
##

{ '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.1
#
##

{ '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.1
#
# 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 negotation 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 negotation 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.1
##

{ '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.1
##

{ '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.1
##

{ 'struct': 'VirtioDeviceFeatures',
  'data': { 'transports': [ 'str' ],
            '*dev-features': [ 'str' ],
            '*unknown-dev-features': 'uint64' } }