qapi/virtio.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4
   5 ##
   6 # = Virtio devices
   7 ##
   8
   9 ##
  10 # @VirtioInfo:
  11 #
  12 # Basic information about a given VirtIODevice
  13 #
  14 # @path: The VirtIODevice's canonical QOM path
  15 #
  16 # @name: Name of the VirtIODevice
  17 #
  18 # Since: 7.2
  19 ##
  20 { 'struct': 'VirtioInfo',
  21   'data': { 'path': 'str',
  22             'name': 'str' } }
  23
  24 ##
  25 # @x-query-virtio:
  26 #
  27 # Returns a list of all realized VirtIODevices
  28 #
  29 # Features:
  30 #
  31 # @unstable: This command is meant for debugging.
  32 #
  33 # Returns: List of gathered VirtIODevices
  34 #
  35 # Since: 7.2
  36 #
  37 # Example:
  38 #
  39 # -> { "execute": "x-query-virtio" }
  40 # <- { "return": [
  41 #          {
  42 #              "name": "virtio-input",
  43 #              "path": "/machine/peripheral-anon/device[4]/virtio-backend"
  44 #          },
  45 #          {
  46 #              "name": "virtio-crypto",
  47 #              "path": "/machine/peripheral/crypto0/virtio-backend"
  48 #          },
  49 #          {
  50 #              "name": "virtio-scsi",
  51 #              "path": "/machine/peripheral-anon/device[2]/virtio-backend"
  52 #          },
  53 #          {
  54 #              "name": "virtio-net",
  55 #              "path": "/machine/peripheral-anon/device[1]/virtio-backend"
  56 #          },
  57 #          {
  58 #              "name": "virtio-serial",
  59 #              "path": "/machine/peripheral-anon/device[0]/virtio-backend"
  60 #          }
  61 #      ]
  62 #    }
  63 ##
  64 { 'command': 'x-query-virtio',
  65   'returns': [ 'VirtioInfo' ],
  66   'features': [ 'unstable' ] }
  67
  68 ##
  69 # @VhostStatus:
  70 #
  71 # Information about a vhost device.  This information will only be
  72 # displayed if the vhost device is active.
  73 #
  74 # @n-mem-sections: vhost_dev n_mem_sections
  75 #
  76 # @n-tmp-sections: vhost_dev n_tmp_sections
  77 #
  78 # @nvqs: vhost_dev nvqs (number of virtqueues being used)
  79 #
  80 # @vq-index: vhost_dev vq_index
  81 #
  82 # @features: vhost_dev features
  83 #
  84 # @acked-features: vhost_dev acked_features
  85 #
  86 # @backend-features: vhost_dev backend_features
  87 #
  88 # @protocol-features: vhost_dev protocol_features
  89 #
  90 # @max-queues: vhost_dev max_queues
  91 #
  92 # @backend-cap: vhost_dev backend_cap
  93 #
  94 # @log-enabled: vhost_dev log_enabled flag
  95 #
  96 # @log-size: vhost_dev log_size
  97 #
  98 # Since: 7.2
  99 ##
 100 { 'struct': 'VhostStatus',
 101   'data': { 'n-mem-sections': 'int',
 102             'n-tmp-sections': 'int',
 103             'nvqs': 'uint32',
 104             'vq-index': 'int',
 105             'features': 'VirtioDeviceFeatures',
 106             'acked-features': 'VirtioDeviceFeatures',
 107             'backend-features': 'VirtioDeviceFeatures',
 108             'protocol-features': 'VhostDeviceProtocols',
 109             'max-queues': 'uint64',
 110             'backend-cap': 'uint64',
 111             'log-enabled': 'bool',
 112             'log-size': 'uint64' } }
 113
 114 ##
 115 # @VirtioStatus:
 116 #
 117 # Full status of the virtio device with most VirtIODevice members.
 118 # Also includes the full status of the corresponding vhost device if
 119 # the vhost device is active.
 120 #
 121 # @name: VirtIODevice name
 122 #
 123 # @device-id: VirtIODevice ID
 124 #
 125 # @vhost-started: VirtIODevice vhost_started flag
 126 #
 127 # @guest-features: VirtIODevice guest_features
 128 #
 129 # @host-features: VirtIODevice host_features
 130 #
 131 # @backend-features: VirtIODevice backend_features
 132 #
 133 # @device-endian: VirtIODevice device_endian
 134 #
 135 # @num-vqs: VirtIODevice virtqueue count.  This is the number of
 136 #     active virtqueues being used by the VirtIODevice.
 137 #
 138 # @status: VirtIODevice configuration status (VirtioDeviceStatus)
 139 #
 140 # @isr: VirtIODevice ISR
 141 #
 142 # @queue-sel: VirtIODevice queue_sel
 143 #
 144 # @vm-running: VirtIODevice vm_running flag
 145 #
 146 # @broken: VirtIODevice broken flag
 147 #
 148 # @disabled: VirtIODevice disabled flag
 149 #
 150 # @use-started: VirtIODevice use_started flag
 151 #
 152 # @started: VirtIODevice started flag
 153 #
 154 # @start-on-kick: VirtIODevice start_on_kick flag
 155 #
 156 # @disable-legacy-check: VirtIODevice disabled_legacy_check flag
 157 #
 158 # @bus-name: VirtIODevice bus_name
 159 #
 160 # @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag
 161 #
 162 # @vhost-dev: Corresponding vhost device info for a given
 163 #     VirtIODevice.  Present if the given VirtIODevice has an active
 164 #     vhost device.
 165 #
 166 # Since: 7.2
 167 ##
 168 { 'struct': 'VirtioStatus',
 169   'data': { 'name': 'str',
 170             'device-id': 'uint16',
 171             'vhost-started': 'bool',
 172             'device-endian': 'str',
 173             'guest-features': 'VirtioDeviceFeatures',
 174             'host-features': 'VirtioDeviceFeatures',
 175             'backend-features': 'VirtioDeviceFeatures',
 176             'num-vqs': 'int',
 177             'status': 'VirtioDeviceStatus',
 178             'isr': 'uint8',
 179             'queue-sel': 'uint16',
 180             'vm-running': 'bool',
 181             'broken': 'bool',
 182             'disabled': 'bool',
 183             'use-started': 'bool',
 184             'started': 'bool',
 185             'start-on-kick': 'bool',
 186             'disable-legacy-check': 'bool',
 187             'bus-name': 'str',
 188             'use-guest-notifier-mask': 'bool',
 189             '*vhost-dev': 'VhostStatus' } }
 190
 191 ##
 192 # @x-query-virtio-status:
 193 #
 194 # Poll for a comprehensive status of a given virtio device
 195 #
 196 # @path: Canonical QOM path of the VirtIODevice
 197 #
 198 # Features:
 199 #
 200 # @unstable: This command is meant for debugging.
 201 #
 202 # Returns: VirtioStatus of the virtio device
 203 #
 204 # Since: 7.2
 205 #
 206 # Examples:
 207 #
 208 # 1. Poll for the status of virtio-crypto (no vhost-crypto active)
 209 #
 210 # -> { "execute": "x-query-virtio-status",
 211 #      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
 212 #    }
 213 # <- { "return": {
 214 #          "device-endian": "little",
 215 #          "bus-name": "",
 216 #          "disable-legacy-check": false,
 217 #          "name": "virtio-crypto",
 218 #          "started": true,
 219 #          "device-id": 20,
 220 #          "backend-features": {
 221 #              "transports": [],
 222 #              "dev-features": []
 223 #          },
 224 #          "start-on-kick": false,
 225 #          "isr": 1,
 226 #          "broken": false,
 227 #          "status": {
 228 #              "statuses": [
 229 #                  "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
 230 #                  "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
 231 #                  "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
 232 #                  "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
 233 #              ]
 234 #          },
 235 #          "num-vqs": 2,
 236 #          "guest-features": {
 237 #              "dev-features": [],
 238 #              "transports": [
 239 #                  "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 240 #                  "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 241 #                  "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
 242 #              ]
 243 #          },
 244 #          "host-features": {
 245 #              "unknown-dev-features": 1073741824,
 246 #              "dev-features": [],
 247 #              "transports": [
 248 #                  "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 249 #                  "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 250 #                  "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
 251 #                  "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
 252 #                  "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
 253 #              ]
 254 #          },
 255 #          "use-guest-notifier-mask": true,
 256 #          "vm-running": true,
 257 #          "queue-sel": 1,
 258 #          "disabled": false,
 259 #          "vhost-started": false,
 260 #          "use-started": true
 261 #      }
 262 #    }
 263 #
 264 # 2. Poll for the status of virtio-net (vhost-net is active)
 265 #
 266 # -> { "execute": "x-query-virtio-status",
 267 #      "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
 268 #    }
 269 # <- { "return": {
 270 #          "device-endian": "little",
 271 #          "bus-name": "",
 272 #          "disabled-legacy-check": false,
 273 #          "name": "virtio-net",
 274 #          "started": true,
 275 #          "device-id": 1,
 276 #          "vhost-dev": {
 277 #              "n-tmp-sections": 4,
 278 #              "n-mem-sections": 4,
 279 #              "max-queues": 1,
 280 #              "backend-cap": 2,
 281 #              "log-size": 0,
 282 #              "backend-features": {
 283 #                  "dev-features": [],
 284 #                  "transports": []
 285 #              },
 286 #              "nvqs": 2,
 287 #              "protocol-features": {
 288 #                  "protocols": []
 289 #              },
 290 #              "vq-index": 0,
 291 #              "log-enabled": false,
 292 #              "acked-features": {
 293 #                  "dev-features": [
 294 #                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
 295 #                  ],
 296 #                  "transports": [
 297 #                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 298 #                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 299 #                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
 300 #                  ]
 301 #              },
 302 #              "features": {
 303 #                  "dev-features": [
 304 #                      "VHOST_F_LOG_ALL: Logging write descriptors supported",
 305 #                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
 306 #                  ],
 307 #                  "transports": [
 308 #                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 309 #                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 310 #                      "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
 311 #                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
 312 #                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
 313 #                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
 314 #                  ]
 315 #              }
 316 #          },
 317 #          "backend-features": {
 318 #              "dev-features": [
 319 #                  "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
 320 #                  "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
 321 #                  "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
 322 #                  "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
 323 #                  "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
 324 #                  "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
 325 #                  "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
 326 #                  "VIRTIO_NET_F_CTRL_VQ: Control channel available",
 327 #                  "VIRTIO_NET_F_STATUS: Configuration status field available",
 328 #                  "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
 329 #                  "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
 330 #                  "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
 331 #                  "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
 332 #                  "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
 333 #                  "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
 334 #                  "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
 335 #                  "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
 336 #                  "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
 337 #                  "VIRTIO_NET_F_MAC: Device has given MAC address",
 338 #                  "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
 339 #                  "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
 340 #                  "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
 341 #              ],
 342 #              "transports": [
 343 #                  "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 344 #                  "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 345 #                  "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
 346 #                  "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
 347 #                  "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
 348 #              ]
 349 #          },
 350 #          "start-on-kick": false,
 351 #          "isr": 1,
 352 #          "broken": false,
 353 #          "status": {
 354 #              "statuses": [
 355 #                  "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
 356 #                  "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
 357 #                  "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
 358 #                  "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
 359 #              ]
 360 #          },
 361 #          "num-vqs": 3,
 362 #          "guest-features": {
 363 #              "dev-features": [
 364 #                  "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
 365 #                  "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
 366 #                  "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
 367 #                  "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
 368 #                  "VIRTIO_NET_F_CTRL_VQ: Control channel available",
 369 #                  "VIRTIO_NET_F_STATUS: Configuration status field available",
 370 #                  "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
 371 #                  "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
 372 #                  "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
 373 #                  "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
 374 #                  "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
 375 #                  "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
 376 #                  "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
 377 #                  "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
 378 #                  "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
 379 #                  "VIRTIO_NET_F_MAC: Device has given MAC address",
 380 #                  "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
 381 #                  "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
 382 #                  "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
 383 #              ],
 384 #              "transports": [
 385 #                  "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 386 #                  "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 387 #                  "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
 388 #             ]
 389 #          },
 390 #          "host-features": {
 391 #              "dev-features": [
 392 #                  "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
 393 #                  "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
 394 #                  "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
 395 #                  "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
 396 #                  "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
 397 #                  "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
 398 #                  "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
 399 #                  "VIRTIO_NET_F_CTRL_VQ: Control channel available",
 400 #                  "VIRTIO_NET_F_STATUS: Configuration status field available",
 401 #                  "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
 402 #                  "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
 403 #                  "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
 404 #                  "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
 405 #                  "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
 406 #                  "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
 407 #                  "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
 408 #                  "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
 409 #                  "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
 410 #                  "VIRTIO_NET_F_MAC: Device has given MAC address",
 411 #                  "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
 412 #                  "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
 413 #                  "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
 414 #              ],
 415 #              "transports": [
 416 #                  "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
 417 #                  "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
 418 #                  "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
 419 #                  "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
 420 #                  "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
 421 #             ]
 422 #          },
 423 #          "use-guest-notifier-mask": true,
 424 #          "vm-running": true,
 425 #          "queue-sel": 2,
 426 #          "disabled": false,
 427 #          "vhost-started": true,
 428 #          "use-started": true
 429 #      }
 430 #    }
 431 ##
 432 { 'command': 'x-query-virtio-status',
 433   'data': { 'path': 'str' },
 434   'returns': 'VirtioStatus',
 435   'features': [ 'unstable' ] }
 436
 437 ##
 438 # @VirtioDeviceStatus:
 439 #
 440 # A structure defined to list the configuration statuses of a virtio
 441 # device
 442 #
 443 # @statuses: List of decoded configuration statuses of the virtio
 444 #     device
 445 #
 446 # @unknown-statuses: Virtio device statuses bitmap that have not been
 447 #     decoded
 448 #
 449 # Since: 7.2
 450 ##
 451 { 'struct': 'VirtioDeviceStatus',
 452   'data': { 'statuses': [ 'str' ],
 453             '*unknown-statuses': 'uint8' } }
 454
 455 ##
 456 # @VhostDeviceProtocols:
 457 #
 458 # A structure defined to list the vhost user protocol features of a
 459 # Vhost User device
 460 #
 461 # @protocols: List of decoded vhost user protocol features of a vhost
 462 #     user device
 463 #
 464 # @unknown-protocols: Vhost user device protocol features bitmap that
 465 #     have not been decoded
 466 #
 467 # Since: 7.2
 468 ##
 469 { 'struct': 'VhostDeviceProtocols',
 470   'data': { 'protocols': [ 'str' ],
 471             '*unknown-protocols': 'uint64' } }
 472
 473 ##
 474 # @VirtioDeviceFeatures:
 475 #
 476 # The common fields that apply to most Virtio devices.  Some devices
 477 # may not have their own device-specific features (e.g. virtio-rng).
 478 #
 479 # @transports: List of transport features of the virtio device
 480 #
 481 # @dev-features: List of device-specific features (if the device has
 482 #     unique features)
 483 #
 484 # @unknown-dev-features: Virtio device features bitmap that have not
 485 #     been decoded
 486 #
 487 # Since: 7.2
 488 ##
 489 { 'struct': 'VirtioDeviceFeatures',
 490   'data': { 'transports': [ 'str' ],
 491             '*dev-features': [ 'str' ],
 492             '*unknown-dev-features': 'uint64' } }
 493
 494 ##
 495 # @VirtQueueStatus:
 496 #
 497 # Information of a VirtIODevice VirtQueue, including most members of
 498 # the VirtQueue data structure.
 499 #
 500 # @name: Name of the VirtIODevice that uses this VirtQueue
 501 #
 502 # @queue-index: VirtQueue queue_index
 503 #
 504 # @inuse: VirtQueue inuse
 505 #
 506 # @vring-num: VirtQueue vring.num
 507 #
 508 # @vring-num-default: VirtQueue vring.num_default
 509 #
 510 # @vring-align: VirtQueue vring.align
 511 #
 512 # @vring-desc: VirtQueue vring.desc (descriptor area)
 513 #
 514 # @vring-avail: VirtQueue vring.avail (driver area)
 515 #
 516 # @vring-used: VirtQueue vring.used (device area)
 517 #
 518 # @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
 519 #     vhost_get_vring_base (if vhost active)
 520 #
 521 # @shadow-avail-idx: VirtQueue shadow_avail_idx
 522 #
 523 # @used-idx: VirtQueue used_idx
 524 #
 525 # @signalled-used: VirtQueue signalled_used
 526 #
 527 # @signalled-used-valid: VirtQueue signalled_used_valid flag
 528 #
 529 # Since: 7.2
 530 ##
 531 { 'struct': 'VirtQueueStatus',
 532   'data': { 'name': 'str',
 533             'queue-index': 'uint16',
 534             'inuse': 'uint32',
 535             'vring-num': 'uint32',
 536             'vring-num-default': 'uint32',
 537             'vring-align': 'uint32',
 538             'vring-desc': 'uint64',
 539             'vring-avail': 'uint64',
 540             'vring-used': 'uint64',
 541             '*last-avail-idx': 'uint16',
 542             '*shadow-avail-idx': 'uint16',
 543             'used-idx': 'uint16',
 544             'signalled-used': 'uint16',
 545             'signalled-used-valid': 'bool' } }
 546
 547 ##
 548 # @x-query-virtio-queue-status:
 549 #
 550 # Return the status of a given VirtIODevice's VirtQueue
 551 #
 552 # @path: VirtIODevice canonical QOM path
 553 #
 554 # @queue: VirtQueue index to examine
 555 #
 556 # Features:
 557 #
 558 # @unstable: This command is meant for debugging.
 559 #
 560 # Returns: VirtQueueStatus of the VirtQueue
 561 #
 562 # Notes: last_avail_idx will not be displayed in the case where the
 563 #     selected VirtIODevice has a running vhost device and the
 564 #     VirtIODevice VirtQueue index (queue) does not exist for the
 565 #     corresponding vhost device vhost_virtqueue.  Also,
 566 #     shadow_avail_idx will not be displayed in the case where the
 567 #     selected VirtIODevice has a running vhost device.
 568 #
 569 # Since: 7.2
 570 #
 571 # Examples:
 572 #
 573 # 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
 574 #
 575 # -> { "execute": "x-query-virtio-queue-status",
 576 #      "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
 577 #                     "queue": 1 }
 578 #    }
 579 # <- { "return": {
 580 #          "signalled-used": 0,
 581 #          "inuse": 0,
 582 #          "name": "vhost-vsock",
 583 #          "vring-align": 4096,
 584 #          "vring-desc": 5217370112,
 585 #          "signalled-used-valid": false,
 586 #          "vring-num-default": 128,
 587 #          "vring-avail": 5217372160,
 588 #          "queue-index": 1,
 589 #          "last-avail-idx": 0,
 590 #          "vring-used": 5217372480,
 591 #          "used-idx": 0,
 592 #          "vring-num": 128
 593 #      }
 594 #    }
 595 #
 596 # 2. Get VirtQueueStatus for virtio-serial (no vhost)
 597 #
 598 # -> { "execute": "x-query-virtio-queue-status",
 599 #      "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
 600 #                     "queue": 20 }
 601 #    }
 602 # <- { "return": {
 603 #          "signalled-used": 0,
 604 #          "inuse": 0,
 605 #          "name": "virtio-serial",
 606 #          "vring-align": 4096,
 607 #          "vring-desc": 5182074880,
 608 #          "signalled-used-valid": false,
 609 #          "vring-num-default": 128,
 610 #          "vring-avail": 5182076928,
 611 #          "queue-index": 20,
 612 #          "last-avail-idx": 0,
 613 #          "vring-used": 5182077248,
 614 #          "used-idx": 0,
 615 #          "shadow-avail-idx": 0,
 616 #          "vring-num": 128
 617 #      }
 618 #    }
 619 ##
 620 { 'command': 'x-query-virtio-queue-status',
 621   'data': { 'path': 'str', 'queue': 'uint16' },
 622   'returns': 'VirtQueueStatus',
 623   'features': [ 'unstable' ] }
 624
 625 ##
 626 # @VirtVhostQueueStatus:
 627 #
 628 # Information of a vhost device's vhost_virtqueue, including most
 629 # members of the vhost_dev vhost_virtqueue data structure.
 630 #
 631 # @name: Name of the VirtIODevice that uses this vhost_virtqueue
 632 #
 633 # @kick: vhost_virtqueue kick
 634 #
 635 # @call: vhost_virtqueue call
 636 #
 637 # @desc: vhost_virtqueue desc
 638 #
 639 # @avail: vhost_virtqueue avail
 640 #
 641 # @used: vhost_virtqueue used
 642 #
 643 # @num: vhost_virtqueue num
 644 #
 645 # @desc-phys: vhost_virtqueue desc_phys (descriptor area phys. addr.)
 646 #
 647 # @desc-size: vhost_virtqueue desc_size
 648 #
 649 # @avail-phys: vhost_virtqueue avail_phys (driver area phys. addr.)
 650 #
 651 # @avail-size: vhost_virtqueue avail_size
 652 #
 653 # @used-phys: vhost_virtqueue used_phys (device area phys. addr.)
 654 #
 655 # @used-size: vhost_virtqueue used_size
 656 #
 657 # Since: 7.2
 658 ##
 659 { 'struct': 'VirtVhostQueueStatus',
 660   'data': { 'name': 'str',
 661             'kick': 'int',
 662             'call': 'int',
 663             'desc': 'uint64',
 664             'avail': 'uint64',
 665             'used': 'uint64',
 666             'num': 'int',
 667             'desc-phys': 'uint64',
 668             'desc-size': 'uint32',
 669             'avail-phys': 'uint64',
 670             'avail-size': 'uint32',
 671             'used-phys': 'uint64',
 672             'used-size': 'uint32' } }
 673
 674 ##
 675 # @x-query-virtio-vhost-queue-status:
 676 #
 677 # Return information of a given vhost device's vhost_virtqueue
 678 #
 679 # @path: VirtIODevice canonical QOM path
 680 #
 681 # @queue: vhost_virtqueue index to examine
 682 #
 683 # Features:
 684 #
 685 # @unstable: This command is meant for debugging.
 686 #
 687 # Returns: VirtVhostQueueStatus of the vhost_virtqueue
 688 #
 689 # Since: 7.2
 690 #
 691 # Examples:
 692 #
 693 # 1. Get vhost_virtqueue status for vhost-crypto
 694 #
 695 # -> { "execute": "x-query-virtio-vhost-queue-status",
 696 #      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
 697 #                     "queue": 0 }
 698 #    }
 699 # <- { "return": {
 700 #          "avail-phys": 5216124928,
 701 #          "name": "virtio-crypto",
 702 #          "used-phys": 5216127040,
 703 #          "avail-size": 2054,
 704 #          "desc-size": 16384,
 705 #          "used-size": 8198,
 706 #          "desc": 140141447430144,
 707 #          "num": 1024,
 708 #          "call": 0,
 709 #          "avail": 140141447446528,
 710 #          "desc-phys": 5216108544,
 711 #          "used": 140141447448640,
 712 #          "kick": 0
 713 #      }
 714 #    }
 715 #
 716 # 2. Get vhost_virtqueue status for vhost-vsock
 717 #
 718 # -> { "execute": "x-query-virtio-vhost-queue-status",
 719 #      "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
 720 #                     "queue": 0 }
 721 #    }
 722 # <- { "return": {
 723 #          "avail-phys": 5182261248,
 724 #          "name": "vhost-vsock",
 725 #          "used-phys": 5182261568,
 726 #          "avail-size": 262,
 727 #          "desc-size": 2048,
 728 #          "used-size": 1030,
 729 #          "desc": 140141413580800,
 730 #          "num": 128,
 731 #          "call": 0,
 732 #          "avail": 140141413582848,
 733 #          "desc-phys": 5182259200,
 734 #          "used": 140141413583168,
 735 #          "kick": 0
 736 #      }
 737 #    }
 738 ##
 739 { 'command': 'x-query-virtio-vhost-queue-status',
 740   'data': { 'path': 'str', 'queue': 'uint16' },
 741   'returns': 'VirtVhostQueueStatus',
 742   'features': [ 'unstable' ] }
 743
 744 ##
 745 # @VirtioRingDesc:
 746 #
 747 # Information regarding the vring descriptor area
 748 #
 749 # @addr: Guest physical address of the descriptor area
 750 #
 751 # @len: Length of the descriptor area
 752 #
 753 # @flags: List of descriptor flags
 754 #
 755 # Since: 7.2
 756 ##
 757 { 'struct': 'VirtioRingDesc',
 758   'data': { 'addr': 'uint64',
 759             'len': 'uint32',
 760             'flags': [ 'str' ] } }
 761
 762 ##
 763 # @VirtioRingAvail:
 764 #
 765 # Information regarding the avail vring (a.k.a. driver area)
 766 #
 767 # @flags: VRingAvail flags
 768 #
 769 # @idx: VRingAvail index
 770 #
 771 # @ring: VRingAvail ring[] entry at provided index
 772 #
 773 # Since: 7.2
 774 ##
 775 { 'struct': 'VirtioRingAvail',
 776   'data': { 'flags': 'uint16',
 777             'idx': 'uint16',
 778             'ring': 'uint16' } }
 779
 780 ##
 781 # @VirtioRingUsed:
 782 #
 783 # Information regarding the used vring (a.k.a. device area)
 784 #
 785 # @flags: VRingUsed flags
 786 #
 787 # @idx: VRingUsed index
 788 #
 789 # Since: 7.2
 790 ##
 791 { 'struct': 'VirtioRingUsed',
 792   'data': { 'flags': 'uint16',
 793             'idx': 'uint16' } }
 794
 795 ##
 796 # @VirtioQueueElement:
 797 #
 798 # Information regarding a VirtQueue's VirtQueueElement including
 799 # descriptor, driver, and device areas
 800 #
 801 # @name: Name of the VirtIODevice that uses this VirtQueue
 802 #
 803 # @index: Index of the element in the queue
 804 #
 805 # @descs: List of descriptors (VirtioRingDesc)
 806 #
 807 # @avail: VRingAvail info
 808 #
 809 # @used: VRingUsed info
 810 #
 811 # Since: 7.2
 812 ##
 813 { 'struct': 'VirtioQueueElement',
 814   'data': { 'name': 'str',
 815             'index': 'uint32',
 816             'descs': [ 'VirtioRingDesc' ],
 817             'avail': 'VirtioRingAvail',
 818             'used': 'VirtioRingUsed' } }
 819
 820 ##
 821 # @x-query-virtio-queue-element:
 822 #
 823 # Return the information about a VirtQueue's VirtQueueElement
 824 #
 825 # @path: VirtIODevice canonical QOM path
 826 #
 827 # @queue: VirtQueue index to examine
 828 #
 829 # @index: Index of the element in the queue (default: head of the
 830 #     queue)
 831 #
 832 # Features:
 833 #
 834 # @unstable: This command is meant for debugging.
 835 #
 836 # Returns: VirtioQueueElement information
 837 #
 838 # Since: 7.2
 839 #
 840 # Examples:
 841 #
 842 # 1. Introspect on virtio-net's VirtQueue 0 at index 5
 843 #
 844 # -> { "execute": "x-query-virtio-queue-element",
 845 #      "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
 846 #                     "queue": 0,
 847 #                     "index": 5 }
 848 #    }
 849 # <- { "return": {
 850 #          "index": 5,
 851 #          "name": "virtio-net",
 852 #          "descs": [
 853 #              {
 854 #                  "flags": ["write"],
 855 #                  "len": 1536,
 856 #                  "addr": 5257305600
 857 #              }
 858 #          ],
 859 #          "avail": {
 860 #              "idx": 256,
 861 #              "flags": 0,
 862 #              "ring": 5
 863 #          },
 864 #          "used": {
 865 #              "idx": 13,
 866 #              "flags": 0
 867 #          }
 868 #      }
 869 #    }
 870 #
 871 # 2. Introspect on virtio-crypto's VirtQueue 1 at head
 872 #
 873 # -> { "execute": "x-query-virtio-queue-element",
 874 #      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
 875 #                     "queue": 1 }
 876 #    }
 877 # <- { "return": {
 878 #          "index": 0,
 879 #          "name": "virtio-crypto",
 880 #          "descs": [
 881 #              {
 882 #                  "flags": [],
 883 #                  "len": 0,
 884 #                  "addr": 8080268923184214134
 885 #              }
 886 #          ],
 887 #          "avail": {
 888 #              "idx": 280,
 889 #              "flags": 0,
 890 #              "ring": 0
 891 #          },
 892 #          "used": {
 893 #              "idx": 280,
 894 #              "flags": 0
 895 #          }
 896 #      }
 897 #    }
 898 #
 899 # 3. Introspect on virtio-scsi's VirtQueue 2 at head
 900 #
 901 # -> { "execute": "x-query-virtio-queue-element",
 902 #      "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
 903 #                     "queue": 2 }
 904 #    }
 905 # <- { "return": {
 906 #          "index": 19,
 907 #          "name": "virtio-scsi",
 908 #          "descs": [
 909 #              {
 910 #                  "flags": ["used", "indirect", "write"],
 911 #                  "len": 4099327944,
 912 #                  "addr": 12055409292258155293
 913 #              }
 914 #          ],
 915 #          "avail": {
 916 #              "idx": 1147,
 917 #              "flags": 0,
 918 #              "ring": 19
 919 #          },
 920 #          "used": {
 921 #              "idx": 280,
 922 #              "flags": 0
 923 #          }
 924 #      }
 925 #    }
 926 ##
 927 { 'command': 'x-query-virtio-queue-element',
 928   'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
 929   'returns': 'VirtioQueueElement',
 930   'features': [ 'unstable' ] }