##
{ 'include': 'common.json' }
+{ 'include': 'sockets.json' }
##
# @MigrationStats:
# @page-size: The number of bytes per page for the various page-based
# statistics (since 2.10)
#
+# @multifd-bytes: The number of bytes sent through multifd (since 3.0)
+#
+# @pages-per-second: the number of memory pages transferred per second
+# (Since 4.0)
+#
# Since: 0.14.0
##
{ 'struct': 'MigrationStats',
'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
'mbps' : 'number', 'dirty-sync-count' : 'int',
- 'postcopy-requests' : 'int', 'page-size' : 'int' } }
+ 'postcopy-requests' : 'int', 'page-size' : 'int',
+ 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64' } }
##
# @XBZRLECacheStats:
'cache-miss': 'int', 'cache-miss-rate': 'number',
'overflow': 'int' } }
+##
+# @CompressionStats:
+#
+# Detailed migration compression statistics
+#
+# @pages: amount of pages compressed and transferred to the target VM
+#
+# @busy: count of times that no free thread was available to compress data
+#
+# @busy-rate: rate of thread busy
+#
+# @compressed-size: amount of bytes after compression
+#
+# @compression-rate: rate of compressed size
+#
+# Since: 3.1
+##
+{ 'struct': 'CompressionStats',
+ 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number',
+ 'compressed-size': 'int', 'compression-rate': 'number' } }
+
##
# @MigrationStatus:
#
#
# @postcopy-active: like active, but now in postcopy mode. (since 2.5)
#
+# @postcopy-paused: during postcopy but paused. (since 3.0)
+#
+# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0)
+#
# @completed: migration is finished.
#
# @failed: some error occurred during migration process.
##
{ 'enum': 'MigrationStatus',
'data': [ 'none', 'setup', 'cancelling', 'cancelled',
- 'active', 'postcopy-active', 'completed', 'failed', 'colo',
+ 'active', 'postcopy-active', 'postcopy-paused',
+ 'postcopy-recover', 'completed', 'failed', 'colo',
'pre-switchover', 'device' ] }
##
# @status is 'failed'. Clients should not attempt to parse the
# error strings. (Since 2.7)
#
+# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
+# live migration. This is only present when the postcopy-blocktime
+# migration capability is enabled. (Since 3.0)
+#
+# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
+# only present when the postcopy-blocktime migration capability
+# is enabled. (Since 3.0)
+#
+# @compression: migration compression statistics, only returned if compression
+# feature is on and status is 'active' or 'completed' (Since 3.1)
+#
+# @socket-address: Only used for tcp, to know what the real port is (Since 4.0)
+#
# Since: 0.14.0
##
{ 'struct': 'MigrationInfo',
'*downtime': 'int',
'*setup-time': 'int',
'*cpu-throttle-percentage': 'int',
- '*error-desc': 'str'} }
+ '*error-desc': 'str',
+ '*postcopy-blocktime' : 'uint32',
+ '*postcopy-vcpu-blocktime': ['uint32'],
+ '*compression': 'CompressionStats',
+ '*socket-address': ['SocketAddress'] } }
##
# @query-migrate:
# -> { "execute": "query-migrate" }
# <- { "return": {
# "status": "completed",
+# "total-time":12345,
+# "setup-time":12345,
+# "downtime":12345,
# "ram":{
# "transferred":123,
# "remaining":123,
# "total":246,
-# "total-time":12345,
-# "setup-time":12345,
-# "downtime":12345,
# "duplicate":123,
# "normal":123,
# "normal-bytes":123456,
# <- {
# "return":{
# "status":"active",
+# "total-time":12345,
+# "setup-time":12345,
+# "expected-downtime":12345,
# "ram":{
# "transferred":123,
# "remaining":123,
# "total":246,
-# "total-time":12345,
-# "setup-time":12345,
-# "expected-downtime":12345,
# "duplicate":123,
# "normal":123,
# "normal-bytes":123456,
# <- {
# "return":{
# "status":"active",
+# "total-time":12345,
+# "setup-time":12345,
+# "expected-downtime":12345,
# "ram":{
# "total":1057024,
# "remaining":1053304,
# "transferred":3720,
-# "total-time":12345,
-# "setup-time":12345,
-# "expected-downtime":12345,
# "duplicate":123,
# "normal":123,
# "normal-bytes":123456,
# <- {
# "return":{
# "status":"active",
-# "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
+# "total-time":12345,
+# "setup-time":12345,
+# "expected-downtime":12345,
# "ram":{
# "total":1057024,
# "remaining":1053304,
# "transferred":3720,
-# "total-time":12345,
-# "setup-time":12345,
-# "expected-downtime":12345,
# "duplicate":10,
# "normal":3333,
# "normal-bytes":3412992,
# to speed up convergence of RAM migration. (since 1.6)
#
# @postcopy-ram: Start executing on the migration target before all of RAM has
-# been migrated, pulling the remaining pages along as needed. NOTE: If
-# the migration fails during postcopy the VM will fail. (since 2.6)
+# been migrated, pulling the remaining pages along as needed. The
+# capacity must have the same setting on both source and target
+# or migration will not even start. NOTE: If the migration fails during
+# postcopy the VM will fail. (since 2.6)
#
# @x-colo: If enabled, migration will never end, and the state of the VM on the
# primary side will be migrated continuously to the VM on secondary
#
# @x-multifd: Use more than one fd for migration (since 2.11)
#
+# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps.
+# (since 2.12)
+#
+# @postcopy-blocktime: Calculate downtime for postcopy live migration
+# (since 3.0)
+#
+# @late-block-activate: If enabled, the destination will not activate block
+# devices (and thus take locks) immediately at the end of migration.
+# (since 3.0)
+#
+# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0)
+#
# Since: 1.2
##
{ 'enum': 'MigrationCapability',
'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram',
- 'block', 'return-path', 'pause-before-switchover', 'x-multifd' ] }
+ 'block', 'return-path', 'pause-before-switchover', 'x-multifd',
+ 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate',
+ 'x-ignore-shared' ] }
##
# @MigrationCapabilityStatus:
#
# Migration parameters enumeration
#
+# @announce-initial: Initial delay (in milliseconds) before sending the first
+# announce (Since 4.0)
+#
+# @announce-max: Maximum delay (in milliseconds) between packets in the
+# announcement (Since 4.0)
+#
+# @announce-rounds: Number of self-announce packets sent after migration
+# (Since 4.0)
+#
+# @announce-step: Increase in delay (in milliseconds) between subsequent
+# packets in the announcement (Since 4.0)
+#
# @compress-level: Set the compression level to be used in live migration,
# the compression level is an integer between 0 and 9, where 0 means
# no compression, 1 means the best compression speed, and 9 means best
# @compress-threads: Set compression thread count to be used in live migration,
# the compression thread count is an integer between 1 and 255.
#
+# @compress-wait-thread: Controls behavior when all compression threads are
+# currently busy. If true (default), wait for a free
+# compression thread to become available; otherwise,
+# send the page uncompressed. (Since 3.1)
+#
# @decompress-threads: Set decompression thread count to be used in live
# migration, the decompression thread count is an integer between 1
# and 255. Usually, decompression is at least 4 times as fast as
# and a power of 2
# (Since 2.11)
#
+# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
+# Defaults to 0 (unlimited). In bytes per second.
+# (Since 3.0)
+#
+# @max-cpu-throttle: maximum cpu throttle percentage.
+# Defaults to 99. (Since 3.1)
+#
# Since: 2.4
##
{ 'enum': 'MigrationParameter',
- 'data': ['compress-level', 'compress-threads', 'decompress-threads',
+ 'data': ['announce-initial', 'announce-max',
+ 'announce-rounds', 'announce-step',
+ 'compress-level', 'compress-threads', 'decompress-threads',
+ 'compress-wait-thread',
'cpu-throttle-initial', 'cpu-throttle-increment',
'tls-creds', 'tls-hostname', 'max-bandwidth',
'downtime-limit', 'x-checkpoint-delay', 'block-incremental',
'x-multifd-channels', 'x-multifd-page-count',
- 'xbzrle-cache-size' ] }
+ 'xbzrle-cache-size', 'max-postcopy-bandwidth',
+ 'max-cpu-throttle' ] }
##
# @MigrateSetParameters:
#
+# @announce-initial: Initial delay (in milliseconds) before sending the first
+# announce (Since 4.0)
+#
+# @announce-max: Maximum delay (in milliseconds) between packets in the
+# announcement (Since 4.0)
+#
+# @announce-rounds: Number of self-announce packets sent after migration
+# (Since 4.0)
+#
+# @announce-step: Increase in delay (in milliseconds) between subsequent
+# packets in the announcement (Since 4.0)
+#
# @compress-level: compression level
#
# @compress-threads: compression thread count
#
+# @compress-wait-thread: Controls behavior when all compression threads are
+# currently busy. If true (default), wait for a free
+# compression thread to become available; otherwise,
+# send the page uncompressed. (Since 3.1)
+#
# @decompress-threads: decompression thread count
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
# needs to be a multiple of the target page size
# and a power of 2
# (Since 2.11)
+#
+# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
+# Defaults to 0 (unlimited). In bytes per second.
+# (Since 3.0)
+#
+# @max-cpu-throttle: maximum cpu throttle percentage.
+# The default value is 99. (Since 3.1)
+#
# Since: 2.4
##
# TODO either fuse back into MigrationParameters, or make
# MigrationParameters members mandatory
{ 'struct': 'MigrateSetParameters',
- 'data': { '*compress-level': 'int',
+ 'data': { '*announce-initial': 'size',
+ '*announce-max': 'size',
+ '*announce-rounds': 'size',
+ '*announce-step': 'size',
+ '*compress-level': 'int',
'*compress-threads': 'int',
+ '*compress-wait-thread': 'bool',
'*decompress-threads': 'int',
'*cpu-throttle-initial': 'int',
'*cpu-throttle-increment': 'int',
'*block-incremental': 'bool',
'*x-multifd-channels': 'int',
'*x-multifd-page-count': 'int',
- '*xbzrle-cache-size': 'size' } }
+ '*xbzrle-cache-size': 'size',
+ '*max-postcopy-bandwidth': 'size',
+ '*max-cpu-throttle': 'int' } }
##
# @migrate-set-parameters:
#
# The optional members aren't actually optional.
#
+# @announce-initial: Initial delay (in milliseconds) before sending the
+# first announce (Since 4.0)
+#
+# @announce-max: Maximum delay (in milliseconds) between packets in the
+# announcement (Since 4.0)
+#
+# @announce-rounds: Number of self-announce packets sent after migration
+# (Since 4.0)
+#
+# @announce-step: Increase in delay (in milliseconds) between subsequent
+# packets in the announcement (Since 4.0)
+#
# @compress-level: compression level
#
# @compress-threads: compression thread count
#
+# @compress-wait-thread: Controls behavior when all compression threads are
+# currently busy. If true (default), wait for a free
+# compression thread to become available; otherwise,
+# send the page uncompressed. (Since 3.1)
+#
# @decompress-threads: decompression thread count
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
# needs to be a multiple of the target page size
# and a power of 2
# (Since 2.11)
+#
+# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
+# Defaults to 0 (unlimited). In bytes per second.
+# (Since 3.0)
+#
+# @max-cpu-throttle: maximum cpu throttle percentage.
+# Defaults to 99.
+# (Since 3.1)
+#
# Since: 2.4
##
{ 'struct': 'MigrationParameters',
- 'data': { '*compress-level': 'uint8',
+ 'data': { '*announce-initial': 'size',
+ '*announce-max': 'size',
+ '*announce-rounds': 'size',
+ '*announce-step': 'size',
+ '*compress-level': 'uint8',
'*compress-threads': 'uint8',
+ '*compress-wait-thread': 'bool',
'*decompress-threads': 'uint8',
'*cpu-throttle-initial': 'uint8',
'*cpu-throttle-increment': 'uint8',
'*block-incremental': 'bool' ,
'*x-multifd-channels': 'uint8',
'*x-multifd-page-count': 'uint32',
- '*xbzrle-cache-size': 'size' } }
+ '*xbzrle-cache-size': 'size',
+ '*max-postcopy-bandwidth': 'size',
+ '*max-cpu-throttle':'uint8'} }
##
# @query-migrate-parameters:
# @migrate-start-postcopy:
#
# Followup to a migration command to switch the migration to postcopy mode.
-# The postcopy-ram capability must be set before the original migration
-# command.
+# The postcopy-ram capability must be set on both source and destination
+# before the original migration command.
#
# Since: 2.5
#
##
# @COLOMode:
#
-# The colo mode
+# The COLO current mode.
#
-# @unknown: unknown mode
+# @none: COLO is disabled.
#
-# @primary: master side
+# @primary: COLO node in primary side.
#
-# @secondary: slave side
+# @secondary: COLO node in slave side.
#
# Since: 2.8
##
{ 'enum': 'COLOMode',
- 'data': [ 'unknown', 'primary', 'secondary'] }
+ 'data': [ 'none', 'primary', 'secondary'] }
##
# @FailoverStatus:
{ 'enum': 'FailoverStatus',
'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
+##
+# @COLO_EXIT:
+#
+# Emitted when VM finishes COLO mode due to some errors happening or
+# at the request of users.
+#
+# @mode: report COLO mode when COLO exited.
+#
+# @reason: describes the reason for the COLO exit.
+#
+# Since: 3.1
+#
+# Example:
+#
+# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
+# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
+#
+##
+{ 'event': 'COLO_EXIT',
+ 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
+
+##
+# @COLOExitReason:
+#
+# The reason for a COLO exit
+#
+# @none: no failover has ever happened. This can't occur in the
+# COLO_EXIT event, only in the result of query-colo-status.
+#
+# @request: COLO exit is due to an external request
+#
+# @error: COLO exit is due to an internal error
+#
+# Since: 3.1
+##
+{ 'enum': 'COLOExitReason',
+ 'data': [ 'none', 'request', 'error' ] }
+
##
# @x-colo-lost-heartbeat:
#
# @detach: this argument exists only for compatibility reasons and
# is ignored by QEMU
#
+# @resume: resume one paused migration, default "off". (since 3.0)
+#
# Returns: nothing on success
#
# Since: 0.14.0
#
##
{ 'command': 'migrate',
- 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
+ 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
+ '*detach': 'bool', '*resume': 'bool' } }
##
# @migrate-incoming:
# Since: 2.9
##
{ 'command': 'xen-set-replication',
- 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' } }
+ 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' },
+ 'if': 'defined(CONFIG_REPLICATION)' }
##
# @ReplicationStatus:
# Since: 2.9
##
{ 'struct': 'ReplicationStatus',
- 'data': { 'error': 'bool', '*desc': 'str' } }
+ 'data': { 'error': 'bool', '*desc': 'str' },
+ 'if': 'defined(CONFIG_REPLICATION)' }
##
# @query-xen-replication-status:
# Since: 2.9
##
{ 'command': 'query-xen-replication-status',
- 'returns': 'ReplicationStatus' }
+ 'returns': 'ReplicationStatus',
+ 'if': 'defined(CONFIG_REPLICATION)' }
##
# @xen-colo-do-checkpoint:
#
# Since: 2.9
##
-{ 'command': 'xen-colo-do-checkpoint' }
+{ 'command': 'xen-colo-do-checkpoint',
+ 'if': 'defined(CONFIG_REPLICATION)' }
+
+##
+# @COLOStatus:
+#
+# The result format for 'query-colo-status'.
+#
+# @mode: COLO running mode. If COLO is running, this field will return
+# 'primary' or 'secondary'.
+#
+# @reason: describes the reason for the COLO exit.
+#
+# Since: 3.1
+##
+{ 'struct': 'COLOStatus',
+ 'data': { 'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
+
+##
+# @query-colo-status:
+#
+# Query COLO status while the vm is running.
+#
+# Returns: A @COLOStatus object showing the status.
+#
+# Example:
+#
+# -> { "execute": "query-colo-status" }
+# <- { "return": { "mode": "primary", "reason": "request" } }
+#
+# Since: 3.1
+##
+{ 'command': 'query-colo-status',
+ 'returns': 'COLOStatus' }
+
+##
+# @migrate-recover:
+#
+# Provide a recovery migration stream URI.
+#
+# @uri: the URI to be used for the recovery of migration stream.
+#
+# Returns: nothing.
+#
+# Example:
+#
+# -> { "execute": "migrate-recover",
+# "arguments": { "uri": "tcp:192.168.1.200:12345" } }
+# <- { "return": {} }
+#
+# Since: 3.0
+##
+{ 'command': 'migrate-recover',
+ 'data': { 'uri': 'str' },
+ 'allow-oob': true }
+
+##
+# @migrate-pause:
+#
+# Pause a migration. Currently it only supports postcopy.
+#
+# Returns: nothing.
+#
+# Example:
+#
+# -> { "execute": "migrate-pause" }
+# <- { "return": {} }
+#
+# Since: 3.0
+##
+{ 'command': 'migrate-pause', 'allow-oob': true }
projects / qemu.git / blobdiff