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 20# target VM 21# 22# @total: total amount of bytes involved in the migration process 23# 24# @duplicate: number of duplicate (zero) pages (since 1.2) 25# 26# @normal: number of normal pages (since 1.2) 27# 28# @normal-bytes: number of normal bytes sent (since 1.2) 29# 30# @dirty-pages-rate: number of pages dirtied by second by the guest 31# (since 1.3) 32# 33# @mbps: throughput in megabits/sec. (since 1.6) 34# 35# @dirty-sync-count: number of times that dirty ram was synchronized 36# (since 2.1) 37# 38# @postcopy-requests: The number of page requests received from the 39# destination (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# @dirty-sync-missed-zero-copy: Number of times dirty RAM 59# synchronization could not avoid copying dirty pages. This is 60# between 0 and @dirty-sync-count * @multifd-channels. (since 61# 7.1) 62# 63# Since: 0.14 64## 65{ 'struct': 'MigrationStats', 66 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 67 'duplicate': 'int', 68 'normal': 'int', 69 'normal-bytes': 'int', 'dirty-pages-rate': 'int', 70 'mbps': 'number', 'dirty-sync-count': 'int', 71 'postcopy-requests': 'int', 'page-size': 'int', 72 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', 73 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', 74 'postcopy-bytes': 'uint64', 75 'dirty-sync-missed-zero-copy': 'uint64' } } 76 77## 78# @XBZRLECacheStats: 79# 80# Detailed XBZRLE migration cache statistics 81# 82# @cache-size: XBZRLE cache size 83# 84# @bytes: amount of bytes already transferred to the target VM 85# 86# @pages: amount of pages transferred to the target VM 87# 88# @cache-miss: number of cache miss 89# 90# @cache-miss-rate: rate of cache miss (since 2.1) 91# 92# @encoding-rate: rate of encoded bytes (since 5.1) 93# 94# @overflow: number of overflows 95# 96# Since: 1.2 97## 98{ 'struct': 'XBZRLECacheStats', 99 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 100 'cache-miss': 'int', 'cache-miss-rate': 'number', 101 'encoding-rate': 'number', 'overflow': 'int' } } 102 103## 104# @CompressionStats: 105# 106# Detailed migration compression statistics 107# 108# @pages: amount of pages compressed and transferred to the target VM 109# 110# @busy: count of times that no free thread was available to compress 111# data 112# 113# @busy-rate: rate of thread busy 114# 115# @compressed-size: amount of bytes after compression 116# 117# @compression-rate: rate of compressed size 118# 119# Since: 3.1 120## 121{ 'struct': 'CompressionStats', 122 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 123 'compressed-size': 'int', 'compression-rate': 'number' } } 124 125## 126# @MigrationStatus: 127# 128# An enumeration of migration status. 129# 130# @none: no migration has ever happened. 131# 132# @setup: migration process has been initiated. 133# 134# @cancelling: in the process of cancelling migration. 135# 136# @cancelled: cancelling migration is finished. 137# 138# @active: in the process of doing migration. 139# 140# @postcopy-active: like active, but now in postcopy mode. (since 141# 2.5) 142# 143# @postcopy-paused: during postcopy but paused. (since 3.0) 144# 145# @postcopy-recover: trying to recover from a paused postcopy. (since 146# 3.0) 147# 148# @completed: migration is finished. 149# 150# @failed: some error occurred during migration process. 151# 152# @colo: VM is in the process of fault tolerance, VM can not get into 153# this state unless colo capability is enabled for migration. 154# (since 2.8) 155# 156# @pre-switchover: Paused before device serialisation. (since 2.11) 157# 158# @device: During device serialisation when pause-before-switchover is 159# enabled (since 2.11) 160# 161# @wait-unplug: wait for device unplug request by guest OS to be 162# completed. (since 4.2) 163# 164# Since: 2.3 165## 166{ 'enum': 'MigrationStatus', 167 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 168 'active', 'postcopy-active', 'postcopy-paused', 169 'postcopy-recover', 'completed', 'failed', 'colo', 170 'pre-switchover', 'device', 'wait-unplug' ] } 171## 172# @VfioStats: 173# 174# Detailed VFIO devices migration statistics 175# 176# @transferred: amount of bytes transferred to the target VM by VFIO 177# devices 178# 179# Since: 5.2 180## 181{ 'struct': 'VfioStats', 182 'data': {'transferred': 'int' } } 183 184## 185# @MigrationInfo: 186# 187# Information about current migration process. 188# 189# @status: @MigrationStatus describing the current migration status. 190# If this field is not returned, no migration process has been 191# initiated 192# 193# @ram: @MigrationStats containing detailed migration status, only 194# returned if status is 'active' or 'completed'(since 1.2) 195# 196# @disk: @MigrationStats containing detailed disk migration status, 197# only returned if status is 'active' and it is a block migration 198# 199# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 200# migration statistics, only returned if XBZRLE feature is on and 201# status is 'active' or 'completed' (since 1.2) 202# 203# @total-time: total amount of milliseconds since migration started. 204# If migration has ended, it returns the total migration time. 205# (since 1.2) 206# 207# @downtime: only present when migration finishes correctly total 208# downtime in milliseconds for the guest. (since 1.3) 209# 210# @expected-downtime: only present while migration is active expected 211# downtime in milliseconds for the guest in last walk of the dirty 212# bitmap. (since 1.3) 213# 214# @setup-time: amount of setup time in milliseconds *before* the 215# iterations begin but *after* the QMP command is issued. This is 216# designed to provide an accounting of any activities (such as 217# RDMA pinning) which may be expensive, but do not actually occur 218# during the iterative migration rounds themselves. (since 1.6) 219# 220# @cpu-throttle-percentage: percentage of time guest cpus are being 221# throttled during auto-converge. This is only present when 222# auto-converge has started throttling guest cpus. (Since 2.7) 223# 224# @error-desc: the human readable error description string. Clients 225# should not attempt to parse the error strings. (Since 2.7) 226# 227# @postcopy-blocktime: total time when all vCPU were blocked during 228# postcopy live migration. This is only present when the 229# postcopy-blocktime migration capability is enabled. (Since 3.0) 230# 231# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. 232# This is only present when the postcopy-blocktime migration 233# capability is enabled. (Since 3.0) 234# 235# @compression: migration compression statistics, only returned if 236# compression feature is on and status is 'active' or 'completed' 237# (Since 3.1) 238# 239# @socket-address: Only used for tcp, to know what the real port is 240# (Since 4.0) 241# 242# @vfio: @VfioStats containing detailed VFIO devices migration 243# statistics, only returned if VFIO device is present, migration 244# is supported by all VFIO devices and status is 'active' or 245# 'completed' (since 5.2) 246# 247# @blocked-reasons: A list of reasons an outgoing migration is 248# blocked. Present and non-empty when migration is blocked. 249# (since 6.0) 250# 251# @dirty-limit-throttle-time-per-round: Maximum throttle time 252# (in microseconds) of virtual CPUs each dirty ring full round, 253# which shows how MigrationCapability dirty-limit affects the 254# guest during live migration. (Since 8.1) 255# 256# @dirty-limit-ring-full-time: Estimated average dirty ring full time 257# (in microseconds) for each dirty ring full round. The value 258# equals the dirty ring memory size divided by the average dirty 259# page rate of the virtual CPU, which can be used to observe the 260# average memory load of the virtual CPU indirectly. Note that 261# zero means guest doesn't dirty memory. (Since 8.1) 262# 263# Features: 264# 265# @deprecated: Member @disk is deprecated because block migration is. 266# Member @compression is deprecated because it is unreliable and 267# untested. It is recommended to use multifd migration, which 268# offers an alternative compression implementation that is 269# reliable and tested. 270# 271# Since: 0.14 272## 273{ 'struct': 'MigrationInfo', 274 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 275 '*disk': { 'type': 'MigrationStats', 'features': [ 'deprecated' ] }, 276 '*vfio': 'VfioStats', 277 '*xbzrle-cache': 'XBZRLECacheStats', 278 '*total-time': 'int', 279 '*expected-downtime': 'int', 280 '*downtime': 'int', 281 '*setup-time': 'int', 282 '*cpu-throttle-percentage': 'int', 283 '*error-desc': 'str', 284 '*blocked-reasons': ['str'], 285 '*postcopy-blocktime': 'uint32', 286 '*postcopy-vcpu-blocktime': ['uint32'], 287 '*compression': { 'type': 'CompressionStats', 'features': [ 'deprecated' ] }, 288 '*socket-address': ['SocketAddress'], 289 '*dirty-limit-throttle-time-per-round': 'uint64', 290 '*dirty-limit-ring-full-time': 'uint64'} } 291 292## 293# @query-migrate: 294# 295# Returns information about current migration process. If migration 296# is active there will be another json-object with RAM migration 297# status and if block migration is active another one with block 298# migration status. 299# 300# Returns: @MigrationInfo 301# 302# Since: 0.14 303# 304# Examples: 305# 306# 1. Before the first migration 307# 308# -> { "execute": "query-migrate" } 309# <- { "return": {} } 310# 311# 2. Migration is done and has succeeded 312# 313# -> { "execute": "query-migrate" } 314# <- { "return": { 315# "status": "completed", 316# "total-time":12345, 317# "setup-time":12345, 318# "downtime":12345, 319# "ram":{ 320# "transferred":123, 321# "remaining":123, 322# "total":246, 323# "duplicate":123, 324# "normal":123, 325# "normal-bytes":123456, 326# "dirty-sync-count":15 327# } 328# } 329# } 330# 331# 3. Migration is done and has failed 332# 333# -> { "execute": "query-migrate" } 334# <- { "return": { "status": "failed" } } 335# 336# 4. Migration is being performed and is not a block migration: 337# 338# -> { "execute": "query-migrate" } 339# <- { 340# "return":{ 341# "status":"active", 342# "total-time":12345, 343# "setup-time":12345, 344# "expected-downtime":12345, 345# "ram":{ 346# "transferred":123, 347# "remaining":123, 348# "total":246, 349# "duplicate":123, 350# "normal":123, 351# "normal-bytes":123456, 352# "dirty-sync-count":15 353# } 354# } 355# } 356# 357# 5. Migration is being performed and is a block migration: 358# 359# -> { "execute": "query-migrate" } 360# <- { 361# "return":{ 362# "status":"active", 363# "total-time":12345, 364# "setup-time":12345, 365# "expected-downtime":12345, 366# "ram":{ 367# "total":1057024, 368# "remaining":1053304, 369# "transferred":3720, 370# "duplicate":123, 371# "normal":123, 372# "normal-bytes":123456, 373# "dirty-sync-count":15 374# }, 375# "disk":{ 376# "total":20971520, 377# "remaining":20880384, 378# "transferred":91136 379# } 380# } 381# } 382# 383# 6. Migration is being performed and XBZRLE is active: 384# 385# -> { "execute": "query-migrate" } 386# <- { 387# "return":{ 388# "status":"active", 389# "total-time":12345, 390# "setup-time":12345, 391# "expected-downtime":12345, 392# "ram":{ 393# "total":1057024, 394# "remaining":1053304, 395# "transferred":3720, 396# "duplicate":10, 397# "normal":3333, 398# "normal-bytes":3412992, 399# "dirty-sync-count":15 400# }, 401# "xbzrle-cache":{ 402# "cache-size":67108864, 403# "bytes":20971520, 404# "pages":2444343, 405# "cache-miss":2244, 406# "cache-miss-rate":0.123, 407# "encoding-rate":80.1, 408# "overflow":34434 409# } 410# } 411# } 412## 413{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 414 415## 416# @MigrationCapability: 417# 418# Migration capabilities enumeration 419# 420# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 421# Encoding). This feature allows us to minimize migration traffic 422# for certain work loads, by sending compressed difference of the 423# pages 424# 425# @rdma-pin-all: Controls whether or not the entire VM memory 426# footprint is mlock()'d on demand or all at once. Refer to 427# docs/rdma.txt for usage. Disabled by default. (since 2.0) 428# 429# @zero-blocks: During storage migration encode blocks of zeroes 430# efficiently. This essentially saves 1MB of zeroes per block on 431# the wire. Enabling requires source and target VM to support 432# this feature. To enable it is sufficient to enable the 433# capability on the source VM. The feature is disabled by default. 434# (since 1.6) 435# 436# @compress: Use multiple compression threads to accelerate live 437# migration. This feature can help to reduce the migration 438# traffic, by sending compressed pages. Please note that if 439# compress and xbzrle are both on, compress only takes effect in 440# the ram bulk stage, after that, it will be disabled and only 441# xbzrle takes effect, this can help to minimize migration 442# traffic. The feature is disabled by default. (since 2.4) 443# 444# @events: generate events for each migration state change (since 2.4) 445# 446# @auto-converge: If enabled, QEMU will automatically throttle down 447# the guest to speed up convergence of RAM migration. (since 1.6) 448# 449# @postcopy-ram: Start executing on the migration target before all of 450# RAM has been migrated, pulling the remaining pages along as 451# needed. The capacity must have the same setting on both source 452# and target or migration will not even start. NOTE: If the 453# migration fails during postcopy the VM will fail. (since 2.6) 454# 455# @x-colo: If enabled, migration will never end, and the state of the 456# VM on the primary side will be migrated continuously to the VM 457# on secondary side, this process is called COarse-Grain LOck 458# Stepping (COLO) for Non-stop Service. (since 2.8) 459# 460# @release-ram: if enabled, qemu will free the migrated ram pages on 461# the source during postcopy-ram migration. (since 2.9) 462# 463# @block: If enabled, QEMU will also migrate the contents of all block 464# devices. Default is disabled. A possible alternative uses 465# mirror jobs to a builtin NBD server on the destination, which 466# offers more flexibility. (Since 2.10) 467# 468# @return-path: If enabled, migration will use the return path even 469# for precopy. (since 2.10) 470# 471# @pause-before-switchover: Pause outgoing migration before 472# serialising device state and before disabling block IO (since 473# 2.11) 474# 475# @multifd: Use more than one fd for migration (since 4.0) 476# 477# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 478# (since 2.12) 479# 480# @postcopy-blocktime: Calculate downtime for postcopy live migration 481# (since 3.0) 482# 483# @late-block-activate: If enabled, the destination will not activate 484# block devices (and thus take locks) immediately at the end of 485# migration. (since 3.0) 486# 487# @x-ignore-shared: If enabled, QEMU will not migrate shared memory 488# that is accessible on the destination machine. (since 4.0) 489# 490# @validate-uuid: Send the UUID of the source to allow the destination 491# to ensure it is the same. (since 4.2) 492# 493# @background-snapshot: If enabled, the migration stream will be a 494# snapshot of the VM exactly at the point when the migration 495# procedure starts. The VM RAM is saved with running VM. 496# (since 6.0) 497# 498# @zero-copy-send: Controls behavior on sending memory pages on 499# migration. When true, enables a zero-copy mechanism for sending 500# memory pages, if host supports it. Requires that QEMU be 501# permitted to use locked memory for guest RAM pages. (since 7.1) 502# 503# @postcopy-preempt: If enabled, the migration process will allow 504# postcopy requests to preempt precopy stream, so postcopy 505# requests will be handled faster. This is a performance feature 506# and should not affect the correctness of postcopy migration. 507# (since 7.1) 508# 509# @switchover-ack: If enabled, migration will not stop the source VM 510# and complete the migration until an ACK is received from the 511# destination that it's OK to do so. Exactly when this ACK is 512# sent depends on the migrated devices that use this feature. For 513# example, a device can use it to make sure some of its data is 514# sent and loaded in the destination before doing switchover. 515# This can reduce downtime if devices that support this capability 516# are present. 'return-path' capability must be enabled to use 517# it. (since 8.1) 518# 519# @dirty-limit: If enabled, migration will throttle vCPUs as needed to 520# keep their dirty page rate within @vcpu-dirty-limit. This can 521# improve responsiveness of large guests during live migration, 522# and can result in more stable read performance. Requires KVM 523# with accelerator property "dirty-ring-size" set. (Since 8.1) 524# 525# @mapped-ram: Migrate using fixed offsets in the migration file for 526# each RAM page. Requires a migration URI that supports seeking, 527# such as a file. (since 9.0) 528# 529# Features: 530# 531# @deprecated: Member @block is deprecated. Use blockdev-mirror with 532# NBD instead. Member @compress is deprecated because it is 533# unreliable and untested. It is recommended to use multifd 534# migration, which offers an alternative compression 535# implementation that is reliable and tested. 536# 537# @unstable: Members @x-colo and @x-ignore-shared are experimental. 538# 539# Since: 1.2 540## 541{ 'enum': 'MigrationCapability', 542 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 543 { 'name': 'compress', 'features': [ 'deprecated' ] }, 544 'events', 'postcopy-ram', 545 { 'name': 'x-colo', 'features': [ 'unstable' ] }, 546 'release-ram', 547 { 'name': 'block', 'features': [ 'deprecated' ] }, 548 'return-path', 'pause-before-switchover', 'multifd', 549 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 550 { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 551 'validate-uuid', 'background-snapshot', 552 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 553 'dirty-limit', 'mapped-ram'] } 554 555## 556# @MigrationCapabilityStatus: 557# 558# Migration capability information 559# 560# @capability: capability enum 561# 562# @state: capability state bool 563# 564# Since: 1.2 565## 566{ 'struct': 'MigrationCapabilityStatus', 567 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 568 569## 570# @migrate-set-capabilities: 571# 572# Enable/Disable the following migration capabilities (like xbzrle) 573# 574# @capabilities: json array of capability modifications to make 575# 576# Since: 1.2 577# 578# Example: 579# 580# -> { "execute": "migrate-set-capabilities" , "arguments": 581# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 582# <- { "return": {} } 583## 584{ 'command': 'migrate-set-capabilities', 585 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 586 587## 588# @query-migrate-capabilities: 589# 590# Returns information about the current migration capabilities status 591# 592# Returns: @MigrationCapabilityStatus 593# 594# Since: 1.2 595# 596# Example: 597# 598# -> { "execute": "query-migrate-capabilities" } 599# <- { "return": [ 600# {"state": false, "capability": "xbzrle"}, 601# {"state": false, "capability": "rdma-pin-all"}, 602# {"state": false, "capability": "auto-converge"}, 603# {"state": false, "capability": "zero-blocks"}, 604# {"state": false, "capability": "compress"}, 605# {"state": true, "capability": "events"}, 606# {"state": false, "capability": "postcopy-ram"}, 607# {"state": false, "capability": "x-colo"} 608# ]} 609## 610{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 611 612## 613# @MultiFDCompression: 614# 615# An enumeration of multifd compression methods. 616# 617# @none: no compression. 618# 619# @zlib: use zlib compression method. 620# 621# @zstd: use zstd compression method. 622# 623# Since: 5.0 624## 625{ 'enum': 'MultiFDCompression', 626 'data': [ 'none', 'zlib', 627 { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 628 629## 630# @MigMode: 631# 632# @normal: the original form of migration. (since 8.2) 633# 634# @cpr-reboot: The migrate command stops the VM and saves state to the 635# URI. After quitting QEMU, the user resumes by running QEMU 636# -incoming. 637# 638# This mode allows the user to quit QEMU, optionally update and 639# reboot the OS, and restart QEMU. If the user reboots, the URI 640# must persist across the reboot, such as by using a file. 641# 642# Unlike normal mode, the use of certain local storage options 643# does not block the migration, but the user must not modify the 644# contents of guest block devices between the quit and restart. 645# 646# This mode supports VFIO devices provided the user first puts the 647# guest in the suspended runstate, such as by issuing 648# guest-suspend-ram to the QEMU guest agent. 649# 650# Best performance is achieved when the memory backend is shared 651# and the @x-ignore-shared migration capability is set, but this 652# is not required. Further, if the user reboots before restarting 653# such a configuration, the shared memory must persist across the 654# reboot, such as by backing it with a dax device. 655# 656# @cpr-reboot may not be used with postcopy, background-snapshot, 657# or COLO. 658# 659# (since 8.2) 660## 661{ 'enum': 'MigMode', 662 'data': [ 'normal', 'cpr-reboot' ] } 663 664## 665# @ZeroPageDetection: 666# 667# @none: Do not perform zero page checking. 668# 669# @legacy: Perform zero page checking in main migration thread. 670# 671# @multifd: Perform zero page checking in multifd sender thread if 672# multifd migration is enabled, else in the main migration thread 673# as for @legacy. 674# 675# Since: 9.0 676## 677{ 'enum': 'ZeroPageDetection', 678 'data': [ 'none', 'legacy', 'multifd' ] } 679 680## 681# @BitmapMigrationBitmapAliasTransform: 682# 683# @persistent: If present, the bitmap will be made persistent or 684# transient depending on this parameter. 685# 686# Since: 6.0 687## 688{ 'struct': 'BitmapMigrationBitmapAliasTransform', 689 'data': { 690 '*persistent': 'bool' 691 } } 692 693## 694# @BitmapMigrationBitmapAlias: 695# 696# @name: The name of the bitmap. 697# 698# @alias: An alias name for migration (for example the bitmap name on 699# the opposite site). 700# 701# @transform: Allows the modification of the migrated bitmap. (since 702# 6.0) 703# 704# Since: 5.2 705## 706{ 'struct': 'BitmapMigrationBitmapAlias', 707 'data': { 708 'name': 'str', 709 'alias': 'str', 710 '*transform': 'BitmapMigrationBitmapAliasTransform' 711 } } 712 713## 714# @BitmapMigrationNodeAlias: 715# 716# Maps a block node name and the bitmaps it has to aliases for dirty 717# bitmap migration. 718# 719# @node-name: A block node name. 720# 721# @alias: An alias block node name for migration (for example the node 722# name on the opposite site). 723# 724# @bitmaps: Mappings for the bitmaps on this node. 725# 726# Since: 5.2 727## 728{ 'struct': 'BitmapMigrationNodeAlias', 729 'data': { 730 'node-name': 'str', 731 'alias': 'str', 732 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 733 } } 734 735## 736# @MigrationParameter: 737# 738# Migration parameters enumeration 739# 740# @announce-initial: Initial delay (in milliseconds) before sending 741# the first announce (Since 4.0) 742# 743# @announce-max: Maximum delay (in milliseconds) between packets in 744# the announcement (Since 4.0) 745# 746# @announce-rounds: Number of self-announce packets sent after 747# migration (Since 4.0) 748# 749# @announce-step: Increase in delay (in milliseconds) between 750# subsequent packets in the announcement (Since 4.0) 751# 752# @compress-level: Set the compression level to be used in live 753# migration, the compression level is an integer between 0 and 9, 754# where 0 means no compression, 1 means the best compression 755# speed, and 9 means best compression ratio which will consume 756# more CPU. 757# 758# @compress-threads: Set compression thread count to be used in live 759# migration, the compression thread count is an integer between 1 760# and 255. 761# 762# @compress-wait-thread: Controls behavior when all compression 763# threads are currently busy. If true (default), wait for a free 764# compression thread to become available; otherwise, send the page 765# uncompressed. (Since 3.1) 766# 767# @decompress-threads: Set decompression thread count to be used in 768# live migration, the decompression thread count is an integer 769# between 1 and 255. Usually, decompression is at least 4 times as 770# fast as compression, so set the decompress-threads to the number 771# about 1/4 of compress-threads is adequate. 772# 773# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 774# bytes_xfer_period to trigger throttling. It is expressed as 775# percentage. The default value is 50. (Since 5.0) 776# 777# @cpu-throttle-initial: Initial percentage of time guest cpus are 778# throttled when migration auto-converge is activated. The 779# default value is 20. (Since 2.7) 780# 781# @cpu-throttle-increment: throttle percentage increase each time 782# auto-converge detects that migration is not making progress. 783# The default value is 10. (Since 2.7) 784# 785# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 786# the tail stage of throttling, the Guest is very sensitive to CPU 787# percentage while the @cpu-throttle -increment is excessive 788# usually at tail stage. If this parameter is true, we will 789# compute the ideal CPU percentage used by the Guest, which may 790# exactly make the dirty rate match the dirty rate threshold. 791# Then we will choose a smaller throttle increment between the one 792# specified by @cpu-throttle-increment and the one generated by 793# ideal CPU percentage. Therefore, it is compatible to 794# traditional throttling, meanwhile the throttle increment won't 795# be excessive at tail stage. The default value is false. (Since 796# 5.1) 797# 798# @tls-creds: ID of the 'tls-creds' object that provides credentials 799# for establishing a TLS connection over the migration data 800# channel. On the outgoing side of the migration, the credentials 801# must be for a 'client' endpoint, while for the incoming side the 802# credentials must be for a 'server' endpoint. Setting this to a 803# non-empty string enables TLS for all migrations. An empty 804# string means that QEMU will use plain text mode for migration, 805# rather than TLS. (Since 2.7) 806# 807# @tls-hostname: migration target's hostname for validating the 808# server's x509 certificate identity. If empty, QEMU will use the 809# hostname from the migration URI, if any. A non-empty value is 810# required when using x509 based TLS credentials and the migration 811# URI does not include a hostname, such as fd: or exec: based 812# migration. (Since 2.7) 813# 814# Note: empty value works only since 2.9. 815# 816# @tls-authz: ID of the 'authz' object subclass that provides access 817# control checking of the TLS x509 certificate distinguished name. 818# This object is only resolved at time of use, so can be deleted 819# and recreated on the fly while the migration server is active. 820# If missing, it will default to denying access (Since 4.0) 821# 822# @max-bandwidth: maximum speed for migration, in bytes per second. 823# (Since 2.8) 824# 825# @avail-switchover-bandwidth: to set the available bandwidth that 826# migration can use during switchover phase. NOTE! This does not 827# limit the bandwidth during switchover, but only for calculations 828# when making decisions to switchover. By default, this value is 829# zero, which means QEMU will estimate the bandwidth 830# automatically. This can be set when the estimated value is not 831# accurate, while the user is able to guarantee such bandwidth is 832# available when switching over. When specified correctly, this 833# can make the switchover decision much more accurate. 834# (Since 8.2) 835# 836# @downtime-limit: set maximum tolerated downtime for migration. 837# maximum downtime in milliseconds (Since 2.8) 838# 839# @x-checkpoint-delay: The delay time (in ms) between two COLO 840# checkpoints in periodic mode. (Since 2.8) 841# 842# @multifd-channels: Number of channels used to migrate data in 843# parallel. This is the same number that the number of sockets 844# used for migration. The default value is 2 (since 4.0) 845# 846# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 847# needs to be a multiple of the target page size and a power of 2 848# (Since 2.11) 849# 850# @max-postcopy-bandwidth: Background transfer bandwidth during 851# postcopy. Defaults to 0 (unlimited). In bytes per second. 852# (Since 3.0) 853# 854# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 855# (Since 3.1) 856# 857# @multifd-compression: Which compression method to use. Defaults to 858# none. (Since 5.0) 859# 860# @multifd-zlib-level: Set the compression level to be used in live 861# migration, the compression level is an integer between 0 and 9, 862# where 0 means no compression, 1 means the best compression 863# speed, and 9 means best compression ratio which will consume 864# more CPU. Defaults to 1. (Since 5.0) 865# 866# @multifd-zstd-level: Set the compression level to be used in live 867# migration, the compression level is an integer between 0 and 20, 868# where 0 means no compression, 1 means the best compression 869# speed, and 20 means best compression ratio which will consume 870# more CPU. Defaults to 1. (Since 5.0) 871# 872# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 873# aliases for the purpose of dirty bitmap migration. Such aliases 874# may for example be the corresponding names on the opposite site. 875# The mapping must be one-to-one, but not necessarily complete: On 876# the source, unmapped bitmaps and all bitmaps on unmapped nodes 877# will be ignored. On the destination, encountering an unmapped 878# alias in the incoming migration stream will result in a report, 879# and all further bitmap migration data will then be discarded. 880# Note that the destination does not know about bitmaps it does 881# not receive, so there is no limitation or requirement regarding 882# the number of bitmaps received, or how they are named, or on 883# which nodes they are placed. By default (when this parameter 884# has never been set), bitmap names are mapped to themselves. 885# Nodes are mapped to their block device name if there is one, and 886# to their node name otherwise. (Since 5.2) 887# 888# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 889# limit during live migration. Should be in the range 1 to 890# 1000ms. Defaults to 1000ms. (Since 8.1) 891# 892# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 893# Defaults to 1. (Since 8.1) 894# 895# @mode: Migration mode. See description in @MigMode. Default is 896# 'normal'. (Since 8.2) 897# 898# @zero-page-detection: Whether and how to detect zero pages. 899# See description in @ZeroPageDetection. Default is 'multifd'. 900# (since 9.0) 901# 902# Features: 903# 904# @deprecated: Members @compress-level, @compress-threads, 905# @decompress-threads and @compress-wait-thread are deprecated 906# because @compression is deprecated. 907# 908# @unstable: Members @x-checkpoint-delay and 909# @x-vcpu-dirty-limit-period are experimental. 910# 911# Since: 2.4 912## 913{ 'enum': 'MigrationParameter', 914 'data': ['announce-initial', 'announce-max', 915 'announce-rounds', 'announce-step', 916 { 'name': 'compress-level', 'features': [ 'deprecated' ] }, 917 { 'name': 'compress-threads', 'features': [ 'deprecated' ] }, 918 { 'name': 'decompress-threads', 'features': [ 'deprecated' ] }, 919 { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] }, 920 'throttle-trigger-threshold', 921 'cpu-throttle-initial', 'cpu-throttle-increment', 922 'cpu-throttle-tailslow', 923 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 924 'avail-switchover-bandwidth', 'downtime-limit', 925 { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 926 'multifd-channels', 927 'xbzrle-cache-size', 'max-postcopy-bandwidth', 928 'max-cpu-throttle', 'multifd-compression', 929 'multifd-zlib-level', 'multifd-zstd-level', 930 'block-bitmap-mapping', 931 { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 932 'vcpu-dirty-limit', 933 'mode', 934 'zero-page-detection'] } 935 936## 937# @MigrateSetParameters: 938# 939# @announce-initial: Initial delay (in milliseconds) before sending 940# the first announce (Since 4.0) 941# 942# @announce-max: Maximum delay (in milliseconds) between packets in 943# the announcement (Since 4.0) 944# 945# @announce-rounds: Number of self-announce packets sent after 946# migration (Since 4.0) 947# 948# @announce-step: Increase in delay (in milliseconds) between 949# subsequent packets in the announcement (Since 4.0) 950# 951# @compress-level: Set the compression level to be used in live 952# migration, the compression level is an integer between 0 and 9, 953# where 0 means no compression, 1 means the best compression 954# speed, and 9 means best compression ratio which will consume 955# more CPU. 956# 957# @compress-threads: Set compression thread count to be used in live 958# migration, the compression thread count is an integer between 1 959# and 255. 960# 961# @compress-wait-thread: Controls behavior when all compression 962# threads are currently busy. If true (default), wait for a free 963# compression thread to become available; otherwise, send the page 964# uncompressed. (Since 3.1) 965# 966# @decompress-threads: Set decompression thread count to be used in 967# live migration, the decompression thread count is an integer 968# between 1 and 255. Usually, decompression is at least 4 times as 969# fast as compression, so set the decompress-threads to the number 970# about 1/4 of compress-threads is adequate. 971# 972# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 973# bytes_xfer_period to trigger throttling. It is expressed as 974# percentage. The default value is 50. (Since 5.0) 975# 976# @cpu-throttle-initial: Initial percentage of time guest cpus are 977# throttled when migration auto-converge is activated. The 978# default value is 20. (Since 2.7) 979# 980# @cpu-throttle-increment: throttle percentage increase each time 981# auto-converge detects that migration is not making progress. 982# The default value is 10. (Since 2.7) 983# 984# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 985# the tail stage of throttling, the Guest is very sensitive to CPU 986# percentage while the @cpu-throttle -increment is excessive 987# usually at tail stage. If this parameter is true, we will 988# compute the ideal CPU percentage used by the Guest, which may 989# exactly make the dirty rate match the dirty rate threshold. 990# Then we will choose a smaller throttle increment between the one 991# specified by @cpu-throttle-increment and the one generated by 992# ideal CPU percentage. Therefore, it is compatible to 993# traditional throttling, meanwhile the throttle increment won't 994# be excessive at tail stage. The default value is false. (Since 995# 5.1) 996# 997# @tls-creds: ID of the 'tls-creds' object that provides credentials 998# for establishing a TLS connection over the migration data 999# channel. On the outgoing side of the migration, the credentials 1000# must be for a 'client' endpoint, while for the incoming side the 1001# credentials must be for a 'server' endpoint. Setting this to a 1002# non-empty string enables TLS for all migrations. An empty 1003# string means that QEMU will use plain text mode for migration, 1004# rather than TLS. This is the default. (Since 2.7) 1005# 1006# @tls-hostname: migration target's hostname for validating the 1007# server's x509 certificate identity. If empty, QEMU will use the 1008# hostname from the migration URI, if any. A non-empty value is 1009# required when using x509 based TLS credentials and the migration 1010# URI does not include a hostname, such as fd: or exec: based 1011# migration. (Since 2.7) 1012# 1013# Note: empty value works only since 2.9. 1014# 1015# @tls-authz: ID of the 'authz' object subclass that provides access 1016# control checking of the TLS x509 certificate distinguished name. 1017# This object is only resolved at time of use, so can be deleted 1018# and recreated on the fly while the migration server is active. 1019# If missing, it will default to denying access (Since 4.0) 1020# 1021# @max-bandwidth: maximum speed for migration, in bytes per second. 1022# (Since 2.8) 1023# 1024# @avail-switchover-bandwidth: to set the available bandwidth that 1025# migration can use during switchover phase. NOTE! This does not 1026# limit the bandwidth during switchover, but only for calculations 1027# when making decisions to switchover. By default, this value is 1028# zero, which means QEMU will estimate the bandwidth 1029# automatically. This can be set when the estimated value is not 1030# accurate, while the user is able to guarantee such bandwidth is 1031# available when switching over. When specified correctly, this 1032# can make the switchover decision much more accurate. 1033# (Since 8.2) 1034# 1035# @downtime-limit: set maximum tolerated downtime for migration. 1036# maximum downtime in milliseconds (Since 2.8) 1037# 1038# @x-checkpoint-delay: The delay time (in ms) between two COLO 1039# checkpoints in periodic mode. (Since 2.8) 1040# 1041# @multifd-channels: Number of channels used to migrate data in 1042# parallel. This is the same number that the number of sockets 1043# used for migration. The default value is 2 (since 4.0) 1044# 1045# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1046# needs to be a multiple of the target page size and a power of 2 1047# (Since 2.11) 1048# 1049# @max-postcopy-bandwidth: Background transfer bandwidth during 1050# postcopy. Defaults to 0 (unlimited). In bytes per second. 1051# (Since 3.0) 1052# 1053# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1054# (Since 3.1) 1055# 1056# @multifd-compression: Which compression method to use. Defaults to 1057# none. (Since 5.0) 1058# 1059# @multifd-zlib-level: Set the compression level to be used in live 1060# migration, the compression level is an integer between 0 and 9, 1061# where 0 means no compression, 1 means the best compression 1062# speed, and 9 means best compression ratio which will consume 1063# more CPU. Defaults to 1. (Since 5.0) 1064# 1065# @multifd-zstd-level: Set the compression level to be used in live 1066# migration, the compression level is an integer between 0 and 20, 1067# where 0 means no compression, 1 means the best compression 1068# speed, and 20 means best compression ratio which will consume 1069# more CPU. Defaults to 1. (Since 5.0) 1070# 1071# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1072# aliases for the purpose of dirty bitmap migration. Such aliases 1073# may for example be the corresponding names on the opposite site. 1074# The mapping must be one-to-one, but not necessarily complete: On 1075# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1076# will be ignored. On the destination, encountering an unmapped 1077# alias in the incoming migration stream will result in a report, 1078# and all further bitmap migration data will then be discarded. 1079# Note that the destination does not know about bitmaps it does 1080# not receive, so there is no limitation or requirement regarding 1081# the number of bitmaps received, or how they are named, or on 1082# which nodes they are placed. By default (when this parameter 1083# has never been set), bitmap names are mapped to themselves. 1084# Nodes are mapped to their block device name if there is one, and 1085# to their node name otherwise. (Since 5.2) 1086# 1087# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1088# limit during live migration. Should be in the range 1 to 1089# 1000ms. Defaults to 1000ms. (Since 8.1) 1090# 1091# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1092# Defaults to 1. (Since 8.1) 1093# 1094# @mode: Migration mode. See description in @MigMode. Default is 1095# 'normal'. (Since 8.2) 1096# 1097# @zero-page-detection: Whether and how to detect zero pages. 1098# See description in @ZeroPageDetection. Default is 'multifd'. 1099# (since 9.0) 1100# 1101# Features: 1102# 1103# @deprecated: Members @compress-level, @compress-threads, 1104# @decompress-threads and @compress-wait-thread are deprecated 1105# because @compression is deprecated. 1106# 1107# @unstable: Members @x-checkpoint-delay and 1108# @x-vcpu-dirty-limit-period are experimental. 1109# 1110# TODO: either fuse back into MigrationParameters, or make 1111# MigrationParameters members mandatory 1112# 1113# Since: 2.4 1114## 1115{ 'struct': 'MigrateSetParameters', 1116 'data': { '*announce-initial': 'size', 1117 '*announce-max': 'size', 1118 '*announce-rounds': 'size', 1119 '*announce-step': 'size', 1120 '*compress-level': { 'type': 'uint8', 1121 'features': [ 'deprecated' ] }, 1122 '*compress-threads': { 'type': 'uint8', 1123 'features': [ 'deprecated' ] }, 1124 '*compress-wait-thread': { 'type': 'bool', 1125 'features': [ 'deprecated' ] }, 1126 '*decompress-threads': { 'type': 'uint8', 1127 'features': [ 'deprecated' ] }, 1128 '*throttle-trigger-threshold': 'uint8', 1129 '*cpu-throttle-initial': 'uint8', 1130 '*cpu-throttle-increment': 'uint8', 1131 '*cpu-throttle-tailslow': 'bool', 1132 '*tls-creds': 'StrOrNull', 1133 '*tls-hostname': 'StrOrNull', 1134 '*tls-authz': 'StrOrNull', 1135 '*max-bandwidth': 'size', 1136 '*avail-switchover-bandwidth': 'size', 1137 '*downtime-limit': 'uint64', 1138 '*x-checkpoint-delay': { 'type': 'uint32', 1139 'features': [ 'unstable' ] }, 1140 '*multifd-channels': 'uint8', 1141 '*xbzrle-cache-size': 'size', 1142 '*max-postcopy-bandwidth': 'size', 1143 '*max-cpu-throttle': 'uint8', 1144 '*multifd-compression': 'MultiFDCompression', 1145 '*multifd-zlib-level': 'uint8', 1146 '*multifd-zstd-level': 'uint8', 1147 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1148 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1149 'features': [ 'unstable' ] }, 1150 '*vcpu-dirty-limit': 'uint64', 1151 '*mode': 'MigMode', 1152 '*zero-page-detection': 'ZeroPageDetection'} } 1153 1154## 1155# @migrate-set-parameters: 1156# 1157# Set various migration parameters. 1158# 1159# Since: 2.4 1160# 1161# Example: 1162# 1163# -> { "execute": "migrate-set-parameters" , 1164# "arguments": { "multifd-channels": 5 } } 1165# <- { "return": {} } 1166## 1167{ 'command': 'migrate-set-parameters', 'boxed': true, 1168 'data': 'MigrateSetParameters' } 1169 1170## 1171# @MigrationParameters: 1172# 1173# The optional members aren't actually optional. 1174# 1175# @announce-initial: Initial delay (in milliseconds) before sending 1176# the first announce (Since 4.0) 1177# 1178# @announce-max: Maximum delay (in milliseconds) between packets in 1179# the announcement (Since 4.0) 1180# 1181# @announce-rounds: Number of self-announce packets sent after 1182# migration (Since 4.0) 1183# 1184# @announce-step: Increase in delay (in milliseconds) between 1185# subsequent packets in the announcement (Since 4.0) 1186# 1187# @compress-level: compression level 1188# 1189# @compress-threads: compression thread count 1190# 1191# @compress-wait-thread: Controls behavior when all compression 1192# threads are currently busy. If true (default), wait for a free 1193# compression thread to become available; otherwise, send the page 1194# uncompressed. (Since 3.1) 1195# 1196# @decompress-threads: decompression thread count 1197# 1198# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1199# bytes_xfer_period to trigger throttling. It is expressed as 1200# percentage. The default value is 50. (Since 5.0) 1201# 1202# @cpu-throttle-initial: Initial percentage of time guest cpus are 1203# throttled when migration auto-converge is activated. (Since 1204# 2.7) 1205# 1206# @cpu-throttle-increment: throttle percentage increase each time 1207# auto-converge detects that migration is not making progress. 1208# (Since 2.7) 1209# 1210# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1211# the tail stage of throttling, the Guest is very sensitive to CPU 1212# percentage while the @cpu-throttle -increment is excessive 1213# usually at tail stage. If this parameter is true, we will 1214# compute the ideal CPU percentage used by the Guest, which may 1215# exactly make the dirty rate match the dirty rate threshold. 1216# Then we will choose a smaller throttle increment between the one 1217# specified by @cpu-throttle-increment and the one generated by 1218# ideal CPU percentage. Therefore, it is compatible to 1219# traditional throttling, meanwhile the throttle increment won't 1220# be excessive at tail stage. The default value is false. (Since 1221# 5.1) 1222# 1223# @tls-creds: ID of the 'tls-creds' object that provides credentials 1224# for establishing a TLS connection over the migration data 1225# channel. On the outgoing side of the migration, the credentials 1226# must be for a 'client' endpoint, while for the incoming side the 1227# credentials must be for a 'server' endpoint. An empty string 1228# means that QEMU will use plain text mode for migration, rather 1229# than TLS. (Since 2.7) 1230# 1231# Note: 2.8 omits empty @tls-creds instead. 1232# 1233# @tls-hostname: migration target's hostname for validating the 1234# server's x509 certificate identity. If empty, QEMU will use the 1235# hostname from the migration URI, if any. (Since 2.7) 1236# 1237# Note: 2.8 omits empty @tls-hostname instead. 1238# 1239# @tls-authz: ID of the 'authz' object subclass that provides access 1240# control checking of the TLS x509 certificate distinguished name. 1241# (Since 4.0) 1242# 1243# @max-bandwidth: maximum speed for migration, in bytes per second. 1244# (Since 2.8) 1245# 1246# @avail-switchover-bandwidth: to set the available bandwidth that 1247# migration can use during switchover phase. NOTE! This does not 1248# limit the bandwidth during switchover, but only for calculations 1249# when making decisions to switchover. By default, this value is 1250# zero, which means QEMU will estimate the bandwidth 1251# automatically. This can be set when the estimated value is not 1252# accurate, while the user is able to guarantee such bandwidth is 1253# available when switching over. When specified correctly, this 1254# can make the switchover decision much more accurate. 1255# (Since 8.2) 1256# 1257# @downtime-limit: set maximum tolerated downtime for migration. 1258# maximum downtime in milliseconds (Since 2.8) 1259# 1260# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1261# (Since 2.8) 1262# 1263# @multifd-channels: Number of channels used to migrate data in 1264# parallel. This is the same number that the number of sockets 1265# used for migration. The default value is 2 (since 4.0) 1266# 1267# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1268# needs to be a multiple of the target page size and a power of 2 1269# (Since 2.11) 1270# 1271# @max-postcopy-bandwidth: Background transfer bandwidth during 1272# postcopy. Defaults to 0 (unlimited). In bytes per second. 1273# (Since 3.0) 1274# 1275# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1276# (Since 3.1) 1277# 1278# @multifd-compression: Which compression method to use. Defaults to 1279# none. (Since 5.0) 1280# 1281# @multifd-zlib-level: Set the compression level to be used in live 1282# migration, the compression level is an integer between 0 and 9, 1283# where 0 means no compression, 1 means the best compression 1284# speed, and 9 means best compression ratio which will consume 1285# more CPU. Defaults to 1. (Since 5.0) 1286# 1287# @multifd-zstd-level: Set the compression level to be used in live 1288# migration, the compression level is an integer between 0 and 20, 1289# where 0 means no compression, 1 means the best compression 1290# speed, and 20 means best compression ratio which will consume 1291# more CPU. Defaults to 1. (Since 5.0) 1292# 1293# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1294# aliases for the purpose of dirty bitmap migration. Such aliases 1295# may for example be the corresponding names on the opposite site. 1296# The mapping must be one-to-one, but not necessarily complete: On 1297# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1298# will be ignored. On the destination, encountering an unmapped 1299# alias in the incoming migration stream will result in a report, 1300# and all further bitmap migration data will then be discarded. 1301# Note that the destination does not know about bitmaps it does 1302# not receive, so there is no limitation or requirement regarding 1303# the number of bitmaps received, or how they are named, or on 1304# which nodes they are placed. By default (when this parameter 1305# has never been set), bitmap names are mapped to themselves. 1306# Nodes are mapped to their block device name if there is one, and 1307# to their node name otherwise. (Since 5.2) 1308# 1309# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1310# limit during live migration. Should be in the range 1 to 1311# 1000ms. Defaults to 1000ms. (Since 8.1) 1312# 1313# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1314# Defaults to 1. (Since 8.1) 1315# 1316# @mode: Migration mode. See description in @MigMode. Default is 1317# 'normal'. (Since 8.2) 1318# 1319# @zero-page-detection: Whether and how to detect zero pages. 1320# See description in @ZeroPageDetection. Default is 'multifd'. 1321# (since 9.0) 1322# 1323# Features: 1324# 1325# @deprecated: Members @compress-level, @compress-threads, 1326# @decompress-threads and @compress-wait-thread are deprecated 1327# because @compression is deprecated. 1328# 1329# @unstable: Members @x-checkpoint-delay and 1330# @x-vcpu-dirty-limit-period are experimental. 1331# 1332# Since: 2.4 1333## 1334{ 'struct': 'MigrationParameters', 1335 'data': { '*announce-initial': 'size', 1336 '*announce-max': 'size', 1337 '*announce-rounds': 'size', 1338 '*announce-step': 'size', 1339 '*compress-level': { 'type': 'uint8', 1340 'features': [ 'deprecated' ] }, 1341 '*compress-threads': { 'type': 'uint8', 1342 'features': [ 'deprecated' ] }, 1343 '*compress-wait-thread': { 'type': 'bool', 1344 'features': [ 'deprecated' ] }, 1345 '*decompress-threads': { 'type': 'uint8', 1346 'features': [ 'deprecated' ] }, 1347 '*throttle-trigger-threshold': 'uint8', 1348 '*cpu-throttle-initial': 'uint8', 1349 '*cpu-throttle-increment': 'uint8', 1350 '*cpu-throttle-tailslow': 'bool', 1351 '*tls-creds': 'str', 1352 '*tls-hostname': 'str', 1353 '*tls-authz': 'str', 1354 '*max-bandwidth': 'size', 1355 '*avail-switchover-bandwidth': 'size', 1356 '*downtime-limit': 'uint64', 1357 '*x-checkpoint-delay': { 'type': 'uint32', 1358 'features': [ 'unstable' ] }, 1359 '*multifd-channels': 'uint8', 1360 '*xbzrle-cache-size': 'size', 1361 '*max-postcopy-bandwidth': 'size', 1362 '*max-cpu-throttle': 'uint8', 1363 '*multifd-compression': 'MultiFDCompression', 1364 '*multifd-zlib-level': 'uint8', 1365 '*multifd-zstd-level': 'uint8', 1366 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1367 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1368 'features': [ 'unstable' ] }, 1369 '*vcpu-dirty-limit': 'uint64', 1370 '*mode': 'MigMode', 1371 '*zero-page-detection': 'ZeroPageDetection'} } 1372 1373## 1374# @query-migrate-parameters: 1375# 1376# Returns information about the current migration parameters 1377# 1378# Returns: @MigrationParameters 1379# 1380# Since: 2.4 1381# 1382# Example: 1383# 1384# -> { "execute": "query-migrate-parameters" } 1385# <- { "return": { 1386# "multifd-channels": 2, 1387# "cpu-throttle-increment": 10, 1388# "cpu-throttle-initial": 20, 1389# "max-bandwidth": 33554432, 1390# "downtime-limit": 300 1391# } 1392# } 1393## 1394{ 'command': 'query-migrate-parameters', 1395 'returns': 'MigrationParameters' } 1396 1397## 1398# @migrate-start-postcopy: 1399# 1400# Followup to a migration command to switch the migration to postcopy 1401# mode. The postcopy-ram capability must be set on both source and 1402# destination before the original migration command. 1403# 1404# Since: 2.5 1405# 1406# Example: 1407# 1408# -> { "execute": "migrate-start-postcopy" } 1409# <- { "return": {} } 1410## 1411{ 'command': 'migrate-start-postcopy' } 1412 1413## 1414# @MIGRATION: 1415# 1416# Emitted when a migration event happens 1417# 1418# @status: @MigrationStatus describing the current migration status. 1419# 1420# Since: 2.4 1421# 1422# Example: 1423# 1424# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 1425# "event": "MIGRATION", 1426# "data": {"status": "completed"} } 1427## 1428{ 'event': 'MIGRATION', 1429 'data': {'status': 'MigrationStatus'}} 1430 1431## 1432# @MIGRATION_PASS: 1433# 1434# Emitted from the source side of a migration at the start of each 1435# pass (when it syncs the dirty bitmap) 1436# 1437# @pass: An incrementing count (starting at 1 on the first pass) 1438# 1439# Since: 2.6 1440# 1441# Example: 1442# 1443# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 1444# "event": "MIGRATION_PASS", "data": {"pass": 2} } 1445## 1446{ 'event': 'MIGRATION_PASS', 1447 'data': { 'pass': 'int' } } 1448 1449## 1450# @COLOMessage: 1451# 1452# The message transmission between Primary side and Secondary side. 1453# 1454# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 1455# 1456# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1457# checkpointing 1458# 1459# @checkpoint-reply: SVM gets PVM's checkpoint request 1460# 1461# @vmstate-send: VM's state will be sent by PVM. 1462# 1463# @vmstate-size: The total size of VMstate. 1464# 1465# @vmstate-received: VM's state has been received by SVM. 1466# 1467# @vmstate-loaded: VM's state has been loaded by SVM. 1468# 1469# Since: 2.8 1470## 1471{ 'enum': 'COLOMessage', 1472 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 1473 'vmstate-send', 'vmstate-size', 'vmstate-received', 1474 'vmstate-loaded' ] } 1475 1476## 1477# @COLOMode: 1478# 1479# The COLO current mode. 1480# 1481# @none: COLO is disabled. 1482# 1483# @primary: COLO node in primary side. 1484# 1485# @secondary: COLO node in slave side. 1486# 1487# Since: 2.8 1488## 1489{ 'enum': 'COLOMode', 1490 'data': [ 'none', 'primary', 'secondary'] } 1491 1492## 1493# @FailoverStatus: 1494# 1495# An enumeration of COLO failover status 1496# 1497# @none: no failover has ever happened 1498# 1499# @require: got failover requirement but not handled 1500# 1501# @active: in the process of doing failover 1502# 1503# @completed: finish the process of failover 1504# 1505# @relaunch: restart the failover process, from 'none' -> 'completed' 1506# (Since 2.9) 1507# 1508# Since: 2.8 1509## 1510{ 'enum': 'FailoverStatus', 1511 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 1512 1513## 1514# @COLO_EXIT: 1515# 1516# Emitted when VM finishes COLO mode due to some errors happening or 1517# at the request of users. 1518# 1519# @mode: report COLO mode when COLO exited. 1520# 1521# @reason: describes the reason for the COLO exit. 1522# 1523# Since: 3.1 1524# 1525# Example: 1526# 1527# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 1528# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 1529## 1530{ 'event': 'COLO_EXIT', 1531 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 1532 1533## 1534# @COLOExitReason: 1535# 1536# The reason for a COLO exit. 1537# 1538# @none: failover has never happened. This state does not occur in 1539# the COLO_EXIT event, and is only visible in the result of 1540# query-colo-status. 1541# 1542# @request: COLO exit is due to an external request. 1543# 1544# @error: COLO exit is due to an internal error. 1545# 1546# @processing: COLO is currently handling a failover (since 4.0). 1547# 1548# Since: 3.1 1549## 1550{ 'enum': 'COLOExitReason', 1551 'data': [ 'none', 'request', 'error' , 'processing' ] } 1552 1553## 1554# @x-colo-lost-heartbeat: 1555# 1556# Tell qemu that heartbeat is lost, request it to do takeover 1557# procedures. If this command is sent to the PVM, the Primary side 1558# will exit COLO mode. If sent to the Secondary, the Secondary side 1559# will run failover work, then takes over server operation to become 1560# the service VM. 1561# 1562# Features: 1563# 1564# @unstable: This command is experimental. 1565# 1566# Since: 2.8 1567# 1568# Example: 1569# 1570# -> { "execute": "x-colo-lost-heartbeat" } 1571# <- { "return": {} } 1572## 1573{ 'command': 'x-colo-lost-heartbeat', 1574 'features': [ 'unstable' ], 1575 'if': 'CONFIG_REPLICATION' } 1576 1577## 1578# @migrate_cancel: 1579# 1580# Cancel the current executing migration process. 1581# 1582# Notes: This command succeeds even if there is no migration process 1583# running. 1584# 1585# Since: 0.14 1586# 1587# Example: 1588# 1589# -> { "execute": "migrate_cancel" } 1590# <- { "return": {} } 1591## 1592{ 'command': 'migrate_cancel' } 1593 1594## 1595# @migrate-continue: 1596# 1597# Continue migration when it's in a paused state. 1598# 1599# @state: The state the migration is currently expected to be in 1600# 1601# Since: 2.11 1602# 1603# Example: 1604# 1605# -> { "execute": "migrate-continue" , "arguments": 1606# { "state": "pre-switchover" } } 1607# <- { "return": {} } 1608## 1609{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 1610 1611## 1612# @MigrationAddressType: 1613# 1614# The migration stream transport mechanisms. 1615# 1616# @socket: Migrate via socket. 1617# 1618# @exec: Direct the migration stream to another process. 1619# 1620# @rdma: Migrate via RDMA. 1621# 1622# @file: Direct the migration stream to a file. 1623# 1624# Since: 8.2 1625## 1626{ 'enum': 'MigrationAddressType', 1627 'data': [ 'socket', 'exec', 'rdma', 'file' ] } 1628 1629## 1630# @FileMigrationArgs: 1631# 1632# @filename: The file to receive the migration stream 1633# 1634# @offset: The file offset where the migration stream will start 1635# 1636# Since: 8.2 1637## 1638{ 'struct': 'FileMigrationArgs', 1639 'data': { 'filename': 'str', 1640 'offset': 'uint64' } } 1641 1642## 1643# @MigrationExecCommand: 1644# 1645# @args: command (list head) and arguments to execute. 1646# 1647# Since: 8.2 1648## 1649{ 'struct': 'MigrationExecCommand', 1650 'data': {'args': [ 'str' ] } } 1651 1652## 1653# @MigrationAddress: 1654# 1655# Migration endpoint configuration. 1656# 1657# @transport: The migration stream transport mechanism 1658# 1659# Since: 8.2 1660## 1661{ 'union': 'MigrationAddress', 1662 'base': { 'transport' : 'MigrationAddressType'}, 1663 'discriminator': 'transport', 1664 'data': { 1665 'socket': 'SocketAddress', 1666 'exec': 'MigrationExecCommand', 1667 'rdma': 'InetSocketAddress', 1668 'file': 'FileMigrationArgs' } } 1669 1670## 1671# @MigrationChannelType: 1672# 1673# The migration channel-type request options. 1674# 1675# @main: Main outbound migration channel. 1676# 1677# Since: 8.1 1678## 1679{ 'enum': 'MigrationChannelType', 1680 'data': [ 'main' ] } 1681 1682## 1683# @MigrationChannel: 1684# 1685# Migration stream channel parameters. 1686# 1687# @channel-type: Channel type for transferring packet information. 1688# 1689# @addr: Migration endpoint configuration on destination interface. 1690# 1691# Since: 8.1 1692## 1693{ 'struct': 'MigrationChannel', 1694 'data': { 1695 'channel-type': 'MigrationChannelType', 1696 'addr': 'MigrationAddress' } } 1697 1698## 1699# @migrate: 1700# 1701# Migrates the current running guest to another Virtual Machine. 1702# 1703# @uri: the Uniform Resource Identifier of the destination VM 1704# 1705# @channels: list of migration stream channels with each stream in the 1706# list connected to a destination interface endpoint. 1707# 1708# @blk: do block migration (full disk copy) 1709# 1710# @detach: this argument exists only for compatibility reasons and is 1711# ignored by QEMU 1712# 1713# @resume: resume one paused migration, default "off". (since 3.0) 1714# 1715# Features: 1716# 1717# @deprecated: Member @blk is deprecated. Use blockdev-mirror with 1718# NBD instead. 1719# 1720# Since: 0.14 1721# 1722# Notes: 1723# 1724# 1. The 'query-migrate' command should be used to check 1725# migration's progress and final result (this information is 1726# provided by the 'status' member) 1727# 1728# 2. All boolean arguments default to false 1729# 1730# 3. The user Monitor's "detach" argument is invalid in QMP and 1731# should not be used 1732# 1733# 4. The uri argument should have the Uniform Resource Identifier 1734# of default destination VM. This connection will be bound to 1735# default network. 1736# 1737# 5. For now, number of migration streams is restricted to one, 1738# i.e. number of items in 'channels' list is just 1. 1739# 1740# 6. The 'uri' and 'channels' arguments are mutually exclusive; 1741# exactly one of the two should be present. 1742# 1743# Example: 1744# 1745# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 1746# <- { "return": {} } 1747# 1748# -> { "execute": "migrate", 1749# "arguments": { 1750# "channels": [ { "channel-type": "main", 1751# "addr": { "transport": "socket", 1752# "type": "inet", 1753# "host": "10.12.34.9", 1754# "port": "1050" } } ] } } 1755# <- { "return": {} } 1756# 1757# -> { "execute": "migrate", 1758# "arguments": { 1759# "channels": [ { "channel-type": "main", 1760# "addr": { "transport": "exec", 1761# "args": [ "/bin/nc", "-p", "6000", 1762# "/some/sock" ] } } ] } } 1763# <- { "return": {} } 1764# 1765# -> { "execute": "migrate", 1766# "arguments": { 1767# "channels": [ { "channel-type": "main", 1768# "addr": { "transport": "rdma", 1769# "host": "10.12.34.9", 1770# "port": "1050" } } ] } } 1771# <- { "return": {} } 1772# 1773# -> { "execute": "migrate", 1774# "arguments": { 1775# "channels": [ { "channel-type": "main", 1776# "addr": { "transport": "file", 1777# "filename": "/tmp/migfile", 1778# "offset": "0x1000" } } ] } } 1779# <- { "return": {} } 1780# 1781## 1782{ 'command': 'migrate', 1783 'data': {'*uri': 'str', 1784 '*channels': [ 'MigrationChannel' ], 1785 '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] }, 1786 '*detach': 'bool', '*resume': 'bool' } } 1787 1788## 1789# @migrate-incoming: 1790# 1791# Start an incoming migration, the qemu must have been started with 1792# -incoming defer 1793# 1794# @uri: The Uniform Resource Identifier identifying the source or 1795# address to listen on 1796# 1797# @channels: list of migration stream channels with each stream in the 1798# list connected to a destination interface endpoint. 1799# 1800# @exit-on-error: Exit on incoming migration failure. Default true. 1801# When set to false, the failure triggers a MIGRATION event, and 1802# error details could be retrieved with query-migrate. (since 9.1) 1803# 1804# Since: 2.3 1805# 1806# Notes: 1807# 1808# 1. It's a bad idea to use a string for the uri, but it needs to 1809# stay compatible with -incoming and the format of the uri is 1810# already exposed above libvirt. 1811# 1812# 2. QEMU must be started with -incoming defer to allow 1813# migrate-incoming to be used. 1814# 1815# 3. The uri format is the same as for -incoming 1816# 1817# 4. For now, number of migration streams is restricted to one, 1818# i.e. number of items in 'channels' list is just 1. 1819# 1820# 5. The 'uri' and 'channels' arguments are mutually exclusive; 1821# exactly one of the two should be present. 1822# 1823# Example: 1824# 1825# -> { "execute": "migrate-incoming", 1826# "arguments": { "uri": "tcp:0:4446" } } 1827# <- { "return": {} } 1828# 1829# -> { "execute": "migrate-incoming", 1830# "arguments": { 1831# "channels": [ { "channel-type": "main", 1832# "addr": { "transport": "socket", 1833# "type": "inet", 1834# "host": "10.12.34.9", 1835# "port": "1050" } } ] } } 1836# <- { "return": {} } 1837# 1838# -> { "execute": "migrate-incoming", 1839# "arguments": { 1840# "channels": [ { "channel-type": "main", 1841# "addr": { "transport": "exec", 1842# "args": [ "/bin/nc", "-p", "6000", 1843# "/some/sock" ] } } ] } } 1844# <- { "return": {} } 1845# 1846# -> { "execute": "migrate-incoming", 1847# "arguments": { 1848# "channels": [ { "channel-type": "main", 1849# "addr": { "transport": "rdma", 1850# "host": "10.12.34.9", 1851# "port": "1050" } } ] } } 1852# <- { "return": {} } 1853## 1854{ 'command': 'migrate-incoming', 1855 'data': {'*uri': 'str', 1856 '*channels': [ 'MigrationChannel' ], 1857 '*exit-on-error': 'bool' } } 1858 1859## 1860# @xen-save-devices-state: 1861# 1862# Save the state of all devices to file. The RAM and the block 1863# devices of the VM are not saved by this command. 1864# 1865# @filename: the file to save the state of the devices to as binary 1866# data. See xen-save-devices-state.txt for a description of the 1867# binary format. 1868# 1869# @live: Optional argument to ask QEMU to treat this command as part 1870# of a live migration. Default to true. (since 2.11) 1871# 1872# Since: 1.1 1873# 1874# Example: 1875# 1876# -> { "execute": "xen-save-devices-state", 1877# "arguments": { "filename": "/tmp/save" } } 1878# <- { "return": {} } 1879## 1880{ 'command': 'xen-save-devices-state', 1881 'data': {'filename': 'str', '*live':'bool' } } 1882 1883## 1884# @xen-set-global-dirty-log: 1885# 1886# Enable or disable the global dirty log mode. 1887# 1888# @enable: true to enable, false to disable. 1889# 1890# Since: 1.3 1891# 1892# Example: 1893# 1894# -> { "execute": "xen-set-global-dirty-log", 1895# "arguments": { "enable": true } } 1896# <- { "return": {} } 1897## 1898{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 1899 1900## 1901# @xen-load-devices-state: 1902# 1903# Load the state of all devices from file. The RAM and the block 1904# devices of the VM are not loaded by this command. 1905# 1906# @filename: the file to load the state of the devices from as binary 1907# data. See xen-save-devices-state.txt for a description of the 1908# binary format. 1909# 1910# Since: 2.7 1911# 1912# Example: 1913# 1914# -> { "execute": "xen-load-devices-state", 1915# "arguments": { "filename": "/tmp/resume" } } 1916# <- { "return": {} } 1917## 1918{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 1919 1920## 1921# @xen-set-replication: 1922# 1923# Enable or disable replication. 1924# 1925# @enable: true to enable, false to disable. 1926# 1927# @primary: true for primary or false for secondary. 1928# 1929# @failover: true to do failover, false to stop. Cannot be specified 1930# if 'enable' is true. Default value is false. 1931# 1932# Example: 1933# 1934# -> { "execute": "xen-set-replication", 1935# "arguments": {"enable": true, "primary": false} } 1936# <- { "return": {} } 1937# 1938# Since: 2.9 1939## 1940{ 'command': 'xen-set-replication', 1941 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 1942 'if': 'CONFIG_REPLICATION' } 1943 1944## 1945# @ReplicationStatus: 1946# 1947# The result format for 'query-xen-replication-status'. 1948# 1949# @error: true if an error happened, false if replication is normal. 1950# 1951# @desc: the human readable error description string, when @error is 1952# 'true'. 1953# 1954# Since: 2.9 1955## 1956{ 'struct': 'ReplicationStatus', 1957 'data': { 'error': 'bool', '*desc': 'str' }, 1958 'if': 'CONFIG_REPLICATION' } 1959 1960## 1961# @query-xen-replication-status: 1962# 1963# Query replication status while the vm is running. 1964# 1965# Returns: A @ReplicationStatus object showing the status. 1966# 1967# Example: 1968# 1969# -> { "execute": "query-xen-replication-status" } 1970# <- { "return": { "error": false } } 1971# 1972# Since: 2.9 1973## 1974{ 'command': 'query-xen-replication-status', 1975 'returns': 'ReplicationStatus', 1976 'if': 'CONFIG_REPLICATION' } 1977 1978## 1979# @xen-colo-do-checkpoint: 1980# 1981# Xen uses this command to notify replication to trigger a checkpoint. 1982# 1983# Example: 1984# 1985# -> { "execute": "xen-colo-do-checkpoint" } 1986# <- { "return": {} } 1987# 1988# Since: 2.9 1989## 1990{ 'command': 'xen-colo-do-checkpoint', 1991 'if': 'CONFIG_REPLICATION' } 1992 1993## 1994# @COLOStatus: 1995# 1996# The result format for 'query-colo-status'. 1997# 1998# @mode: COLO running mode. If COLO is running, this field will 1999# return 'primary' or 'secondary'. 2000# 2001# @last-mode: COLO last running mode. If COLO is running, this field 2002# will return same like mode field, after failover we can use this 2003# field to get last colo mode. (since 4.0) 2004# 2005# @reason: describes the reason for the COLO exit. 2006# 2007# Since: 3.1 2008## 2009{ 'struct': 'COLOStatus', 2010 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 2011 'reason': 'COLOExitReason' }, 2012 'if': 'CONFIG_REPLICATION' } 2013 2014## 2015# @query-colo-status: 2016# 2017# Query COLO status while the vm is running. 2018# 2019# Returns: A @COLOStatus object showing the status. 2020# 2021# Example: 2022# 2023# -> { "execute": "query-colo-status" } 2024# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 2025# 2026# Since: 3.1 2027## 2028{ 'command': 'query-colo-status', 2029 'returns': 'COLOStatus', 2030 'if': 'CONFIG_REPLICATION' } 2031 2032## 2033# @migrate-recover: 2034# 2035# Provide a recovery migration stream URI. 2036# 2037# @uri: the URI to be used for the recovery of migration stream. 2038# 2039# Example: 2040# 2041# -> { "execute": "migrate-recover", 2042# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 2043# <- { "return": {} } 2044# 2045# Since: 3.0 2046## 2047{ 'command': 'migrate-recover', 2048 'data': { 'uri': 'str' }, 2049 'allow-oob': true } 2050 2051## 2052# @migrate-pause: 2053# 2054# Pause a migration. Currently it only supports postcopy. 2055# 2056# Example: 2057# 2058# -> { "execute": "migrate-pause" } 2059# <- { "return": {} } 2060# 2061# Since: 3.0 2062## 2063{ 'command': 'migrate-pause', 'allow-oob': true } 2064 2065## 2066# @UNPLUG_PRIMARY: 2067# 2068# Emitted from source side of a migration when migration state is 2069# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 2070# resources in QEMU are kept on standby to be able to re-plug it in 2071# case of migration failure. 2072# 2073# @device-id: QEMU device id of the unplugged device 2074# 2075# Since: 4.2 2076# 2077# Example: 2078# 2079# <- { "event": "UNPLUG_PRIMARY", 2080# "data": { "device-id": "hostdev0" }, 2081# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 2082## 2083{ 'event': 'UNPLUG_PRIMARY', 2084 'data': { 'device-id': 'str' } } 2085 2086## 2087# @DirtyRateVcpu: 2088# 2089# Dirty rate of vcpu. 2090# 2091# @id: vcpu index. 2092# 2093# @dirty-rate: dirty rate. 2094# 2095# Since: 6.2 2096## 2097{ 'struct': 'DirtyRateVcpu', 2098 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 2099 2100## 2101# @DirtyRateStatus: 2102# 2103# Dirty page rate measurement status. 2104# 2105# @unstarted: measuring thread has not been started yet 2106# 2107# @measuring: measuring thread is running 2108# 2109# @measured: dirty page rate is measured and the results are available 2110# 2111# Since: 5.2 2112## 2113{ 'enum': 'DirtyRateStatus', 2114 'data': [ 'unstarted', 'measuring', 'measured'] } 2115 2116## 2117# @DirtyRateMeasureMode: 2118# 2119# Method used to measure dirty page rate. Differences between 2120# available methods are explained in @calc-dirty-rate. 2121# 2122# @page-sampling: use page sampling 2123# 2124# @dirty-ring: use dirty ring 2125# 2126# @dirty-bitmap: use dirty bitmap 2127# 2128# Since: 6.2 2129## 2130{ 'enum': 'DirtyRateMeasureMode', 2131 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 2132 2133## 2134# @TimeUnit: 2135# 2136# Specifies unit in which time-related value is specified. 2137# 2138# @second: value is in seconds 2139# 2140# @millisecond: value is in milliseconds 2141# 2142# Since: 8.2 2143## 2144{ 'enum': 'TimeUnit', 2145 'data': ['second', 'millisecond'] } 2146 2147## 2148# @DirtyRateInfo: 2149# 2150# Information about measured dirty page rate. 2151# 2152# @dirty-rate: an estimate of the dirty page rate of the VM in units 2153# of MiB/s. Value is present only when @status is 'measured'. 2154# 2155# @status: current status of dirty page rate measurements 2156# 2157# @start-time: start time in units of second for calculation 2158# 2159# @calc-time: time period for which dirty page rate was measured, 2160# expressed and rounded down to @calc-time-unit. 2161# 2162# @calc-time-unit: time unit of @calc-time (Since 8.2) 2163# 2164# @sample-pages: number of sampled pages per GiB of guest memory. 2165# Valid only in page-sampling mode (Since 6.1) 2166# 2167# @mode: mode that was used to measure dirty page rate (Since 6.2) 2168# 2169# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 2170# specified (Since 6.2) 2171# 2172# Since: 5.2 2173## 2174{ 'struct': 'DirtyRateInfo', 2175 'data': {'*dirty-rate': 'int64', 2176 'status': 'DirtyRateStatus', 2177 'start-time': 'int64', 2178 'calc-time': 'int64', 2179 'calc-time-unit': 'TimeUnit', 2180 'sample-pages': 'uint64', 2181 'mode': 'DirtyRateMeasureMode', 2182 '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 2183 2184## 2185# @calc-dirty-rate: 2186# 2187# Start measuring dirty page rate of the VM. Results can be retrieved 2188# with @query-dirty-rate after measurements are completed. 2189# 2190# Dirty page rate is the number of pages changed in a given time 2191# period expressed in MiB/s. The following methods of calculation are 2192# available: 2193# 2194# 1. In page sampling mode, a random subset of pages are selected and 2195# hashed twice: once at the beginning of measurement time period, 2196# and once again at the end. If two hashes for some page are 2197# different, the page is counted as changed. Since this method 2198# relies on sampling and hashing, calculated dirty page rate is 2199# only an estimate of its true value. Increasing @sample-pages 2200# improves estimation quality at the cost of higher computational 2201# overhead. 2202# 2203# 2. Dirty bitmap mode captures writes to memory (for example by 2204# temporarily revoking write access to all pages) and counting page 2205# faults. Information about modified pages is collected into a 2206# bitmap, where each bit corresponds to one guest page. This mode 2207# requires that KVM accelerator property "dirty-ring-size" is *not* 2208# set. 2209# 2210# 3. Dirty ring mode is similar to dirty bitmap mode, but the 2211# information about modified pages is collected into ring buffer. 2212# This mode tracks page modification per each vCPU separately. It 2213# requires that KVM accelerator property "dirty-ring-size" is set. 2214# 2215# @calc-time: time period for which dirty page rate is calculated. 2216# By default it is specified in seconds, but the unit can be set 2217# explicitly with @calc-time-unit. Note that larger @calc-time 2218# values will typically result in smaller dirty page rates because 2219# page dirtying is a one-time event. Once some page is counted 2220# as dirty during @calc-time period, further writes to this page 2221# will not increase dirty page rate anymore. 2222# 2223# @calc-time-unit: time unit in which @calc-time is specified. 2224# By default it is seconds. (Since 8.2) 2225# 2226# @sample-pages: number of sampled pages per each GiB of guest memory. 2227# Default value is 512. For 4KiB guest pages this corresponds to 2228# sampling ratio of 0.2%. This argument is used only in page 2229# sampling mode. (Since 6.1) 2230# 2231# @mode: mechanism for tracking dirty pages. Default value is 2232# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 2233# (Since 6.1) 2234# 2235# Since: 5.2 2236# 2237# Example: 2238# 2239# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 2240# 'sample-pages': 512} } 2241# <- { "return": {} } 2242# 2243# Measure dirty rate using dirty bitmap for 500 milliseconds: 2244# 2245# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, 2246# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } 2247# 2248# <- { "return": {} } 2249## 2250{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 2251 '*calc-time-unit': 'TimeUnit', 2252 '*sample-pages': 'int', 2253 '*mode': 'DirtyRateMeasureMode'} } 2254 2255## 2256# @query-dirty-rate: 2257# 2258# Query results of the most recent invocation of @calc-dirty-rate. 2259# 2260# @calc-time-unit: time unit in which to report calculation time. 2261# By default it is reported in seconds. (Since 8.2) 2262# 2263# Since: 5.2 2264# 2265# Examples: 2266# 2267# 1. Measurement is in progress: 2268# 2269# <- {"status": "measuring", "sample-pages": 512, 2270# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2271# "calc-time-unit": "second"} 2272# 2273# 2. Measurement has been completed: 2274# 2275# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 2276# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2277# "calc-time-unit": "second"} 2278## 2279{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 2280 'returns': 'DirtyRateInfo' } 2281 2282## 2283# @DirtyLimitInfo: 2284# 2285# Dirty page rate limit information of a virtual CPU. 2286# 2287# @cpu-index: index of a virtual CPU. 2288# 2289# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 2290# CPU, 0 means unlimited. 2291# 2292# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 2293# 2294# Since: 7.1 2295## 2296{ 'struct': 'DirtyLimitInfo', 2297 'data': { 'cpu-index': 'int', 2298 'limit-rate': 'uint64', 2299 'current-rate': 'uint64' } } 2300 2301## 2302# @set-vcpu-dirty-limit: 2303# 2304# Set the upper limit of dirty page rate for virtual CPUs. 2305# 2306# Requires KVM with accelerator property "dirty-ring-size" set. A 2307# virtual CPU's dirty page rate is a measure of its memory load. To 2308# observe dirty page rates, use @calc-dirty-rate. 2309# 2310# @cpu-index: index of a virtual CPU, default is all. 2311# 2312# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 2313# 2314# Since: 7.1 2315# 2316# Example: 2317# 2318# -> {"execute": "set-vcpu-dirty-limit"} 2319# "arguments": { "dirty-rate": 200, 2320# "cpu-index": 1 } } 2321# <- { "return": {} } 2322## 2323{ 'command': 'set-vcpu-dirty-limit', 2324 'data': { '*cpu-index': 'int', 2325 'dirty-rate': 'uint64' } } 2326 2327## 2328# @cancel-vcpu-dirty-limit: 2329# 2330# Cancel the upper limit of dirty page rate for virtual CPUs. 2331# 2332# Cancel the dirty page limit for the vCPU which has been set with 2333# set-vcpu-dirty-limit command. Note that this command requires 2334# support from dirty ring, same as the "set-vcpu-dirty-limit". 2335# 2336# @cpu-index: index of a virtual CPU, default is all. 2337# 2338# Since: 7.1 2339# 2340# Example: 2341# 2342# -> {"execute": "cancel-vcpu-dirty-limit"}, 2343# "arguments": { "cpu-index": 1 } } 2344# <- { "return": {} } 2345## 2346{ 'command': 'cancel-vcpu-dirty-limit', 2347 'data': { '*cpu-index': 'int'} } 2348 2349## 2350# @query-vcpu-dirty-limit: 2351# 2352# Returns information about virtual CPU dirty page rate limits, if 2353# any. 2354# 2355# Since: 7.1 2356# 2357# Example: 2358# 2359# -> {"execute": "query-vcpu-dirty-limit"} 2360# <- {"return": [ 2361# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 2362# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 2363## 2364{ 'command': 'query-vcpu-dirty-limit', 2365 'returns': [ 'DirtyLimitInfo' ] } 2366 2367## 2368# @MigrationThreadInfo: 2369# 2370# Information about migrationthreads 2371# 2372# @name: the name of migration thread 2373# 2374# @thread-id: ID of the underlying host thread 2375# 2376# Since: 7.2 2377## 2378{ 'struct': 'MigrationThreadInfo', 2379 'data': {'name': 'str', 2380 'thread-id': 'int'} } 2381 2382## 2383# @query-migrationthreads: 2384# 2385# Returns information of migration threads 2386# 2387# Returns: @MigrationThreadInfo 2388# 2389# Since: 7.2 2390## 2391{ 'command': 'query-migrationthreads', 2392 'returns': ['MigrationThreadInfo'] } 2393 2394## 2395# @snapshot-save: 2396# 2397# Save a VM snapshot 2398# 2399# @job-id: identifier for the newly created job 2400# 2401# @tag: name of the snapshot to create 2402# 2403# @vmstate: block device node name to save vmstate to 2404# 2405# @devices: list of block device node names to save a snapshot to 2406# 2407# Applications should not assume that the snapshot save is complete 2408# when this command returns. The job commands / events must be used 2409# to determine completion and to fetch details of any errors that 2410# arise. 2411# 2412# Note that execution of the guest CPUs may be stopped during the time 2413# it takes to save the snapshot. A future version of QEMU may ensure 2414# CPUs are executing continuously. 2415# 2416# It is strongly recommended that @devices contain all writable block 2417# device nodes if a consistent snapshot is required. 2418# 2419# If @tag already exists, an error will be reported 2420# 2421# Example: 2422# 2423# -> { "execute": "snapshot-save", 2424# "arguments": { 2425# "job-id": "snapsave0", 2426# "tag": "my-snap", 2427# "vmstate": "disk0", 2428# "devices": ["disk0", "disk1"] 2429# } 2430# } 2431# <- { "return": { } } 2432# <- {"event": "JOB_STATUS_CHANGE", 2433# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 2434# "data": {"status": "created", "id": "snapsave0"}} 2435# <- {"event": "JOB_STATUS_CHANGE", 2436# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 2437# "data": {"status": "running", "id": "snapsave0"}} 2438# <- {"event": "STOP", 2439# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 2440# <- {"event": "RESUME", 2441# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 2442# <- {"event": "JOB_STATUS_CHANGE", 2443# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 2444# "data": {"status": "waiting", "id": "snapsave0"}} 2445# <- {"event": "JOB_STATUS_CHANGE", 2446# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 2447# "data": {"status": "pending", "id": "snapsave0"}} 2448# <- {"event": "JOB_STATUS_CHANGE", 2449# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 2450# "data": {"status": "concluded", "id": "snapsave0"}} 2451# -> {"execute": "query-jobs"} 2452# <- {"return": [{"current-progress": 1, 2453# "status": "concluded", 2454# "total-progress": 1, 2455# "type": "snapshot-save", 2456# "id": "snapsave0"}]} 2457# 2458# Since: 6.0 2459## 2460{ 'command': 'snapshot-save', 2461 'data': { 'job-id': 'str', 2462 'tag': 'str', 2463 'vmstate': 'str', 2464 'devices': ['str'] } } 2465 2466## 2467# @snapshot-load: 2468# 2469# Load a VM snapshot 2470# 2471# @job-id: identifier for the newly created job 2472# 2473# @tag: name of the snapshot to load. 2474# 2475# @vmstate: block device node name to load vmstate from 2476# 2477# @devices: list of block device node names to load a snapshot from 2478# 2479# Applications should not assume that the snapshot load is complete 2480# when this command returns. The job commands / events must be used 2481# to determine completion and to fetch details of any errors that 2482# arise. 2483# 2484# Note that execution of the guest CPUs will be stopped during the 2485# time it takes to load the snapshot. 2486# 2487# It is strongly recommended that @devices contain all writable block 2488# device nodes that can have changed since the original @snapshot-save 2489# command execution. 2490# 2491# Example: 2492# 2493# -> { "execute": "snapshot-load", 2494# "arguments": { 2495# "job-id": "snapload0", 2496# "tag": "my-snap", 2497# "vmstate": "disk0", 2498# "devices": ["disk0", "disk1"] 2499# } 2500# } 2501# <- { "return": { } } 2502# <- {"event": "JOB_STATUS_CHANGE", 2503# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 2504# "data": {"status": "created", "id": "snapload0"}} 2505# <- {"event": "JOB_STATUS_CHANGE", 2506# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 2507# "data": {"status": "running", "id": "snapload0"}} 2508# <- {"event": "STOP", 2509# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 2510# <- {"event": "RESUME", 2511# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 2512# <- {"event": "JOB_STATUS_CHANGE", 2513# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 2514# "data": {"status": "waiting", "id": "snapload0"}} 2515# <- {"event": "JOB_STATUS_CHANGE", 2516# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 2517# "data": {"status": "pending", "id": "snapload0"}} 2518# <- {"event": "JOB_STATUS_CHANGE", 2519# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 2520# "data": {"status": "concluded", "id": "snapload0"}} 2521# -> {"execute": "query-jobs"} 2522# <- {"return": [{"current-progress": 1, 2523# "status": "concluded", 2524# "total-progress": 1, 2525# "type": "snapshot-load", 2526# "id": "snapload0"}]} 2527# 2528# Since: 6.0 2529## 2530{ 'command': 'snapshot-load', 2531 'data': { 'job-id': 'str', 2532 'tag': 'str', 2533 'vmstate': 'str', 2534 'devices': ['str'] } } 2535 2536## 2537# @snapshot-delete: 2538# 2539# Delete a VM snapshot 2540# 2541# @job-id: identifier for the newly created job 2542# 2543# @tag: name of the snapshot to delete. 2544# 2545# @devices: list of block device node names to delete a snapshot from 2546# 2547# Applications should not assume that the snapshot delete is complete 2548# when this command returns. The job commands / events must be used 2549# to determine completion and to fetch details of any errors that 2550# arise. 2551# 2552# Example: 2553# 2554# -> { "execute": "snapshot-delete", 2555# "arguments": { 2556# "job-id": "snapdelete0", 2557# "tag": "my-snap", 2558# "devices": ["disk0", "disk1"] 2559# } 2560# } 2561# <- { "return": { } } 2562# <- {"event": "JOB_STATUS_CHANGE", 2563# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 2564# "data": {"status": "created", "id": "snapdelete0"}} 2565# <- {"event": "JOB_STATUS_CHANGE", 2566# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 2567# "data": {"status": "running", "id": "snapdelete0"}} 2568# <- {"event": "JOB_STATUS_CHANGE", 2569# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 2570# "data": {"status": "waiting", "id": "snapdelete0"}} 2571# <- {"event": "JOB_STATUS_CHANGE", 2572# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 2573# "data": {"status": "pending", "id": "snapdelete0"}} 2574# <- {"event": "JOB_STATUS_CHANGE", 2575# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 2576# "data": {"status": "concluded", "id": "snapdelete0"}} 2577# -> {"execute": "query-jobs"} 2578# <- {"return": [{"current-progress": 1, 2579# "status": "concluded", 2580# "total-progress": 1, 2581# "type": "snapshot-delete", 2582# "id": "snapdelete0"}]} 2583# 2584# Since: 6.0 2585## 2586{ 'command': 'snapshot-delete', 2587 'data': { 'job-id': 'str', 2588 'tag': 'str', 2589 'devices': ['str'] } } 2590