# average memory load of the virtual CPU indirectly. Note that
# zero means guest doesn't dirty memory. (Since 8.1)
#
+# Features:
+#
+# @deprecated: Member @disk is deprecated because block migration is.
+# Member @compression is deprecated because it is unreliable and
+# untested. It is recommended to use multifd migration, which
+# offers an alternative compression implementation that is
+# reliable and tested.
+#
# Since: 0.14
##
{ 'struct': 'MigrationInfo',
'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
- '*disk': 'MigrationStats',
+ '*disk': { 'type': 'MigrationStats', 'features': [ 'deprecated' ] },
'*vfio': 'VfioStats',
'*xbzrle-cache': 'XBZRLECacheStats',
'*total-time': 'int',
'*blocked-reasons': ['str'],
'*postcopy-blocktime': 'uint32',
'*postcopy-vcpu-blocktime': ['uint32'],
- '*compression': 'CompressionStats',
+ '*compression': { 'type': 'CompressionStats', 'features': [ 'deprecated' ] },
'*socket-address': ['SocketAddress'],
'*dirty-limit-throttle-time-per-round': 'uint64',
'*dirty-limit-ring-full-time': 'uint64'} }
#
# Features:
#
+# @deprecated: Member @block is deprecated. Use blockdev-mirror with
+# NBD instead. Member @compression is deprecated because it is
+# unreliable and untested. It is recommended to use multifd
+# migration, which offers an alternative compression
+# implementation that is reliable and tested.
+#
# @unstable: Members @x-colo and @x-ignore-shared are experimental.
#
# Since: 1.2
##
{ 'enum': 'MigrationCapability',
'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
- 'compress', 'events', 'postcopy-ram',
+ { 'name': 'compress', 'features': [ 'deprecated' ] },
+ 'events', 'postcopy-ram',
{ 'name': 'x-colo', 'features': [ 'unstable' ] },
'release-ram',
- 'block', 'return-path', 'pause-before-switchover', 'multifd',
+ { 'name': 'block', 'features': [ 'deprecated' ] },
+ 'return-path', 'pause-before-switchover', 'multifd',
'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate',
{ 'name': 'x-ignore-shared', 'features': [ 'unstable' ] },
'validate-uuid', 'background-snapshot',
'data': [ 'none', 'zlib',
{ 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] }
+##
+# @MigMode:
+#
+# @normal: the original form of migration. (since 8.2)
+#
+# @cpr-reboot: The migrate command saves state to a file, allowing one to
+# quit qemu, reboot to an updated kernel, and restart an updated
+# version of qemu. The caller must specify a migration URI
+# that writes to and reads from a file. Unlike normal mode,
+# the use of certain local storage options does not block the
+# migration, but the caller must not modify guest block devices
+# between the quit and restart. To avoid saving guest RAM to the
+# file, the memory backend must be shared, and the @x-ignore-shared
+# migration capability must be set. Guest RAM must be non-volatile
+# across reboot, such as by backing it with a dax device, but this
+# is not enforced. The restarted qemu arguments must match those
+# used to initially start qemu, plus the -incoming option.
+# (since 8.2)
+##
+{ 'enum': 'MigMode',
+ 'data': [ 'normal', 'cpr-reboot' ] }
+
##
# @BitmapMigrationBitmapAliasTransform:
#
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
+# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
+# (Since 8.2)
+#
# Features:
#
+# @deprecated: Member @block-incremental is deprecated. Use
+# blockdev-mirror with NBD instead. Members @compress-level,
+# @compress-threads, @decompress-threads and @compress-wait-thread
+# are deprecated because @compression is deprecated.
+#
# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
# are experimental.
#
{ 'enum': 'MigrationParameter',
'data': ['announce-initial', 'announce-max',
'announce-rounds', 'announce-step',
- 'compress-level', 'compress-threads', 'decompress-threads',
- 'compress-wait-thread', 'throttle-trigger-threshold',
+ { 'name': 'compress-level', 'features': [ 'deprecated' ] },
+ { 'name': 'compress-threads', 'features': [ 'deprecated' ] },
+ { 'name': 'decompress-threads', 'features': [ 'deprecated' ] },
+ { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] },
+ 'throttle-trigger-threshold',
'cpu-throttle-initial', 'cpu-throttle-increment',
'cpu-throttle-tailslow',
'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
'avail-switchover-bandwidth', 'downtime-limit',
{ 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] },
- 'block-incremental',
+ { 'name': 'block-incremental', 'features': [ 'deprecated' ] },
'multifd-channels',
'xbzrle-cache-size', 'max-postcopy-bandwidth',
'max-cpu-throttle', 'multifd-compression',
'multifd-zlib-level', 'multifd-zstd-level',
'block-bitmap-mapping',
{ 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] },
- 'vcpu-dirty-limit'] }
+ 'vcpu-dirty-limit',
+ 'mode'] }
##
# @MigrateSetParameters:
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
+# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
+# (Since 8.2)
+#
# Features:
#
+# @deprecated: Member @block-incremental is deprecated. Use
+# blockdev-mirror with NBD instead. Members @compress-level,
+# @compress-threads, @decompress-threads and @compress-wait-thread
+# are deprecated because @compression is deprecated.
+#
# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
# are experimental.
#
'*announce-max': 'size',
'*announce-rounds': 'size',
'*announce-step': 'size',
- '*compress-level': 'uint8',
- '*compress-threads': 'uint8',
- '*compress-wait-thread': 'bool',
- '*decompress-threads': 'uint8',
+ '*compress-level': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
+ '*compress-threads': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
+ '*compress-wait-thread': { 'type': 'bool',
+ 'features': [ 'deprecated' ] },
+ '*decompress-threads': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
'*throttle-trigger-threshold': 'uint8',
'*cpu-throttle-initial': 'uint8',
'*cpu-throttle-increment': 'uint8',
'*downtime-limit': 'uint64',
'*x-checkpoint-delay': { 'type': 'uint32',
'features': [ 'unstable' ] },
- '*block-incremental': 'bool',
+ '*block-incremental': { 'type': 'bool',
+ 'features': [ 'deprecated' ] },
'*multifd-channels': 'uint8',
'*xbzrle-cache-size': 'size',
'*max-postcopy-bandwidth': 'size',
'*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ],
'*x-vcpu-dirty-limit-period': { 'type': 'uint64',
'features': [ 'unstable' ] },
- '*vcpu-dirty-limit': 'uint64'} }
+ '*vcpu-dirty-limit': 'uint64',
+ '*mode': 'MigMode'} }
##
# @migrate-set-parameters:
# Example:
#
# -> { "execute": "migrate-set-parameters" ,
-# "arguments": { "compress-level": 1 } }
+# "arguments": { "multifd-channels": 5 } }
# <- { "return": {} }
##
{ 'command': 'migrate-set-parameters', 'boxed': true,
# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
# Defaults to 1. (Since 8.1)
#
+# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
+# (Since 8.2)
+#
# Features:
#
+# @deprecated: Member @block-incremental is deprecated. Use
+# blockdev-mirror with NBD instead. Members @compress-level,
+# @compress-threads, @decompress-threads and @compress-wait-thread
+# are deprecated because @compression is deprecated.
+#
# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
# are experimental.
#
'*announce-max': 'size',
'*announce-rounds': 'size',
'*announce-step': 'size',
- '*compress-level': 'uint8',
- '*compress-threads': 'uint8',
- '*compress-wait-thread': 'bool',
- '*decompress-threads': 'uint8',
+ '*compress-level': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
+ '*compress-threads': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
+ '*compress-wait-thread': { 'type': 'bool',
+ 'features': [ 'deprecated' ] },
+ '*decompress-threads': { 'type': 'uint8',
+ 'features': [ 'deprecated' ] },
'*throttle-trigger-threshold': 'uint8',
'*cpu-throttle-initial': 'uint8',
'*cpu-throttle-increment': 'uint8',
'*downtime-limit': 'uint64',
'*x-checkpoint-delay': { 'type': 'uint32',
'features': [ 'unstable' ] },
- '*block-incremental': 'bool',
+ '*block-incremental': { 'type': 'bool',
+ 'features': [ 'deprecated' ] },
'*multifd-channels': 'uint8',
'*xbzrle-cache-size': 'size',
'*max-postcopy-bandwidth': 'size',
'*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ],
'*x-vcpu-dirty-limit-period': { 'type': 'uint64',
'features': [ 'unstable' ] },
- '*vcpu-dirty-limit': 'uint64'} }
+ '*vcpu-dirty-limit': 'uint64',
+ '*mode': 'MigMode'} }
##
# @query-migrate-parameters:
#
# -> { "execute": "query-migrate-parameters" }
# <- { "return": {
-# "decompress-threads": 2,
+# "multifd-channels": 2,
# "cpu-throttle-increment": 10,
-# "compress-threads": 8,
-# "compress-level": 1,
# "cpu-throttle-initial": 20,
# "max-bandwidth": 33554432,
# "downtime-limit": 300
##
{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
+##
+# @MigrationAddressType:
+#
+# The migration stream transport mechanisms.
+#
+# @socket: Migrate via socket.
+#
+# @exec: Direct the migration stream to another process.
+#
+# @rdma: Migrate via RDMA.
+#
+# @file: Direct the migration stream to a file.
+#
+# Since 8.2
+##
+{ 'enum': 'MigrationAddressType',
+ 'data': [ 'socket', 'exec', 'rdma', 'file' ] }
+
+##
+# @FileMigrationArgs:
+#
+# @filename: The file to receive the migration stream
+#
+# @offset: The file offset where the migration stream will start
+#
+# Since 8.2
+##
+{ 'struct': 'FileMigrationArgs',
+ 'data': { 'filename': 'str',
+ 'offset': 'uint64' } }
+
+##
+# @MigrationExecCommand:
+#
+# @args: command (list head) and arguments to execute.
+#
+# Since 8.2
+##
+{ 'struct': 'MigrationExecCommand',
+ 'data': {'args': [ 'str' ] } }
+
+##
+# @MigrationAddress:
+#
+# Migration endpoint configuration.
+#
+# Since 8.2
+##
+{ 'union': 'MigrationAddress',
+ 'base': { 'transport' : 'MigrationAddressType'},
+ 'discriminator': 'transport',
+ 'data': {
+ 'socket': 'SocketAddress',
+ 'exec': 'MigrationExecCommand',
+ 'rdma': 'InetSocketAddress',
+ 'file': 'FileMigrationArgs' } }
+
+##
+# @MigrationChannelType:
+#
+# The migration channel-type request options.
+#
+# @main: Main outbound migration channel.
+#
+# Since 8.1
+##
+{ 'enum': 'MigrationChannelType',
+ 'data': [ 'main' ] }
+
+##
+# @MigrationChannel:
+#
+# Migration stream channel parameters.
+#
+# @channel-type: Channel type for transferring packet information.
+#
+# @addr: Migration endpoint configuration on destination interface.
+#
+# Since 8.1
+##
+{ 'struct': 'MigrationChannel',
+ 'data': {
+ 'channel-type': 'MigrationChannelType',
+ 'addr': 'MigrationAddress' } }
+
##
# @migrate:
#
#
# @uri: the Uniform Resource Identifier of the destination VM
#
+# @channels: list of migration stream channels with each stream in the
+# list connected to a destination interface endpoint.
+#
# @blk: do block migration (full disk copy)
#
# @inc: incremental disk copy migration
#
# @resume: resume one paused migration, default "off". (since 3.0)
#
+# Features:
+#
+# @deprecated: Members @inc and @blk are deprecated. Use
+# blockdev-mirror with NBD instead.
+#
# Returns: nothing on success
#
# Since: 0.14
# 3. The user Monitor's "detach" argument is invalid in QMP and should
# not be used
#
+# 4. The uri argument should have the Uniform Resource Identifier of
+# default destination VM. This connection will be bound to default
+# network.
+#
+# 5. For now, number of migration streams is restricted to one, i.e
+# number of items in 'channels' list is just 1.
+#
+# 6. The 'uri' and 'channels' arguments are mutually exclusive;
+# exactly one of the two should be present.
+#
# Example:
#
# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
# <- { "return": {} }
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "socket",
+# "type": "inet",
+# "host": "10.12.34.9",
+# "port": "1050" } } ] } }
+# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "exec",
+# "args": [ "/bin/nc", "-p", "6000",
+# "/some/sock" ] } } ] } }
+# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "rdma",
+# "host": "10.12.34.9",
+# "port": "1050" } } ] } }
+# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "file",
+# "filename": "/tmp/migfile",
+# "offset": "0x1000" } } ] } }
+# <- { "return": {} }
+#
##
{ 'command': 'migrate',
- 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
+ 'data': {'uri': 'str',
+ '*channels': [ 'MigrationChannel' ],
+ '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] },
+ '*inc': { 'type': 'bool', 'features': [ 'deprecated' ] },
'*detach': 'bool', '*resume': 'bool' } }
##
# @uri: The Uniform Resource Identifier identifying the source or
# address to listen on
#
+# @channels: list of migration stream channels with each stream in the
+# list connected to a destination interface endpoint.
+#
# Returns: nothing on success
#
# Since: 2.3
#
# 3. The uri format is the same as for -incoming
#
+# 5. For now, number of migration streams is restricted to one, i.e
+# number of items in 'channels' list is just 1.
+#
+# 4. The 'uri' and 'channels' arguments are mutually exclusive;
+# exactly one of the two should be present.
+#
# Example:
#
# -> { "execute": "migrate-incoming",
# "arguments": { "uri": "tcp::4446" } }
# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "socket",
+# "type": "inet",
+# "host": "10.12.34.9",
+# "port": "1050" } } ] } }
+# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "exec",
+# "args": [ "/bin/nc", "-p", "6000",
+# "/some/sock" ] } } ] } }
+# <- { "return": {} }
+#
+# -> { "execute": "migrate",
+# "arguments": {
+# "channels": [ { "channel-type": "main",
+# "addr": { "transport": "rdma",
+# "host": "10.12.34.9",
+# "port": "1050" } } ] } }
+# <- { "return": {} }
##
-{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
+{ 'command': 'migrate-incoming',
+ 'data': {'*uri': 'str',
+ '*channels': [ 'MigrationChannel' ] } }
##
# @xen-save-devices-state: