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