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 physical
 646 #     address)
 647 #
 648 # @desc-size: vhost_virtqueue desc_size
 649 #
 650 # @avail-phys: vhost_virtqueue avail_phys (driver area physical
 651 #     address)
 652 #
 653 # @avail-size: vhost_virtqueue avail_size
 654 #
 655 # @used-phys: vhost_virtqueue used_phys (device area physical address)
 656 #
 657 # @used-size: vhost_virtqueue used_size
 658 #
 659 # Since: 7.2
 660 ##
 661 { 'struct': 'VirtVhostQueueStatus',
 662   'data': { 'name': 'str',
 663             'kick': 'int',
 664             'call': 'int',
 665             'desc': 'uint64',
 666             'avail': 'uint64',
 667             'used': 'uint64',
 668             'num': 'int',
 669             'desc-phys': 'uint64',
 670             'desc-size': 'uint32',
 671             'avail-phys': 'uint64',
 672             'avail-size': 'uint32',
 673             'used-phys': 'uint64',
 674             'used-size': 'uint32' } }
 675
 676 ##
 677 # @x-query-virtio-vhost-queue-status:
 678 #
 679 # Return information of a given vhost device's vhost_virtqueue
 680 #
 681 # @path: VirtIODevice canonical QOM path
 682 #
 683 # @queue: vhost_virtqueue index to examine
 684 #
 685 # Features:
 686 #
 687 # @unstable: This command is meant for debugging.
 688 #
 689 # Returns: VirtVhostQueueStatus of the vhost_virtqueue
 690 #
 691 # Since: 7.2
 692 #
 693 # Examples:
 694 #
 695 #     1. Get vhost_virtqueue status for vhost-crypto
 696 #
 697 #     -> { "execute": "x-query-virtio-vhost-queue-status",
 698 #          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
 699 #                         "queue": 0 }
 700 #        }
 701 #     <- { "return": {
 702 #              "avail-phys": 5216124928,
 703 #              "name": "virtio-crypto",
 704 #              "used-phys": 5216127040,
 705 #              "avail-size": 2054,
 706 #              "desc-size": 16384,
 707 #              "used-size": 8198,
 708 #              "desc": 140141447430144,
 709 #              "num": 1024,
 710 #              "call": 0,
 711 #              "avail": 140141447446528,
 712 #              "desc-phys": 5216108544,
 713 #              "used": 140141447448640,
 714 #              "kick": 0
 715 #          }
 716 #        }
 717 #
 718 #     2. Get vhost_virtqueue status for vhost-vsock
 719 #
 720 #     -> { "execute": "x-query-virtio-vhost-queue-status",
 721 #          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
 722 #                         "queue": 0 }
 723 #        }
 724 #     <- { "return": {
 725 #              "avail-phys": 5182261248,
 726 #              "name": "vhost-vsock",
 727 #              "used-phys": 5182261568,
 728 #              "avail-size": 262,
 729 #              "desc-size": 2048,
 730 #              "used-size": 1030,
 731 #              "desc": 140141413580800,
 732 #              "num": 128,
 733 #              "call": 0,
 734 #              "avail": 140141413582848,
 735 #              "desc-phys": 5182259200,
 736 #              "used": 140141413583168,
 737 #              "kick": 0
 738 #          }
 739 #        }
 740 ##
 741 { 'command': 'x-query-virtio-vhost-queue-status',
 742   'data': { 'path': 'str', 'queue': 'uint16' },
 743   'returns': 'VirtVhostQueueStatus',
 744   'features': [ 'unstable' ] }
 745
 746 ##
 747 # @VirtioRingDesc:
 748 #
 749 # Information regarding the vring descriptor area
 750 #
 751 # @addr: Guest physical address of the descriptor area
 752 #
 753 # @len: Length of the descriptor area
 754 #
 755 # @flags: List of descriptor flags
 756 #
 757 # Since: 7.2
 758 ##
 759 { 'struct': 'VirtioRingDesc',
 760   'data': { 'addr': 'uint64',
 761             'len': 'uint32',
 762             'flags': [ 'str' ] } }
 763
 764 ##
 765 # @VirtioRingAvail:
 766 #
 767 # Information regarding the avail vring (a.k.a. driver area)
 768 #
 769 # @flags: VRingAvail flags
 770 #
 771 # @idx: VRingAvail index
 772 #
 773 # @ring: VRingAvail ring[] entry at provided index
 774 #
 775 # Since: 7.2
 776 ##
 777 { 'struct': 'VirtioRingAvail',
 778   'data': { 'flags': 'uint16',
 779             'idx': 'uint16',
 780             'ring': 'uint16' } }
 781
 782 ##
 783 # @VirtioRingUsed:
 784 #
 785 # Information regarding the used vring (a.k.a. device area)
 786 #
 787 # @flags: VRingUsed flags
 788 #
 789 # @idx: VRingUsed index
 790 #
 791 # Since: 7.2
 792 ##
 793 { 'struct': 'VirtioRingUsed',
 794   'data': { 'flags': 'uint16',
 795             'idx': 'uint16' } }
 796
 797 ##
 798 # @VirtioQueueElement:
 799 #
 800 # Information regarding a VirtQueue's VirtQueueElement including
 801 # descriptor, driver, and device areas
 802 #
 803 # @name: Name of the VirtIODevice that uses this VirtQueue
 804 #
 805 # @index: Index of the element in the queue
 806 #
 807 # @descs: List of descriptors (VirtioRingDesc)
 808 #
 809 # @avail: VRingAvail info
 810 #
 811 # @used: VRingUsed info
 812 #
 813 # Since: 7.2
 814 ##
 815 { 'struct': 'VirtioQueueElement',
 816   'data': { 'name': 'str',
 817             'index': 'uint32',
 818             'descs': [ 'VirtioRingDesc' ],
 819             'avail': 'VirtioRingAvail',
 820             'used': 'VirtioRingUsed' } }
 821
 822 ##
 823 # @x-query-virtio-queue-element:
 824 #
 825 # Return the information about a VirtQueue's VirtQueueElement
 826 #
 827 # @path: VirtIODevice canonical QOM path
 828 #
 829 # @queue: VirtQueue index to examine
 830 #
 831 # @index: Index of the element in the queue (default: head of the
 832 #     queue)
 833 #
 834 # Features:
 835 #
 836 # @unstable: This command is meant for debugging.
 837 #
 838 # Returns: VirtioQueueElement information
 839 #
 840 # Since: 7.2
 841 #
 842 # Examples:
 843 #
 844 #     1. Introspect on virtio-net's VirtQueue 0 at index 5
 845 #
 846 #     -> { "execute": "x-query-virtio-queue-element",
 847 #          "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
 848 #                         "queue": 0,
 849 #                         "index": 5 }
 850 #        }
 851 #     <- { "return": {
 852 #              "index": 5,
 853 #              "name": "virtio-net",
 854 #              "descs": [
 855 #                  {
 856 #                      "flags": ["write"],
 857 #                      "len": 1536,
 858 #                      "addr": 5257305600
 859 #                  }
 860 #              ],
 861 #              "avail": {
 862 #                  "idx": 256,
 863 #                  "flags": 0,
 864 #                  "ring": 5
 865 #              },
 866 #              "used": {
 867 #                  "idx": 13,
 868 #                  "flags": 0
 869 #              }
 870 #          }
 871 #        }
 872 #
 873 #     2. Introspect on virtio-crypto's VirtQueue 1 at head
 874 #
 875 #     -> { "execute": "x-query-virtio-queue-element",
 876 #          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
 877 #                         "queue": 1 }
 878 #        }
 879 #     <- { "return": {
 880 #              "index": 0,
 881 #              "name": "virtio-crypto",
 882 #              "descs": [
 883 #                  {
 884 #                      "flags": [],
 885 #                      "len": 0,
 886 #                      "addr": 8080268923184214134
 887 #                  }
 888 #              ],
 889 #              "avail": {
 890 #                  "idx": 280,
 891 #                  "flags": 0,
 892 #                  "ring": 0
 893 #              },
 894 #              "used": {
 895 #                  "idx": 280,
 896 #                  "flags": 0
 897 #              }
 898 #          }
 899 #        }
 900 #
 901 #     3. Introspect on virtio-scsi's VirtQueue 2 at head
 902 #
 903 #     -> { "execute": "x-query-virtio-queue-element",
 904 #          "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
 905 #                         "queue": 2 }
 906 #        }
 907 #     <- { "return": {
 908 #              "index": 19,
 909 #              "name": "virtio-scsi",
 910 #              "descs": [
 911 #                  {
 912 #                      "flags": ["used", "indirect", "write"],
 913 #                      "len": 4099327944,
 914 #                      "addr": 12055409292258155293
 915 #                  }
 916 #              ],
 917 #              "avail": {
 918 #                  "idx": 1147,
 919 #                  "flags": 0,
 920 #                  "ring": 19
 921 #              },
 922 #              "used": {
 923 #                  "idx": 280,
 924 #                  "flags": 0
 925 #              }
 926 #          }
 927 #        }
 928 ##
 929 { 'command': 'x-query-virtio-queue-element',
 930   'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
 931   'returns': 'VirtioQueueElement',
 932   'features': [ 'unstable' ] }
 933
 934 ##
 935 # @IOThreadVirtQueueMapping:
 936 #
 937 # Describes the subset of virtqueues assigned to an IOThread.
 938 #
 939 # @iothread: the id of IOThread object
 940 #
 941 # @vqs: an optional array of virtqueue indices that will be handled by
 942 #     this IOThread.  When absent, virtqueues are assigned round-robin
 943 #     across all IOThreadVirtQueueMappings provided.  Either all
 944 #     IOThreadVirtQueueMappings must have @vqs or none of them must
 945 #     have it.
 946 #
 947 # Since: 9.0
 948 ##
 949
 950 { 'struct': 'IOThreadVirtQueueMapping',
 951   'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
 952
 953 ##
 954 # @DummyVirtioForceArrays:
 955 #
 956 # Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
 957 # internally
 958 #
 959 # Since: 9.0
 960 ##
 961
 962 { 'struct': 'DummyVirtioForceArrays',
 963   'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } }
 964
 965 ##
 966 # @GranuleMode:
 967 #
 968 # @4k: granule page size of 4KiB
 969 #
 970 # @8k: granule page size of 8KiB
 971 #
 972 # @16k: granule page size of 16KiB
 973 #
 974 # @64k: granule page size of 64KiB
 975 #
 976 # @host: granule matches the host page size
 977 #
 978 # Since: 9.0
 979 ##
 980 { 'enum': 'GranuleMode',
 981   'data': [ '4k', '8k', '16k', '64k', 'host' ] }