qapi/migration.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4
   5 ##
   6 # = Migration
   7 ##
   8
   9 { 'include': 'common.json' }
  10 { 'include': 'sockets.json' }
  11
  12 ##
  13 # @MigrationStats:
  14 #
  15 # Detailed migration status.
  16 #
  17 # @transferred: amount of bytes already transferred to the target VM
  18 #
  19 # @remaining: amount of bytes remaining to be transferred to the target VM
  20 #
  21 # @total: total amount of bytes involved in the migration process
  22 #
  23 # @duplicate: number of duplicate (zero) pages (since 1.2)
  24 #
  25 # @skipped: number of skipped zero pages (since 1.5)
  26 #
  27 # @normal: number of normal pages (since 1.2)
  28 #
  29 # @normal-bytes: number of normal bytes sent (since 1.2)
  30 #
  31 # @dirty-pages-rate: number of pages dirtied by second by the
  32 #                    guest (since 1.3)
  33 #
  34 # @mbps: throughput in megabits/sec. (since 1.6)
  35 #
  36 # @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
  37 #
  38 # @postcopy-requests: The number of page requests received from the destination
  39 #                     (since 2.7)
  40 #
  41 # @page-size: The number of bytes per page for the various page-based
  42 #             statistics (since 2.10)
  43 #
  44 # @multifd-bytes: The number of bytes sent through multifd (since 3.0)
  45 #
  46 # @pages-per-second: the number of memory pages transferred per second
  47 #                    (Since 4.0)
  48 #
  49 # @precopy-bytes: The number of bytes sent in the pre-copy phase
  50 #                 (since 7.0).
  51 #
  52 # @downtime-bytes: The number of bytes sent while the guest is paused
  53 #                  (since 7.0).
  54 #
  55 # @postcopy-bytes: The number of bytes sent during the post-copy phase
  56 #                  (since 7.0).
  57 #
  58 # Since: 0.14
  59 ##
  60 { 'struct': 'MigrationStats',
  61   'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
  62            'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
  63            'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
  64            'mbps' : 'number', 'dirty-sync-count' : 'int',
  65            'postcopy-requests' : 'int', 'page-size' : 'int',
  66            'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64',
  67            'precopy-bytes' : 'uint64', 'downtime-bytes' : 'uint64',
  68            'postcopy-bytes' : 'uint64' } }
  69
  70 ##
  71 # @XBZRLECacheStats:
  72 #
  73 # Detailed XBZRLE migration cache statistics
  74 #
  75 # @cache-size: XBZRLE cache size
  76 #
  77 # @bytes: amount of bytes already transferred to the target VM
  78 #
  79 # @pages: amount of pages transferred to the target VM
  80 #
  81 # @cache-miss: number of cache miss
  82 #
  83 # @cache-miss-rate: rate of cache miss (since 2.1)
  84 #
  85 # @encoding-rate: rate of encoded bytes (since 5.1)
  86 #
  87 # @overflow: number of overflows
  88 #
  89 # Since: 1.2
  90 ##
  91 { 'struct': 'XBZRLECacheStats',
  92   'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int',
  93            'cache-miss': 'int', 'cache-miss-rate': 'number',
  94            'encoding-rate': 'number', 'overflow': 'int' } }
  95
  96 ##
  97 # @CompressionStats:
  98 #
  99 # Detailed migration compression statistics
 100 #
 101 # @pages: amount of pages compressed and transferred to the target VM
 102 #
 103 # @busy: count of times that no free thread was available to compress data
 104 #
 105 # @busy-rate: rate of thread busy
 106 #
 107 # @compressed-size: amount of bytes after compression
 108 #
 109 # @compression-rate: rate of compressed size
 110 #
 111 # Since: 3.1
 112 ##
 113 { 'struct': 'CompressionStats',
 114   'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number',
 115            'compressed-size': 'int', 'compression-rate': 'number' } }
 116
 117 ##
 118 # @MigrationStatus:
 119 #
 120 # An enumeration of migration status.
 121 #
 122 # @none: no migration has ever happened.
 123 #
 124 # @setup: migration process has been initiated.
 125 #
 126 # @cancelling: in the process of cancelling migration.
 127 #
 128 # @cancelled: cancelling migration is finished.
 129 #
 130 # @active: in the process of doing migration.
 131 #
 132 # @postcopy-active: like active, but now in postcopy mode. (since 2.5)
 133 #
 134 # @postcopy-paused: during postcopy but paused. (since 3.0)
 135 #
 136 # @postcopy-recover: trying to recover from a paused postcopy. (since 3.0)
 137 #
 138 # @completed: migration is finished.
 139 #
 140 # @failed: some error occurred during migration process.
 141 #
 142 # @colo: VM is in the process of fault tolerance, VM can not get into this
 143 #        state unless colo capability is enabled for migration. (since 2.8)
 144 #
 145 # @pre-switchover: Paused before device serialisation. (since 2.11)
 146 #
 147 # @device: During device serialisation when pause-before-switchover is enabled
 148 #          (since 2.11)
 149 #
 150 # @wait-unplug: wait for device unplug request by guest OS to be completed.
 151 #               (since 4.2)
 152 #
 153 # Since: 2.3
 154 ##
 155 { 'enum': 'MigrationStatus',
 156   'data': [ 'none', 'setup', 'cancelling', 'cancelled',
 157             'active', 'postcopy-active', 'postcopy-paused',
 158             'postcopy-recover', 'completed', 'failed', 'colo',
 159             'pre-switchover', 'device', 'wait-unplug' ] }
 160 ##
 161 # @VfioStats:
 162 #
 163 # Detailed VFIO devices migration statistics
 164 #
 165 # @transferred: amount of bytes transferred to the target VM by VFIO devices
 166 #
 167 # Since: 5.2
 168 ##
 169 { 'struct': 'VfioStats',
 170   'data': {'transferred': 'int' } }
 171
 172 ##
 173 # @MigrationInfo:
 174 #
 175 # Information about current migration process.
 176 #
 177 # @status: @MigrationStatus describing the current migration status.
 178 #          If this field is not returned, no migration process
 179 #          has been initiated
 180 #
 181 # @ram: @MigrationStats containing detailed migration
 182 #       status, only returned if status is 'active' or
 183 #       'completed'(since 1.2)
 184 #
 185 # @disk: @MigrationStats containing detailed disk migration
 186 #        status, only returned if status is 'active' and it is a block
 187 #        migration
 188 #
 189 # @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
 190 #                migration statistics, only returned if XBZRLE feature is on and
 191 #                status is 'active' or 'completed' (since 1.2)
 192 #
 193 # @total-time: total amount of milliseconds since migration started.
 194 #              If migration has ended, it returns the total migration
 195 #              time. (since 1.2)
 196 #
 197 # @downtime: only present when migration finishes correctly
 198 #            total downtime in milliseconds for the guest.
 199 #            (since 1.3)
 200 #
 201 # @expected-downtime: only present while migration is active
 202 #                     expected downtime in milliseconds for the guest in last walk
 203 #                     of the dirty bitmap. (since 1.3)
 204 #
 205 # @setup-time: amount of setup time in milliseconds *before* the
 206 #              iterations begin but *after* the QMP command is issued. This is designed
 207 #              to provide an accounting of any activities (such as RDMA pinning) which
 208 #              may be expensive, but do not actually occur during the iterative
 209 #              migration rounds themselves. (since 1.6)
 210 #
 211 # @cpu-throttle-percentage: percentage of time guest cpus are being
 212 #                           throttled during auto-converge. This is only present when auto-converge
 213 #                           has started throttling guest cpus. (Since 2.7)
 214 #
 215 # @error-desc: the human readable error description string, when
 216 #              @status is 'failed'. Clients should not attempt to parse the
 217 #              error strings. (Since 2.7)
 218 #
 219 # @postcopy-blocktime: total time when all vCPU were blocked during postcopy
 220 #                      live migration. This is only present when the postcopy-blocktime
 221 #                      migration capability is enabled. (Since 3.0)
 222 #
 223 # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.  This is
 224 #                           only present when the postcopy-blocktime migration capability
 225 #                           is enabled. (Since 3.0)
 226 #
 227 # @compression: migration compression statistics, only returned if compression
 228 #               feature is on and status is 'active' or 'completed' (Since 3.1)
 229 #
 230 # @socket-address: Only used for tcp, to know what the real port is (Since 4.0)
 231 #
 232 # @vfio: @VfioStats containing detailed VFIO devices migration statistics,
 233 #        only returned if VFIO device is present, migration is supported by all
 234 #        VFIO devices and status is 'active' or 'completed' (since 5.2)
 235 #
 236 # @blocked-reasons: A list of reasons an outgoing migration is blocked.
 237 #                   Present and non-empty when migration is blocked.
 238 #                   (since 6.0)
 239 #
 240 # Since: 0.14
 241 ##
 242 { 'struct': 'MigrationInfo',
 243   'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
 244            '*disk': 'MigrationStats',
 245            '*vfio': 'VfioStats',
 246            '*xbzrle-cache': 'XBZRLECacheStats',
 247            '*total-time': 'int',
 248            '*expected-downtime': 'int',
 249            '*downtime': 'int',
 250            '*setup-time': 'int',
 251            '*cpu-throttle-percentage': 'int',
 252            '*error-desc': 'str',
 253            '*blocked-reasons': ['str'],
 254            '*postcopy-blocktime' : 'uint32',
 255            '*postcopy-vcpu-blocktime': ['uint32'],
 256            '*compression': 'CompressionStats',
 257            '*socket-address': ['SocketAddress'] } }
 258
 259 ##
 260 # @query-migrate:
 261 #
 262 # Returns information about current migration process. If migration
 263 # is active there will be another json-object with RAM migration
 264 # status and if block migration is active another one with block
 265 # migration status.
 266 #
 267 # Returns: @MigrationInfo
 268 #
 269 # Since: 0.14
 270 #
 271 # Example:
 272 #
 273 # 1. Before the first migration
 274 #
 275 # -> { "execute": "query-migrate" }
 276 # <- { "return": {} }
 277 #
 278 # 2. Migration is done and has succeeded
 279 #
 280 # -> { "execute": "query-migrate" }
 281 # <- { "return": {
 282 #         "status": "completed",
 283 #         "total-time":12345,
 284 #         "setup-time":12345,
 285 #         "downtime":12345,
 286 #         "ram":{
 287 #           "transferred":123,
 288 #           "remaining":123,
 289 #           "total":246,
 290 #           "duplicate":123,
 291 #           "normal":123,
 292 #           "normal-bytes":123456,
 293 #           "dirty-sync-count":15
 294 #         }
 295 #      }
 296 #    }
 297 #
 298 # 3. Migration is done and has failed
 299 #
 300 # -> { "execute": "query-migrate" }
 301 # <- { "return": { "status": "failed" } }
 302 #
 303 # 4. Migration is being performed and is not a block migration:
 304 #
 305 # -> { "execute": "query-migrate" }
 306 # <- {
 307 #       "return":{
 308 #          "status":"active",
 309 #          "total-time":12345,
 310 #          "setup-time":12345,
 311 #          "expected-downtime":12345,
 312 #          "ram":{
 313 #             "transferred":123,
 314 #             "remaining":123,
 315 #             "total":246,
 316 #             "duplicate":123,
 317 #             "normal":123,
 318 #             "normal-bytes":123456,
 319 #             "dirty-sync-count":15
 320 #          }
 321 #       }
 322 #    }
 323 #
 324 # 5. Migration is being performed and is a block migration:
 325 #
 326 # -> { "execute": "query-migrate" }
 327 # <- {
 328 #       "return":{
 329 #          "status":"active",
 330 #          "total-time":12345,
 331 #          "setup-time":12345,
 332 #          "expected-downtime":12345,
 333 #          "ram":{
 334 #             "total":1057024,
 335 #             "remaining":1053304,
 336 #             "transferred":3720,
 337 #             "duplicate":123,
 338 #             "normal":123,
 339 #             "normal-bytes":123456,
 340 #             "dirty-sync-count":15
 341 #          },
 342 #          "disk":{
 343 #             "total":20971520,
 344 #             "remaining":20880384,
 345 #             "transferred":91136
 346 #          }
 347 #       }
 348 #    }
 349 #
 350 # 6. Migration is being performed and XBZRLE is active:
 351 #
 352 # -> { "execute": "query-migrate" }
 353 # <- {
 354 #       "return":{
 355 #          "status":"active",
 356 #          "total-time":12345,
 357 #          "setup-time":12345,
 358 #          "expected-downtime":12345,
 359 #          "ram":{
 360 #             "total":1057024,
 361 #             "remaining":1053304,
 362 #             "transferred":3720,
 363 #             "duplicate":10,
 364 #             "normal":3333,
 365 #             "normal-bytes":3412992,
 366 #             "dirty-sync-count":15
 367 #          },
 368 #          "xbzrle-cache":{
 369 #             "cache-size":67108864,
 370 #             "bytes":20971520,
 371 #             "pages":2444343,
 372 #             "cache-miss":2244,
 373 #             "cache-miss-rate":0.123,
 374 #             "encoding-rate":80.1,
 375 #             "overflow":34434
 376 #          }
 377 #       }
 378 #    }
 379 #
 380 ##
 381 { 'command': 'query-migrate', 'returns': 'MigrationInfo' }
 382
 383 ##
 384 # @MigrationCapability:
 385 #
 386 # Migration capabilities enumeration
 387 #
 388 # @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
 389 #          This feature allows us to minimize migration traffic for certain work
 390 #          loads, by sending compressed difference of the pages
 391 #
 392 # @rdma-pin-all: Controls whether or not the entire VM memory footprint is
 393 #                mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
 394 #                Disabled by default. (since 2.0)
 395 #
 396 # @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
 397 #               essentially saves 1MB of zeroes per block on the wire. Enabling requires
 398 #               source and target VM to support this feature. To enable it is sufficient
 399 #               to enable the capability on the source VM. The feature is disabled by
 400 #               default. (since 1.6)
 401 #
 402 # @compress: Use multiple compression threads to accelerate live migration.
 403 #            This feature can help to reduce the migration traffic, by sending
 404 #            compressed pages. Please note that if compress and xbzrle are both
 405 #            on, compress only takes effect in the ram bulk stage, after that,
 406 #            it will be disabled and only xbzrle takes effect, this can help to
 407 #            minimize migration traffic. The feature is disabled by default.
 408 #            (since 2.4 )
 409 #
 410 # @events: generate events for each migration state change
 411 #          (since 2.4 )
 412 #
 413 # @auto-converge: If enabled, QEMU will automatically throttle down the guest
 414 #                 to speed up convergence of RAM migration. (since 1.6)
 415 #
 416 # @postcopy-ram: Start executing on the migration target before all of RAM has
 417 #                been migrated, pulling the remaining pages along as needed. The
 418 #                capacity must have the same setting on both source and target
 419 #                or migration will not even start. NOTE: If the migration fails during
 420 #                postcopy the VM will fail.  (since 2.6)
 421 #
 422 # @x-colo: If enabled, migration will never end, and the state of the VM on the
 423 #          primary side will be migrated continuously to the VM on secondary
 424 #          side, this process is called COarse-Grain LOck Stepping (COLO) for
 425 #          Non-stop Service. (since 2.8)
 426 #
 427 # @release-ram: if enabled, qemu will free the migrated ram pages on the source
 428 #               during postcopy-ram migration. (since 2.9)
 429 #
 430 # @block: If enabled, QEMU will also migrate the contents of all block
 431 #         devices.  Default is disabled.  A possible alternative uses
 432 #         mirror jobs to a builtin NBD server on the destination, which
 433 #         offers more flexibility.
 434 #         (Since 2.10)
 435 #
 436 # @return-path: If enabled, migration will use the return path even
 437 #               for precopy. (since 2.10)
 438 #
 439 # @pause-before-switchover: Pause outgoing migration before serialising device
 440 #                           state and before disabling block IO (since 2.11)
 441 #
 442 # @multifd: Use more than one fd for migration (since 4.0)
 443 #
 444 # @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps.
 445 #                 (since 2.12)
 446 #
 447 # @postcopy-blocktime: Calculate downtime for postcopy live migration
 448 #                      (since 3.0)
 449 #
 450 # @late-block-activate: If enabled, the destination will not activate block
 451 #                       devices (and thus take locks) immediately at the end of migration.
 452 #                       (since 3.0)
 453 #
 454 # @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0)
 455 #
 456 # @validate-uuid: Send the UUID of the source to allow the destination
 457 #                 to ensure it is the same. (since 4.2)
 458 #
 459 # @background-snapshot: If enabled, the migration stream will be a snapshot
 460 #                       of the VM exactly at the point when the migration
 461 #                       procedure starts. The VM RAM is saved with running VM.
 462 #                       (since 6.0)
 463 #
 464 # Features:
 465 # @unstable: Members @x-colo and @x-ignore-shared are experimental.
 466 #
 467 # Since: 1.2
 468 ##
 469 { 'enum': 'MigrationCapability',
 470   'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
 471            'compress', 'events', 'postcopy-ram',
 472            { 'name': 'x-colo', 'features': [ 'unstable' ] },
 473            'release-ram',
 474            'block', 'return-path', 'pause-before-switchover', 'multifd',
 475            'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate',
 476            { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] },
 477            'validate-uuid', 'background-snapshot'] }
 478
 479 ##
 480 # @MigrationCapabilityStatus:
 481 #
 482 # Migration capability information
 483 #
 484 # @capability: capability enum
 485 #
 486 # @state: capability state bool
 487 #
 488 # Since: 1.2
 489 ##
 490 { 'struct': 'MigrationCapabilityStatus',
 491   'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
 492
 493 ##
 494 # @migrate-set-capabilities:
 495 #
 496 # Enable/Disable the following migration capabilities (like xbzrle)
 497 #
 498 # @capabilities: json array of capability modifications to make
 499 #
 500 # Since: 1.2
 501 #
 502 # Example:
 503 #
 504 # -> { "execute": "migrate-set-capabilities" , "arguments":
 505 #      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
 506 #
 507 ##
 508 { 'command': 'migrate-set-capabilities',
 509   'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
 510
 511 ##
 512 # @query-migrate-capabilities:
 513 #
 514 # Returns information about the current migration capabilities status
 515 #
 516 # Returns: @MigrationCapabilitiesStatus
 517 #
 518 # Since: 1.2
 519 #
 520 # Example:
 521 #
 522 # -> { "execute": "query-migrate-capabilities" }
 523 # <- { "return": [
 524 #       {"state": false, "capability": "xbzrle"},
 525 #       {"state": false, "capability": "rdma-pin-all"},
 526 #       {"state": false, "capability": "auto-converge"},
 527 #       {"state": false, "capability": "zero-blocks"},
 528 #       {"state": false, "capability": "compress"},
 529 #       {"state": true, "capability": "events"},
 530 #       {"state": false, "capability": "postcopy-ram"},
 531 #       {"state": false, "capability": "x-colo"}
 532 #    ]}
 533 #
 534 ##
 535 { 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
 536
 537 ##
 538 # @MultiFDCompression:
 539 #
 540 # An enumeration of multifd compression methods.
 541 #
 542 # @none: no compression.
 543 # @zlib: use zlib compression method.
 544 # @zstd: use zstd compression method.
 545 #
 546 # Since: 5.0
 547 ##
 548 { 'enum': 'MultiFDCompression',
 549   'data': [ 'none', 'zlib',
 550             { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] }
 551
 552 ##
 553 # @BitmapMigrationBitmapAliasTransform:
 554 #
 555 # @persistent: If present, the bitmap will be made persistent
 556 #              or transient depending on this parameter.
 557 #
 558 # Since: 6.0
 559 ##
 560 { 'struct': 'BitmapMigrationBitmapAliasTransform',
 561   'data': {
 562       '*persistent': 'bool'
 563   } }
 564
 565 ##
 566 # @BitmapMigrationBitmapAlias:
 567 #
 568 # @name: The name of the bitmap.
 569 #
 570 # @alias: An alias name for migration (for example the bitmap name on
 571 #         the opposite site).
 572 #
 573 # @transform: Allows the modification of the migrated bitmap.
 574 #             (since 6.0)
 575 #
 576 # Since: 5.2
 577 ##
 578 { 'struct': 'BitmapMigrationBitmapAlias',
 579   'data': {
 580       'name': 'str',
 581       'alias': 'str',
 582       '*transform': 'BitmapMigrationBitmapAliasTransform'
 583   } }
 584
 585 ##
 586 # @BitmapMigrationNodeAlias:
 587 #
 588 # Maps a block node name and the bitmaps it has to aliases for dirty
 589 # bitmap migration.
 590 #
 591 # @node-name: A block node name.
 592 #
 593 # @alias: An alias block node name for migration (for example the
 594 #         node name on the opposite site).
 595 #
 596 # @bitmaps: Mappings for the bitmaps on this node.
 597 #
 598 # Since: 5.2
 599 ##
 600 { 'struct': 'BitmapMigrationNodeAlias',
 601   'data': {
 602       'node-name': 'str',
 603       'alias': 'str',
 604       'bitmaps': [ 'BitmapMigrationBitmapAlias' ]
 605   } }
 606
 607 ##
 608 # @MigrationParameter:
 609 #
 610 # Migration parameters enumeration
 611 #
 612 # @announce-initial: Initial delay (in milliseconds) before sending the first
 613 #                    announce (Since 4.0)
 614 #
 615 # @announce-max: Maximum delay (in milliseconds) between packets in the
 616 #                announcement (Since 4.0)
 617 #
 618 # @announce-rounds: Number of self-announce packets sent after migration
 619 #                   (Since 4.0)
 620 #
 621 # @announce-step: Increase in delay (in milliseconds) between subsequent
 622 #                 packets in the announcement (Since 4.0)
 623 #
 624 # @compress-level: Set the compression level to be used in live migration,
 625 #                  the compression level is an integer between 0 and 9, where 0 means
 626 #                  no compression, 1 means the best compression speed, and 9 means best
 627 #                  compression ratio which will consume more CPU.
 628 #
 629 # @compress-threads: Set compression thread count to be used in live migration,
 630 #                    the compression thread count is an integer between 1 and 255.
 631 #
 632 # @compress-wait-thread: Controls behavior when all compression threads are
 633 #                        currently busy. If true (default), wait for a free
 634 #                        compression thread to become available; otherwise,
 635 #                        send the page uncompressed. (Since 3.1)
 636 #
 637 # @decompress-threads: Set decompression thread count to be used in live
 638 #                      migration, the decompression thread count is an integer between 1
 639 #                      and 255. Usually, decompression is at least 4 times as fast as
 640 #                      compression, so set the decompress-threads to the number about 1/4
 641 #                      of compress-threads is adequate.
 642 #
 643 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
 644 #                              to trigger throttling. It is expressed as percentage.
 645 #                              The default value is 50. (Since 5.0)
 646 #
 647 # @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
 648 #                        when migration auto-converge is activated. The
 649 #                        default value is 20. (Since 2.7)
 650 #
 651 # @cpu-throttle-increment: throttle percentage increase each time
 652 #                          auto-converge detects that migration is not making
 653 #                          progress. The default value is 10. (Since 2.7)
 654 #
 655 # @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
 656 #                         At the tail stage of throttling, the Guest is very
 657 #                         sensitive to CPU percentage while the @cpu-throttle
 658 #                         -increment is excessive usually at tail stage.
 659 #                         If this parameter is true, we will compute the ideal
 660 #                         CPU percentage used by the Guest, which may exactly make
 661 #                         the dirty rate match the dirty rate threshold. Then we
 662 #                         will choose a smaller throttle increment between the
 663 #                         one specified by @cpu-throttle-increment and the one
 664 #                         generated by ideal CPU percentage.
 665 #                         Therefore, it is compatible to traditional throttling,
 666 #                         meanwhile the throttle increment won't be excessive
 667 #                         at tail stage.
 668 #                         The default value is false. (Since 5.1)
 669 #
 670 # @tls-creds: ID of the 'tls-creds' object that provides credentials for
 671 #             establishing a TLS connection over the migration data channel.
 672 #             On the outgoing side of the migration, the credentials must
 673 #             be for a 'client' endpoint, while for the incoming side the
 674 #             credentials must be for a 'server' endpoint. Setting this
 675 #             will enable TLS for all migrations. The default is unset,
 676 #             resulting in unsecured migration at the QEMU level. (Since 2.7)
 677 #
 678 # @tls-hostname: hostname of the target host for the migration. This is
 679 #                required when using x509 based TLS credentials and the
 680 #                migration URI does not already include a hostname. For
 681 #                example if using fd: or exec: based migration, the
 682 #                hostname must be provided so that the server's x509
 683 #                certificate identity can be validated. (Since 2.7)
 684 #
 685 # @tls-authz: ID of the 'authz' object subclass that provides access control
 686 #             checking of the TLS x509 certificate distinguished name.
 687 #             This object is only resolved at time of use, so can be deleted
 688 #             and recreated on the fly while the migration server is active.
 689 #             If missing, it will default to denying access (Since 4.0)
 690 #
 691 # @max-bandwidth: to set maximum speed for migration. maximum speed in
 692 #                 bytes per second. (Since 2.8)
 693 #
 694 # @downtime-limit: set maximum tolerated downtime for migration. maximum
 695 #                  downtime in milliseconds (Since 2.8)
 696 #
 697 # @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
 698 #                      periodic mode. (Since 2.8)
 699 #
 700 # @block-incremental: Affects how much storage is migrated when the
 701 #                     block migration capability is enabled.  When false, the entire
 702 #                     storage backing chain is migrated into a flattened image at
 703 #                     the destination; when true, only the active qcow2 layer is
 704 #                     migrated and the destination must already have access to the
 705 #                     same backing chain as was used on the source.  (since 2.10)
 706 #
 707 # @multifd-channels: Number of channels used to migrate data in
 708 #                    parallel. This is the same number that the
 709 #                    number of sockets used for migration.  The
 710 #                    default value is 2 (since 4.0)
 711 #
 712 # @xbzrle-cache-size: cache size to be used by XBZRLE migration.  It
 713 #                     needs to be a multiple of the target page size
 714 #                     and a power of 2
 715 #                     (Since 2.11)
 716 #
 717 # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
 718 #                          Defaults to 0 (unlimited).  In bytes per second.
 719 #                          (Since 3.0)
 720 #
 721 # @max-cpu-throttle: maximum cpu throttle percentage.
 722 #                    Defaults to 99. (Since 3.1)
 723 #
 724 # @multifd-compression: Which compression method to use.
 725 #                       Defaults to none. (Since 5.0)
 726 #
 727 # @multifd-zlib-level: Set the compression level to be used in live
 728 #                      migration, the compression level is an integer between 0
 729 #                      and 9, where 0 means no compression, 1 means the best
 730 #                      compression speed, and 9 means best compression ratio which
 731 #                      will consume more CPU.
 732 #                      Defaults to 1. (Since 5.0)
 733 #
 734 # @multifd-zstd-level: Set the compression level to be used in live
 735 #                      migration, the compression level is an integer between 0
 736 #                      and 20, where 0 means no compression, 1 means the best
 737 #                      compression speed, and 20 means best compression ratio which
 738 #                      will consume more CPU.
 739 #                      Defaults to 1. (Since 5.0)
 740 #
 741 # @zero-copy-send: Controls behavior on sending memory pages on migration.
 742 #                  When true, enables a zero-copy mechanism for sending
 743 #                  memory pages, if host supports it.
 744 #                  Requires that QEMU be permitted to use locked memory
 745 #                  for guest RAM pages.
 746 #                  Defaults to false. (Since 7.1)
 747 #
 748 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 749 #                        aliases for the purpose of dirty bitmap migration.  Such
 750 #                        aliases may for example be the corresponding names on the
 751 #                        opposite site.
 752 #                        The mapping must be one-to-one, but not necessarily
 753 #                        complete: On the source, unmapped bitmaps and all bitmaps
 754 #                        on unmapped nodes will be ignored.  On the destination,
 755 #                        encountering an unmapped alias in the incoming migration
 756 #                        stream will result in a report, and all further bitmap
 757 #                        migration data will then be discarded.
 758 #                        Note that the destination does not know about bitmaps it
 759 #                        does not receive, so there is no limitation or requirement
 760 #                        regarding the number of bitmaps received, or how they are
 761 #                        named, or on which nodes they are placed.
 762 #                        By default (when this parameter has never been set), bitmap
 763 #                        names are mapped to themselves.  Nodes are mapped to their
 764 #                        block device name if there is one, and to their node name
 765 #                        otherwise. (Since 5.2)
 766 #
 767 # Features:
 768 # @unstable: Member @x-checkpoint-delay is experimental.
 769 #
 770 # Since: 2.4
 771 ##
 772 { 'enum': 'MigrationParameter',
 773   'data': ['announce-initial', 'announce-max',
 774            'announce-rounds', 'announce-step',
 775            'compress-level', 'compress-threads', 'decompress-threads',
 776            'compress-wait-thread', 'throttle-trigger-threshold',
 777            'cpu-throttle-initial', 'cpu-throttle-increment',
 778            'cpu-throttle-tailslow',
 779            'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
 780            'downtime-limit',
 781            { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] },
 782            'block-incremental',
 783            'multifd-channels',
 784            'xbzrle-cache-size', 'max-postcopy-bandwidth',
 785            'max-cpu-throttle', 'multifd-compression',
 786            'multifd-zlib-level' ,'multifd-zstd-level',
 787            { 'name': 'zero-copy-send', 'if' : 'CONFIG_LINUX'},
 788            'block-bitmap-mapping' ] }
 789
 790 ##
 791 # @MigrateSetParameters:
 792 #
 793 # @announce-initial: Initial delay (in milliseconds) before sending the first
 794 #                    announce (Since 4.0)
 795 #
 796 # @announce-max: Maximum delay (in milliseconds) between packets in the
 797 #                announcement (Since 4.0)
 798 #
 799 # @announce-rounds: Number of self-announce packets sent after migration
 800 #                   (Since 4.0)
 801 #
 802 # @announce-step: Increase in delay (in milliseconds) between subsequent
 803 #                 packets in the announcement (Since 4.0)
 804 #
 805 # @compress-level: compression level
 806 #
 807 # @compress-threads: compression thread count
 808 #
 809 # @compress-wait-thread: Controls behavior when all compression threads are
 810 #                        currently busy. If true (default), wait for a free
 811 #                        compression thread to become available; otherwise,
 812 #                        send the page uncompressed. (Since 3.1)
 813 #
 814 # @decompress-threads: decompression thread count
 815 #
 816 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
 817 #                              to trigger throttling. It is expressed as percentage.
 818 #                              The default value is 50. (Since 5.0)
 819 #
 820 # @cpu-throttle-initial: Initial percentage of time guest cpus are
 821 #                        throttled when migration auto-converge is activated.
 822 #                        The default value is 20. (Since 2.7)
 823 #
 824 # @cpu-throttle-increment: throttle percentage increase each time
 825 #                          auto-converge detects that migration is not making
 826 #                          progress. The default value is 10. (Since 2.7)
 827 #
 828 # @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
 829 #                         At the tail stage of throttling, the Guest is very
 830 #                         sensitive to CPU percentage while the @cpu-throttle
 831 #                         -increment is excessive usually at tail stage.
 832 #                         If this parameter is true, we will compute the ideal
 833 #                         CPU percentage used by the Guest, which may exactly make
 834 #                         the dirty rate match the dirty rate threshold. Then we
 835 #                         will choose a smaller throttle increment between the
 836 #                         one specified by @cpu-throttle-increment and the one
 837 #                         generated by ideal CPU percentage.
 838 #                         Therefore, it is compatible to traditional throttling,
 839 #                         meanwhile the throttle increment won't be excessive
 840 #                         at tail stage.
 841 #                         The default value is false. (Since 5.1)
 842 #
 843 # @tls-creds: ID of the 'tls-creds' object that provides credentials
 844 #             for establishing a TLS connection over the migration data
 845 #             channel. On the outgoing side of the migration, the credentials
 846 #             must be for a 'client' endpoint, while for the incoming side the
 847 #             credentials must be for a 'server' endpoint. Setting this
 848 #             to a non-empty string enables TLS for all migrations.
 849 #             An empty string means that QEMU will use plain text mode for
 850 #             migration, rather than TLS (Since 2.9)
 851 #             Previously (since 2.7), this was reported by omitting
 852 #             tls-creds instead.
 853 #
 854 # @tls-hostname: hostname of the target host for the migration. This
 855 #                is required when using x509 based TLS credentials and the
 856 #                migration URI does not already include a hostname. For
 857 #                example if using fd: or exec: based migration, the
 858 #                hostname must be provided so that the server's x509
 859 #                certificate identity can be validated. (Since 2.7)
 860 #                An empty string means that QEMU will use the hostname
 861 #                associated with the migration URI, if any. (Since 2.9)
 862 #                Previously (since 2.7), this was reported by omitting
 863 #                tls-hostname instead.
 864 #
 865 # @max-bandwidth: to set maximum speed for migration. maximum speed in
 866 #                 bytes per second. (Since 2.8)
 867 #
 868 # @downtime-limit: set maximum tolerated downtime for migration. maximum
 869 #                  downtime in milliseconds (Since 2.8)
 870 #
 871 # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
 872 #
 873 # @block-incremental: Affects how much storage is migrated when the
 874 #                     block migration capability is enabled.  When false, the entire
 875 #                     storage backing chain is migrated into a flattened image at
 876 #                     the destination; when true, only the active qcow2 layer is
 877 #                     migrated and the destination must already have access to the
 878 #                     same backing chain as was used on the source.  (since 2.10)
 879 #
 880 # @multifd-channels: Number of channels used to migrate data in
 881 #                    parallel. This is the same number that the
 882 #                    number of sockets used for migration.  The
 883 #                    default value is 2 (since 4.0)
 884 #
 885 # @xbzrle-cache-size: cache size to be used by XBZRLE migration.  It
 886 #                     needs to be a multiple of the target page size
 887 #                     and a power of 2
 888 #                     (Since 2.11)
 889 #
 890 # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
 891 #                          Defaults to 0 (unlimited).  In bytes per second.
 892 #                          (Since 3.0)
 893 #
 894 # @max-cpu-throttle: maximum cpu throttle percentage.
 895 #                    The default value is 99. (Since 3.1)
 896 #
 897 # @multifd-compression: Which compression method to use.
 898 #                       Defaults to none. (Since 5.0)
 899 #
 900 # @multifd-zlib-level: Set the compression level to be used in live
 901 #                      migration, the compression level is an integer between 0
 902 #                      and 9, where 0 means no compression, 1 means the best
 903 #                      compression speed, and 9 means best compression ratio which
 904 #                      will consume more CPU.
 905 #                      Defaults to 1. (Since 5.0)
 906 #
 907 # @multifd-zstd-level: Set the compression level to be used in live
 908 #                      migration, the compression level is an integer between 0
 909 #                      and 20, where 0 means no compression, 1 means the best
 910 #                      compression speed, and 20 means best compression ratio which
 911 #                      will consume more CPU.
 912 #                      Defaults to 1. (Since 5.0)
 913 #
 914 # @zero-copy-send: Controls behavior on sending memory pages on migration.
 915 #                  When true, enables a zero-copy mechanism for sending
 916 #                  memory pages, if host supports it.
 917 #                  Requires that QEMU be permitted to use locked memory
 918 #                  for guest RAM pages.
 919 #                  Defaults to false. (Since 7.1)
 920 #
 921 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 922 #                        aliases for the purpose of dirty bitmap migration.  Such
 923 #                        aliases may for example be the corresponding names on the
 924 #                        opposite site.
 925 #                        The mapping must be one-to-one, but not necessarily
 926 #                        complete: On the source, unmapped bitmaps and all bitmaps
 927 #                        on unmapped nodes will be ignored.  On the destination,
 928 #                        encountering an unmapped alias in the incoming migration
 929 #                        stream will result in a report, and all further bitmap
 930 #                        migration data will then be discarded.
 931 #                        Note that the destination does not know about bitmaps it
 932 #                        does not receive, so there is no limitation or requirement
 933 #                        regarding the number of bitmaps received, or how they are
 934 #                        named, or on which nodes they are placed.
 935 #                        By default (when this parameter has never been set), bitmap
 936 #                        names are mapped to themselves.  Nodes are mapped to their
 937 #                        block device name if there is one, and to their node name
 938 #                        otherwise. (Since 5.2)
 939 #
 940 # Features:
 941 # @unstable: Member @x-checkpoint-delay is experimental.
 942 #
 943 # Since: 2.4
 944 ##
 945 # TODO either fuse back into MigrationParameters, or make
 946 # MigrationParameters members mandatory
 947 { 'struct': 'MigrateSetParameters',
 948   'data': { '*announce-initial': 'size',
 949             '*announce-max': 'size',
 950             '*announce-rounds': 'size',
 951             '*announce-step': 'size',
 952             '*compress-level': 'uint8',
 953             '*compress-threads': 'uint8',
 954             '*compress-wait-thread': 'bool',
 955             '*decompress-threads': 'uint8',
 956             '*throttle-trigger-threshold': 'uint8',
 957             '*cpu-throttle-initial': 'uint8',
 958             '*cpu-throttle-increment': 'uint8',
 959             '*cpu-throttle-tailslow': 'bool',
 960             '*tls-creds': 'StrOrNull',
 961             '*tls-hostname': 'StrOrNull',
 962             '*tls-authz': 'StrOrNull',
 963             '*max-bandwidth': 'size',
 964             '*downtime-limit': 'uint64',
 965             '*x-checkpoint-delay': { 'type': 'uint32',
 966                                      'features': [ 'unstable' ] },
 967             '*block-incremental': 'bool',
 968             '*multifd-channels': 'uint8',
 969             '*xbzrle-cache-size': 'size',
 970             '*max-postcopy-bandwidth': 'size',
 971             '*max-cpu-throttle': 'uint8',
 972             '*multifd-compression': 'MultiFDCompression',
 973             '*multifd-zlib-level': 'uint8',
 974             '*multifd-zstd-level': 'uint8',
 975             '*zero-copy-send': { 'type': 'bool', 'if': 'CONFIG_LINUX' },
 976             '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } }
 977
 978 ##
 979 # @migrate-set-parameters:
 980 #
 981 # Set various migration parameters.
 982 #
 983 # Since: 2.4
 984 #
 985 # Example:
 986 #
 987 # -> { "execute": "migrate-set-parameters" ,
 988 #      "arguments": { "compress-level": 1 } }
 989 #
 990 ##
 991 { 'command': 'migrate-set-parameters', 'boxed': true,
 992   'data': 'MigrateSetParameters' }
 993
 994 ##
 995 # @MigrationParameters:
 996 #
 997 # The optional members aren't actually optional.
 998 #
 999 # @announce-initial: Initial delay (in milliseconds) before sending the
1000 #                    first announce (Since 4.0)
1001 #
1002 # @announce-max: Maximum delay (in milliseconds) between packets in the
1003 #                announcement (Since 4.0)
1004 #
1005 # @announce-rounds: Number of self-announce packets sent after migration
1006 #                   (Since 4.0)
1007 #
1008 # @announce-step: Increase in delay (in milliseconds) between subsequent
1009 #                 packets in the announcement (Since 4.0)
1010 #
1011 # @compress-level: compression level
1012 #
1013 # @compress-threads: compression thread count
1014 #
1015 # @compress-wait-thread: Controls behavior when all compression threads are
1016 #                        currently busy. If true (default), wait for a free
1017 #                        compression thread to become available; otherwise,
1018 #                        send the page uncompressed. (Since 3.1)
1019 #
1020 # @decompress-threads: decompression thread count
1021 #
1022 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
1023 #                              to trigger throttling. It is expressed as percentage.
1024 #                              The default value is 50. (Since 5.0)
1025 #
1026 # @cpu-throttle-initial: Initial percentage of time guest cpus are
1027 #                        throttled when migration auto-converge is activated.
1028 #                        (Since 2.7)
1029 #
1030 # @cpu-throttle-increment: throttle percentage increase each time
1031 #                          auto-converge detects that migration is not making
1032 #                          progress. (Since 2.7)
1033 #
1034 # @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
1035 #                         At the tail stage of throttling, the Guest is very
1036 #                         sensitive to CPU percentage while the @cpu-throttle
1037 #                         -increment is excessive usually at tail stage.
1038 #                         If this parameter is true, we will compute the ideal
1039 #                         CPU percentage used by the Guest, which may exactly make
1040 #                         the dirty rate match the dirty rate threshold. Then we
1041 #                         will choose a smaller throttle increment between the
1042 #                         one specified by @cpu-throttle-increment and the one
1043 #                         generated by ideal CPU percentage.
1044 #                         Therefore, it is compatible to traditional throttling,
1045 #                         meanwhile the throttle increment won't be excessive
1046 #                         at tail stage.
1047 #                         The default value is false. (Since 5.1)
1048 #
1049 # @tls-creds: ID of the 'tls-creds' object that provides credentials
1050 #             for establishing a TLS connection over the migration data
1051 #             channel. On the outgoing side of the migration, the credentials
1052 #             must be for a 'client' endpoint, while for the incoming side the
1053 #             credentials must be for a 'server' endpoint.
1054 #             An empty string means that QEMU will use plain text mode for
1055 #             migration, rather than TLS (Since 2.7)
1056 #             Note: 2.8 reports this by omitting tls-creds instead.
1057 #
1058 # @tls-hostname: hostname of the target host for the migration. This
1059 #                is required when using x509 based TLS credentials and the
1060 #                migration URI does not already include a hostname. For
1061 #                example if using fd: or exec: based migration, the
1062 #                hostname must be provided so that the server's x509
1063 #                certificate identity can be validated. (Since 2.7)
1064 #                An empty string means that QEMU will use the hostname
1065 #                associated with the migration URI, if any. (Since 2.9)
1066 #                Note: 2.8 reports this by omitting tls-hostname instead.
1067 #
1068 # @tls-authz: ID of the 'authz' object subclass that provides access control
1069 #             checking of the TLS x509 certificate distinguished name. (Since
1070 #             4.0)
1071 #
1072 # @max-bandwidth: to set maximum speed for migration. maximum speed in
1073 #                 bytes per second. (Since 2.8)
1074 #
1075 # @downtime-limit: set maximum tolerated downtime for migration. maximum
1076 #                  downtime in milliseconds (Since 2.8)
1077 #
1078 # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
1079 #
1080 # @block-incremental: Affects how much storage is migrated when the
1081 #                     block migration capability is enabled.  When false, the entire
1082 #                     storage backing chain is migrated into a flattened image at
1083 #                     the destination; when true, only the active qcow2 layer is
1084 #                     migrated and the destination must already have access to the
1085 #                     same backing chain as was used on the source.  (since 2.10)
1086 #
1087 # @multifd-channels: Number of channels used to migrate data in
1088 #                    parallel. This is the same number that the
1089 #                    number of sockets used for migration.
1090 #                    The default value is 2 (since 4.0)
1091 #
1092 # @xbzrle-cache-size: cache size to be used by XBZRLE migration.  It
1093 #                     needs to be a multiple of the target page size
1094 #                     and a power of 2
1095 #                     (Since 2.11)
1096 #
1097 # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
1098 #                          Defaults to 0 (unlimited).  In bytes per second.
1099 #                          (Since 3.0)
1100 #
1101 # @max-cpu-throttle: maximum cpu throttle percentage.
1102 #                    Defaults to 99.
1103 #                    (Since 3.1)
1104 #
1105 # @multifd-compression: Which compression method to use.
1106 #                       Defaults to none. (Since 5.0)
1107 #
1108 # @multifd-zlib-level: Set the compression level to be used in live
1109 #                      migration, the compression level is an integer between 0
1110 #                      and 9, where 0 means no compression, 1 means the best
1111 #                      compression speed, and 9 means best compression ratio which
1112 #                      will consume more CPU.
1113 #                      Defaults to 1. (Since 5.0)
1114 #
1115 # @multifd-zstd-level: Set the compression level to be used in live
1116 #                      migration, the compression level is an integer between 0
1117 #                      and 20, where 0 means no compression, 1 means the best
1118 #                      compression speed, and 20 means best compression ratio which
1119 #                      will consume more CPU.
1120 #                      Defaults to 1. (Since 5.0)
1121 #
1122 # @zero-copy-send: Controls behavior on sending memory pages on migration.
1123 #                  When true, enables a zero-copy mechanism for sending
1124 #                  memory pages, if host supports it.
1125 #                  Requires that QEMU be permitted to use locked memory
1126 #                  for guest RAM pages.
1127 #                  Defaults to false. (Since 7.1)
1128 #
1129 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
1130 #                        aliases for the purpose of dirty bitmap migration.  Such
1131 #                        aliases may for example be the corresponding names on the
1132 #                        opposite site.
1133 #                        The mapping must be one-to-one, but not necessarily
1134 #                        complete: On the source, unmapped bitmaps and all bitmaps
1135 #                        on unmapped nodes will be ignored.  On the destination,
1136 #                        encountering an unmapped alias in the incoming migration
1137 #                        stream will result in a report, and all further bitmap
1138 #                        migration data will then be discarded.
1139 #                        Note that the destination does not know about bitmaps it
1140 #                        does not receive, so there is no limitation or requirement
1141 #                        regarding the number of bitmaps received, or how they are
1142 #                        named, or on which nodes they are placed.
1143 #                        By default (when this parameter has never been set), bitmap
1144 #                        names are mapped to themselves.  Nodes are mapped to their
1145 #                        block device name if there is one, and to their node name
1146 #                        otherwise. (Since 5.2)
1147 #
1148 # Features:
1149 # @unstable: Member @x-checkpoint-delay is experimental.
1150 #
1151 # Since: 2.4
1152 ##
1153 { 'struct': 'MigrationParameters',
1154   'data': { '*announce-initial': 'size',
1155             '*announce-max': 'size',
1156             '*announce-rounds': 'size',
1157             '*announce-step': 'size',
1158             '*compress-level': 'uint8',
1159             '*compress-threads': 'uint8',
1160             '*compress-wait-thread': 'bool',
1161             '*decompress-threads': 'uint8',
1162             '*throttle-trigger-threshold': 'uint8',
1163             '*cpu-throttle-initial': 'uint8',
1164             '*cpu-throttle-increment': 'uint8',
1165             '*cpu-throttle-tailslow': 'bool',
1166             '*tls-creds': 'str',
1167             '*tls-hostname': 'str',
1168             '*tls-authz': 'str',
1169             '*max-bandwidth': 'size',
1170             '*downtime-limit': 'uint64',
1171             '*x-checkpoint-delay': { 'type': 'uint32',
1172                                      'features': [ 'unstable' ] },
1173             '*block-incremental': 'bool',
1174             '*multifd-channels': 'uint8',
1175             '*xbzrle-cache-size': 'size',
1176             '*max-postcopy-bandwidth': 'size',
1177             '*max-cpu-throttle': 'uint8',
1178             '*multifd-compression': 'MultiFDCompression',
1179             '*multifd-zlib-level': 'uint8',
1180             '*multifd-zstd-level': 'uint8',
1181             '*zero-copy-send': { 'type': 'bool', 'if': 'CONFIG_LINUX' },
1182             '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } }
1183
1184 ##
1185 # @query-migrate-parameters:
1186 #
1187 # Returns information about the current migration parameters
1188 #
1189 # Returns: @MigrationParameters
1190 #
1191 # Since: 2.4
1192 #
1193 # Example:
1194 #
1195 # -> { "execute": "query-migrate-parameters" }
1196 # <- { "return": {
1197 #          "decompress-threads": 2,
1198 #          "cpu-throttle-increment": 10,
1199 #          "compress-threads": 8,
1200 #          "compress-level": 1,
1201 #          "cpu-throttle-initial": 20,
1202 #          "max-bandwidth": 33554432,
1203 #          "downtime-limit": 300
1204 #       }
1205 #    }
1206 #
1207 ##
1208 { 'command': 'query-migrate-parameters',
1209   'returns': 'MigrationParameters' }
1210
1211 ##
1212 # @client_migrate_info:
1213 #
1214 # Set migration information for remote display.  This makes the server
1215 # ask the client to automatically reconnect using the new parameters
1216 # once migration finished successfully.  Only implemented for SPICE.
1217 #
1218 # @protocol: must be "spice"
1219 # @hostname: migration target hostname
1220 # @port: spice tcp port for plaintext channels
1221 # @tls-port: spice tcp port for tls-secured channels
1222 # @cert-subject: server certificate subject
1223 #
1224 # Since: 0.14
1225 #
1226 # Example:
1227 #
1228 # -> { "execute": "client_migrate_info",
1229 #      "arguments": { "protocol": "spice",
1230 #                     "hostname": "virt42.lab.kraxel.org",
1231 #                     "port": 1234 } }
1232 # <- { "return": {} }
1233 #
1234 ##
1235 { 'command': 'client_migrate_info',
1236   'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
1237             '*tls-port': 'int', '*cert-subject': 'str' } }
1238
1239 ##
1240 # @migrate-start-postcopy:
1241 #
1242 # Followup to a migration command to switch the migration to postcopy mode.
1243 # The postcopy-ram capability must be set on both source and destination
1244 # before the original migration command.
1245 #
1246 # Since: 2.5
1247 #
1248 # Example:
1249 #
1250 # -> { "execute": "migrate-start-postcopy" }
1251 # <- { "return": {} }
1252 #
1253 ##
1254 { 'command': 'migrate-start-postcopy' }
1255
1256 ##
1257 # @MIGRATION:
1258 #
1259 # Emitted when a migration event happens
1260 #
1261 # @status: @MigrationStatus describing the current migration status.
1262 #
1263 # Since: 2.4
1264 #
1265 # Example:
1266 #
1267 # <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
1268 #     "event": "MIGRATION",
1269 #     "data": {"status": "completed"} }
1270 #
1271 ##
1272 { 'event': 'MIGRATION',
1273   'data': {'status': 'MigrationStatus'}}
1274
1275 ##
1276 # @MIGRATION_PASS:
1277 #
1278 # Emitted from the source side of a migration at the start of each pass
1279 # (when it syncs the dirty bitmap)
1280 #
1281 # @pass: An incrementing count (starting at 1 on the first pass)
1282 #
1283 # Since: 2.6
1284 #
1285 # Example:
1286 #
1287 # { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
1288 #   "event": "MIGRATION_PASS", "data": {"pass": 2} }
1289 #
1290 ##
1291 { 'event': 'MIGRATION_PASS',
1292   'data': { 'pass': 'int' } }
1293
1294 ##
1295 # @COLOMessage:
1296 #
1297 # The message transmission between Primary side and Secondary side.
1298 #
1299 # @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
1300 #
1301 # @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
1302 #
1303 # @checkpoint-reply: SVM gets PVM's checkpoint request
1304 #
1305 # @vmstate-send: VM's state will be sent by PVM.
1306 #
1307 # @vmstate-size: The total size of VMstate.
1308 #
1309 # @vmstate-received: VM's state has been received by SVM.
1310 #
1311 # @vmstate-loaded: VM's state has been loaded by SVM.
1312 #
1313 # Since: 2.8
1314 ##
1315 { 'enum': 'COLOMessage',
1316   'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
1317             'vmstate-send', 'vmstate-size', 'vmstate-received',
1318             'vmstate-loaded' ] }
1319
1320 ##
1321 # @COLOMode:
1322 #
1323 # The COLO current mode.
1324 #
1325 # @none: COLO is disabled.
1326 #
1327 # @primary: COLO node in primary side.
1328 #
1329 # @secondary: COLO node in slave side.
1330 #
1331 # Since: 2.8
1332 ##
1333 { 'enum': 'COLOMode',
1334   'data': [ 'none', 'primary', 'secondary'] }
1335
1336 ##
1337 # @FailoverStatus:
1338 #
1339 # An enumeration of COLO failover status
1340 #
1341 # @none: no failover has ever happened
1342 #
1343 # @require: got failover requirement but not handled
1344 #
1345 # @active: in the process of doing failover
1346 #
1347 # @completed: finish the process of failover
1348 #
1349 # @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9)
1350 #
1351 # Since: 2.8
1352 ##
1353 { 'enum': 'FailoverStatus',
1354   'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
1355
1356 ##
1357 # @COLO_EXIT:
1358 #
1359 # Emitted when VM finishes COLO mode due to some errors happening or
1360 # at the request of users.
1361 #
1362 # @mode: report COLO mode when COLO exited.
1363 #
1364 # @reason: describes the reason for the COLO exit.
1365 #
1366 # Since: 3.1
1367 #
1368 # Example:
1369 #
1370 # <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
1371 #      "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
1372 #
1373 ##
1374 { 'event': 'COLO_EXIT',
1375   'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
1376
1377 ##
1378 # @COLOExitReason:
1379 #
1380 # The reason for a COLO exit.
1381 #
1382 # @none: failover has never happened. This state does not occur
1383 #        in the COLO_EXIT event, and is only visible in the result of
1384 #        query-colo-status.
1385 #
1386 # @request: COLO exit is due to an external request.
1387 #
1388 # @error: COLO exit is due to an internal error.
1389 #
1390 # @processing: COLO is currently handling a failover (since 4.0).
1391 #
1392 # Since: 3.1
1393 ##
1394 { 'enum': 'COLOExitReason',
1395   'data': [ 'none', 'request', 'error' , 'processing' ] }
1396
1397 ##
1398 # @x-colo-lost-heartbeat:
1399 #
1400 # Tell qemu that heartbeat is lost, request it to do takeover procedures.
1401 # If this command is sent to the PVM, the Primary side will exit COLO mode.
1402 # If sent to the Secondary, the Secondary side will run failover work,
1403 # then takes over server operation to become the service VM.
1404 #
1405 # Features:
1406 # @unstable: This command is experimental.
1407 #
1408 # Since: 2.8
1409 #
1410 # Example:
1411 #
1412 # -> { "execute": "x-colo-lost-heartbeat" }
1413 # <- { "return": {} }
1414 #
1415 ##
1416 { 'command': 'x-colo-lost-heartbeat',
1417   'features': [ 'unstable' ] }
1418
1419 ##
1420 # @migrate_cancel:
1421 #
1422 # Cancel the current executing migration process.
1423 #
1424 # Returns: nothing on success
1425 #
1426 # Notes: This command succeeds even if there is no migration process running.
1427 #
1428 # Since: 0.14
1429 #
1430 # Example:
1431 #
1432 # -> { "execute": "migrate_cancel" }
1433 # <- { "return": {} }
1434 #
1435 ##
1436 { 'command': 'migrate_cancel' }
1437
1438 ##
1439 # @migrate-continue:
1440 #
1441 # Continue migration when it's in a paused state.
1442 #
1443 # @state: The state the migration is currently expected to be in
1444 #
1445 # Returns: nothing on success
1446 #
1447 # Since: 2.11
1448 #
1449 # Example:
1450 #
1451 # -> { "execute": "migrate-continue" , "arguments":
1452 #      { "state": "pre-switchover" } }
1453 # <- { "return": {} }
1454 ##
1455 { 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
1456
1457 ##
1458 # @migrate:
1459 #
1460 # Migrates the current running guest to another Virtual Machine.
1461 #
1462 # @uri: the Uniform Resource Identifier of the destination VM
1463 #
1464 # @blk: do block migration (full disk copy)
1465 #
1466 # @inc: incremental disk copy migration
1467 #
1468 # @detach: this argument exists only for compatibility reasons and
1469 #          is ignored by QEMU
1470 #
1471 # @resume: resume one paused migration, default "off". (since 3.0)
1472 #
1473 # Returns: nothing on success
1474 #
1475 # Since: 0.14
1476 #
1477 # Notes:
1478 #
1479 # 1. The 'query-migrate' command should be used to check migration's progress
1480 #    and final result (this information is provided by the 'status' member)
1481 #
1482 # 2. All boolean arguments default to false
1483 #
1484 # 3. The user Monitor's "detach" argument is invalid in QMP and should not
1485 #    be used
1486 #
1487 # Example:
1488 #
1489 # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1490 # <- { "return": {} }
1491 #
1492 ##
1493 { 'command': 'migrate',
1494   'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
1495            '*detach': 'bool', '*resume': 'bool' } }
1496
1497 ##
1498 # @migrate-incoming:
1499 #
1500 # Start an incoming migration, the qemu must have been started
1501 # with -incoming defer
1502 #
1503 # @uri: The Uniform Resource Identifier identifying the source or
1504 #       address to listen on
1505 #
1506 # Returns: nothing on success
1507 #
1508 # Since: 2.3
1509 #
1510 # Notes:
1511 #
1512 # 1. It's a bad idea to use a string for the uri, but it needs to stay
1513 #    compatible with -incoming and the format of the uri is already exposed
1514 #    above libvirt.
1515 #
1516 # 2. QEMU must be started with -incoming defer to allow migrate-incoming to
1517 #    be used.
1518 #
1519 # 3. The uri format is the same as for -incoming
1520 #
1521 # Example:
1522 #
1523 # -> { "execute": "migrate-incoming",
1524 #      "arguments": { "uri": "tcp::4446" } }
1525 # <- { "return": {} }
1526 #
1527 ##
1528 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
1529
1530 ##
1531 # @xen-save-devices-state:
1532 #
1533 # Save the state of all devices to file. The RAM and the block devices
1534 # of the VM are not saved by this command.
1535 #
1536 # @filename: the file to save the state of the devices to as binary
1537 #            data. See xen-save-devices-state.txt for a description of the binary
1538 #            format.
1539 #
1540 # @live: Optional argument to ask QEMU to treat this command as part of a live
1541 #        migration. Default to true. (since 2.11)
1542 #
1543 # Returns: Nothing on success
1544 #
1545 # Since: 1.1
1546 #
1547 # Example:
1548 #
1549 # -> { "execute": "xen-save-devices-state",
1550 #      "arguments": { "filename": "/tmp/save" } }
1551 # <- { "return": {} }
1552 #
1553 ##
1554 { 'command': 'xen-save-devices-state',
1555   'data': {'filename': 'str', '*live':'bool' } }
1556
1557 ##
1558 # @xen-set-global-dirty-log:
1559 #
1560 # Enable or disable the global dirty log mode.
1561 #
1562 # @enable: true to enable, false to disable.
1563 #
1564 # Returns: nothing
1565 #
1566 # Since: 1.3
1567 #
1568 # Example:
1569 #
1570 # -> { "execute": "xen-set-global-dirty-log",
1571 #      "arguments": { "enable": true } }
1572 # <- { "return": {} }
1573 #
1574 ##
1575 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
1576
1577 ##
1578 # @xen-load-devices-state:
1579 #
1580 # Load the state of all devices from file. The RAM and the block devices
1581 # of the VM are not loaded by this command.
1582 #
1583 # @filename: the file to load the state of the devices from as binary
1584 #            data. See xen-save-devices-state.txt for a description of the binary
1585 #            format.
1586 #
1587 # Since: 2.7
1588 #
1589 # Example:
1590 #
1591 # -> { "execute": "xen-load-devices-state",
1592 #      "arguments": { "filename": "/tmp/resume" } }
1593 # <- { "return": {} }
1594 #
1595 ##
1596 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
1597
1598 ##
1599 # @xen-set-replication:
1600 #
1601 # Enable or disable replication.
1602 #
1603 # @enable: true to enable, false to disable.
1604 #
1605 # @primary: true for primary or false for secondary.
1606 #
1607 # @failover: true to do failover, false to stop. but cannot be
1608 #            specified if 'enable' is true. default value is false.
1609 #
1610 # Returns: nothing.
1611 #
1612 # Example:
1613 #
1614 # -> { "execute": "xen-set-replication",
1615 #      "arguments": {"enable": true, "primary": false} }
1616 # <- { "return": {} }
1617 #
1618 # Since: 2.9
1619 ##
1620 { 'command': 'xen-set-replication',
1621   'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' },
1622   'if': 'CONFIG_REPLICATION' }
1623
1624 ##
1625 # @ReplicationStatus:
1626 #
1627 # The result format for 'query-xen-replication-status'.
1628 #
1629 # @error: true if an error happened, false if replication is normal.
1630 #
1631 # @desc: the human readable error description string, when
1632 #        @error is 'true'.
1633 #
1634 # Since: 2.9
1635 ##
1636 { 'struct': 'ReplicationStatus',
1637   'data': { 'error': 'bool', '*desc': 'str' },
1638   'if': 'CONFIG_REPLICATION' }
1639
1640 ##
1641 # @query-xen-replication-status:
1642 #
1643 # Query replication status while the vm is running.
1644 #
1645 # Returns: A @ReplicationStatus object showing the status.
1646 #
1647 # Example:
1648 #
1649 # -> { "execute": "query-xen-replication-status" }
1650 # <- { "return": { "error": false } }
1651 #
1652 # Since: 2.9
1653 ##
1654 { 'command': 'query-xen-replication-status',
1655   'returns': 'ReplicationStatus',
1656   'if': 'CONFIG_REPLICATION' }
1657
1658 ##
1659 # @xen-colo-do-checkpoint:
1660 #
1661 # Xen uses this command to notify replication to trigger a checkpoint.
1662 #
1663 # Returns: nothing.
1664 #
1665 # Example:
1666 #
1667 # -> { "execute": "xen-colo-do-checkpoint" }
1668 # <- { "return": {} }
1669 #
1670 # Since: 2.9
1671 ##
1672 { 'command': 'xen-colo-do-checkpoint',
1673   'if': 'CONFIG_REPLICATION' }
1674
1675 ##
1676 # @COLOStatus:
1677 #
1678 # The result format for 'query-colo-status'.
1679 #
1680 # @mode: COLO running mode. If COLO is running, this field will return
1681 #        'primary' or 'secondary'.
1682 #
1683 # @last-mode: COLO last running mode. If COLO is running, this field
1684 #             will return same like mode field, after failover we can
1685 #             use this field to get last colo mode. (since 4.0)
1686 #
1687 # @reason: describes the reason for the COLO exit.
1688 #
1689 # Since: 3.1
1690 ##
1691 { 'struct': 'COLOStatus',
1692   'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode',
1693             'reason': 'COLOExitReason' } }
1694
1695 ##
1696 # @query-colo-status:
1697 #
1698 # Query COLO status while the vm is running.
1699 #
1700 # Returns: A @COLOStatus object showing the status.
1701 #
1702 # Example:
1703 #
1704 # -> { "execute": "query-colo-status" }
1705 # <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
1706 #
1707 # Since: 3.1
1708 ##
1709 { 'command': 'query-colo-status',
1710   'returns': 'COLOStatus' }
1711
1712 ##
1713 # @migrate-recover:
1714 #
1715 # Provide a recovery migration stream URI.
1716 #
1717 # @uri: the URI to be used for the recovery of migration stream.
1718 #
1719 # Returns: nothing.
1720 #
1721 # Example:
1722 #
1723 # -> { "execute": "migrate-recover",
1724 #      "arguments": { "uri": "tcp:192.168.1.200:12345" } }
1725 # <- { "return": {} }
1726 #
1727 # Since: 3.0
1728 ##
1729 { 'command': 'migrate-recover',
1730   'data': { 'uri': 'str' },
1731   'allow-oob': true }
1732
1733 ##
1734 # @migrate-pause:
1735 #
1736 # Pause a migration.  Currently it only supports postcopy.
1737 #
1738 # Returns: nothing.
1739 #
1740 # Example:
1741 #
1742 # -> { "execute": "migrate-pause" }
1743 # <- { "return": {} }
1744 #
1745 # Since: 3.0
1746 ##
1747 { 'command': 'migrate-pause', 'allow-oob': true }
1748
1749 ##
1750 # @UNPLUG_PRIMARY:
1751 #
1752 # Emitted from source side of a migration when migration state is
1753 # WAIT_UNPLUG. Device was unplugged by guest operating system.
1754 # Device resources in QEMU are kept on standby to be able to re-plug it in case
1755 # of migration failure.
1756 #
1757 # @device-id: QEMU device id of the unplugged device
1758 #
1759 # Since: 4.2
1760 #
1761 # Example:
1762 #
1763 # <- { "event": "UNPLUG_PRIMARY",
1764 #      "data": { "device-id": "hostdev0" },
1765 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1766 #
1767 ##
1768 { 'event': 'UNPLUG_PRIMARY',
1769   'data': { 'device-id': 'str' } }
1770
1771 ##
1772 # @DirtyRateVcpu:
1773 #
1774 # Dirty rate of vcpu.
1775 #
1776 # @id: vcpu index.
1777 #
1778 # @dirty-rate: dirty rate.
1779 #
1780 # Since: 6.2
1781 ##
1782 { 'struct': 'DirtyRateVcpu',
1783   'data': { 'id': 'int', 'dirty-rate': 'int64' } }
1784
1785 ##
1786 # @DirtyRateStatus:
1787 #
1788 # An enumeration of dirtyrate status.
1789 #
1790 # @unstarted: the dirtyrate thread has not been started.
1791 #
1792 # @measuring: the dirtyrate thread is measuring.
1793 #
1794 # @measured: the dirtyrate thread has measured and results are available.
1795 #
1796 # Since: 5.2
1797 ##
1798 { 'enum': 'DirtyRateStatus',
1799   'data': [ 'unstarted', 'measuring', 'measured'] }
1800
1801 ##
1802 # @DirtyRateMeasureMode:
1803 #
1804 # An enumeration of mode of measuring dirtyrate.
1805 #
1806 # @page-sampling: calculate dirtyrate by sampling pages.
1807 #
1808 # @dirty-ring: calculate dirtyrate by dirty ring.
1809 #
1810 # @dirty-bitmap: calculate dirtyrate by dirty bitmap.
1811 #
1812 # Since: 6.2
1813 ##
1814 { 'enum': 'DirtyRateMeasureMode',
1815   'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] }
1816
1817 ##
1818 # @DirtyRateInfo:
1819 #
1820 # Information about current dirty page rate of vm.
1821 #
1822 # @dirty-rate: an estimate of the dirty page rate of the VM in units of
1823 #              MB/s, present only when estimating the rate has completed.
1824 #
1825 # @status: status containing dirtyrate query status includes
1826 #          'unstarted' or 'measuring' or 'measured'
1827 #
1828 # @start-time: start time in units of second for calculation
1829 #
1830 # @calc-time: time in units of second for sample dirty pages
1831 #
1832 # @sample-pages: page count per GB for sample dirty pages
1833 #                the default value is 512 (since 6.1)
1834 #
1835 # @mode: mode containing method of calculate dirtyrate includes
1836 #        'page-sampling' and 'dirty-ring' (Since 6.2)
1837 #
1838 # @vcpu-dirty-rate: dirtyrate for each vcpu if dirty-ring
1839 #                   mode specified (Since 6.2)
1840 #
1841 # Since: 5.2
1842 ##
1843 { 'struct': 'DirtyRateInfo',
1844   'data': {'*dirty-rate': 'int64',
1845            'status': 'DirtyRateStatus',
1846            'start-time': 'int64',
1847            'calc-time': 'int64',
1848            'sample-pages': 'uint64',
1849            'mode': 'DirtyRateMeasureMode',
1850            '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } }
1851
1852 ##
1853 # @calc-dirty-rate:
1854 #
1855 # start calculating dirty page rate for vm
1856 #
1857 # @calc-time: time in units of second for sample dirty pages
1858 #
1859 # @sample-pages: page count per GB for sample dirty pages
1860 #                the default value is 512 (since 6.1)
1861 #
1862 # @mode: mechanism of calculating dirtyrate includes
1863 #        'page-sampling' and 'dirty-ring' (Since 6.1)
1864 #
1865 # Since: 5.2
1866 #
1867 # Example:
1868 #
1869 #   {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
1870 #                                                'sample-pages': 512} }
1871 #
1872 ##
1873 { 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64',
1874                                          '*sample-pages': 'int',
1875                                          '*mode': 'DirtyRateMeasureMode'} }
1876
1877 ##
1878 # @query-dirty-rate:
1879 #
1880 # query dirty page rate in units of MB/s for vm
1881 #
1882 # Since: 5.2
1883 ##
1884 { 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' }
1885
1886 ##
1887 # @snapshot-save:
1888 #
1889 # Save a VM snapshot
1890 #
1891 # @job-id: identifier for the newly created job
1892 # @tag: name of the snapshot to create
1893 # @vmstate: block device node name to save vmstate to
1894 # @devices: list of block device node names to save a snapshot to
1895 #
1896 # Applications should not assume that the snapshot save is complete
1897 # when this command returns. The job commands / events must be used
1898 # to determine completion and to fetch details of any errors that arise.
1899 #
1900 # Note that execution of the guest CPUs may be stopped during the
1901 # time it takes to save the snapshot. A future version of QEMU
1902 # may ensure CPUs are executing continuously.
1903 #
1904 # It is strongly recommended that @devices contain all writable
1905 # block device nodes if a consistent snapshot is required.
1906 #
1907 # If @tag already exists, an error will be reported
1908 #
1909 # Returns: nothing
1910 #
1911 # Example:
1912 #
1913 # -> { "execute": "snapshot-save",
1914 #      "arguments": {
1915 #         "job-id": "snapsave0",
1916 #         "tag": "my-snap",
1917 #         "vmstate": "disk0",
1918 #         "devices": ["disk0", "disk1"]
1919 #      }
1920 #    }
1921 # <- { "return": { } }
1922 # <- {"event": "JOB_STATUS_CHANGE",
1923 #     "data": {"status": "created", "id": "snapsave0"}}
1924 # <- {"event": "JOB_STATUS_CHANGE",
1925 #     "data": {"status": "running", "id": "snapsave0"}}
1926 # <- {"event": "STOP"}
1927 # <- {"event": "RESUME"}
1928 # <- {"event": "JOB_STATUS_CHANGE",
1929 #     "data": {"status": "waiting", "id": "snapsave0"}}
1930 # <- {"event": "JOB_STATUS_CHANGE",
1931 #     "data": {"status": "pending", "id": "snapsave0"}}
1932 # <- {"event": "JOB_STATUS_CHANGE",
1933 #     "data": {"status": "concluded", "id": "snapsave0"}}
1934 # -> {"execute": "query-jobs"}
1935 # <- {"return": [{"current-progress": 1,
1936 #                 "status": "concluded",
1937 #                 "total-progress": 1,
1938 #                 "type": "snapshot-save",
1939 #                 "id": "snapsave0"}]}
1940 #
1941 # Since: 6.0
1942 ##
1943 { 'command': 'snapshot-save',
1944   'data': { 'job-id': 'str',
1945             'tag': 'str',
1946             'vmstate': 'str',
1947             'devices': ['str'] } }
1948
1949 ##
1950 # @snapshot-load:
1951 #
1952 # Load a VM snapshot
1953 #
1954 # @job-id: identifier for the newly created job
1955 # @tag: name of the snapshot to load.
1956 # @vmstate: block device node name to load vmstate from
1957 # @devices: list of block device node names to load a snapshot from
1958 #
1959 # Applications should not assume that the snapshot load is complete
1960 # when this command returns. The job commands / events must be used
1961 # to determine completion and to fetch details of any errors that arise.
1962 #
1963 # Note that execution of the guest CPUs will be stopped during the
1964 # time it takes to load the snapshot.
1965 #
1966 # It is strongly recommended that @devices contain all writable
1967 # block device nodes that can have changed since the original
1968 # @snapshot-save command execution.
1969 #
1970 # Returns: nothing
1971 #
1972 # Example:
1973 #
1974 # -> { "execute": "snapshot-load",
1975 #      "arguments": {
1976 #         "job-id": "snapload0",
1977 #         "tag": "my-snap",
1978 #         "vmstate": "disk0",
1979 #         "devices": ["disk0", "disk1"]
1980 #      }
1981 #    }
1982 # <- { "return": { } }
1983 # <- {"event": "JOB_STATUS_CHANGE",
1984 #     "data": {"status": "created", "id": "snapload0"}}
1985 # <- {"event": "JOB_STATUS_CHANGE",
1986 #     "data": {"status": "running", "id": "snapload0"}}
1987 # <- {"event": "STOP"}
1988 # <- {"event": "RESUME"}
1989 # <- {"event": "JOB_STATUS_CHANGE",
1990 #     "data": {"status": "waiting", "id": "snapload0"}}
1991 # <- {"event": "JOB_STATUS_CHANGE",
1992 #     "data": {"status": "pending", "id": "snapload0"}}
1993 # <- {"event": "JOB_STATUS_CHANGE",
1994 #     "data": {"status": "concluded", "id": "snapload0"}}
1995 # -> {"execute": "query-jobs"}
1996 # <- {"return": [{"current-progress": 1,
1997 #                 "status": "concluded",
1998 #                 "total-progress": 1,
1999 #                 "type": "snapshot-load",
2000 #                 "id": "snapload0"}]}
2001 #
2002 # Since: 6.0
2003 ##
2004 { 'command': 'snapshot-load',
2005   'data': { 'job-id': 'str',
2006             'tag': 'str',
2007             'vmstate': 'str',
2008             'devices': ['str'] } }
2009
2010 ##
2011 # @snapshot-delete:
2012 #
2013 # Delete a VM snapshot
2014 #
2015 # @job-id: identifier for the newly created job
2016 # @tag: name of the snapshot to delete.
2017 # @devices: list of block device node names to delete a snapshot from
2018 #
2019 # Applications should not assume that the snapshot delete is complete
2020 # when this command returns. The job commands / events must be used
2021 # to determine completion and to fetch details of any errors that arise.
2022 #
2023 # Returns: nothing
2024 #
2025 # Example:
2026 #
2027 # -> { "execute": "snapshot-delete",
2028 #      "arguments": {
2029 #         "job-id": "snapdelete0",
2030 #         "tag": "my-snap",
2031 #         "devices": ["disk0", "disk1"]
2032 #      }
2033 #    }
2034 # <- { "return": { } }
2035 # <- {"event": "JOB_STATUS_CHANGE",
2036 #     "data": {"status": "created", "id": "snapdelete0"}}
2037 # <- {"event": "JOB_STATUS_CHANGE",
2038 #     "data": {"status": "running", "id": "snapdelete0"}}
2039 # <- {"event": "JOB_STATUS_CHANGE",
2040 #     "data": {"status": "waiting", "id": "snapdelete0"}}
2041 # <- {"event": "JOB_STATUS_CHANGE",
2042 #     "data": {"status": "pending", "id": "snapdelete0"}}
2043 # <- {"event": "JOB_STATUS_CHANGE",
2044 #     "data": {"status": "concluded", "id": "snapdelete0"}}
2045 # -> {"execute": "query-jobs"}
2046 # <- {"return": [{"current-progress": 1,
2047 #                 "status": "concluded",
2048 #                 "total-progress": 1,
2049 #                 "type": "snapshot-delete",
2050 #                 "id": "snapdelete0"}]}
2051 #
2052 # Since: 6.0
2053 ##
2054 { 'command': 'snapshot-delete',
2055   'data': { 'job-id': 'str',
2056             'tag': 'str',
2057             'devices': ['str'] } }