blob: a5da513c9e05bea7a2f9080426c8f3f9b75a4688 [file] [log] [blame]
Markus Armbruster48685a82017-08-24 21:14:01 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Markus Armbruster48685a82017-08-24 21:14:01 +02003#
4
5##
6# = Migration
7##
8
9{ 'include': 'common.json' }
Juan Quintela9aca82b2019-02-27 11:51:27 +010010{ 'include': 'sockets.json' }
Markus Armbruster48685a82017-08-24 21:14:01 +020011
12##
13# @MigrationStats:
14#
15# Detailed migration status.
16#
17# @transferred: amount of bytes already transferred to the target VM
18#
19# @remaining: amount of bytes remaining to be transferred to the target VM
20#
21# @total: total amount of bytes involved in the migration process
22#
23# @duplicate: number of duplicate (zero) pages (since 1.2)
24#
25# @skipped: number of skipped zero pages (since 1.5)
26#
27# @normal: number of normal pages (since 1.2)
28#
29# @normal-bytes: number of normal bytes sent (since 1.2)
30#
31# @dirty-pages-rate: number of pages dirtied by second by the
Peter Maydell26ec4e52020-02-13 17:56:26 +000032# guest (since 1.3)
Markus Armbruster48685a82017-08-24 21:14:01 +020033#
34# @mbps: throughput in megabits/sec. (since 1.6)
35#
36# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
37#
38# @postcopy-requests: The number of page requests received from the destination
Peter Maydell26ec4e52020-02-13 17:56:26 +000039# (since 2.7)
Markus Armbruster48685a82017-08-24 21:14:01 +020040#
41# @page-size: The number of bytes per page for the various page-based
Peter Maydell26ec4e52020-02-13 17:56:26 +000042# statistics (since 2.10)
Markus Armbruster48685a82017-08-24 21:14:01 +020043#
Juan Quintelaa61c45b2018-06-26 15:20:11 +020044# @multifd-bytes: The number of bytes sent through multifd (since 3.0)
45#
Xiao Guangrongaecbfe92019-01-11 14:37:30 +080046# @pages-per-second: the number of memory pages transferred per second
Peter Maydell26ec4e52020-02-13 17:56:26 +000047# (Since 4.0)
Xiao Guangrongaecbfe92019-01-11 14:37:30 +080048#
Markus Armbruster48685a82017-08-24 21:14:01 +020049# Since: 0.14.0
50##
51{ 'struct': 'MigrationStats',
52 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
53 'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
54 'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
55 'mbps' : 'number', 'dirty-sync-count' : 'int',
Juan Quintelaa61c45b2018-06-26 15:20:11 +020056 'postcopy-requests' : 'int', 'page-size' : 'int',
Xiao Guangrongaecbfe92019-01-11 14:37:30 +080057 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64' } }
Markus Armbruster48685a82017-08-24 21:14:01 +020058
59##
60# @XBZRLECacheStats:
61#
62# Detailed XBZRLE migration cache statistics
63#
64# @cache-size: XBZRLE cache size
65#
66# @bytes: amount of bytes already transferred to the target VM
67#
68# @pages: amount of pages transferred to the target VM
69#
70# @cache-miss: number of cache miss
71#
72# @cache-miss-rate: rate of cache miss (since 2.1)
73#
Wei Wange460a4b2020-04-30 08:59:35 +080074# @encoding-rate: rate of encoded bytes (since 5.1)
75#
Markus Armbruster48685a82017-08-24 21:14:01 +020076# @overflow: number of overflows
77#
78# Since: 1.2
79##
80{ 'struct': 'XBZRLECacheStats',
81 'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
82 'cache-miss': 'int', 'cache-miss-rate': 'number',
Wei Wange460a4b2020-04-30 08:59:35 +080083 'encoding-rate': 'number', 'overflow': 'int' } }
Markus Armbruster48685a82017-08-24 21:14:01 +020084
85##
Xiao Guangrong76e03002018-09-06 15:01:00 +080086# @CompressionStats:
87#
88# Detailed migration compression statistics
89#
90# @pages: amount of pages compressed and transferred to the target VM
91#
92# @busy: count of times that no free thread was available to compress data
93#
94# @busy-rate: rate of thread busy
95#
96# @compressed-size: amount of bytes after compression
97#
98# @compression-rate: rate of compressed size
99#
100# Since: 3.1
101##
102{ 'struct': 'CompressionStats',
103 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number',
Peter Maydelldbb28bc2020-02-13 17:56:27 +0000104 'compressed-size': 'int', 'compression-rate': 'number' } }
Xiao Guangrong76e03002018-09-06 15:01:00 +0800105
106##
Markus Armbruster48685a82017-08-24 21:14:01 +0200107# @MigrationStatus:
108#
109# An enumeration of migration status.
110#
111# @none: no migration has ever happened.
112#
113# @setup: migration process has been initiated.
114#
115# @cancelling: in the process of cancelling migration.
116#
117# @cancelled: cancelling migration is finished.
118#
119# @active: in the process of doing migration.
120#
121# @postcopy-active: like active, but now in postcopy mode. (since 2.5)
122#
Peter Maydell51f63ec2018-05-22 11:39:56 +0100123# @postcopy-paused: during postcopy but paused. (since 3.0)
Peter Xua688d2c2018-05-02 18:47:18 +0800124#
Peter Maydell51f63ec2018-05-22 11:39:56 +0100125# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0)
Peter Xu135b87b2018-05-02 18:47:25 +0800126#
Markus Armbruster48685a82017-08-24 21:14:01 +0200127# @completed: migration is finished.
128#
129# @failed: some error occurred during migration process.
130#
131# @colo: VM is in the process of fault tolerance, VM can not get into this
132# state unless colo capability is enabled for migration. (since 2.8)
133#
Dr. David Alan Gilbert31e06072017-10-20 10:05:51 +0100134# @pre-switchover: Paused before device serialisation. (since 2.11)
135#
136# @device: During device serialisation when pause-before-switchover is enabled
Peter Maydell26ec4e52020-02-13 17:56:26 +0000137# (since 2.11)
Dr. David Alan Gilbert31e06072017-10-20 10:05:51 +0100138#
Jens Freimannc7e0acd2019-10-29 12:49:02 +0100139# @wait-unplug: wait for device unplug request by guest OS to be completed.
140# (since 4.2)
141#
Markus Armbruster48685a82017-08-24 21:14:01 +0200142# Since: 2.3
143#
144##
145{ 'enum': 'MigrationStatus',
146 'data': [ 'none', 'setup', 'cancelling', 'cancelled',
Peter Xua688d2c2018-05-02 18:47:18 +0800147 'active', 'postcopy-active', 'postcopy-paused',
Peter Xu135b87b2018-05-02 18:47:25 +0800148 'postcopy-recover', 'completed', 'failed', 'colo',
Jens Freimannc7e0acd2019-10-29 12:49:02 +0100149 'pre-switchover', 'device', 'wait-unplug' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +0200150
151##
152# @MigrationInfo:
153#
154# Information about current migration process.
155#
156# @status: @MigrationStatus describing the current migration status.
157# If this field is not returned, no migration process
158# has been initiated
159#
160# @ram: @MigrationStats containing detailed migration
161# status, only returned if status is 'active' or
162# 'completed'(since 1.2)
163#
164# @disk: @MigrationStats containing detailed disk migration
165# status, only returned if status is 'active' and it is a block
166# migration
167#
168# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
169# migration statistics, only returned if XBZRLE feature is on and
170# status is 'active' or 'completed' (since 1.2)
171#
172# @total-time: total amount of milliseconds since migration started.
Peter Maydell26ec4e52020-02-13 17:56:26 +0000173# If migration has ended, it returns the total migration
174# time. (since 1.2)
Markus Armbruster48685a82017-08-24 21:14:01 +0200175#
176# @downtime: only present when migration finishes correctly
Peter Maydell26ec4e52020-02-13 17:56:26 +0000177# total downtime in milliseconds for the guest.
178# (since 1.3)
Markus Armbruster48685a82017-08-24 21:14:01 +0200179#
180# @expected-downtime: only present while migration is active
Peter Maydell26ec4e52020-02-13 17:56:26 +0000181# expected downtime in milliseconds for the guest in last walk
182# of the dirty bitmap. (since 1.3)
Markus Armbruster48685a82017-08-24 21:14:01 +0200183#
Peter Maydella660eed2020-02-13 17:56:34 +0000184# @setup-time: amount of setup time in milliseconds *before* the
185# iterations begin but *after* the QMP command is issued. This is designed
Peter Maydell26ec4e52020-02-13 17:56:26 +0000186# to provide an accounting of any activities (such as RDMA pinning) which
187# may be expensive, but do not actually occur during the iterative
188# migration rounds themselves. (since 1.6)
Markus Armbruster48685a82017-08-24 21:14:01 +0200189#
190# @cpu-throttle-percentage: percentage of time guest cpus are being
Peter Maydell26ec4e52020-02-13 17:56:26 +0000191# throttled during auto-converge. This is only present when auto-converge
192# has started throttling guest cpus. (Since 2.7)
Markus Armbruster48685a82017-08-24 21:14:01 +0200193#
194# @error-desc: the human readable error description string, when
195# @status is 'failed'. Clients should not attempt to parse the
196# error strings. (Since 2.7)
197#
Alexey Perevalov65ace062018-03-22 21:17:27 +0300198# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
Peter Maydell26ec4e52020-02-13 17:56:26 +0000199# live migration. This is only present when the postcopy-blocktime
200# migration capability is enabled. (Since 3.0)
Alexey Perevalov65ace062018-03-22 21:17:27 +0300201#
Dr. David Alan Gilbert5e50cae2018-04-27 12:15:02 +0100202# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
Peter Maydell26ec4e52020-02-13 17:56:26 +0000203# only present when the postcopy-blocktime migration capability
204# is enabled. (Since 3.0)
Alexey Perevalov65ace062018-03-22 21:17:27 +0300205#
Xiao Guangrong76e03002018-09-06 15:01:00 +0800206# @compression: migration compression statistics, only returned if compression
Peter Maydell26ec4e52020-02-13 17:56:26 +0000207# feature is on and status is 'active' or 'completed' (Since 3.1)
Alexey Perevalov65ace062018-03-22 21:17:27 +0300208#
Juan Quintela9aca82b2019-02-27 11:51:27 +0100209# @socket-address: Only used for tcp, to know what the real port is (Since 4.0)
210#
Markus Armbruster48685a82017-08-24 21:14:01 +0200211# Since: 0.14.0
212##
213{ 'struct': 'MigrationInfo',
214 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
215 '*disk': 'MigrationStats',
216 '*xbzrle-cache': 'XBZRLECacheStats',
217 '*total-time': 'int',
218 '*expected-downtime': 'int',
219 '*downtime': 'int',
220 '*setup-time': 'int',
221 '*cpu-throttle-percentage': 'int',
Alexey Perevalov65ace062018-03-22 21:17:27 +0300222 '*error-desc': 'str',
223 '*postcopy-blocktime' : 'uint32',
Xiao Guangrong76e03002018-09-06 15:01:00 +0800224 '*postcopy-vcpu-blocktime': ['uint32'],
Juan Quintela9aca82b2019-02-27 11:51:27 +0100225 '*compression': 'CompressionStats',
226 '*socket-address': ['SocketAddress'] } }
Markus Armbruster48685a82017-08-24 21:14:01 +0200227
228##
229# @query-migrate:
230#
231# Returns information about current migration process. If migration
232# is active there will be another json-object with RAM migration
233# status and if block migration is active another one with block
234# migration status.
235#
236# Returns: @MigrationInfo
237#
238# Since: 0.14.0
239#
240# Example:
241#
242# 1. Before the first migration
243#
244# -> { "execute": "query-migrate" }
245# <- { "return": {} }
246#
247# 2. Migration is done and has succeeded
248#
249# -> { "execute": "query-migrate" }
250# <- { "return": {
251# "status": "completed",
jialina01be1d2c42018-08-21 20:39:26 +0800252# "total-time":12345,
253# "setup-time":12345,
254# "downtime":12345,
Markus Armbruster48685a82017-08-24 21:14:01 +0200255# "ram":{
256# "transferred":123,
257# "remaining":123,
258# "total":246,
Markus Armbruster48685a82017-08-24 21:14:01 +0200259# "duplicate":123,
260# "normal":123,
261# "normal-bytes":123456,
262# "dirty-sync-count":15
263# }
264# }
265# }
266#
267# 3. Migration is done and has failed
268#
269# -> { "execute": "query-migrate" }
270# <- { "return": { "status": "failed" } }
271#
272# 4. Migration is being performed and is not a block migration:
273#
274# -> { "execute": "query-migrate" }
275# <- {
276# "return":{
277# "status":"active",
jialina01be1d2c42018-08-21 20:39:26 +0800278# "total-time":12345,
279# "setup-time":12345,
280# "expected-downtime":12345,
Markus Armbruster48685a82017-08-24 21:14:01 +0200281# "ram":{
282# "transferred":123,
283# "remaining":123,
284# "total":246,
Markus Armbruster48685a82017-08-24 21:14:01 +0200285# "duplicate":123,
286# "normal":123,
287# "normal-bytes":123456,
288# "dirty-sync-count":15
289# }
290# }
291# }
292#
293# 5. Migration is being performed and is a block migration:
294#
295# -> { "execute": "query-migrate" }
296# <- {
297# "return":{
298# "status":"active",
jialina01be1d2c42018-08-21 20:39:26 +0800299# "total-time":12345,
300# "setup-time":12345,
301# "expected-downtime":12345,
Markus Armbruster48685a82017-08-24 21:14:01 +0200302# "ram":{
303# "total":1057024,
304# "remaining":1053304,
305# "transferred":3720,
Markus Armbruster48685a82017-08-24 21:14:01 +0200306# "duplicate":123,
307# "normal":123,
308# "normal-bytes":123456,
309# "dirty-sync-count":15
310# },
311# "disk":{
312# "total":20971520,
313# "remaining":20880384,
314# "transferred":91136
315# }
316# }
317# }
318#
319# 6. Migration is being performed and XBZRLE is active:
320#
321# -> { "execute": "query-migrate" }
322# <- {
323# "return":{
324# "status":"active",
jialina01be1d2c42018-08-21 20:39:26 +0800325# "total-time":12345,
326# "setup-time":12345,
327# "expected-downtime":12345,
Markus Armbruster48685a82017-08-24 21:14:01 +0200328# "ram":{
329# "total":1057024,
330# "remaining":1053304,
331# "transferred":3720,
Markus Armbruster48685a82017-08-24 21:14:01 +0200332# "duplicate":10,
333# "normal":3333,
334# "normal-bytes":3412992,
335# "dirty-sync-count":15
336# },
337# "xbzrle-cache":{
338# "cache-size":67108864,
339# "bytes":20971520,
340# "pages":2444343,
341# "cache-miss":2244,
342# "cache-miss-rate":0.123,
Wei Wange460a4b2020-04-30 08:59:35 +0800343# "encoding-rate":80.1,
Markus Armbruster48685a82017-08-24 21:14:01 +0200344# "overflow":34434
345# }
346# }
347# }
348#
349##
350{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
351
352##
353# @MigrationCapability:
354#
355# Migration capabilities enumeration
356#
357# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
358# This feature allows us to minimize migration traffic for certain work
359# loads, by sending compressed difference of the pages
360#
361# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
Peter Maydell26ec4e52020-02-13 17:56:26 +0000362# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
363# Disabled by default. (since 2.0)
Markus Armbruster48685a82017-08-24 21:14:01 +0200364#
365# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
Peter Maydell26ec4e52020-02-13 17:56:26 +0000366# essentially saves 1MB of zeroes per block on the wire. Enabling requires
367# source and target VM to support this feature. To enable it is sufficient
368# to enable the capability on the source VM. The feature is disabled by
369# default. (since 1.6)
Markus Armbruster48685a82017-08-24 21:14:01 +0200370#
371# @compress: Use multiple compression threads to accelerate live migration.
Peter Maydell26ec4e52020-02-13 17:56:26 +0000372# This feature can help to reduce the migration traffic, by sending
373# compressed pages. Please note that if compress and xbzrle are both
374# on, compress only takes effect in the ram bulk stage, after that,
375# it will be disabled and only xbzrle takes effect, this can help to
376# minimize migration traffic. The feature is disabled by default.
377# (since 2.4 )
Markus Armbruster48685a82017-08-24 21:14:01 +0200378#
379# @events: generate events for each migration state change
380# (since 2.4 )
381#
382# @auto-converge: If enabled, QEMU will automatically throttle down the guest
Peter Maydell26ec4e52020-02-13 17:56:26 +0000383# to speed up convergence of RAM migration. (since 1.6)
Markus Armbruster48685a82017-08-24 21:14:01 +0200384#
385# @postcopy-ram: Start executing on the migration target before all of RAM has
Peter Maydell26ec4e52020-02-13 17:56:26 +0000386# been migrated, pulling the remaining pages along as needed. The
387# capacity must have the same setting on both source and target
388# or migration will not even start. NOTE: If the migration fails during
389# postcopy the VM will fail. (since 2.6)
Markus Armbruster48685a82017-08-24 21:14:01 +0200390#
391# @x-colo: If enabled, migration will never end, and the state of the VM on the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000392# primary side will be migrated continuously to the VM on secondary
393# side, this process is called COarse-Grain LOck Stepping (COLO) for
394# Non-stop Service. (since 2.8)
Markus Armbruster48685a82017-08-24 21:14:01 +0200395#
396# @release-ram: if enabled, qemu will free the migrated ram pages on the source
Peter Maydell26ec4e52020-02-13 17:56:26 +0000397# during postcopy-ram migration. (since 2.9)
Markus Armbruster48685a82017-08-24 21:14:01 +0200398#
399# @block: If enabled, QEMU will also migrate the contents of all block
Peter Maydell26ec4e52020-02-13 17:56:26 +0000400# devices. Default is disabled. A possible alternative uses
401# mirror jobs to a builtin NBD server on the destination, which
402# offers more flexibility.
403# (Since 2.10)
Markus Armbruster48685a82017-08-24 21:14:01 +0200404#
405# @return-path: If enabled, migration will use the return path even
406# for precopy. (since 2.10)
407#
Dr. David Alan Gilbert93fbd032017-10-20 10:05:50 +0100408# @pause-before-switchover: Pause outgoing migration before serialising device
Peter Maydell26ec4e52020-02-13 17:56:26 +0000409# state and before disabling block IO (since 2.11)
Dr. David Alan Gilbert93fbd032017-10-20 10:05:50 +0100410#
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100411# @multifd: Use more than one fd for migration (since 4.0)
Juan Quintela30126bb2016-01-14 12:23:00 +0100412#
Vladimir Sementsov-Ogievskiy55efc8c2018-03-13 15:34:00 -0400413# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps.
414# (since 2.12)
415#
Alexey Perevalovf22f9282018-03-22 21:17:22 +0300416# @postcopy-blocktime: Calculate downtime for postcopy live migration
Peter Maydell26ec4e52020-02-13 17:56:26 +0000417# (since 3.0)
Alexey Perevalovf22f9282018-03-22 21:17:22 +0300418#
Dr. David Alan Gilbert0f073f42018-04-16 18:09:30 +0100419# @late-block-activate: If enabled, the destination will not activate block
Peter Maydell26ec4e52020-02-13 17:56:26 +0000420# devices (and thus take locks) immediately at the end of migration.
421# (since 3.0)
Dr. David Alan Gilbert0f073f42018-04-16 18:09:30 +0100422#
Yury Kotov18269062019-02-15 20:45:45 +0300423# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0)
424#
Yury Kotovb9d68df2019-09-03 19:22:44 +0300425# @validate-uuid: Send the UUID of the source to allow the destination
426# to ensure it is the same. (since 4.2)
427#
Markus Armbruster48685a82017-08-24 21:14:01 +0200428# Since: 1.2
429##
430{ 'enum': 'MigrationCapability',
431 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
432 'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram',
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100433 'block', 'return-path', 'pause-before-switchover', 'multifd',
Yury Kotov18269062019-02-15 20:45:45 +0300434 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate',
Yury Kotovb9d68df2019-09-03 19:22:44 +0300435 'x-ignore-shared', 'validate-uuid' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +0200436
437##
438# @MigrationCapabilityStatus:
439#
440# Migration capability information
441#
442# @capability: capability enum
443#
444# @state: capability state bool
445#
446# Since: 1.2
447##
448{ 'struct': 'MigrationCapabilityStatus',
449 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
450
451##
452# @migrate-set-capabilities:
453#
454# Enable/Disable the following migration capabilities (like xbzrle)
455#
456# @capabilities: json array of capability modifications to make
457#
458# Since: 1.2
459#
460# Example:
461#
462# -> { "execute": "migrate-set-capabilities" , "arguments":
463# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
464#
465##
466{ 'command': 'migrate-set-capabilities',
467 'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
468
469##
470# @query-migrate-capabilities:
471#
472# Returns information about the current migration capabilities status
473#
474# Returns: @MigrationCapabilitiesStatus
475#
476# Since: 1.2
477#
478# Example:
479#
480# -> { "execute": "query-migrate-capabilities" }
481# <- { "return": [
482# {"state": false, "capability": "xbzrle"},
483# {"state": false, "capability": "rdma-pin-all"},
484# {"state": false, "capability": "auto-converge"},
485# {"state": false, "capability": "zero-blocks"},
486# {"state": false, "capability": "compress"},
487# {"state": true, "capability": "events"},
488# {"state": false, "capability": "postcopy-ram"},
489# {"state": false, "capability": "x-colo"}
490# ]}
491#
492##
493{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
494
495##
Juan Quintela96eef042019-01-16 10:35:55 +0100496# @MultiFDCompression:
497#
498# An enumeration of multifd compression methods.
499#
500# @none: no compression.
Juan Quintela7ec2c2b2019-01-04 15:30:06 +0100501# @zlib: use zlib compression method.
Juan Quintela87dc6f52019-12-13 13:47:14 +0100502# @zstd: use zstd compression method.
Juan Quintela96eef042019-01-16 10:35:55 +0100503#
504# Since: 5.0
505#
506##
507{ 'enum': 'MultiFDCompression',
Juan Quintela87dc6f52019-12-13 13:47:14 +0100508 'data': [ 'none', 'zlib',
509 { 'name': 'zstd', 'if': 'defined(CONFIG_ZSTD)' } ] }
Juan Quintela96eef042019-01-16 10:35:55 +0100510
511##
Max Reitz31e4c352020-08-20 17:07:23 +0200512# @BitmapMigrationBitmapAlias:
513#
514# @name: The name of the bitmap.
515#
516# @alias: An alias name for migration (for example the bitmap name on
517# the opposite site).
518#
519# Since: 5.2
520##
521{ 'struct': 'BitmapMigrationBitmapAlias',
522 'data': {
523 'name': 'str',
524 'alias': 'str'
525 } }
526
527##
528# @BitmapMigrationNodeAlias:
529#
530# Maps a block node name and the bitmaps it has to aliases for dirty
531# bitmap migration.
532#
533# @node-name: A block node name.
534#
535# @alias: An alias block node name for migration (for example the
536# node name on the opposite site).
537#
538# @bitmaps: Mappings for the bitmaps on this node.
539#
540# Since: 5.2
541##
542{ 'struct': 'BitmapMigrationNodeAlias',
543 'data': {
544 'node-name': 'str',
545 'alias': 'str',
546 'bitmaps': [ 'BitmapMigrationBitmapAlias' ]
547 } }
548
549##
Markus Armbruster48685a82017-08-24 21:14:01 +0200550# @MigrationParameter:
551#
552# Migration parameters enumeration
553#
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000554# @announce-initial: Initial delay (in milliseconds) before sending the first
Peter Maydell26ec4e52020-02-13 17:56:26 +0000555# announce (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000556#
557# @announce-max: Maximum delay (in milliseconds) between packets in the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000558# announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000559#
560# @announce-rounds: Number of self-announce packets sent after migration
Peter Maydell26ec4e52020-02-13 17:56:26 +0000561# (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000562#
563# @announce-step: Increase in delay (in milliseconds) between subsequent
Peter Maydell26ec4e52020-02-13 17:56:26 +0000564# packets in the announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000565#
Markus Armbruster48685a82017-08-24 21:14:01 +0200566# @compress-level: Set the compression level to be used in live migration,
Peter Maydell26ec4e52020-02-13 17:56:26 +0000567# the compression level is an integer between 0 and 9, where 0 means
568# no compression, 1 means the best compression speed, and 9 means best
569# compression ratio which will consume more CPU.
Markus Armbruster48685a82017-08-24 21:14:01 +0200570#
571# @compress-threads: Set compression thread count to be used in live migration,
Peter Maydell26ec4e52020-02-13 17:56:26 +0000572# the compression thread count is an integer between 1 and 255.
Markus Armbruster48685a82017-08-24 21:14:01 +0200573#
Xiao Guangrong1d588722018-08-21 16:10:20 +0800574# @compress-wait-thread: Controls behavior when all compression threads are
575# currently busy. If true (default), wait for a free
576# compression thread to become available; otherwise,
577# send the page uncompressed. (Since 3.1)
578#
Markus Armbruster48685a82017-08-24 21:14:01 +0200579# @decompress-threads: Set decompression thread count to be used in live
Peter Maydell26ec4e52020-02-13 17:56:26 +0000580# migration, the decompression thread count is an integer between 1
581# and 255. Usually, decompression is at least 4 times as fast as
582# compression, so set the decompress-threads to the number about 1/4
583# of compress-threads is adequate.
Markus Armbruster48685a82017-08-24 21:14:01 +0200584#
Keqian Zhudc14a472020-02-24 10:31:42 +0800585# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
586# to trigger throttling. It is expressed as percentage.
587# The default value is 50. (Since 5.0)
588#
Markus Armbruster48685a82017-08-24 21:14:01 +0200589# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
590# when migration auto-converge is activated. The
591# default value is 20. (Since 2.7)
592#
593# @cpu-throttle-increment: throttle percentage increase each time
594# auto-converge detects that migration is not making
595# progress. The default value is 10. (Since 2.7)
596#
Keqian Zhucbbf8182020-04-13 18:15:08 +0800597# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
598# At the tail stage of throttling, the Guest is very
599# sensitive to CPU percentage while the @cpu-throttle
600# -increment is excessive usually at tail stage.
601# If this parameter is true, we will compute the ideal
602# CPU percentage used by the Guest, which may exactly make
603# the dirty rate match the dirty rate threshold. Then we
604# will choose a smaller throttle increment between the
605# one specified by @cpu-throttle-increment and the one
606# generated by ideal CPU percentage.
607# Therefore, it is compatible to traditional throttling,
608# meanwhile the throttle increment won't be excessive
609# at tail stage.
610# The default value is false. (Since 5.1)
611#
Markus Armbruster48685a82017-08-24 21:14:01 +0200612# @tls-creds: ID of the 'tls-creds' object that provides credentials for
613# establishing a TLS connection over the migration data channel.
614# On the outgoing side of the migration, the credentials must
615# be for a 'client' endpoint, while for the incoming side the
616# credentials must be for a 'server' endpoint. Setting this
617# will enable TLS for all migrations. The default is unset,
618# resulting in unsecured migration at the QEMU level. (Since 2.7)
619#
620# @tls-hostname: hostname of the target host for the migration. This is
621# required when using x509 based TLS credentials and the
622# migration URI does not already include a hostname. For
623# example if using fd: or exec: based migration, the
624# hostname must be provided so that the server's x509
625# certificate identity can be validated. (Since 2.7)
626#
Daniel P. Berranged2f1d292019-02-27 14:53:24 +0000627# @tls-authz: ID of the 'authz' object subclass that provides access control
628# checking of the TLS x509 certificate distinguished name.
629# This object is only resolved at time of use, so can be deleted
630# and recreated on the fly while the migration server is active.
631# If missing, it will default to denying access (Since 4.0)
632#
Markus Armbruster48685a82017-08-24 21:14:01 +0200633# @max-bandwidth: to set maximum speed for migration. maximum speed in
634# bytes per second. (Since 2.8)
635#
636# @downtime-limit: set maximum tolerated downtime for migration. maximum
637# downtime in milliseconds (Since 2.8)
638#
639# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
Peter Maydell26ec4e52020-02-13 17:56:26 +0000640# periodic mode. (Since 2.8)
Markus Armbruster48685a82017-08-24 21:14:01 +0200641#
642# @block-incremental: Affects how much storage is migrated when the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000643# block migration capability is enabled. When false, the entire
644# storage backing chain is migrated into a flattened image at
645# the destination; when true, only the active qcow2 layer is
646# migrated and the destination must already have access to the
647# same backing chain as was used on the source. (since 2.10)
Markus Armbruster48685a82017-08-24 21:14:01 +0200648#
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100649# @multifd-channels: Number of channels used to migrate data in
650# parallel. This is the same number that the
651# number of sockets used for migration. The
652# default value is 2 (since 4.0)
Juan Quintela4075fb12016-01-15 08:56:17 +0100653#
Juan Quintela73af8dd2017-10-05 21:30:10 +0200654# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
655# needs to be a multiple of the target page size
656# and a power of 2
657# (Since 2.11)
658#
Dr. David Alan Gilbert7e555c62018-06-13 11:26:40 +0100659# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
Peter Maydell26ec4e52020-02-13 17:56:26 +0000660# Defaults to 0 (unlimited). In bytes per second.
661# (Since 3.0)
Li Qiang4cbc9c72018-08-01 06:00:20 -0700662#
663# @max-cpu-throttle: maximum cpu throttle percentage.
664# Defaults to 99. (Since 3.1)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000665#
Juan Quintela96eef042019-01-16 10:35:55 +0100666# @multifd-compression: Which compression method to use.
667# Defaults to none. (Since 5.0)
668#
Juan Quintela9004db42020-01-23 17:08:52 +0100669# @multifd-zlib-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +0100670# migration, the compression level is an integer between 0
671# and 9, where 0 means no compression, 1 means the best
672# compression speed, and 9 means best compression ratio which
673# will consume more CPU.
674# Defaults to 1. (Since 5.0)
Juan Quintela9004db42020-01-23 17:08:52 +0100675#
Juan Quintela6a9ad152020-01-23 17:41:36 +0100676# @multifd-zstd-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +0100677# migration, the compression level is an integer between 0
678# and 20, where 0 means no compression, 1 means the best
679# compression speed, and 20 means best compression ratio which
680# will consume more CPU.
681# Defaults to 1. (Since 5.0)
Juan Quintela6a9ad152020-01-23 17:41:36 +0100682#
Max Reitz31e4c352020-08-20 17:07:23 +0200683# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
Peter Maydell826bd062020-09-25 17:22:56 +0100684# aliases for the purpose of dirty bitmap migration. Such
685# aliases may for example be the corresponding names on the
686# opposite site.
687# The mapping must be one-to-one, but not necessarily
688# complete: On the source, unmapped bitmaps and all bitmaps
689# on unmapped nodes will be ignored. On the destination,
690# encountering an unmapped alias in the incoming migration
691# stream will result in a report, and all further bitmap
692# migration data will then be discarded.
693# Note that the destination does not know about bitmaps it
694# does not receive, so there is no limitation or requirement
695# regarding the number of bitmaps received, or how they are
696# named, or on which nodes they are placed.
697# By default (when this parameter has never been set), bitmap
698# names are mapped to themselves. Nodes are mapped to their
699# block device name if there is one, and to their node name
700# otherwise. (Since 5.2)
Max Reitz31e4c352020-08-20 17:07:23 +0200701#
Markus Armbruster48685a82017-08-24 21:14:01 +0200702# Since: 2.4
703##
704{ 'enum': 'MigrationParameter',
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000705 'data': ['announce-initial', 'announce-max',
706 'announce-rounds', 'announce-step',
707 'compress-level', 'compress-threads', 'decompress-threads',
Keqian Zhudc14a472020-02-24 10:31:42 +0800708 'compress-wait-thread', 'throttle-trigger-threshold',
Markus Armbruster48685a82017-08-24 21:14:01 +0200709 'cpu-throttle-initial', 'cpu-throttle-increment',
Keqian Zhucbbf8182020-04-13 18:15:08 +0800710 'cpu-throttle-tailslow',
Daniel P. Berranged2f1d292019-02-27 14:53:24 +0000711 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
Juan Quintela4075fb12016-01-15 08:56:17 +0100712 'downtime-limit', 'x-checkpoint-delay', 'block-incremental',
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100713 'multifd-channels',
Li Qiang4cbc9c72018-08-01 06:00:20 -0700714 'xbzrle-cache-size', 'max-postcopy-bandwidth',
Juan Quintela9004db42020-01-23 17:08:52 +0100715 'max-cpu-throttle', 'multifd-compression',
Max Reitz31e4c352020-08-20 17:07:23 +0200716 'multifd-zlib-level' ,'multifd-zstd-level',
717 'block-bitmap-mapping' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +0200718
719##
720# @MigrateSetParameters:
721#
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000722# @announce-initial: Initial delay (in milliseconds) before sending the first
Peter Maydell26ec4e52020-02-13 17:56:26 +0000723# announce (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000724#
725# @announce-max: Maximum delay (in milliseconds) between packets in the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000726# announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000727#
728# @announce-rounds: Number of self-announce packets sent after migration
Peter Maydell26ec4e52020-02-13 17:56:26 +0000729# (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000730#
731# @announce-step: Increase in delay (in milliseconds) between subsequent
Peter Maydell26ec4e52020-02-13 17:56:26 +0000732# packets in the announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000733#
Markus Armbruster48685a82017-08-24 21:14:01 +0200734# @compress-level: compression level
735#
736# @compress-threads: compression thread count
737#
Xiao Guangrong1d588722018-08-21 16:10:20 +0800738# @compress-wait-thread: Controls behavior when all compression threads are
739# currently busy. If true (default), wait for a free
740# compression thread to become available; otherwise,
741# send the page uncompressed. (Since 3.1)
742#
Markus Armbruster48685a82017-08-24 21:14:01 +0200743# @decompress-threads: decompression thread count
744#
Keqian Zhudc14a472020-02-24 10:31:42 +0800745# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
746# to trigger throttling. It is expressed as percentage.
747# The default value is 50. (Since 5.0)
748#
Markus Armbruster48685a82017-08-24 21:14:01 +0200749# @cpu-throttle-initial: Initial percentage of time guest cpus are
750# throttled when migration auto-converge is activated.
751# The default value is 20. (Since 2.7)
752#
753# @cpu-throttle-increment: throttle percentage increase each time
754# auto-converge detects that migration is not making
755# progress. The default value is 10. (Since 2.7)
756#
Keqian Zhucbbf8182020-04-13 18:15:08 +0800757# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
758# At the tail stage of throttling, the Guest is very
759# sensitive to CPU percentage while the @cpu-throttle
760# -increment is excessive usually at tail stage.
761# If this parameter is true, we will compute the ideal
762# CPU percentage used by the Guest, which may exactly make
763# the dirty rate match the dirty rate threshold. Then we
764# will choose a smaller throttle increment between the
765# one specified by @cpu-throttle-increment and the one
766# generated by ideal CPU percentage.
767# Therefore, it is compatible to traditional throttling,
768# meanwhile the throttle increment won't be excessive
769# at tail stage.
770# The default value is false. (Since 5.1)
771#
Markus Armbruster48685a82017-08-24 21:14:01 +0200772# @tls-creds: ID of the 'tls-creds' object that provides credentials
773# for establishing a TLS connection over the migration data
774# channel. On the outgoing side of the migration, the credentials
775# must be for a 'client' endpoint, while for the incoming side the
776# credentials must be for a 'server' endpoint. Setting this
777# to a non-empty string enables TLS for all migrations.
778# An empty string means that QEMU will use plain text mode for
779# migration, rather than TLS (Since 2.9)
780# Previously (since 2.7), this was reported by omitting
781# tls-creds instead.
782#
783# @tls-hostname: hostname of the target host for the migration. This
784# is required when using x509 based TLS credentials and the
785# migration URI does not already include a hostname. For
786# example if using fd: or exec: based migration, the
787# hostname must be provided so that the server's x509
788# certificate identity can be validated. (Since 2.7)
789# An empty string means that QEMU will use the hostname
790# associated with the migration URI, if any. (Since 2.9)
791# Previously (since 2.7), this was reported by omitting
792# tls-hostname instead.
793#
794# @max-bandwidth: to set maximum speed for migration. maximum speed in
795# bytes per second. (Since 2.8)
796#
797# @downtime-limit: set maximum tolerated downtime for migration. maximum
798# downtime in milliseconds (Since 2.8)
799#
800# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
801#
802# @block-incremental: Affects how much storage is migrated when the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000803# block migration capability is enabled. When false, the entire
804# storage backing chain is migrated into a flattened image at
805# the destination; when true, only the active qcow2 layer is
806# migrated and the destination must already have access to the
807# same backing chain as was used on the source. (since 2.10)
Markus Armbruster48685a82017-08-24 21:14:01 +0200808#
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100809# @multifd-channels: Number of channels used to migrate data in
810# parallel. This is the same number that the
811# number of sockets used for migration. The
812# default value is 2 (since 4.0)
Juan Quintela4075fb12016-01-15 08:56:17 +0100813#
Juan Quintela73af8dd2017-10-05 21:30:10 +0200814# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
815# needs to be a multiple of the target page size
816# and a power of 2
817# (Since 2.11)
Dr. David Alan Gilbert7e555c62018-06-13 11:26:40 +0100818#
819# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
Peter Maydell26ec4e52020-02-13 17:56:26 +0000820# Defaults to 0 (unlimited). In bytes per second.
821# (Since 3.0)
Li Qiang4cbc9c72018-08-01 06:00:20 -0700822#
823# @max-cpu-throttle: maximum cpu throttle percentage.
824# The default value is 99. (Since 3.1)
825#
Juan Quintela96eef042019-01-16 10:35:55 +0100826# @multifd-compression: Which compression method to use.
827# Defaults to none. (Since 5.0)
828#
Juan Quintela9004db42020-01-23 17:08:52 +0100829# @multifd-zlib-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +0100830# migration, the compression level is an integer between 0
831# and 9, where 0 means no compression, 1 means the best
832# compression speed, and 9 means best compression ratio which
833# will consume more CPU.
834# Defaults to 1. (Since 5.0)
Juan Quintela9004db42020-01-23 17:08:52 +0100835#
Juan Quintela6a9ad152020-01-23 17:41:36 +0100836# @multifd-zstd-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +0100837# migration, the compression level is an integer between 0
838# and 20, where 0 means no compression, 1 means the best
839# compression speed, and 20 means best compression ratio which
840# will consume more CPU.
841# Defaults to 1. (Since 5.0)
Juan Quintela6a9ad152020-01-23 17:41:36 +0100842#
Max Reitz31e4c352020-08-20 17:07:23 +0200843# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
Peter Maydell826bd062020-09-25 17:22:56 +0100844# aliases for the purpose of dirty bitmap migration. Such
845# aliases may for example be the corresponding names on the
846# opposite site.
847# The mapping must be one-to-one, but not necessarily
848# complete: On the source, unmapped bitmaps and all bitmaps
849# on unmapped nodes will be ignored. On the destination,
850# encountering an unmapped alias in the incoming migration
851# stream will result in a report, and all further bitmap
852# migration data will then be discarded.
853# Note that the destination does not know about bitmaps it
854# does not receive, so there is no limitation or requirement
855# regarding the number of bitmaps received, or how they are
856# named, or on which nodes they are placed.
857# By default (when this parameter has never been set), bitmap
858# names are mapped to themselves. Nodes are mapped to their
859# block device name if there is one, and to their node name
860# otherwise. (Since 5.2)
Max Reitz31e4c352020-08-20 17:07:23 +0200861#
Markus Armbruster48685a82017-08-24 21:14:01 +0200862# Since: 2.4
863##
864# TODO either fuse back into MigrationParameters, or make
865# MigrationParameters members mandatory
866{ 'struct': 'MigrateSetParameters',
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000867 'data': { '*announce-initial': 'size',
868 '*announce-max': 'size',
869 '*announce-rounds': 'size',
870 '*announce-step': 'size',
871 '*compress-level': 'int',
Markus Armbruster48685a82017-08-24 21:14:01 +0200872 '*compress-threads': 'int',
Xiao Guangrong1d588722018-08-21 16:10:20 +0800873 '*compress-wait-thread': 'bool',
Markus Armbruster48685a82017-08-24 21:14:01 +0200874 '*decompress-threads': 'int',
Keqian Zhudc14a472020-02-24 10:31:42 +0800875 '*throttle-trigger-threshold': 'int',
Markus Armbruster48685a82017-08-24 21:14:01 +0200876 '*cpu-throttle-initial': 'int',
877 '*cpu-throttle-increment': 'int',
Keqian Zhucbbf8182020-04-13 18:15:08 +0800878 '*cpu-throttle-tailslow': 'bool',
Markus Armbruster48685a82017-08-24 21:14:01 +0200879 '*tls-creds': 'StrOrNull',
880 '*tls-hostname': 'StrOrNull',
Daniel P. Berranged2f1d292019-02-27 14:53:24 +0000881 '*tls-authz': 'StrOrNull',
Markus Armbruster48685a82017-08-24 21:14:01 +0200882 '*max-bandwidth': 'int',
883 '*downtime-limit': 'int',
884 '*x-checkpoint-delay': 'int',
Juan Quintela4075fb12016-01-15 08:56:17 +0100885 '*block-incremental': 'bool',
Juan Quintelacbfd6c92019-02-06 13:54:06 +0100886 '*multifd-channels': 'int',
Dr. David Alan Gilbert7e555c62018-06-13 11:26:40 +0100887 '*xbzrle-cache-size': 'size',
Li Qiang4cbc9c72018-08-01 06:00:20 -0700888 '*max-postcopy-bandwidth': 'size',
Juan Quintela96eef042019-01-16 10:35:55 +0100889 '*max-cpu-throttle': 'int',
Juan Quintela9004db42020-01-23 17:08:52 +0100890 '*multifd-compression': 'MultiFDCompression',
Juan Quintela6a9ad152020-01-23 17:41:36 +0100891 '*multifd-zlib-level': 'int',
Max Reitz31e4c352020-08-20 17:07:23 +0200892 '*multifd-zstd-level': 'int',
893 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } }
Markus Armbruster48685a82017-08-24 21:14:01 +0200894
895##
896# @migrate-set-parameters:
897#
898# Set various migration parameters.
899#
900# Since: 2.4
901#
902# Example:
903#
904# -> { "execute": "migrate-set-parameters" ,
905# "arguments": { "compress-level": 1 } }
906#
907##
908{ 'command': 'migrate-set-parameters', 'boxed': true,
909 'data': 'MigrateSetParameters' }
910
911##
912# @MigrationParameters:
913#
914# The optional members aren't actually optional.
915#
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000916# @announce-initial: Initial delay (in milliseconds) before sending the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000917# first announce (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000918#
919# @announce-max: Maximum delay (in milliseconds) between packets in the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000920# announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000921#
922# @announce-rounds: Number of self-announce packets sent after migration
Peter Maydell26ec4e52020-02-13 17:56:26 +0000923# (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000924#
925# @announce-step: Increase in delay (in milliseconds) between subsequent
Peter Maydell26ec4e52020-02-13 17:56:26 +0000926# packets in the announcement (Since 4.0)
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +0000927#
Markus Armbruster48685a82017-08-24 21:14:01 +0200928# @compress-level: compression level
929#
930# @compress-threads: compression thread count
931#
Xiao Guangrong1d588722018-08-21 16:10:20 +0800932# @compress-wait-thread: Controls behavior when all compression threads are
933# currently busy. If true (default), wait for a free
934# compression thread to become available; otherwise,
935# send the page uncompressed. (Since 3.1)
936#
Markus Armbruster48685a82017-08-24 21:14:01 +0200937# @decompress-threads: decompression thread count
938#
Keqian Zhudc14a472020-02-24 10:31:42 +0800939# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period
940# to trigger throttling. It is expressed as percentage.
941# The default value is 50. (Since 5.0)
942#
Markus Armbruster48685a82017-08-24 21:14:01 +0200943# @cpu-throttle-initial: Initial percentage of time guest cpus are
944# throttled when migration auto-converge is activated.
945# (Since 2.7)
946#
947# @cpu-throttle-increment: throttle percentage increase each time
948# auto-converge detects that migration is not making
949# progress. (Since 2.7)
950#
Keqian Zhucbbf8182020-04-13 18:15:08 +0800951# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage
952# At the tail stage of throttling, the Guest is very
953# sensitive to CPU percentage while the @cpu-throttle
954# -increment is excessive usually at tail stage.
955# If this parameter is true, we will compute the ideal
956# CPU percentage used by the Guest, which may exactly make
957# the dirty rate match the dirty rate threshold. Then we
958# will choose a smaller throttle increment between the
959# one specified by @cpu-throttle-increment and the one
960# generated by ideal CPU percentage.
961# Therefore, it is compatible to traditional throttling,
962# meanwhile the throttle increment won't be excessive
963# at tail stage.
964# The default value is false. (Since 5.1)
965#
Markus Armbruster48685a82017-08-24 21:14:01 +0200966# @tls-creds: ID of the 'tls-creds' object that provides credentials
967# for establishing a TLS connection over the migration data
968# channel. On the outgoing side of the migration, the credentials
969# must be for a 'client' endpoint, while for the incoming side the
970# credentials must be for a 'server' endpoint.
971# An empty string means that QEMU will use plain text mode for
972# migration, rather than TLS (Since 2.7)
973# Note: 2.8 reports this by omitting tls-creds instead.
974#
975# @tls-hostname: hostname of the target host for the migration. This
976# is required when using x509 based TLS credentials and the
977# migration URI does not already include a hostname. For
978# example if using fd: or exec: based migration, the
979# hostname must be provided so that the server's x509
980# certificate identity can be validated. (Since 2.7)
981# An empty string means that QEMU will use the hostname
982# associated with the migration URI, if any. (Since 2.9)
983# Note: 2.8 reports this by omitting tls-hostname instead.
984#
Daniel P. Berranged2f1d292019-02-27 14:53:24 +0000985# @tls-authz: ID of the 'authz' object subclass that provides access control
986# checking of the TLS x509 certificate distinguished name. (Since
987# 4.0)
988#
Markus Armbruster48685a82017-08-24 21:14:01 +0200989# @max-bandwidth: to set maximum speed for migration. maximum speed in
990# bytes per second. (Since 2.8)
991#
992# @downtime-limit: set maximum tolerated downtime for migration. maximum
993# downtime in milliseconds (Since 2.8)
994#
995# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
996#
997# @block-incremental: Affects how much storage is migrated when the
Peter Maydell26ec4e52020-02-13 17:56:26 +0000998# block migration capability is enabled. When false, the entire
999# storage backing chain is migrated into a flattened image at
1000# the destination; when true, only the active qcow2 layer is
1001# migrated and the destination must already have access to the
1002# same backing chain as was used on the source. (since 2.10)
Markus Armbruster48685a82017-08-24 21:14:01 +02001003#
Juan Quintelacbfd6c92019-02-06 13:54:06 +01001004# @multifd-channels: Number of channels used to migrate data in
1005# parallel. This is the same number that the
1006# number of sockets used for migration.
1007# The default value is 2 (since 4.0)
Juan Quintela4075fb12016-01-15 08:56:17 +01001008#
Juan Quintela73af8dd2017-10-05 21:30:10 +02001009# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
1010# needs to be a multiple of the target page size
1011# and a power of 2
1012# (Since 2.11)
Dr. David Alan Gilbert7e555c62018-06-13 11:26:40 +01001013#
1014# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
Peter Maydell26ec4e52020-02-13 17:56:26 +00001015# Defaults to 0 (unlimited). In bytes per second.
1016# (Since 3.0)
Li Qiang4cbc9c72018-08-01 06:00:20 -07001017#
1018# @max-cpu-throttle: maximum cpu throttle percentage.
1019# Defaults to 99.
Peter Maydell26ec4e52020-02-13 17:56:26 +00001020# (Since 3.1)
Li Qiang4cbc9c72018-08-01 06:00:20 -07001021#
Juan Quintela96eef042019-01-16 10:35:55 +01001022# @multifd-compression: Which compression method to use.
1023# Defaults to none. (Since 5.0)
1024#
Juan Quintela9004db42020-01-23 17:08:52 +01001025# @multifd-zlib-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +01001026# migration, the compression level is an integer between 0
1027# and 9, where 0 means no compression, 1 means the best
1028# compression speed, and 9 means best compression ratio which
1029# will consume more CPU.
1030# Defaults to 1. (Since 5.0)
Juan Quintela9004db42020-01-23 17:08:52 +01001031#
Juan Quintela6a9ad152020-01-23 17:41:36 +01001032# @multifd-zstd-level: Set the compression level to be used in live
Peter Maydell76dd0f82020-08-10 20:50:00 +01001033# migration, the compression level is an integer between 0
1034# and 20, where 0 means no compression, 1 means the best
1035# compression speed, and 20 means best compression ratio which
1036# will consume more CPU.
1037# Defaults to 1. (Since 5.0)
Juan Quintela6a9ad152020-01-23 17:41:36 +01001038#
Max Reitz31e4c352020-08-20 17:07:23 +02001039# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
Peter Maydell826bd062020-09-25 17:22:56 +01001040# aliases for the purpose of dirty bitmap migration. Such
1041# aliases may for example be the corresponding names on the
1042# opposite site.
1043# The mapping must be one-to-one, but not necessarily
1044# complete: On the source, unmapped bitmaps and all bitmaps
1045# on unmapped nodes will be ignored. On the destination,
1046# encountering an unmapped alias in the incoming migration
1047# stream will result in a report, and all further bitmap
1048# migration data will then be discarded.
1049# Note that the destination does not know about bitmaps it
1050# does not receive, so there is no limitation or requirement
1051# regarding the number of bitmaps received, or how they are
1052# named, or on which nodes they are placed.
1053# By default (when this parameter has never been set), bitmap
1054# names are mapped to themselves. Nodes are mapped to their
1055# block device name if there is one, and to their node name
1056# otherwise. (Since 5.2)
Max Reitz31e4c352020-08-20 17:07:23 +02001057#
Markus Armbruster48685a82017-08-24 21:14:01 +02001058# Since: 2.4
1059##
1060{ 'struct': 'MigrationParameters',
Dr. David Alan Gilbertee3d96b2019-02-27 13:24:06 +00001061 'data': { '*announce-initial': 'size',
1062 '*announce-max': 'size',
1063 '*announce-rounds': 'size',
1064 '*announce-step': 'size',
1065 '*compress-level': 'uint8',
Juan Quintela741d4082017-12-01 13:08:38 +01001066 '*compress-threads': 'uint8',
Xiao Guangrong1d588722018-08-21 16:10:20 +08001067 '*compress-wait-thread': 'bool',
Juan Quintela741d4082017-12-01 13:08:38 +01001068 '*decompress-threads': 'uint8',
Keqian Zhudc14a472020-02-24 10:31:42 +08001069 '*throttle-trigger-threshold': 'uint8',
Juan Quintela741d4082017-12-01 13:08:38 +01001070 '*cpu-throttle-initial': 'uint8',
1071 '*cpu-throttle-increment': 'uint8',
Keqian Zhucbbf8182020-04-13 18:15:08 +08001072 '*cpu-throttle-tailslow': 'bool',
Markus Armbruster48685a82017-08-24 21:14:01 +02001073 '*tls-creds': 'str',
1074 '*tls-hostname': 'str',
Daniel P. Berranged2f1d292019-02-27 14:53:24 +00001075 '*tls-authz': 'str',
Juan Quintela741d4082017-12-01 13:08:38 +01001076 '*max-bandwidth': 'size',
1077 '*downtime-limit': 'uint64',
1078 '*x-checkpoint-delay': 'uint32',
Juan Quintela4075fb12016-01-15 08:56:17 +01001079 '*block-incremental': 'bool' ,
Juan Quintelacbfd6c92019-02-06 13:54:06 +01001080 '*multifd-channels': 'uint8',
Dr. David Alan Gilbert7e555c62018-06-13 11:26:40 +01001081 '*xbzrle-cache-size': 'size',
Peter Maydelldbb28bc2020-02-13 17:56:27 +00001082 '*max-postcopy-bandwidth': 'size',
Juan Quintela96eef042019-01-16 10:35:55 +01001083 '*max-cpu-throttle': 'uint8',
Juan Quintela9004db42020-01-23 17:08:52 +01001084 '*multifd-compression': 'MultiFDCompression',
Juan Quintela6a9ad152020-01-23 17:41:36 +01001085 '*multifd-zlib-level': 'uint8',
Max Reitz31e4c352020-08-20 17:07:23 +02001086 '*multifd-zstd-level': 'uint8',
1087 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } }
Markus Armbruster48685a82017-08-24 21:14:01 +02001088
1089##
1090# @query-migrate-parameters:
1091#
1092# Returns information about the current migration parameters
1093#
1094# Returns: @MigrationParameters
1095#
1096# Since: 2.4
1097#
1098# Example:
1099#
1100# -> { "execute": "query-migrate-parameters" }
1101# <- { "return": {
1102# "decompress-threads": 2,
1103# "cpu-throttle-increment": 10,
1104# "compress-threads": 8,
1105# "compress-level": 1,
1106# "cpu-throttle-initial": 20,
1107# "max-bandwidth": 33554432,
1108# "downtime-limit": 300
1109# }
1110# }
1111#
1112##
1113{ 'command': 'query-migrate-parameters',
1114 'returns': 'MigrationParameters' }
1115
1116##
1117# @client_migrate_info:
1118#
1119# Set migration information for remote display. This makes the server
1120# ask the client to automatically reconnect using the new parameters
1121# once migration finished successfully. Only implemented for SPICE.
1122#
1123# @protocol: must be "spice"
1124# @hostname: migration target hostname
1125# @port: spice tcp port for plaintext channels
1126# @tls-port: spice tcp port for tls-secured channels
1127# @cert-subject: server certificate subject
1128#
1129# Since: 0.14.0
1130#
1131# Example:
1132#
1133# -> { "execute": "client_migrate_info",
1134# "arguments": { "protocol": "spice",
1135# "hostname": "virt42.lab.kraxel.org",
1136# "port": 1234 } }
1137# <- { "return": {} }
1138#
1139##
1140{ 'command': 'client_migrate_info',
1141 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
1142 '*tls-port': 'int', '*cert-subject': 'str' } }
1143
1144##
1145# @migrate-start-postcopy:
1146#
1147# Followup to a migration command to switch the migration to postcopy mode.
Greg Kurzc2eb7f22018-02-07 16:41:43 +01001148# The postcopy-ram capability must be set on both source and destination
1149# before the original migration command.
Markus Armbruster48685a82017-08-24 21:14:01 +02001150#
1151# Since: 2.5
1152#
1153# Example:
1154#
1155# -> { "execute": "migrate-start-postcopy" }
1156# <- { "return": {} }
1157#
1158##
1159{ 'command': 'migrate-start-postcopy' }
1160
1161##
1162# @MIGRATION:
1163#
1164# Emitted when a migration event happens
1165#
1166# @status: @MigrationStatus describing the current migration status.
1167#
1168# Since: 2.4
1169#
1170# Example:
1171#
1172# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
1173# "event": "MIGRATION",
1174# "data": {"status": "completed"} }
1175#
1176##
1177{ 'event': 'MIGRATION',
1178 'data': {'status': 'MigrationStatus'}}
1179
1180##
1181# @MIGRATION_PASS:
1182#
1183# Emitted from the source side of a migration at the start of each pass
1184# (when it syncs the dirty bitmap)
1185#
1186# @pass: An incrementing count (starting at 1 on the first pass)
1187#
1188# Since: 2.6
1189#
1190# Example:
1191#
1192# { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
1193# "event": "MIGRATION_PASS", "data": {"pass": 2} }
1194#
1195##
1196{ 'event': 'MIGRATION_PASS',
1197 'data': { 'pass': 'int' } }
1198
1199##
1200# @COLOMessage:
1201#
1202# The message transmission between Primary side and Secondary side.
1203#
1204# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
1205#
1206# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
1207#
1208# @checkpoint-reply: SVM gets PVM's checkpoint request
1209#
1210# @vmstate-send: VM's state will be sent by PVM.
1211#
1212# @vmstate-size: The total size of VMstate.
1213#
1214# @vmstate-received: VM's state has been received by SVM.
1215#
1216# @vmstate-loaded: VM's state has been loaded by SVM.
1217#
1218# Since: 2.8
1219##
1220{ 'enum': 'COLOMessage',
1221 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
1222 'vmstate-send', 'vmstate-size', 'vmstate-received',
1223 'vmstate-loaded' ] }
1224
1225##
1226# @COLOMode:
1227#
Zhang Chen41b6b772018-09-03 12:38:52 +08001228# The COLO current mode.
Markus Armbruster48685a82017-08-24 21:14:01 +02001229#
Zhang Chen41b6b772018-09-03 12:38:52 +08001230# @none: COLO is disabled.
Markus Armbruster48685a82017-08-24 21:14:01 +02001231#
Zhang Chen41b6b772018-09-03 12:38:52 +08001232# @primary: COLO node in primary side.
Markus Armbruster48685a82017-08-24 21:14:01 +02001233#
Zhang Chen41b6b772018-09-03 12:38:52 +08001234# @secondary: COLO node in slave side.
Markus Armbruster48685a82017-08-24 21:14:01 +02001235#
1236# Since: 2.8
1237##
1238{ 'enum': 'COLOMode',
Zhang Chen41b6b772018-09-03 12:38:52 +08001239 'data': [ 'none', 'primary', 'secondary'] }
Markus Armbruster48685a82017-08-24 21:14:01 +02001240
1241##
1242# @FailoverStatus:
1243#
1244# An enumeration of COLO failover status
1245#
1246# @none: no failover has ever happened
1247#
1248# @require: got failover requirement but not handled
1249#
1250# @active: in the process of doing failover
1251#
1252# @completed: finish the process of failover
1253#
1254# @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9)
1255#
1256# Since: 2.8
1257##
1258{ 'enum': 'FailoverStatus',
1259 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
1260
1261##
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001262# @COLO_EXIT:
1263#
1264# Emitted when VM finishes COLO mode due to some errors happening or
1265# at the request of users.
1266#
1267# @mode: report COLO mode when COLO exited.
1268#
1269# @reason: describes the reason for the COLO exit.
1270#
1271# Since: 3.1
1272#
1273# Example:
1274#
1275# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
1276# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
1277#
1278##
1279{ 'event': 'COLO_EXIT',
1280 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
1281
1282##
1283# @COLOExitReason:
1284#
Zhang Chen3a43ac42019-03-22 18:13:31 +08001285# The reason for a COLO exit.
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001286#
Zhang Chen3a43ac42019-03-22 18:13:31 +08001287# @none: failover has never happened. This state does not occur
Peter Maydell26ec4e52020-02-13 17:56:26 +00001288# in the COLO_EXIT event, and is only visible in the result of
1289# query-colo-status.
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001290#
Zhang Chen3a43ac42019-03-22 18:13:31 +08001291# @request: COLO exit is due to an external request.
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001292#
Zhang Chen3a43ac42019-03-22 18:13:31 +08001293# @error: COLO exit is due to an internal error.
1294#
1295# @processing: COLO is currently handling a failover (since 4.0).
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001296#
1297# Since: 3.1
1298##
1299{ 'enum': 'COLOExitReason',
Zhang Chen3a43ac42019-03-22 18:13:31 +08001300 'data': [ 'none', 'request', 'error' , 'processing' ] }
zhanghailiang9ecff6d2018-09-03 12:38:51 +08001301
1302##
Markus Armbruster48685a82017-08-24 21:14:01 +02001303# @x-colo-lost-heartbeat:
1304#
1305# Tell qemu that heartbeat is lost, request it to do takeover procedures.
1306# If this command is sent to the PVM, the Primary side will exit COLO mode.
1307# If sent to the Secondary, the Secondary side will run failover work,
1308# then takes over server operation to become the service VM.
1309#
1310# Since: 2.8
1311#
1312# Example:
1313#
1314# -> { "execute": "x-colo-lost-heartbeat" }
1315# <- { "return": {} }
1316#
1317##
1318{ 'command': 'x-colo-lost-heartbeat' }
1319
1320##
1321# @migrate_cancel:
1322#
1323# Cancel the current executing migration process.
1324#
1325# Returns: nothing on success
1326#
1327# Notes: This command succeeds even if there is no migration process running.
1328#
1329# Since: 0.14.0
1330#
1331# Example:
1332#
1333# -> { "execute": "migrate_cancel" }
1334# <- { "return": {} }
1335#
1336##
1337{ 'command': 'migrate_cancel' }
1338
1339##
Dr. David Alan Gilbert89cfc022017-10-20 10:05:53 +01001340# @migrate-continue:
1341#
1342# Continue migration when it's in a paused state.
1343#
1344# @state: The state the migration is currently expected to be in
1345#
1346# Returns: nothing on success
1347# Since: 2.11
1348# Example:
1349#
1350# -> { "execute": "migrate-continue" , "arguments":
1351# { "state": "pre-switchover" } }
1352# <- { "return": {} }
1353##
1354{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
1355
1356##
Markus Armbruster48685a82017-08-24 21:14:01 +02001357# @migrate_set_downtime:
1358#
1359# Set maximum tolerated downtime for migration.
1360#
1361# @value: maximum downtime in seconds
1362#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001363# Features:
1364# @deprecated: This command is deprecated. Use
Peter Maydellb2f1c132020-08-10 20:50:01 +01001365# 'migrate-set-parameters' instead.
Markus Armbruster48685a82017-08-24 21:14:01 +02001366#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001367# Returns: nothing on success
Markus Armbruster48685a82017-08-24 21:14:01 +02001368#
1369# Since: 0.14.0
1370#
1371# Example:
1372#
1373# -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1374# <- { "return": {} }
1375#
1376##
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001377{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'},
1378 'features': [ 'deprecated' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +02001379
1380##
1381# @migrate_set_speed:
1382#
1383# Set maximum speed for migration.
1384#
1385# @value: maximum speed in bytes per second.
1386#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001387# Features:
1388# @deprecated: This command is deprecated. Use
Peter Maydellb2f1c132020-08-10 20:50:01 +01001389# 'migrate-set-parameters' instead.
Markus Armbruster48685a82017-08-24 21:14:01 +02001390#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001391# Returns: nothing on success
Markus Armbruster48685a82017-08-24 21:14:01 +02001392#
1393# Since: 0.14.0
1394#
1395# Example:
1396#
1397# -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1398# <- { "return": {} }
1399#
1400##
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001401{ 'command': 'migrate_set_speed', 'data': {'value': 'int'},
1402 'features': [ 'deprecated' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +02001403
1404##
1405# @migrate-set-cache-size:
1406#
1407# Set cache size to be used by XBZRLE migration
1408#
1409# @value: cache size in bytes
1410#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001411# Features:
1412# @deprecated: This command is deprecated. Use
Peter Maydellb2f1c132020-08-10 20:50:01 +01001413# 'migrate-set-parameters' instead.
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001414#
Markus Armbruster48685a82017-08-24 21:14:01 +02001415# The size will be rounded down to the nearest power of 2.
1416# The cache size can be modified before and during ongoing migration
1417#
1418# Returns: nothing on success
1419#
1420# Since: 1.2
1421#
1422# Example:
1423#
1424# -> { "execute": "migrate-set-cache-size",
1425# "arguments": { "value": 536870912 } }
1426# <- { "return": {} }
1427#
1428##
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001429{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'},
1430 'features': [ 'deprecated' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +02001431
1432##
1433# @query-migrate-cache-size:
1434#
1435# Query migration XBZRLE cache size
1436#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001437# Features:
1438# @deprecated: This command is deprecated. Use
Peter Maydellb2f1c132020-08-10 20:50:01 +01001439# 'query-migrate-parameters' instead.
Markus Armbruster48685a82017-08-24 21:14:01 +02001440#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001441# Returns: XBZRLE cache size in bytes
Juan Quintela73af8dd2017-10-05 21:30:10 +02001442#
Markus Armbruster48685a82017-08-24 21:14:01 +02001443# Since: 1.2
1444#
1445# Example:
1446#
1447# -> { "execute": "query-migrate-cache-size" }
1448# <- { "return": 67108864 }
1449#
1450##
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001451{ 'command': 'query-migrate-cache-size', 'returns': 'int',
1452 'features': [ 'deprecated' ] }
Markus Armbruster48685a82017-08-24 21:14:01 +02001453
1454##
1455# @migrate:
1456#
1457# Migrates the current running guest to another Virtual Machine.
1458#
1459# @uri: the Uniform Resource Identifier of the destination VM
1460#
1461# @blk: do block migration (full disk copy)
1462#
1463# @inc: incremental disk copy migration
1464#
1465# @detach: this argument exists only for compatibility reasons and
1466# is ignored by QEMU
1467#
Peter Maydell51f63ec2018-05-22 11:39:56 +01001468# @resume: resume one paused migration, default "off". (since 3.0)
Peter Xu7a4da282018-05-02 18:47:23 +08001469#
Markus Armbruster48685a82017-08-24 21:14:01 +02001470# Returns: nothing on success
1471#
1472# Since: 0.14.0
1473#
1474# Notes:
1475#
1476# 1. The 'query-migrate' command should be used to check migration's progress
1477# and final result (this information is provided by the 'status' member)
1478#
1479# 2. All boolean arguments default to false
1480#
1481# 3. The user Monitor's "detach" argument is invalid in QMP and should not
1482# be used
1483#
1484# Example:
1485#
1486# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1487# <- { "return": {} }
1488#
1489##
1490{ 'command': 'migrate',
Peter Xu7a4da282018-05-02 18:47:23 +08001491 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
1492 '*detach': 'bool', '*resume': 'bool' } }
Markus Armbruster48685a82017-08-24 21:14:01 +02001493
1494##
1495# @migrate-incoming:
1496#
1497# Start an incoming migration, the qemu must have been started
1498# with -incoming defer
1499#
1500# @uri: The Uniform Resource Identifier identifying the source or
1501# address to listen on
1502#
1503# Returns: nothing on success
1504#
1505# Since: 2.3
1506#
1507# Notes:
1508#
1509# 1. It's a bad idea to use a string for the uri, but it needs to stay
1510# compatible with -incoming and the format of the uri is already exposed
1511# above libvirt.
1512#
1513# 2. QEMU must be started with -incoming defer to allow migrate-incoming to
1514# be used.
1515#
1516# 3. The uri format is the same as for -incoming
1517#
1518# Example:
1519#
1520# -> { "execute": "migrate-incoming",
1521# "arguments": { "uri": "tcp::4446" } }
1522# <- { "return": {} }
1523#
1524##
1525{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
1526
1527##
1528# @xen-save-devices-state:
1529#
1530# Save the state of all devices to file. The RAM and the block devices
1531# of the VM are not saved by this command.
1532#
1533# @filename: the file to save the state of the devices to as binary
Peter Maydell26ec4e52020-02-13 17:56:26 +00001534# data. See xen-save-devices-state.txt for a description of the binary
1535# format.
Markus Armbruster48685a82017-08-24 21:14:01 +02001536#
Anthony PERARD5d6c5992017-11-16 15:14:19 +00001537# @live: Optional argument to ask QEMU to treat this command as part of a live
Peter Maydell26ec4e52020-02-13 17:56:26 +00001538# migration. Default to true. (since 2.11)
Anthony PERARD5d6c5992017-11-16 15:14:19 +00001539#
Markus Armbruster48685a82017-08-24 21:14:01 +02001540# Returns: Nothing on success
1541#
1542# Since: 1.1
1543#
1544# Example:
1545#
1546# -> { "execute": "xen-save-devices-state",
1547# "arguments": { "filename": "/tmp/save" } }
1548# <- { "return": {} }
1549#
1550##
Anthony PERARD5d6c5992017-11-16 15:14:19 +00001551{ 'command': 'xen-save-devices-state',
1552 'data': {'filename': 'str', '*live':'bool' } }
Markus Armbruster48685a82017-08-24 21:14:01 +02001553
1554##
Philippe Mathieu-Daudé28af9ba2020-10-12 14:15:36 +02001555# @xen-set-global-dirty-log:
1556#
1557# Enable or disable the global dirty log mode.
1558#
1559# @enable: true to enable, false to disable.
1560#
1561# Returns: nothing
1562#
1563# Since: 1.3
1564#
1565# Example:
1566#
1567# -> { "execute": "xen-set-global-dirty-log",
1568# "arguments": { "enable": true } }
1569# <- { "return": {} }
1570#
1571##
1572{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
1573
1574##
1575# @xen-load-devices-state:
1576#
1577# Load the state of all devices from file. The RAM and the block devices
1578# of the VM are not loaded by this command.
1579#
1580# @filename: the file to load the state of the devices from as binary
1581# data. See xen-save-devices-state.txt for a description of the binary
1582# format.
1583#
1584# Since: 2.7
1585#
1586# Example:
1587#
1588# -> { "execute": "xen-load-devices-state",
1589# "arguments": { "filename": "/tmp/resume" } }
1590# <- { "return": {} }
1591#
1592##
1593{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
1594
1595##
Markus Armbruster48685a82017-08-24 21:14:01 +02001596# @xen-set-replication:
1597#
1598# Enable or disable replication.
1599#
1600# @enable: true to enable, false to disable.
1601#
1602# @primary: true for primary or false for secondary.
1603#
1604# @failover: true to do failover, false to stop. but cannot be
1605# specified if 'enable' is true. default value is false.
1606#
1607# Returns: nothing.
1608#
1609# Example:
1610#
1611# -> { "execute": "xen-set-replication",
1612# "arguments": {"enable": true, "primary": false} }
1613# <- { "return": {} }
1614#
1615# Since: 2.9
1616##
1617{ 'command': 'xen-set-replication',
Marc-André Lureau335d10c2018-12-13 16:37:24 +04001618 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' },
1619 'if': 'defined(CONFIG_REPLICATION)' }
Markus Armbruster48685a82017-08-24 21:14:01 +02001620
1621##
1622# @ReplicationStatus:
1623#
1624# The result format for 'query-xen-replication-status'.
1625#
1626# @error: true if an error happened, false if replication is normal.
1627#
1628# @desc: the human readable error description string, when
1629# @error is 'true'.
1630#
1631# Since: 2.9
1632##
1633{ 'struct': 'ReplicationStatus',
Marc-André Lureau335d10c2018-12-13 16:37:24 +04001634 'data': { 'error': 'bool', '*desc': 'str' },
1635 'if': 'defined(CONFIG_REPLICATION)' }
Markus Armbruster48685a82017-08-24 21:14:01 +02001636
1637##
1638# @query-xen-replication-status:
1639#
1640# Query replication status while the vm is running.
1641#
1642# Returns: A @ReplicationResult object showing the status.
1643#
1644# Example:
1645#
1646# -> { "execute": "query-xen-replication-status" }
1647# <- { "return": { "error": false } }
1648#
1649# Since: 2.9
1650##
1651{ 'command': 'query-xen-replication-status',
Marc-André Lureau335d10c2018-12-13 16:37:24 +04001652 'returns': 'ReplicationStatus',
1653 'if': 'defined(CONFIG_REPLICATION)' }
Markus Armbruster48685a82017-08-24 21:14:01 +02001654
1655##
1656# @xen-colo-do-checkpoint:
1657#
1658# Xen uses this command to notify replication to trigger a checkpoint.
1659#
1660# Returns: nothing.
1661#
1662# Example:
1663#
1664# -> { "execute": "xen-colo-do-checkpoint" }
1665# <- { "return": {} }
1666#
1667# Since: 2.9
1668##
Marc-André Lureau335d10c2018-12-13 16:37:24 +04001669{ 'command': 'xen-colo-do-checkpoint',
1670 'if': 'defined(CONFIG_REPLICATION)' }
Peter Xu02affd42018-05-02 18:47:36 +08001671
1672##
Zhang Chenf56c0062018-09-03 12:38:53 +08001673# @COLOStatus:
1674#
1675# The result format for 'query-colo-status'.
1676#
1677# @mode: COLO running mode. If COLO is running, this field will return
1678# 'primary' or 'secondary'.
1679#
Zhang Chen5cc8f9e2019-04-02 16:55:21 +08001680# @last-mode: COLO last running mode. If COLO is running, this field
Zhang Chen5ed0dec2019-03-22 18:13:33 +08001681# will return same like mode field, after failover we can
Zhang Chen966c0d42019-03-27 01:45:10 +08001682# use this field to get last colo mode. (since 4.0)
Zhang Chen5ed0dec2019-03-22 18:13:33 +08001683#
Zhang Chenf56c0062018-09-03 12:38:53 +08001684# @reason: describes the reason for the COLO exit.
1685#
Zhang Chenea3b23e2018-10-23 00:41:18 +08001686# Since: 3.1
Zhang Chenf56c0062018-09-03 12:38:53 +08001687##
1688{ 'struct': 'COLOStatus',
Zhang Chen5cc8f9e2019-04-02 16:55:21 +08001689 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode',
Zhang Chen5ed0dec2019-03-22 18:13:33 +08001690 'reason': 'COLOExitReason' } }
Zhang Chenf56c0062018-09-03 12:38:53 +08001691
1692##
1693# @query-colo-status:
1694#
1695# Query COLO status while the vm is running.
1696#
1697# Returns: A @COLOStatus object showing the status.
1698#
1699# Example:
1700#
1701# -> { "execute": "query-colo-status" }
Zhang Chenb5922fc2019-03-03 22:50:19 +08001702# <- { "return": { "mode": "primary", "reason": "request" } }
Zhang Chenf56c0062018-09-03 12:38:53 +08001703#
Zhang Chenea3b23e2018-10-23 00:41:18 +08001704# Since: 3.1
Zhang Chenf56c0062018-09-03 12:38:53 +08001705##
1706{ 'command': 'query-colo-status',
1707 'returns': 'COLOStatus' }
1708
1709##
Peter Xu02affd42018-05-02 18:47:36 +08001710# @migrate-recover:
1711#
1712# Provide a recovery migration stream URI.
1713#
1714# @uri: the URI to be used for the recovery of migration stream.
1715#
1716# Returns: nothing.
1717#
1718# Example:
1719#
1720# -> { "execute": "migrate-recover",
1721# "arguments": { "uri": "tcp:192.168.1.200:12345" } }
1722# <- { "return": {} }
1723#
Peter Maydell51f63ec2018-05-22 11:39:56 +01001724# Since: 3.0
Peter Xu02affd42018-05-02 18:47:36 +08001725##
Marc-André Lureaub0ddeba2018-12-08 15:16:04 +04001726{ 'command': 'migrate-recover',
1727 'data': { 'uri': 'str' },
Peter Xu02affd42018-05-02 18:47:36 +08001728 'allow-oob': true }
Peter Xubfbf89c2018-05-02 18:47:39 +08001729
1730##
1731# @migrate-pause:
1732#
1733# Pause a migration. Currently it only supports postcopy.
1734#
1735# Returns: nothing.
1736#
1737# Example:
1738#
1739# -> { "execute": "migrate-pause" }
1740# <- { "return": {} }
1741#
Peter Maydell51f63ec2018-05-22 11:39:56 +01001742# Since: 3.0
Peter Xubfbf89c2018-05-02 18:47:39 +08001743##
1744{ 'command': 'migrate-pause', 'allow-oob': true }
Jens Freimannd328e6f2019-10-29 12:48:59 +01001745
1746##
1747# @UNPLUG_PRIMARY:
1748#
1749# Emitted from source side of a migration when migration state is
1750# WAIT_UNPLUG. Device was unplugged by guest operating system.
1751# Device resources in QEMU are kept on standby to be able to re-plug it in case
1752# of migration failure.
1753#
1754# @device-id: QEMU device id of the unplugged device
1755#
1756# Since: 4.2
1757#
1758# Example:
1759# {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
1760#
1761##
1762{ 'event': 'UNPLUG_PRIMARY',
1763 'data': { 'device-id': 'str' } }
Chuan Zheng7df3aa32020-09-16 14:21:57 +08001764
1765##
1766# @DirtyRateStatus:
1767#
1768# An enumeration of dirtyrate status.
1769#
1770# @unstarted: the dirtyrate thread has not been started.
1771#
1772# @measuring: the dirtyrate thread is measuring.
1773#
1774# @measured: the dirtyrate thread has measured and results are available.
1775#
1776# Since: 5.2
1777#
1778##
1779{ 'enum': 'DirtyRateStatus',
1780 'data': [ 'unstarted', 'measuring', 'measured'] }
Chuan Zheng4c437252020-09-16 14:22:06 +08001781
1782##
1783# @DirtyRateInfo:
1784#
1785# Information about current dirty page rate of vm.
1786#
Chuan Zhengb1a859c2020-09-29 11:42:18 +08001787# @dirty-rate: an estimate of the dirty page rate of the VM in units of
1788# MB/s, present only when estimating the rate has completed.
Chuan Zheng4c437252020-09-16 14:22:06 +08001789#
1790# @status: status containing dirtyrate query status includes
1791# 'unstarted' or 'measuring' or 'measured'
1792#
1793# @start-time: start time in units of second for calculation
1794#
1795# @calc-time: time in units of second for sample dirty pages
1796#
1797# Since: 5.2
1798#
1799##
1800{ 'struct': 'DirtyRateInfo',
Chuan Zhengb1a859c2020-09-29 11:42:18 +08001801 'data': {'*dirty-rate': 'int64',
Chuan Zheng4c437252020-09-16 14:22:06 +08001802 'status': 'DirtyRateStatus',
1803 'start-time': 'int64',
1804 'calc-time': 'int64'} }
1805
1806##
1807# @calc-dirty-rate:
1808#
1809# start calculating dirty page rate for vm
1810#
1811# @calc-time: time in units of second for sample dirty pages
1812#
1813# Since: 5.2
1814#
1815# Example:
1816# {"command": "calc-dirty-rate", "data": {"calc-time": 1} }
1817#
1818##
1819{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64'} }
1820
1821##
1822# @query-dirty-rate:
1823#
1824# query dirty page rate in units of MB/s for vm
1825#
1826# Since: 5.2
1827##
1828{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' }