]> git.proxmox.com Git - mirror_qemu.git/blame - qapi/migration.json
Merge remote-tracking branch 'remotes/dgibson/tags/ppc-for-4.0-20190219' into staging
[mirror_qemu.git] / qapi / migration.json
CommitLineData
48685a8e
MA
1# -*- Mode: Python -*-
2#
3
4##
5# = Migration
6##
7
8{ 'include': 'common.json' }
9
10##
11# @MigrationStats:
12#
13# Detailed migration status.
14#
15# @transferred: amount of bytes already transferred to the target VM
16#
17# @remaining: amount of bytes remaining to be transferred to the target VM
18#
19# @total: total amount of bytes involved in the migration process
20#
21# @duplicate: number of duplicate (zero) pages (since 1.2)
22#
23# @skipped: number of skipped zero pages (since 1.5)
24#
25# @normal: number of normal pages (since 1.2)
26#
27# @normal-bytes: number of normal bytes sent (since 1.2)
28#
29# @dirty-pages-rate: number of pages dirtied by second by the
30# guest (since 1.3)
31#
32# @mbps: throughput in megabits/sec. (since 1.6)
33#
34# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
35#
36# @postcopy-requests: The number of page requests received from the destination
37# (since 2.7)
38#
39# @page-size: The number of bytes per page for the various page-based
40# statistics (since 2.10)
41#
a61c45bd
JQ
42# @multifd-bytes: The number of bytes sent through multifd (since 3.0)
43#
aecbfe9c
XG
44# @pages-per-second: the number of memory pages transferred per second
45# (Since 4.0)
46#
48685a8e
MA
47# Since: 0.14.0
48##
49{ 'struct': 'MigrationStats',
50 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
51 'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
52 'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
53 'mbps' : 'number', 'dirty-sync-count' : 'int',
a61c45bd 54 'postcopy-requests' : 'int', 'page-size' : 'int',
aecbfe9c 55 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64' } }
48685a8e
MA
56
57##
58# @XBZRLECacheStats:
59#
60# Detailed XBZRLE migration cache statistics
61#
62# @cache-size: XBZRLE cache size
63#
64# @bytes: amount of bytes already transferred to the target VM
65#
66# @pages: amount of pages transferred to the target VM
67#
68# @cache-miss: number of cache miss
69#
70# @cache-miss-rate: rate of cache miss (since 2.1)
71#
72# @overflow: number of overflows
73#
74# Since: 1.2
75##
76{ 'struct': 'XBZRLECacheStats',
77 'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
78 'cache-miss': 'int', 'cache-miss-rate': 'number',
79 'overflow': 'int' } }
80
76e03000
XG
81##
82# @CompressionStats:
83#
84# Detailed migration compression statistics
85#
86# @pages: amount of pages compressed and transferred to the target VM
87#
88# @busy: count of times that no free thread was available to compress data
89#
90# @busy-rate: rate of thread busy
91#
92# @compressed-size: amount of bytes after compression
93#
94# @compression-rate: rate of compressed size
95#
96# Since: 3.1
97##
98{ 'struct': 'CompressionStats',
99 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number',
100 'compressed-size': 'int', 'compression-rate': 'number' } }
101
48685a8e
MA
102##
103# @MigrationStatus:
104#
105# An enumeration of migration status.
106#
107# @none: no migration has ever happened.
108#
109# @setup: migration process has been initiated.
110#
111# @cancelling: in the process of cancelling migration.
112#
113# @cancelled: cancelling migration is finished.
114#
115# @active: in the process of doing migration.
116#
117# @postcopy-active: like active, but now in postcopy mode. (since 2.5)
118#
51f63ec7 119# @postcopy-paused: during postcopy but paused. (since 3.0)
a688d2c1 120#
51f63ec7 121# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0)
135b87b4 122#
48685a8e
MA
123# @completed: migration is finished.
124#
125# @failed: some error occurred during migration process.
126#
127# @colo: VM is in the process of fault tolerance, VM can not get into this
128# state unless colo capability is enabled for migration. (since 2.8)
129#
31e06077
DDAG
130# @pre-switchover: Paused before device serialisation. (since 2.11)
131#
132# @device: During device serialisation when pause-before-switchover is enabled
133# (since 2.11)
134#
48685a8e
MA
135# Since: 2.3
136#
137##
138{ 'enum': 'MigrationStatus',
139 'data': [ 'none', 'setup', 'cancelling', 'cancelled',
a688d2c1 140 'active', 'postcopy-active', 'postcopy-paused',
135b87b4 141 'postcopy-recover', 'completed', 'failed', 'colo',
31e06077 142 'pre-switchover', 'device' ] }
48685a8e
MA
143
144##
145# @MigrationInfo:
146#
147# Information about current migration process.
148#
149# @status: @MigrationStatus describing the current migration status.
150# If this field is not returned, no migration process
151# has been initiated
152#
153# @ram: @MigrationStats containing detailed migration
154# status, only returned if status is 'active' or
155# 'completed'(since 1.2)
156#
157# @disk: @MigrationStats containing detailed disk migration
158# status, only returned if status is 'active' and it is a block
159# migration
160#
161# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
162# migration statistics, only returned if XBZRLE feature is on and
163# status is 'active' or 'completed' (since 1.2)
164#
165# @total-time: total amount of milliseconds since migration started.
166# If migration has ended, it returns the total migration
167# time. (since 1.2)
168#
169# @downtime: only present when migration finishes correctly
170# total downtime in milliseconds for the guest.
171# (since 1.3)
172#
173# @expected-downtime: only present while migration is active
174# expected downtime in milliseconds for the guest in last walk
175# of the dirty bitmap. (since 1.3)
176#
177# @setup-time: amount of setup time in milliseconds _before_ the
178# iterations begin but _after_ the QMP command is issued. This is designed
179# to provide an accounting of any activities (such as RDMA pinning) which
180# may be expensive, but do not actually occur during the iterative
181# migration rounds themselves. (since 1.6)
182#
183# @cpu-throttle-percentage: percentage of time guest cpus are being
184# throttled during auto-converge. This is only present when auto-converge
185# has started throttling guest cpus. (Since 2.7)
186#
187# @error-desc: the human readable error description string, when
188# @status is 'failed'. Clients should not attempt to parse the
189# error strings. (Since 2.7)
65ace060
AP
190#
191# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
5e50cae4 192# live migration. This is only present when the postcopy-blocktime
51f63ec7 193# migration capability is enabled. (Since 3.0)
65ace060 194#
5e50cae4
DDAG
195# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
196# only present when the postcopy-blocktime migration capability
51f63ec7 197# is enabled. (Since 3.0)
65ace060 198#
76e03000
XG
199# @compression: migration compression statistics, only returned if compression
200# feature is on and status is 'active' or 'completed' (Since 3.1)
48685a8e
MA
201#
202# Since: 0.14.0
203##
204{ 'struct': 'MigrationInfo',
205 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
206 '*disk': 'MigrationStats',
207 '*xbzrle-cache': 'XBZRLECacheStats',
208 '*total-time': 'int',
209 '*expected-downtime': 'int',
210 '*downtime': 'int',
211 '*setup-time': 'int',
212 '*cpu-throttle-percentage': 'int',
65ace060
AP
213 '*error-desc': 'str',
214 '*postcopy-blocktime' : 'uint32',
76e03000
XG
215 '*postcopy-vcpu-blocktime': ['uint32'],
216 '*compression': 'CompressionStats'} }
48685a8e
MA
217
218##
219# @query-migrate:
220#
221# Returns information about current migration process. If migration
222# is active there will be another json-object with RAM migration
223# status and if block migration is active another one with block
224# migration status.
225#
226# Returns: @MigrationInfo
227#
228# Since: 0.14.0
229#
230# Example:
231#
232# 1. Before the first migration
233#
234# -> { "execute": "query-migrate" }
235# <- { "return": {} }
236#
237# 2. Migration is done and has succeeded
238#
239# -> { "execute": "query-migrate" }
240# <- { "return": {
241# "status": "completed",
be1d2c49 242# "total-time":12345,
243# "setup-time":12345,
244# "downtime":12345,
48685a8e
MA
245# "ram":{
246# "transferred":123,
247# "remaining":123,
248# "total":246,
48685a8e
MA
249# "duplicate":123,
250# "normal":123,
251# "normal-bytes":123456,
252# "dirty-sync-count":15
253# }
254# }
255# }
256#
257# 3. Migration is done and has failed
258#
259# -> { "execute": "query-migrate" }
260# <- { "return": { "status": "failed" } }
261#
262# 4. Migration is being performed and is not a block migration:
263#
264# -> { "execute": "query-migrate" }
265# <- {
266# "return":{
267# "status":"active",
be1d2c49 268# "total-time":12345,
269# "setup-time":12345,
270# "expected-downtime":12345,
48685a8e
MA
271# "ram":{
272# "transferred":123,
273# "remaining":123,
274# "total":246,
48685a8e
MA
275# "duplicate":123,
276# "normal":123,
277# "normal-bytes":123456,
278# "dirty-sync-count":15
279# }
280# }
281# }
282#
283# 5. Migration is being performed and is a block migration:
284#
285# -> { "execute": "query-migrate" }
286# <- {
287# "return":{
288# "status":"active",
be1d2c49 289# "total-time":12345,
290# "setup-time":12345,
291# "expected-downtime":12345,
48685a8e
MA
292# "ram":{
293# "total":1057024,
294# "remaining":1053304,
295# "transferred":3720,
48685a8e
MA
296# "duplicate":123,
297# "normal":123,
298# "normal-bytes":123456,
299# "dirty-sync-count":15
300# },
301# "disk":{
302# "total":20971520,
303# "remaining":20880384,
304# "transferred":91136
305# }
306# }
307# }
308#
309# 6. Migration is being performed and XBZRLE is active:
310#
311# -> { "execute": "query-migrate" }
312# <- {
313# "return":{
314# "status":"active",
be1d2c49 315# "total-time":12345,
316# "setup-time":12345,
317# "expected-downtime":12345,
48685a8e
MA
318# "ram":{
319# "total":1057024,
320# "remaining":1053304,
321# "transferred":3720,
48685a8e
MA
322# "duplicate":10,
323# "normal":3333,
324# "normal-bytes":3412992,
325# "dirty-sync-count":15
326# },
327# "xbzrle-cache":{
328# "cache-size":67108864,
329# "bytes":20971520,
330# "pages":2444343,
331# "cache-miss":2244,
332# "cache-miss-rate":0.123,
333# "overflow":34434
334# }
335# }
336# }
337#
338##
339{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
340
341##
342# @MigrationCapability:
343#
344# Migration capabilities enumeration
345#
346# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
347# This feature allows us to minimize migration traffic for certain work
348# loads, by sending compressed difference of the pages
349#
350# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
351# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
352# Disabled by default. (since 2.0)
353#
354# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
355# essentially saves 1MB of zeroes per block on the wire. Enabling requires
356# source and target VM to support this feature. To enable it is sufficient
357# to enable the capability on the source VM. The feature is disabled by
358# default. (since 1.6)
359#
360# @compress: Use multiple compression threads to accelerate live migration.
361# This feature can help to reduce the migration traffic, by sending
362# compressed pages. Please note that if compress and xbzrle are both
363# on, compress only takes effect in the ram bulk stage, after that,
364# it will be disabled and only xbzrle takes effect, this can help to
365# minimize migration traffic. The feature is disabled by default.
366# (since 2.4 )
367#
368# @events: generate events for each migration state change
369# (since 2.4 )
370#
371# @auto-converge: If enabled, QEMU will automatically throttle down the guest
372# to speed up convergence of RAM migration. (since 1.6)
373#
374# @postcopy-ram: Start executing on the migration target before all of RAM has
c2eb7f21
GK
375# been migrated, pulling the remaining pages along as needed. The
376# capacity must have the same setting on both source and target
377# or migration will not even start. NOTE: If the migration fails during
378# postcopy the VM will fail. (since 2.6)
48685a8e
MA
379#
380# @x-colo: If enabled, migration will never end, and the state of the VM on the
381# primary side will be migrated continuously to the VM on secondary
382# side, this process is called COarse-Grain LOck Stepping (COLO) for
383# Non-stop Service. (since 2.8)
384#
385# @release-ram: if enabled, qemu will free the migrated ram pages on the source
386# during postcopy-ram migration. (since 2.9)
387#
388# @block: If enabled, QEMU will also migrate the contents of all block
389# devices. Default is disabled. A possible alternative uses
390# mirror jobs to a builtin NBD server on the destination, which
391# offers more flexibility.
392# (Since 2.10)
393#
394# @return-path: If enabled, migration will use the return path even
395# for precopy. (since 2.10)
396#
93fbd031
DDAG
397# @pause-before-switchover: Pause outgoing migration before serialising device
398# state and before disabling block IO (since 2.11)
399#
30126bbf
JQ
400# @x-multifd: Use more than one fd for migration (since 2.11)
401#
55efc8c2
VSO
402# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps.
403# (since 2.12)
404#
f22f928e 405# @postcopy-blocktime: Calculate downtime for postcopy live migration
51f63ec7 406# (since 3.0)
f22f928e 407#
0f073f44
DDAG
408# @late-block-activate: If enabled, the destination will not activate block
409# devices (and thus take locks) immediately at the end of migration.
410# (since 3.0)
411#
48685a8e
MA
412# Since: 1.2
413##
414{ 'enum': 'MigrationCapability',
415 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
416 'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram',
55efc8c2 417 'block', 'return-path', 'pause-before-switchover', 'x-multifd',
0f073f44 418 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate' ] }
48685a8e
MA
419
420##
421# @MigrationCapabilityStatus:
422#
423# Migration capability information
424#
425# @capability: capability enum
426#
427# @state: capability state bool
428#
429# Since: 1.2
430##
431{ 'struct': 'MigrationCapabilityStatus',
432 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
433
434##
435# @migrate-set-capabilities:
436#
437# Enable/Disable the following migration capabilities (like xbzrle)
438#
439# @capabilities: json array of capability modifications to make
440#
441# Since: 1.2
442#
443# Example:
444#
445# -> { "execute": "migrate-set-capabilities" , "arguments":
446# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
447#
448##
449{ 'command': 'migrate-set-capabilities',
450 'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
451
452##
453# @query-migrate-capabilities:
454#
455# Returns information about the current migration capabilities status
456#
457# Returns: @MigrationCapabilitiesStatus
458#
459# Since: 1.2
460#
461# Example:
462#
463# -> { "execute": "query-migrate-capabilities" }
464# <- { "return": [
465# {"state": false, "capability": "xbzrle"},
466# {"state": false, "capability": "rdma-pin-all"},
467# {"state": false, "capability": "auto-converge"},
468# {"state": false, "capability": "zero-blocks"},
469# {"state": false, "capability": "compress"},
470# {"state": true, "capability": "events"},
471# {"state": false, "capability": "postcopy-ram"},
472# {"state": false, "capability": "x-colo"}
473# ]}
474#
475##
476{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
477
478##
479# @MigrationParameter:
480#
481# Migration parameters enumeration
482#
483# @compress-level: Set the compression level to be used in live migration,
484# the compression level is an integer between 0 and 9, where 0 means
485# no compression, 1 means the best compression speed, and 9 means best
486# compression ratio which will consume more CPU.
487#
488# @compress-threads: Set compression thread count to be used in live migration,
489# the compression thread count is an integer between 1 and 255.
490#
1d58872a
XG
491# @compress-wait-thread: Controls behavior when all compression threads are
492# currently busy. If true (default), wait for a free
493# compression thread to become available; otherwise,
494# send the page uncompressed. (Since 3.1)
495#
48685a8e
MA
496# @decompress-threads: Set decompression thread count to be used in live
497# migration, the decompression thread count is an integer between 1
498# and 255. Usually, decompression is at least 4 times as fast as
499# compression, so set the decompress-threads to the number about 1/4
500# of compress-threads is adequate.
501#
502# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
503# when migration auto-converge is activated. The
504# default value is 20. (Since 2.7)
505#
506# @cpu-throttle-increment: throttle percentage increase each time
507# auto-converge detects that migration is not making
508# progress. The default value is 10. (Since 2.7)
509#
510# @tls-creds: ID of the 'tls-creds' object that provides credentials for
511# establishing a TLS connection over the migration data channel.
512# On the outgoing side of the migration, the credentials must
513# be for a 'client' endpoint, while for the incoming side the
514# credentials must be for a 'server' endpoint. Setting this
515# will enable TLS for all migrations. The default is unset,
516# resulting in unsecured migration at the QEMU level. (Since 2.7)
517#
518# @tls-hostname: hostname of the target host for the migration. This is
519# required when using x509 based TLS credentials and the
520# migration URI does not already include a hostname. For
521# example if using fd: or exec: based migration, the
522# hostname must be provided so that the server's x509
523# certificate identity can be validated. (Since 2.7)
524#
525# @max-bandwidth: to set maximum speed for migration. maximum speed in
526# bytes per second. (Since 2.8)
527#
528# @downtime-limit: set maximum tolerated downtime for migration. maximum
529# downtime in milliseconds (Since 2.8)
530#
531# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
532# periodic mode. (Since 2.8)
533#
534# @block-incremental: Affects how much storage is migrated when the
535# block migration capability is enabled. When false, the entire
536# storage backing chain is migrated into a flattened image at
537# the destination; when true, only the active qcow2 layer is
538# migrated and the destination must already have access to the
539# same backing chain as was used on the source. (since 2.10)
540#
4075fb1c
JQ
541# @x-multifd-channels: Number of channels used to migrate data in
542# parallel. This is the same number that the
543# number of sockets used for migration. The
544# default value is 2 (since 2.11)
545#
40a5532f 546# @x-multifd-page-count: Number of pages sent together to a thread.
0fb86605
JQ
547# The default value is 16 (since 2.11)
548#
73af8dd8
JQ
549# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
550# needs to be a multiple of the target page size
551# and a power of 2
552# (Since 2.11)
553#
7e555c6c
DDAG
554# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
555# Defaults to 0 (unlimited). In bytes per second.
556# (Since 3.0)
4cbc9c7f
LQ
557#
558# @max-cpu-throttle: maximum cpu throttle percentage.
559# Defaults to 99. (Since 3.1)
48685a8e
MA
560# Since: 2.4
561##
562{ 'enum': 'MigrationParameter',
563 'data': ['compress-level', 'compress-threads', 'decompress-threads',
1d58872a 564 'compress-wait-thread',
48685a8e
MA
565 'cpu-throttle-initial', 'cpu-throttle-increment',
566 'tls-creds', 'tls-hostname', 'max-bandwidth',
4075fb1c 567 'downtime-limit', 'x-checkpoint-delay', 'block-incremental',
73af8dd8 568 'x-multifd-channels', 'x-multifd-page-count',
4cbc9c7f
LQ
569 'xbzrle-cache-size', 'max-postcopy-bandwidth',
570 'max-cpu-throttle' ] }
48685a8e
MA
571
572##
573# @MigrateSetParameters:
574#
575# @compress-level: compression level
576#
577# @compress-threads: compression thread count
578#
1d58872a
XG
579# @compress-wait-thread: Controls behavior when all compression threads are
580# currently busy. If true (default), wait for a free
581# compression thread to become available; otherwise,
582# send the page uncompressed. (Since 3.1)
583#
48685a8e
MA
584# @decompress-threads: decompression thread count
585#
586# @cpu-throttle-initial: Initial percentage of time guest cpus are
587# throttled when migration auto-converge is activated.
588# The default value is 20. (Since 2.7)
589#
590# @cpu-throttle-increment: throttle percentage increase each time
591# auto-converge detects that migration is not making
592# progress. The default value is 10. (Since 2.7)
593#
594# @tls-creds: ID of the 'tls-creds' object that provides credentials
595# for establishing a TLS connection over the migration data
596# channel. On the outgoing side of the migration, the credentials
597# must be for a 'client' endpoint, while for the incoming side the
598# credentials must be for a 'server' endpoint. Setting this
599# to a non-empty string enables TLS for all migrations.
600# An empty string means that QEMU will use plain text mode for
601# migration, rather than TLS (Since 2.9)
602# Previously (since 2.7), this was reported by omitting
603# tls-creds instead.
604#
605# @tls-hostname: hostname of the target host for the migration. This
606# is required when using x509 based TLS credentials and the
607# migration URI does not already include a hostname. For
608# example if using fd: or exec: based migration, the
609# hostname must be provided so that the server's x509
610# certificate identity can be validated. (Since 2.7)
611# An empty string means that QEMU will use the hostname
612# associated with the migration URI, if any. (Since 2.9)
613# Previously (since 2.7), this was reported by omitting
614# tls-hostname instead.
615#
616# @max-bandwidth: to set maximum speed for migration. maximum speed in
617# bytes per second. (Since 2.8)
618#
619# @downtime-limit: set maximum tolerated downtime for migration. maximum
620# downtime in milliseconds (Since 2.8)
621#
622# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
623#
624# @block-incremental: Affects how much storage is migrated when the
625# block migration capability is enabled. When false, the entire
626# storage backing chain is migrated into a flattened image at
627# the destination; when true, only the active qcow2 layer is
628# migrated and the destination must already have access to the
629# same backing chain as was used on the source. (since 2.10)
630#
4075fb1c
JQ
631# @x-multifd-channels: Number of channels used to migrate data in
632# parallel. This is the same number that the
633# number of sockets used for migration. The
634# default value is 2 (since 2.11)
635#
40a5532f 636# @x-multifd-page-count: Number of pages sent together to a thread.
0fb86605
JQ
637# The default value is 16 (since 2.11)
638#
73af8dd8
JQ
639# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
640# needs to be a multiple of the target page size
641# and a power of 2
642# (Since 2.11)
7e555c6c
DDAG
643#
644# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
645# Defaults to 0 (unlimited). In bytes per second.
646# (Since 3.0)
4cbc9c7f
LQ
647#
648# @max-cpu-throttle: maximum cpu throttle percentage.
649# The default value is 99. (Since 3.1)
650#
48685a8e
MA
651# Since: 2.4
652##
653# TODO either fuse back into MigrationParameters, or make
654# MigrationParameters members mandatory
655{ 'struct': 'MigrateSetParameters',
656 'data': { '*compress-level': 'int',
657 '*compress-threads': 'int',
1d58872a 658 '*compress-wait-thread': 'bool',
48685a8e
MA
659 '*decompress-threads': 'int',
660 '*cpu-throttle-initial': 'int',
661 '*cpu-throttle-increment': 'int',
662 '*tls-creds': 'StrOrNull',
663 '*tls-hostname': 'StrOrNull',
664 '*max-bandwidth': 'int',
665 '*downtime-limit': 'int',
666 '*x-checkpoint-delay': 'int',
4075fb1c 667 '*block-incremental': 'bool',
0fb86605 668 '*x-multifd-channels': 'int',
73af8dd8 669 '*x-multifd-page-count': 'int',
7e555c6c 670 '*xbzrle-cache-size': 'size',
4cbc9c7f
LQ
671 '*max-postcopy-bandwidth': 'size',
672 '*max-cpu-throttle': 'int' } }
48685a8e
MA
673
674##
675# @migrate-set-parameters:
676#
677# Set various migration parameters.
678#
679# Since: 2.4
680#
681# Example:
682#
683# -> { "execute": "migrate-set-parameters" ,
684# "arguments": { "compress-level": 1 } }
685#
686##
687{ 'command': 'migrate-set-parameters', 'boxed': true,
688 'data': 'MigrateSetParameters' }
689
690##
691# @MigrationParameters:
692#
693# The optional members aren't actually optional.
694#
695# @compress-level: compression level
696#
697# @compress-threads: compression thread count
698#
1d58872a
XG
699# @compress-wait-thread: Controls behavior when all compression threads are
700# currently busy. If true (default), wait for a free
701# compression thread to become available; otherwise,
702# send the page uncompressed. (Since 3.1)
703#
48685a8e
MA
704# @decompress-threads: decompression thread count
705#
706# @cpu-throttle-initial: Initial percentage of time guest cpus are
707# throttled when migration auto-converge is activated.
708# (Since 2.7)
709#
710# @cpu-throttle-increment: throttle percentage increase each time
711# auto-converge detects that migration is not making
712# progress. (Since 2.7)
713#
714# @tls-creds: ID of the 'tls-creds' object that provides credentials
715# for establishing a TLS connection over the migration data
716# channel. On the outgoing side of the migration, the credentials
717# must be for a 'client' endpoint, while for the incoming side the
718# credentials must be for a 'server' endpoint.
719# An empty string means that QEMU will use plain text mode for
720# migration, rather than TLS (Since 2.7)
721# Note: 2.8 reports this by omitting tls-creds instead.
722#
723# @tls-hostname: hostname of the target host for the migration. This
724# is required when using x509 based TLS credentials and the
725# migration URI does not already include a hostname. For
726# example if using fd: or exec: based migration, the
727# hostname must be provided so that the server's x509
728# certificate identity can be validated. (Since 2.7)
729# An empty string means that QEMU will use the hostname
730# associated with the migration URI, if any. (Since 2.9)
731# Note: 2.8 reports this by omitting tls-hostname instead.
732#
733# @max-bandwidth: to set maximum speed for migration. maximum speed in
734# bytes per second. (Since 2.8)
735#
736# @downtime-limit: set maximum tolerated downtime for migration. maximum
737# downtime in milliseconds (Since 2.8)
738#
739# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
740#
741# @block-incremental: Affects how much storage is migrated when the
742# block migration capability is enabled. When false, the entire
743# storage backing chain is migrated into a flattened image at
744# the destination; when true, only the active qcow2 layer is
745# migrated and the destination must already have access to the
746# same backing chain as was used on the source. (since 2.10)
747#
4075fb1c
JQ
748# @x-multifd-channels: Number of channels used to migrate data in
749# parallel. This is the same number that the
750# number of sockets used for migration.
751# The default value is 2 (since 2.11)
752#
40a5532f 753# @x-multifd-page-count: Number of pages sent together to a thread.
0fb86605
JQ
754# The default value is 16 (since 2.11)
755#
73af8dd8
JQ
756# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
757# needs to be a multiple of the target page size
758# and a power of 2
759# (Since 2.11)
7e555c6c
DDAG
760#
761# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
762# Defaults to 0 (unlimited). In bytes per second.
763# (Since 3.0)
4cbc9c7f
LQ
764#
765# @max-cpu-throttle: maximum cpu throttle percentage.
766# Defaults to 99.
767# (Since 3.1)
768#
48685a8e
MA
769# Since: 2.4
770##
771{ 'struct': 'MigrationParameters',
741d4086
JQ
772 'data': { '*compress-level': 'uint8',
773 '*compress-threads': 'uint8',
1d58872a 774 '*compress-wait-thread': 'bool',
741d4086
JQ
775 '*decompress-threads': 'uint8',
776 '*cpu-throttle-initial': 'uint8',
777 '*cpu-throttle-increment': 'uint8',
48685a8e
MA
778 '*tls-creds': 'str',
779 '*tls-hostname': 'str',
741d4086
JQ
780 '*max-bandwidth': 'size',
781 '*downtime-limit': 'uint64',
782 '*x-checkpoint-delay': 'uint32',
4075fb1c 783 '*block-incremental': 'bool' ,
741d4086
JQ
784 '*x-multifd-channels': 'uint8',
785 '*x-multifd-page-count': 'uint32',
7e555c6c 786 '*xbzrle-cache-size': 'size',
4cbc9c7f
LQ
787 '*max-postcopy-bandwidth': 'size',
788 '*max-cpu-throttle':'uint8'} }
48685a8e
MA
789
790##
791# @query-migrate-parameters:
792#
793# Returns information about the current migration parameters
794#
795# Returns: @MigrationParameters
796#
797# Since: 2.4
798#
799# Example:
800#
801# -> { "execute": "query-migrate-parameters" }
802# <- { "return": {
803# "decompress-threads": 2,
804# "cpu-throttle-increment": 10,
805# "compress-threads": 8,
806# "compress-level": 1,
807# "cpu-throttle-initial": 20,
808# "max-bandwidth": 33554432,
809# "downtime-limit": 300
810# }
811# }
812#
813##
814{ 'command': 'query-migrate-parameters',
815 'returns': 'MigrationParameters' }
816
817##
818# @client_migrate_info:
819#
820# Set migration information for remote display. This makes the server
821# ask the client to automatically reconnect using the new parameters
822# once migration finished successfully. Only implemented for SPICE.
823#
824# @protocol: must be "spice"
825# @hostname: migration target hostname
826# @port: spice tcp port for plaintext channels
827# @tls-port: spice tcp port for tls-secured channels
828# @cert-subject: server certificate subject
829#
830# Since: 0.14.0
831#
832# Example:
833#
834# -> { "execute": "client_migrate_info",
835# "arguments": { "protocol": "spice",
836# "hostname": "virt42.lab.kraxel.org",
837# "port": 1234 } }
838# <- { "return": {} }
839#
840##
841{ 'command': 'client_migrate_info',
842 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
843 '*tls-port': 'int', '*cert-subject': 'str' } }
844
845##
846# @migrate-start-postcopy:
847#
848# Followup to a migration command to switch the migration to postcopy mode.
c2eb7f21
GK
849# The postcopy-ram capability must be set on both source and destination
850# before the original migration command.
48685a8e
MA
851#
852# Since: 2.5
853#
854# Example:
855#
856# -> { "execute": "migrate-start-postcopy" }
857# <- { "return": {} }
858#
859##
860{ 'command': 'migrate-start-postcopy' }
861
862##
863# @MIGRATION:
864#
865# Emitted when a migration event happens
866#
867# @status: @MigrationStatus describing the current migration status.
868#
869# Since: 2.4
870#
871# Example:
872#
873# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
874# "event": "MIGRATION",
875# "data": {"status": "completed"} }
876#
877##
878{ 'event': 'MIGRATION',
879 'data': {'status': 'MigrationStatus'}}
880
881##
882# @MIGRATION_PASS:
883#
884# Emitted from the source side of a migration at the start of each pass
885# (when it syncs the dirty bitmap)
886#
887# @pass: An incrementing count (starting at 1 on the first pass)
888#
889# Since: 2.6
890#
891# Example:
892#
893# { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
894# "event": "MIGRATION_PASS", "data": {"pass": 2} }
895#
896##
897{ 'event': 'MIGRATION_PASS',
898 'data': { 'pass': 'int' } }
899
900##
901# @COLOMessage:
902#
903# The message transmission between Primary side and Secondary side.
904#
905# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
906#
907# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
908#
909# @checkpoint-reply: SVM gets PVM's checkpoint request
910#
911# @vmstate-send: VM's state will be sent by PVM.
912#
913# @vmstate-size: The total size of VMstate.
914#
915# @vmstate-received: VM's state has been received by SVM.
916#
917# @vmstate-loaded: VM's state has been loaded by SVM.
918#
919# Since: 2.8
920##
921{ 'enum': 'COLOMessage',
922 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
923 'vmstate-send', 'vmstate-size', 'vmstate-received',
924 'vmstate-loaded' ] }
925
926##
927# @COLOMode:
928#
41b6b779 929# The COLO current mode.
48685a8e 930#
41b6b779 931# @none: COLO is disabled.
48685a8e 932#
41b6b779 933# @primary: COLO node in primary side.
48685a8e 934#
41b6b779 935# @secondary: COLO node in slave side.
48685a8e
MA
936#
937# Since: 2.8
938##
939{ 'enum': 'COLOMode',
41b6b779 940 'data': [ 'none', 'primary', 'secondary'] }
48685a8e
MA
941
942##
943# @FailoverStatus:
944#
945# An enumeration of COLO failover status
946#
947# @none: no failover has ever happened
948#
949# @require: got failover requirement but not handled
950#
951# @active: in the process of doing failover
952#
953# @completed: finish the process of failover
954#
955# @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9)
956#
957# Since: 2.8
958##
959{ 'enum': 'FailoverStatus',
960 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
961
9ecff6d6
HZ
962##
963# @COLO_EXIT:
964#
965# Emitted when VM finishes COLO mode due to some errors happening or
966# at the request of users.
967#
968# @mode: report COLO mode when COLO exited.
969#
970# @reason: describes the reason for the COLO exit.
971#
972# Since: 3.1
973#
974# Example:
975#
976# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
977# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
978#
979##
980{ 'event': 'COLO_EXIT',
981 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
982
983##
984# @COLOExitReason:
985#
986# The reason for a COLO exit
987#
988# @none: no failover has ever happened. This can't occur in the
989# COLO_EXIT event, only in the result of query-colo-status.
990#
991# @request: COLO exit is due to an external request
992#
993# @error: COLO exit is due to an internal error
994#
995# Since: 3.1
996##
997{ 'enum': 'COLOExitReason',
998 'data': [ 'none', 'request', 'error' ] }
999
48685a8e
MA
1000##
1001# @x-colo-lost-heartbeat:
1002#
1003# Tell qemu that heartbeat is lost, request it to do takeover procedures.
1004# If this command is sent to the PVM, the Primary side will exit COLO mode.
1005# If sent to the Secondary, the Secondary side will run failover work,
1006# then takes over server operation to become the service VM.
1007#
1008# Since: 2.8
1009#
1010# Example:
1011#
1012# -> { "execute": "x-colo-lost-heartbeat" }
1013# <- { "return": {} }
1014#
1015##
1016{ 'command': 'x-colo-lost-heartbeat' }
1017
1018##
1019# @migrate_cancel:
1020#
1021# Cancel the current executing migration process.
1022#
1023# Returns: nothing on success
1024#
1025# Notes: This command succeeds even if there is no migration process running.
1026#
1027# Since: 0.14.0
1028#
1029# Example:
1030#
1031# -> { "execute": "migrate_cancel" }
1032# <- { "return": {} }
1033#
1034##
1035{ 'command': 'migrate_cancel' }
1036
89cfc02c
DDAG
1037##
1038# @migrate-continue:
1039#
1040# Continue migration when it's in a paused state.
1041#
1042# @state: The state the migration is currently expected to be in
1043#
1044# Returns: nothing on success
1045# Since: 2.11
1046# Example:
1047#
1048# -> { "execute": "migrate-continue" , "arguments":
1049# { "state": "pre-switchover" } }
1050# <- { "return": {} }
1051##
1052{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
1053
48685a8e
MA
1054##
1055# @migrate_set_downtime:
1056#
1057# Set maximum tolerated downtime for migration.
1058#
1059# @value: maximum downtime in seconds
1060#
1061# Returns: nothing on success
1062#
1063# Notes: This command is deprecated in favor of 'migrate-set-parameters'
1064#
1065# Since: 0.14.0
1066#
1067# Example:
1068#
1069# -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1070# <- { "return": {} }
1071#
1072##
1073{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
1074
1075##
1076# @migrate_set_speed:
1077#
1078# Set maximum speed for migration.
1079#
1080# @value: maximum speed in bytes per second.
1081#
1082# Returns: nothing on success
1083#
1084# Notes: This command is deprecated in favor of 'migrate-set-parameters'
1085#
1086# Since: 0.14.0
1087#
1088# Example:
1089#
1090# -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1091# <- { "return": {} }
1092#
1093##
1094{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
1095
1096##
1097# @migrate-set-cache-size:
1098#
1099# Set cache size to be used by XBZRLE migration
1100#
1101# @value: cache size in bytes
1102#
1103# The size will be rounded down to the nearest power of 2.
1104# The cache size can be modified before and during ongoing migration
1105#
1106# Returns: nothing on success
1107#
73af8dd8
JQ
1108# Notes: This command is deprecated in favor of 'migrate-set-parameters'
1109#
48685a8e
MA
1110# Since: 1.2
1111#
1112# Example:
1113#
1114# -> { "execute": "migrate-set-cache-size",
1115# "arguments": { "value": 536870912 } }
1116# <- { "return": {} }
1117#
1118##
1119{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
1120
1121##
1122# @query-migrate-cache-size:
1123#
1124# Query migration XBZRLE cache size
1125#
1126# Returns: XBZRLE cache size in bytes
1127#
73af8dd8
JQ
1128# Notes: This command is deprecated in favor of 'query-migrate-parameters'
1129#
48685a8e
MA
1130# Since: 1.2
1131#
1132# Example:
1133#
1134# -> { "execute": "query-migrate-cache-size" }
1135# <- { "return": 67108864 }
1136#
1137##
1138{ 'command': 'query-migrate-cache-size', 'returns': 'int' }
1139
1140##
1141# @migrate:
1142#
1143# Migrates the current running guest to another Virtual Machine.
1144#
1145# @uri: the Uniform Resource Identifier of the destination VM
1146#
1147# @blk: do block migration (full disk copy)
1148#
1149# @inc: incremental disk copy migration
1150#
1151# @detach: this argument exists only for compatibility reasons and
1152# is ignored by QEMU
1153#
51f63ec7 1154# @resume: resume one paused migration, default "off". (since 3.0)
7a4da28b 1155#
48685a8e
MA
1156# Returns: nothing on success
1157#
1158# Since: 0.14.0
1159#
1160# Notes:
1161#
1162# 1. The 'query-migrate' command should be used to check migration's progress
1163# and final result (this information is provided by the 'status' member)
1164#
1165# 2. All boolean arguments default to false
1166#
1167# 3. The user Monitor's "detach" argument is invalid in QMP and should not
1168# be used
1169#
1170# Example:
1171#
1172# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1173# <- { "return": {} }
1174#
1175##
1176{ 'command': 'migrate',
7a4da28b
PX
1177 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
1178 '*detach': 'bool', '*resume': 'bool' } }
48685a8e
MA
1179
1180##
1181# @migrate-incoming:
1182#
1183# Start an incoming migration, the qemu must have been started
1184# with -incoming defer
1185#
1186# @uri: The Uniform Resource Identifier identifying the source or
1187# address to listen on
1188#
1189# Returns: nothing on success
1190#
1191# Since: 2.3
1192#
1193# Notes:
1194#
1195# 1. It's a bad idea to use a string for the uri, but it needs to stay
1196# compatible with -incoming and the format of the uri is already exposed
1197# above libvirt.
1198#
1199# 2. QEMU must be started with -incoming defer to allow migrate-incoming to
1200# be used.
1201#
1202# 3. The uri format is the same as for -incoming
1203#
1204# Example:
1205#
1206# -> { "execute": "migrate-incoming",
1207# "arguments": { "uri": "tcp::4446" } }
1208# <- { "return": {} }
1209#
1210##
1211{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
1212
1213##
1214# @xen-save-devices-state:
1215#
1216# Save the state of all devices to file. The RAM and the block devices
1217# of the VM are not saved by this command.
1218#
1219# @filename: the file to save the state of the devices to as binary
1220# data. See xen-save-devices-state.txt for a description of the binary
1221# format.
1222#
5d6c599f
AP
1223# @live: Optional argument to ask QEMU to treat this command as part of a live
1224# migration. Default to true. (since 2.11)
1225#
48685a8e
MA
1226# Returns: Nothing on success
1227#
1228# Since: 1.1
1229#
1230# Example:
1231#
1232# -> { "execute": "xen-save-devices-state",
1233# "arguments": { "filename": "/tmp/save" } }
1234# <- { "return": {} }
1235#
1236##
5d6c599f
AP
1237{ 'command': 'xen-save-devices-state',
1238 'data': {'filename': 'str', '*live':'bool' } }
48685a8e
MA
1239
1240##
1241# @xen-set-replication:
1242#
1243# Enable or disable replication.
1244#
1245# @enable: true to enable, false to disable.
1246#
1247# @primary: true for primary or false for secondary.
1248#
1249# @failover: true to do failover, false to stop. but cannot be
1250# specified if 'enable' is true. default value is false.
1251#
1252# Returns: nothing.
1253#
1254# Example:
1255#
1256# -> { "execute": "xen-set-replication",
1257# "arguments": {"enable": true, "primary": false} }
1258# <- { "return": {} }
1259#
1260# Since: 2.9
1261##
1262{ 'command': 'xen-set-replication',
335d10cd
MAL
1263 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' },
1264 'if': 'defined(CONFIG_REPLICATION)' }
48685a8e
MA
1265
1266##
1267# @ReplicationStatus:
1268#
1269# The result format for 'query-xen-replication-status'.
1270#
1271# @error: true if an error happened, false if replication is normal.
1272#
1273# @desc: the human readable error description string, when
1274# @error is 'true'.
1275#
1276# Since: 2.9
1277##
1278{ 'struct': 'ReplicationStatus',
335d10cd
MAL
1279 'data': { 'error': 'bool', '*desc': 'str' },
1280 'if': 'defined(CONFIG_REPLICATION)' }
48685a8e
MA
1281
1282##
1283# @query-xen-replication-status:
1284#
1285# Query replication status while the vm is running.
1286#
1287# Returns: A @ReplicationResult object showing the status.
1288#
1289# Example:
1290#
1291# -> { "execute": "query-xen-replication-status" }
1292# <- { "return": { "error": false } }
1293#
1294# Since: 2.9
1295##
1296{ 'command': 'query-xen-replication-status',
335d10cd
MAL
1297 'returns': 'ReplicationStatus',
1298 'if': 'defined(CONFIG_REPLICATION)' }
48685a8e
MA
1299
1300##
1301# @xen-colo-do-checkpoint:
1302#
1303# Xen uses this command to notify replication to trigger a checkpoint.
1304#
1305# Returns: nothing.
1306#
1307# Example:
1308#
1309# -> { "execute": "xen-colo-do-checkpoint" }
1310# <- { "return": {} }
1311#
1312# Since: 2.9
1313##
335d10cd
MAL
1314{ 'command': 'xen-colo-do-checkpoint',
1315 'if': 'defined(CONFIG_REPLICATION)' }
02affd41 1316
f56c0065
ZC
1317##
1318# @COLOStatus:
1319#
1320# The result format for 'query-colo-status'.
1321#
1322# @mode: COLO running mode. If COLO is running, this field will return
1323# 'primary' or 'secondary'.
1324#
1325# @reason: describes the reason for the COLO exit.
1326#
ea3b23e5 1327# Since: 3.1
f56c0065
ZC
1328##
1329{ 'struct': 'COLOStatus',
1330 'data': { 'mode': 'COLOMode', 'reason': 'COLOExitReason' } }
1331
1332##
1333# @query-colo-status:
1334#
1335# Query COLO status while the vm is running.
1336#
1337# Returns: A @COLOStatus object showing the status.
1338#
1339# Example:
1340#
1341# -> { "execute": "query-colo-status" }
1342# <- { "return": { "mode": "primary", "active": true, "reason": "request" } }
1343#
ea3b23e5 1344# Since: 3.1
f56c0065
ZC
1345##
1346{ 'command': 'query-colo-status',
1347 'returns': 'COLOStatus' }
1348
02affd41
PX
1349##
1350# @migrate-recover:
1351#
1352# Provide a recovery migration stream URI.
1353#
1354# @uri: the URI to be used for the recovery of migration stream.
1355#
1356# Returns: nothing.
1357#
1358# Example:
1359#
1360# -> { "execute": "migrate-recover",
1361# "arguments": { "uri": "tcp:192.168.1.200:12345" } }
1362# <- { "return": {} }
1363#
51f63ec7 1364# Since: 3.0
02affd41 1365##
b0ddeba2
MAL
1366{ 'command': 'migrate-recover',
1367 'data': { 'uri': 'str' },
02affd41 1368 'allow-oob': true }
bfbf89c2
PX
1369
1370##
1371# @migrate-pause:
1372#
1373# Pause a migration. Currently it only supports postcopy.
1374#
1375# Returns: nothing.
1376#
1377# Example:
1378#
1379# -> { "execute": "migrate-pause" }
1380# <- { "return": {} }
1381#
51f63ec7 1382# Since: 3.0
bfbf89c2
PX
1383##
1384{ 'command': 'migrate-pause', 'allow-oob': true }