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