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