148685a8eSMarkus Armbruster# -*- Mode: Python -*- 2f7160f32SAndrea Bolognani# vim: filetype=python 348685a8eSMarkus Armbruster# 448685a8eSMarkus Armbruster 548685a8eSMarkus Armbruster## 648685a8eSMarkus Armbruster# = Migration 748685a8eSMarkus Armbruster## 848685a8eSMarkus Armbruster 948685a8eSMarkus Armbruster{ 'include': 'common.json' } 109aca82baSJuan Quintela{ 'include': 'sockets.json' } 1148685a8eSMarkus Armbruster 1248685a8eSMarkus Armbruster## 1348685a8eSMarkus Armbruster# @MigrationStats: 1448685a8eSMarkus Armbruster# 1548685a8eSMarkus Armbruster# Detailed migration status. 1648685a8eSMarkus Armbruster# 1748685a8eSMarkus Armbruster# @transferred: amount of bytes already transferred to the target VM 1848685a8eSMarkus Armbruster# 19a937b6aaSMarkus Armbruster# @remaining: amount of bytes remaining to be transferred to the 20a937b6aaSMarkus Armbruster# target VM 2148685a8eSMarkus Armbruster# 2248685a8eSMarkus Armbruster# @total: total amount of bytes involved in the migration process 2348685a8eSMarkus Armbruster# 2448685a8eSMarkus Armbruster# @duplicate: number of duplicate (zero) pages (since 1.2) 2548685a8eSMarkus Armbruster# 2648685a8eSMarkus Armbruster# @normal: number of normal pages (since 1.2) 2748685a8eSMarkus Armbruster# 2848685a8eSMarkus Armbruster# @normal-bytes: number of normal bytes sent (since 1.2) 2948685a8eSMarkus Armbruster# 30a937b6aaSMarkus Armbruster# @dirty-pages-rate: number of pages dirtied by second by the guest 31a937b6aaSMarkus Armbruster# (since 1.3) 3248685a8eSMarkus Armbruster# 3348685a8eSMarkus Armbruster# @mbps: throughput in megabits/sec. (since 1.6) 3448685a8eSMarkus Armbruster# 35a937b6aaSMarkus Armbruster# @dirty-sync-count: number of times that dirty ram was synchronized 36a937b6aaSMarkus Armbruster# (since 2.1) 3748685a8eSMarkus Armbruster# 38a937b6aaSMarkus Armbruster# @postcopy-requests: The number of page requests received from the 39a937b6aaSMarkus Armbruster# destination (since 2.7) 4048685a8eSMarkus Armbruster# 4148685a8eSMarkus Armbruster# @page-size: The number of bytes per page for the various page-based 4248685a8eSMarkus Armbruster# statistics (since 2.10) 4348685a8eSMarkus Armbruster# 44a61c45bdSJuan Quintela# @multifd-bytes: The number of bytes sent through multifd (since 3.0) 45a61c45bdSJuan Quintela# 46aecbfe9cSXiao Guangrong# @pages-per-second: the number of memory pages transferred per second 47aecbfe9cSXiao Guangrong# (Since 4.0) 48aecbfe9cSXiao Guangrong# 49ae680668SDavid Edmondson# @precopy-bytes: The number of bytes sent in the pre-copy phase 50ae680668SDavid Edmondson# (since 7.0). 51ae680668SDavid Edmondson# 52ae680668SDavid Edmondson# @downtime-bytes: The number of bytes sent while the guest is paused 53ae680668SDavid Edmondson# (since 7.0). 54ae680668SDavid Edmondson# 55ae680668SDavid Edmondson# @postcopy-bytes: The number of bytes sent during the post-copy phase 56ae680668SDavid Edmondson# (since 7.0). 57ae680668SDavid Edmondson# 58a937b6aaSMarkus Armbruster# @dirty-sync-missed-zero-copy: Number of times dirty RAM 59a937b6aaSMarkus Armbruster# synchronization could not avoid copying dirty pages. This is 60a937b6aaSMarkus Armbruster# between 0 and @dirty-sync-count * @multifd-channels. (since 61a937b6aaSMarkus Armbruster# 7.1) 62a937b6aaSMarkus Armbruster# 639bc6e893SMarkus Armbruster# Since: 0.14 6448685a8eSMarkus Armbruster## 6548685a8eSMarkus Armbruster{ 'struct': 'MigrationStats', 6648685a8eSMarkus Armbruster 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 677b24d326SJuan Quintela 'duplicate': 'int', 687b24d326SJuan Quintela 'normal': 'int', 6948685a8eSMarkus Armbruster 'normal-bytes': 'int', 'dirty-pages-rate': 'int', 7048685a8eSMarkus Armbruster 'mbps': 'number', 'dirty-sync-count': 'int', 71a61c45bdSJuan Quintela 'postcopy-requests': 'int', 'page-size': 'int', 72ae680668SDavid Edmondson 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', 73ae680668SDavid Edmondson 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', 74cf20c897SLeonardo Bras 'postcopy-bytes': 'uint64', 75cf20c897SLeonardo Bras 'dirty-sync-missed-zero-copy': 'uint64' } } 7648685a8eSMarkus Armbruster 7748685a8eSMarkus Armbruster## 7848685a8eSMarkus Armbruster# @XBZRLECacheStats: 7948685a8eSMarkus Armbruster# 8048685a8eSMarkus Armbruster# Detailed XBZRLE migration cache statistics 8148685a8eSMarkus Armbruster# 8248685a8eSMarkus Armbruster# @cache-size: XBZRLE cache size 8348685a8eSMarkus Armbruster# 8448685a8eSMarkus Armbruster# @bytes: amount of bytes already transferred to the target VM 8548685a8eSMarkus Armbruster# 8648685a8eSMarkus Armbruster# @pages: amount of pages transferred to the target VM 8748685a8eSMarkus Armbruster# 8848685a8eSMarkus Armbruster# @cache-miss: number of cache miss 8948685a8eSMarkus Armbruster# 9048685a8eSMarkus Armbruster# @cache-miss-rate: rate of cache miss (since 2.1) 9148685a8eSMarkus Armbruster# 92e460a4b1SWei Wang# @encoding-rate: rate of encoded bytes (since 5.1) 93e460a4b1SWei Wang# 9448685a8eSMarkus Armbruster# @overflow: number of overflows 9548685a8eSMarkus Armbruster# 9648685a8eSMarkus Armbruster# Since: 1.2 9748685a8eSMarkus Armbruster## 9848685a8eSMarkus Armbruster{ 'struct': 'XBZRLECacheStats', 998b9407a0SMarkus Armbruster 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 10048685a8eSMarkus Armbruster 'cache-miss': 'int', 'cache-miss-rate': 'number', 101e460a4b1SWei Wang 'encoding-rate': 'number', 'overflow': 'int' } } 10248685a8eSMarkus Armbruster 10348685a8eSMarkus Armbruster## 10476e03000SXiao Guangrong# @CompressionStats: 10576e03000SXiao Guangrong# 10676e03000SXiao Guangrong# Detailed migration compression statistics 10776e03000SXiao Guangrong# 10876e03000SXiao Guangrong# @pages: amount of pages compressed and transferred to the target VM 10976e03000SXiao Guangrong# 110a937b6aaSMarkus Armbruster# @busy: count of times that no free thread was available to compress 111a937b6aaSMarkus Armbruster# data 11276e03000SXiao Guangrong# 11376e03000SXiao Guangrong# @busy-rate: rate of thread busy 11476e03000SXiao Guangrong# 11576e03000SXiao Guangrong# @compressed-size: amount of bytes after compression 11676e03000SXiao Guangrong# 11776e03000SXiao Guangrong# @compression-rate: rate of compressed size 11876e03000SXiao Guangrong# 11976e03000SXiao Guangrong# Since: 3.1 12076e03000SXiao Guangrong## 12176e03000SXiao Guangrong{ 'struct': 'CompressionStats', 12276e03000SXiao Guangrong 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 12376e03000SXiao Guangrong 'compressed-size': 'int', 'compression-rate': 'number' } } 12476e03000SXiao Guangrong 12576e03000SXiao Guangrong## 12648685a8eSMarkus Armbruster# @MigrationStatus: 12748685a8eSMarkus Armbruster# 12848685a8eSMarkus Armbruster# An enumeration of migration status. 12948685a8eSMarkus Armbruster# 13048685a8eSMarkus Armbruster# @none: no migration has ever happened. 13148685a8eSMarkus Armbruster# 13248685a8eSMarkus Armbruster# @setup: migration process has been initiated. 13348685a8eSMarkus Armbruster# 13448685a8eSMarkus Armbruster# @cancelling: in the process of cancelling migration. 13548685a8eSMarkus Armbruster# 13648685a8eSMarkus Armbruster# @cancelled: cancelling migration is finished. 13748685a8eSMarkus Armbruster# 13848685a8eSMarkus Armbruster# @active: in the process of doing migration. 13948685a8eSMarkus Armbruster# 140a937b6aaSMarkus Armbruster# @postcopy-active: like active, but now in postcopy mode. (since 141a937b6aaSMarkus Armbruster# 2.5) 14248685a8eSMarkus Armbruster# 14351f63ec7SPeter Maydell# @postcopy-paused: during postcopy but paused. (since 3.0) 144a688d2c1SPeter Xu# 14501bed0ffSMarkus Armbruster# @postcopy-recover-setup: setup phase for a postcopy recovery 14601bed0ffSMarkus Armbruster# process, preparing for a recovery phase to start. (since 9.1) 1474146b77eSPeter Xu# 148a937b6aaSMarkus Armbruster# @postcopy-recover: trying to recover from a paused postcopy. (since 149a937b6aaSMarkus Armbruster# 3.0) 150135b87b4SPeter Xu# 15148685a8eSMarkus Armbruster# @completed: migration is finished. 15248685a8eSMarkus Armbruster# 15348685a8eSMarkus Armbruster# @failed: some error occurred during migration process. 15448685a8eSMarkus Armbruster# 155a937b6aaSMarkus Armbruster# @colo: VM is in the process of fault tolerance, VM can not get into 156a937b6aaSMarkus Armbruster# this state unless colo capability is enabled for migration. 157a937b6aaSMarkus Armbruster# (since 2.8) 15848685a8eSMarkus Armbruster# 15931e06077SDr. David Alan Gilbert# @pre-switchover: Paused before device serialisation. (since 2.11) 16031e06077SDr. David Alan Gilbert# 161a937b6aaSMarkus Armbruster# @device: During device serialisation when pause-before-switchover is 162a937b6aaSMarkus Armbruster# enabled (since 2.11) 16331e06077SDr. David Alan Gilbert# 164a937b6aaSMarkus Armbruster# @wait-unplug: wait for device unplug request by guest OS to be 165a937b6aaSMarkus Armbruster# completed. (since 4.2) 166c7e0acd5SJens Freimann# 16748685a8eSMarkus Armbruster# Since: 2.3 16848685a8eSMarkus Armbruster## 16948685a8eSMarkus Armbruster{ 'enum': 'MigrationStatus', 17048685a8eSMarkus Armbruster 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 171a688d2c1SPeter Xu 'active', 'postcopy-active', 'postcopy-paused', 1724146b77eSPeter Xu 'postcopy-recover-setup', 173135b87b4SPeter Xu 'postcopy-recover', 'completed', 'failed', 'colo', 174c7e0acd5SJens Freimann 'pre-switchover', 'device', 'wait-unplug' ] } 1753710586cSKirti Wankhede## 1763710586cSKirti Wankhede# @VfioStats: 1773710586cSKirti Wankhede# 1783710586cSKirti Wankhede# Detailed VFIO devices migration statistics 1793710586cSKirti Wankhede# 180a937b6aaSMarkus Armbruster# @transferred: amount of bytes transferred to the target VM by VFIO 181a937b6aaSMarkus Armbruster# devices 1823710586cSKirti Wankhede# 1833710586cSKirti Wankhede# Since: 5.2 1843710586cSKirti Wankhede## 1853710586cSKirti Wankhede{ 'struct': 'VfioStats', 1863710586cSKirti Wankhede 'data': {'transferred': 'int' } } 18748685a8eSMarkus Armbruster 18848685a8eSMarkus Armbruster## 18948685a8eSMarkus Armbruster# @MigrationInfo: 19048685a8eSMarkus Armbruster# 19148685a8eSMarkus Armbruster# Information about current migration process. 19248685a8eSMarkus Armbruster# 19348685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 194a937b6aaSMarkus Armbruster# If this field is not returned, no migration process has been 195a937b6aaSMarkus Armbruster# initiated 19648685a8eSMarkus Armbruster# 197a937b6aaSMarkus Armbruster# @ram: @MigrationStats containing detailed migration status, only 198a937b6aaSMarkus Armbruster# returned if status is 'active' or 'completed'(since 1.2) 19948685a8eSMarkus Armbruster# 20048685a8eSMarkus Armbruster# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 20148685a8eSMarkus Armbruster# migration statistics, only returned if XBZRLE feature is on and 20248685a8eSMarkus Armbruster# status is 'active' or 'completed' (since 1.2) 20348685a8eSMarkus Armbruster# 20448685a8eSMarkus Armbruster# @total-time: total amount of milliseconds since migration started. 205a937b6aaSMarkus Armbruster# If migration has ended, it returns the total migration time. 206a937b6aaSMarkus Armbruster# (since 1.2) 20748685a8eSMarkus Armbruster# 208a937b6aaSMarkus Armbruster# @downtime: only present when migration finishes correctly total 209a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest. (since 1.3) 21048685a8eSMarkus Armbruster# 211a937b6aaSMarkus Armbruster# @expected-downtime: only present while migration is active expected 212a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest in last walk of the dirty 213a937b6aaSMarkus Armbruster# bitmap. (since 1.3) 21448685a8eSMarkus Armbruster# 215a660eed4SPeter Maydell# @setup-time: amount of setup time in milliseconds *before* the 216a937b6aaSMarkus Armbruster# iterations begin but *after* the QMP command is issued. This is 217a937b6aaSMarkus Armbruster# designed to provide an accounting of any activities (such as 218a937b6aaSMarkus Armbruster# RDMA pinning) which may be expensive, but do not actually occur 219a937b6aaSMarkus Armbruster# during the iterative migration rounds themselves. (since 1.6) 22048685a8eSMarkus Armbruster# 22148685a8eSMarkus Armbruster# @cpu-throttle-percentage: percentage of time guest cpus are being 222a937b6aaSMarkus Armbruster# throttled during auto-converge. This is only present when 223a937b6aaSMarkus Armbruster# auto-converge has started throttling guest cpus. (Since 2.7) 22448685a8eSMarkus Armbruster# 225c94143e5SPeter Xu# @error-desc: the human readable error description string. Clients 226c94143e5SPeter Xu# should not attempt to parse the error strings. (Since 2.7) 22748685a8eSMarkus Armbruster# 228a937b6aaSMarkus Armbruster# @postcopy-blocktime: total time when all vCPU were blocked during 229a937b6aaSMarkus Armbruster# postcopy live migration. This is only present when the 230a937b6aaSMarkus Armbruster# postcopy-blocktime migration capability is enabled. (Since 3.0) 23165ace060SAlexey Perevalov# 232a937b6aaSMarkus Armbruster# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. 233a937b6aaSMarkus Armbruster# This is only present when the postcopy-blocktime migration 234a937b6aaSMarkus Armbruster# capability is enabled. (Since 3.0) 23565ace060SAlexey Perevalov# 236a937b6aaSMarkus Armbruster# @socket-address: Only used for tcp, to know what the real port is 237a937b6aaSMarkus Armbruster# (Since 4.0) 2389aca82baSJuan Quintela# 239a937b6aaSMarkus Armbruster# @vfio: @VfioStats containing detailed VFIO devices migration 240a937b6aaSMarkus Armbruster# statistics, only returned if VFIO device is present, migration 241a937b6aaSMarkus Armbruster# is supported by all VFIO devices and status is 'active' or 242a937b6aaSMarkus Armbruster# 'completed' (since 5.2) 2433710586cSKirti Wankhede# 244a937b6aaSMarkus Armbruster# @blocked-reasons: A list of reasons an outgoing migration is 245a937b6aaSMarkus Armbruster# blocked. Present and non-empty when migration is blocked. 246e11ce6c0SMarkus Armbruster# (since 6.0) 247e11ce6c0SMarkus Armbruster# 24801bed0ffSMarkus Armbruster# @dirty-limit-throttle-time-per-round: Maximum throttle time (in 24901bed0ffSMarkus Armbruster# microseconds) of virtual CPUs each dirty ring full round, which 25001bed0ffSMarkus Armbruster# shows how MigrationCapability dirty-limit affects the guest 25101bed0ffSMarkus Armbruster# during live migration. (Since 8.1) 25215699cf5SHyman Huang(黄勇)# 2538abc8115SHyman Huang(黄勇)# @dirty-limit-ring-full-time: Estimated average dirty ring full time 2548abc8115SHyman Huang(黄勇)# (in microseconds) for each dirty ring full round. The value 2558abc8115SHyman Huang(黄勇)# equals the dirty ring memory size divided by the average dirty 2568abc8115SHyman Huang(黄勇)# page rate of the virtual CPU, which can be used to observe the 2578abc8115SHyman Huang(黄勇)# average memory load of the virtual CPU indirectly. Note that 2588abc8115SHyman Huang(黄勇)# zero means guest doesn't dirty memory. (Since 8.1) 25915699cf5SHyman Huang(黄勇)# 2609bc6e893SMarkus Armbruster# Since: 0.14 26148685a8eSMarkus Armbruster## 26248685a8eSMarkus Armbruster{ 'struct': 'MigrationInfo', 26348685a8eSMarkus Armbruster 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 2643710586cSKirti Wankhede '*vfio': 'VfioStats', 26548685a8eSMarkus Armbruster '*xbzrle-cache': 'XBZRLECacheStats', 26648685a8eSMarkus Armbruster '*total-time': 'int', 26748685a8eSMarkus Armbruster '*expected-downtime': 'int', 26848685a8eSMarkus Armbruster '*downtime': 'int', 26948685a8eSMarkus Armbruster '*setup-time': 'int', 27048685a8eSMarkus Armbruster '*cpu-throttle-percentage': 'int', 27165ace060SAlexey Perevalov '*error-desc': 'str', 2723af8554bSDr. David Alan Gilbert '*blocked-reasons': ['str'], 27365ace060SAlexey Perevalov '*postcopy-blocktime': 'uint32', 27476e03000SXiao Guangrong '*postcopy-vcpu-blocktime': ['uint32'], 27515699cf5SHyman Huang(黄勇) '*socket-address': ['SocketAddress'], 27615699cf5SHyman Huang(黄勇) '*dirty-limit-throttle-time-per-round': 'uint64', 27715699cf5SHyman Huang(黄勇) '*dirty-limit-ring-full-time': 'uint64'} } 27848685a8eSMarkus Armbruster 27948685a8eSMarkus Armbruster## 28048685a8eSMarkus Armbruster# @query-migrate: 28148685a8eSMarkus Armbruster# 28248685a8eSMarkus Armbruster# Returns information about current migration process. If migration 28348685a8eSMarkus Armbruster# is active there will be another json-object with RAM migration 284eef0bae3SFabiano Rosas# status. 28548685a8eSMarkus Armbruster# 28648685a8eSMarkus Armbruster# Returns: @MigrationInfo 28748685a8eSMarkus Armbruster# 2889bc6e893SMarkus Armbruster# Since: 0.14 28948685a8eSMarkus Armbruster# 290a9eab6e2SJohn Snow# .. qmp-example:: 291a9eab6e2SJohn Snow# :title: Before the first migration 29248685a8eSMarkus Armbruster# 29348685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 29448685a8eSMarkus Armbruster# <- { "return": {} } 29548685a8eSMarkus Armbruster# 296a9eab6e2SJohn Snow# .. qmp-example:: 297a9eab6e2SJohn Snow# :title: Migration is done and has succeeded 29848685a8eSMarkus Armbruster# 29948685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 30048685a8eSMarkus Armbruster# <- { "return": { 30148685a8eSMarkus Armbruster# "status": "completed", 302be1d2c49Sjialina01# "total-time":12345, 303be1d2c49Sjialina01# "setup-time":12345, 304be1d2c49Sjialina01# "downtime":12345, 30548685a8eSMarkus Armbruster# "ram":{ 30648685a8eSMarkus Armbruster# "transferred":123, 30748685a8eSMarkus Armbruster# "remaining":123, 30848685a8eSMarkus Armbruster# "total":246, 30948685a8eSMarkus Armbruster# "duplicate":123, 31048685a8eSMarkus Armbruster# "normal":123, 31148685a8eSMarkus Armbruster# "normal-bytes":123456, 31248685a8eSMarkus Armbruster# "dirty-sync-count":15 31348685a8eSMarkus Armbruster# } 31448685a8eSMarkus Armbruster# } 31548685a8eSMarkus Armbruster# } 31648685a8eSMarkus Armbruster# 317a9eab6e2SJohn Snow# .. qmp-example:: 318a9eab6e2SJohn Snow# :title: Migration is done and has failed 31948685a8eSMarkus Armbruster# 32048685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 32148685a8eSMarkus Armbruster# <- { "return": { "status": "failed" } } 32248685a8eSMarkus Armbruster# 323a9eab6e2SJohn Snow# .. qmp-example:: 324a9eab6e2SJohn Snow# :title: Migration is being performed 32548685a8eSMarkus Armbruster# 32648685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 32748685a8eSMarkus Armbruster# <- { 32848685a8eSMarkus Armbruster# "return":{ 32948685a8eSMarkus Armbruster# "status":"active", 330be1d2c49Sjialina01# "total-time":12345, 331be1d2c49Sjialina01# "setup-time":12345, 332be1d2c49Sjialina01# "expected-downtime":12345, 33348685a8eSMarkus Armbruster# "ram":{ 33448685a8eSMarkus Armbruster# "transferred":123, 33548685a8eSMarkus Armbruster# "remaining":123, 33648685a8eSMarkus Armbruster# "total":246, 33748685a8eSMarkus Armbruster# "duplicate":123, 33848685a8eSMarkus Armbruster# "normal":123, 33948685a8eSMarkus Armbruster# "normal-bytes":123456, 34048685a8eSMarkus Armbruster# "dirty-sync-count":15 34148685a8eSMarkus Armbruster# } 34248685a8eSMarkus Armbruster# } 34348685a8eSMarkus Armbruster# } 34448685a8eSMarkus Armbruster# 345a9eab6e2SJohn Snow# .. qmp-example:: 346a9eab6e2SJohn Snow# :title: Migration is being performed and XBZRLE is active 34748685a8eSMarkus Armbruster# 34848685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 34948685a8eSMarkus Armbruster# <- { 35048685a8eSMarkus Armbruster# "return":{ 35148685a8eSMarkus Armbruster# "status":"active", 352be1d2c49Sjialina01# "total-time":12345, 353be1d2c49Sjialina01# "setup-time":12345, 354be1d2c49Sjialina01# "expected-downtime":12345, 35548685a8eSMarkus Armbruster# "ram":{ 35648685a8eSMarkus Armbruster# "total":1057024, 35748685a8eSMarkus Armbruster# "remaining":1053304, 35848685a8eSMarkus Armbruster# "transferred":3720, 35948685a8eSMarkus Armbruster# "duplicate":10, 36048685a8eSMarkus Armbruster# "normal":3333, 36148685a8eSMarkus Armbruster# "normal-bytes":3412992, 36248685a8eSMarkus Armbruster# "dirty-sync-count":15 36348685a8eSMarkus Armbruster# }, 36448685a8eSMarkus Armbruster# "xbzrle-cache":{ 36548685a8eSMarkus Armbruster# "cache-size":67108864, 36648685a8eSMarkus Armbruster# "bytes":20971520, 36748685a8eSMarkus Armbruster# "pages":2444343, 36848685a8eSMarkus Armbruster# "cache-miss":2244, 36948685a8eSMarkus Armbruster# "cache-miss-rate":0.123, 370e460a4b1SWei Wang# "encoding-rate":80.1, 37148685a8eSMarkus Armbruster# "overflow":34434 37248685a8eSMarkus Armbruster# } 37348685a8eSMarkus Armbruster# } 37448685a8eSMarkus Armbruster# } 37548685a8eSMarkus Armbruster## 37648685a8eSMarkus Armbruster{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 37748685a8eSMarkus Armbruster 37848685a8eSMarkus Armbruster## 37948685a8eSMarkus Armbruster# @MigrationCapability: 38048685a8eSMarkus Armbruster# 38148685a8eSMarkus Armbruster# Migration capabilities enumeration 38248685a8eSMarkus Armbruster# 383a937b6aaSMarkus Armbruster# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 384a937b6aaSMarkus Armbruster# Encoding). This feature allows us to minimize migration traffic 385a937b6aaSMarkus Armbruster# for certain work loads, by sending compressed difference of the 386a937b6aaSMarkus Armbruster# pages 38748685a8eSMarkus Armbruster# 388a937b6aaSMarkus Armbruster# @rdma-pin-all: Controls whether or not the entire VM memory 389a937b6aaSMarkus Armbruster# footprint is mlock()'d on demand or all at once. Refer to 390a937b6aaSMarkus Armbruster# docs/rdma.txt for usage. Disabled by default. (since 2.0) 39148685a8eSMarkus Armbruster# 392a937b6aaSMarkus Armbruster# @zero-blocks: During storage migration encode blocks of zeroes 393a937b6aaSMarkus Armbruster# efficiently. This essentially saves 1MB of zeroes per block on 394a937b6aaSMarkus Armbruster# the wire. Enabling requires source and target VM to support 395a937b6aaSMarkus Armbruster# this feature. To enable it is sufficient to enable the 39601bed0ffSMarkus Armbruster# capability on the source VM. The feature is disabled by 39701bed0ffSMarkus Armbruster# default. (since 1.6) 39848685a8eSMarkus Armbruster# 399e4ceec29SJuan Quintela# @events: generate events for each migration state change (since 2.4) 40048685a8eSMarkus Armbruster# 401a937b6aaSMarkus Armbruster# @auto-converge: If enabled, QEMU will automatically throttle down 402a937b6aaSMarkus Armbruster# the guest to speed up convergence of RAM migration. (since 1.6) 40348685a8eSMarkus Armbruster# 404a937b6aaSMarkus Armbruster# @postcopy-ram: Start executing on the migration target before all of 405a937b6aaSMarkus Armbruster# RAM has been migrated, pulling the remaining pages along as 406a937b6aaSMarkus Armbruster# needed. The capacity must have the same setting on both source 407a937b6aaSMarkus Armbruster# and target or migration will not even start. NOTE: If the 408a937b6aaSMarkus Armbruster# migration fails during postcopy the VM will fail. (since 2.6) 40948685a8eSMarkus Armbruster# 410a937b6aaSMarkus Armbruster# @x-colo: If enabled, migration will never end, and the state of the 411a937b6aaSMarkus Armbruster# VM on the primary side will be migrated continuously to the VM 412a937b6aaSMarkus Armbruster# on secondary side, this process is called COarse-Grain LOck 413a937b6aaSMarkus Armbruster# Stepping (COLO) for Non-stop Service. (since 2.8) 41448685a8eSMarkus Armbruster# 415a937b6aaSMarkus Armbruster# @release-ram: if enabled, qemu will free the migrated ram pages on 416a937b6aaSMarkus Armbruster# the source during postcopy-ram migration. (since 2.9) 41748685a8eSMarkus Armbruster# 41848685a8eSMarkus Armbruster# @return-path: If enabled, migration will use the return path even 41948685a8eSMarkus Armbruster# for precopy. (since 2.10) 42048685a8eSMarkus Armbruster# 421a937b6aaSMarkus Armbruster# @pause-before-switchover: Pause outgoing migration before 422a937b6aaSMarkus Armbruster# serialising device state and before disabling block IO (since 423a937b6aaSMarkus Armbruster# 2.11) 42493fbd031SDr. David Alan Gilbert# 425cbfd6c95SJuan Quintela# @multifd: Use more than one fd for migration (since 4.0) 42630126bbfSJuan Quintela# 42755efc8c2SVladimir Sementsov-Ogievskiy# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 42855efc8c2SVladimir Sementsov-Ogievskiy# (since 2.12) 42955efc8c2SVladimir Sementsov-Ogievskiy# 430f22f928eSAlexey Perevalov# @postcopy-blocktime: Calculate downtime for postcopy live migration 43151f63ec7SPeter Maydell# (since 3.0) 432f22f928eSAlexey Perevalov# 433a937b6aaSMarkus Armbruster# @late-block-activate: If enabled, the destination will not activate 434a937b6aaSMarkus Armbruster# block devices (and thus take locks) immediately at the end of 435a937b6aaSMarkus Armbruster# migration. (since 3.0) 4360f073f44SDr. David Alan Gilbert# 4379e272073SMarkus Armbruster# @x-ignore-shared: If enabled, QEMU will not migrate shared memory 4389e272073SMarkus Armbruster# that is accessible on the destination machine. (since 4.0) 43918269069SYury Kotov# 440b9d68df6SYury Kotov# @validate-uuid: Send the UUID of the source to allow the destination 441b9d68df6SYury Kotov# to ensure it is the same. (since 4.2) 442b9d68df6SYury Kotov# 443a937b6aaSMarkus Armbruster# @background-snapshot: If enabled, the migration stream will be a 444a937b6aaSMarkus Armbruster# snapshot of the VM exactly at the point when the migration 445209e64d9SMarkus Armbruster# procedure starts. The VM RAM is saved with running VM. 446209e64d9SMarkus Armbruster# (since 6.0) 4476e8c25b4SAndrey Gruzdev# 448a937b6aaSMarkus Armbruster# @zero-copy-send: Controls behavior on sending memory pages on 449a937b6aaSMarkus Armbruster# migration. When true, enables a zero-copy mechanism for sending 450a937b6aaSMarkus Armbruster# memory pages, if host supports it. Requires that QEMU be 451a937b6aaSMarkus Armbruster# permitted to use locked memory for guest RAM pages. (since 7.1) 452a937b6aaSMarkus Armbruster# 453a937b6aaSMarkus Armbruster# @postcopy-preempt: If enabled, the migration process will allow 454a937b6aaSMarkus Armbruster# postcopy requests to preempt precopy stream, so postcopy 455a937b6aaSMarkus Armbruster# requests will be handled faster. This is a performance feature 456a937b6aaSMarkus Armbruster# and should not affect the correctness of postcopy migration. 457ce5b0f4aSPeter Xu# (since 7.1) 4581abaec9aSLeonardo Bras# 4596574232fSAvihai Horon# @switchover-ack: If enabled, migration will not stop the source VM 4606574232fSAvihai Horon# and complete the migration until an ACK is received from the 4616574232fSAvihai Horon# destination that it's OK to do so. Exactly when this ACK is 4629e272073SMarkus Armbruster# sent depends on the migrated devices that use this feature. For 4639e272073SMarkus Armbruster# example, a device can use it to make sure some of its data is 4649e272073SMarkus Armbruster# sent and loaded in the destination before doing switchover. 4656574232fSAvihai Horon# This can reduce downtime if devices that support this capability 4666574232fSAvihai Horon# are present. 'return-path' capability must be enabled to use 4676574232fSAvihai Horon# it. (since 8.1) 4686574232fSAvihai Horon# 469ef965377SHyman Huang(黄勇)# @dirty-limit: If enabled, migration will throttle vCPUs as needed to 470ef965377SHyman Huang(黄勇)# keep their dirty page rate within @vcpu-dirty-limit. This can 471ef965377SHyman Huang(黄勇)# improve responsiveness of large guests during live migration, 472ef965377SHyman Huang(黄勇)# and can result in more stable read performance. Requires KVM 473ef965377SHyman Huang(黄勇)# with accelerator property "dirty-ring-size" set. (Since 8.1) 474dc623955SHyman Huang(黄勇)# 4754ed49febSFabiano Rosas# @mapped-ram: Migrate using fixed offsets in the migration file for 4764ed49febSFabiano Rosas# each RAM page. Requires a migration URI that supports seeking, 4774ed49febSFabiano Rosas# such as a file. (since 9.0) 4784ed49febSFabiano Rosas# 4799fb49daaSMarkus Armbruster# Features: 480a937b6aaSMarkus Armbruster# 4819fb49daaSMarkus Armbruster# @unstable: Members @x-colo and @x-ignore-shared are experimental. 4829fb49daaSMarkus Armbruster# 48348685a8eSMarkus Armbruster# Since: 1.2 48448685a8eSMarkus Armbruster## 48548685a8eSMarkus Armbruster{ 'enum': 'MigrationCapability', 48648685a8eSMarkus Armbruster 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 487864128dfSJuan Quintela 'events', 'postcopy-ram', 4889fb49daaSMarkus Armbruster { 'name': 'x-colo', 'features': [ 'unstable' ] }, 4899fb49daaSMarkus Armbruster 'release-ram', 49066db46caSJuan Quintela 'return-path', 'pause-before-switchover', 'multifd', 49118269069SYury Kotov 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 4929fb49daaSMarkus Armbruster { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 4931abaec9aSLeonardo Bras 'validate-uuid', 'background-snapshot', 494dc623955SHyman Huang(黄勇) 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 4954ed49febSFabiano Rosas 'dirty-limit', 'mapped-ram'] } 49648685a8eSMarkus Armbruster 49748685a8eSMarkus Armbruster## 49848685a8eSMarkus Armbruster# @MigrationCapabilityStatus: 49948685a8eSMarkus Armbruster# 50048685a8eSMarkus Armbruster# Migration capability information 50148685a8eSMarkus Armbruster# 50248685a8eSMarkus Armbruster# @capability: capability enum 50348685a8eSMarkus Armbruster# 50448685a8eSMarkus Armbruster# @state: capability state bool 50548685a8eSMarkus Armbruster# 50648685a8eSMarkus Armbruster# Since: 1.2 50748685a8eSMarkus Armbruster## 50848685a8eSMarkus Armbruster{ 'struct': 'MigrationCapabilityStatus', 50948685a8eSMarkus Armbruster 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 51048685a8eSMarkus Armbruster 51148685a8eSMarkus Armbruster## 51248685a8eSMarkus Armbruster# @migrate-set-capabilities: 51348685a8eSMarkus Armbruster# 51448685a8eSMarkus Armbruster# Enable/Disable the following migration capabilities (like xbzrle) 51548685a8eSMarkus Armbruster# 51648685a8eSMarkus Armbruster# @capabilities: json array of capability modifications to make 51748685a8eSMarkus Armbruster# 51848685a8eSMarkus Armbruster# Since: 1.2 51948685a8eSMarkus Armbruster# 52014b48aaaSJohn Snow# .. qmp-example:: 52148685a8eSMarkus Armbruster# 52248685a8eSMarkus Armbruster# -> { "execute": "migrate-set-capabilities" , "arguments": 52348685a8eSMarkus Armbruster# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 52437fa48a4SMarkus Armbruster# <- { "return": {} } 52548685a8eSMarkus Armbruster## 52648685a8eSMarkus Armbruster{ 'command': 'migrate-set-capabilities', 52748685a8eSMarkus Armbruster 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 52848685a8eSMarkus Armbruster 52948685a8eSMarkus Armbruster## 53048685a8eSMarkus Armbruster# @query-migrate-capabilities: 53148685a8eSMarkus Armbruster# 53248685a8eSMarkus Armbruster# Returns information about the current migration capabilities status 53348685a8eSMarkus Armbruster# 534d93ed1bdSMarkus Armbruster# Returns: @MigrationCapabilityStatus 53548685a8eSMarkus Armbruster# 53648685a8eSMarkus Armbruster# Since: 1.2 53748685a8eSMarkus Armbruster# 53814b48aaaSJohn Snow# .. qmp-example:: 53948685a8eSMarkus Armbruster# 54048685a8eSMarkus Armbruster# -> { "execute": "query-migrate-capabilities" } 54148685a8eSMarkus Armbruster# <- { "return": [ 54248685a8eSMarkus Armbruster# {"state": false, "capability": "xbzrle"}, 54348685a8eSMarkus Armbruster# {"state": false, "capability": "rdma-pin-all"}, 54448685a8eSMarkus Armbruster# {"state": false, "capability": "auto-converge"}, 54548685a8eSMarkus Armbruster# {"state": false, "capability": "zero-blocks"}, 54648685a8eSMarkus Armbruster# {"state": true, "capability": "events"}, 54748685a8eSMarkus Armbruster# {"state": false, "capability": "postcopy-ram"}, 54848685a8eSMarkus Armbruster# {"state": false, "capability": "x-colo"} 54948685a8eSMarkus Armbruster# ]} 55048685a8eSMarkus Armbruster## 55148685a8eSMarkus Armbruster{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 55248685a8eSMarkus Armbruster 55348685a8eSMarkus Armbruster## 55496eef042SJuan Quintela# @MultiFDCompression: 55596eef042SJuan Quintela# 55696eef042SJuan Quintela# An enumeration of multifd compression methods. 55796eef042SJuan Quintela# 55896eef042SJuan Quintela# @none: no compression. 559a937b6aaSMarkus Armbruster# 5607ec2c2b3SJuan Quintela# @zlib: use zlib compression method. 561a937b6aaSMarkus Armbruster# 56287dc6f5fSJuan Quintela# @zstd: use zstd compression method. 56396eef042SJuan Quintela# 564354cac28SYuan Liu# @qatzip: use qatzip compression method. (Since 9.2) 565354cac28SYuan Liu# 56601bed0ffSMarkus Armbruster# @qpl: use qpl compression method. Query Processing Library(qpl) is 56701bed0ffSMarkus Armbruster# based on the deflate compression algorithm and use the Intel 568354cac28SYuan Liu# In-Memory Analytics Accelerator(IAA) accelerated compression and 569f3d8bb75SShameer Kolothum# decompression. (Since 9.1) 570f3d8bb75SShameer Kolothum# 57196eef042SJuan Quintela# @uadk: use UADK library compression method. (Since 9.1) 57296eef042SJuan Quintela# 57396eef042SJuan Quintela# Since: 5.0 574*7b29353fSMarkus Armbruster## 57587dc6f5fSJuan Quintela{ 'enum': 'MultiFDCompression', 576354cac28SYuan Liu 'prefix': 'MULTIFD_COMPRESSION', 577f3d8bb75SShameer Kolothum 'data': [ 'none', 'zlib', 578f3d8bb75SShameer Kolothum { 'name': 'zstd', 'if': 'CONFIG_ZSTD' }, 57996eef042SJuan Quintela { 'name': 'qatzip', 'if': 'CONFIG_QATZIP'}, 58096eef042SJuan Quintela { 'name': 'qpl', 'if': 'CONFIG_QPL' }, 581eea1e5c9SSteve Sistare { 'name': 'uadk', 'if': 'CONFIG_UADK' } ] } 582eea1e5c9SSteve Sistare 583eea1e5c9SSteve Sistare## 584eea1e5c9SSteve Sistare# @MigMode: 585209e64d9SMarkus Armbruster# 586209e64d9SMarkus Armbruster# @normal: the original form of migration. (since 8.2) 587209e64d9SMarkus Armbruster# 588ce5db1cbSSteve Sistare# @cpr-reboot: The migrate command stops the VM and saves state to the 58987a28487SSteve Sistare# URI. After quitting QEMU, the user resumes by running QEMU 59087a28487SSteve Sistare# -incoming. 59187a28487SSteve Sistare# 592ce5db1cbSSteve Sistare# This mode allows the user to quit QEMU, optionally update and 59387a28487SSteve Sistare# reboot the OS, and restart QEMU. If the user reboots, the URI 59487a28487SSteve Sistare# must persist across the reboot, such as by using a file. 59587a28487SSteve Sistare# 596ce5db1cbSSteve Sistare# Unlike normal mode, the use of certain local storage options 597209e64d9SMarkus Armbruster# does not block the migration, but the user must not modify the 598209e64d9SMarkus Armbruster# contents of guest block devices between the quit and restart. 59987a28487SSteve Sistare# 600ce5db1cbSSteve Sistare# This mode supports VFIO devices provided the user first puts the 60187a28487SSteve Sistare# guest in the suspended runstate, such as by issuing 60287a28487SSteve Sistare# guest-suspend-ram to the QEMU guest agent. 60387a28487SSteve Sistare# 60487a28487SSteve Sistare# Best performance is achieved when the memory backend is shared 60587a28487SSteve Sistare# and the @x-ignore-shared migration capability is set, but this 606ce5db1cbSSteve Sistare# is not required. Further, if the user reboots before restarting 60787a28487SSteve Sistare# such a configuration, the shared memory must persist across the 60887a28487SSteve Sistare# reboot, such as by backing it with a dax device. 609cbdafc1bSSteve Sistare# 610a87e6451SSteve Sistare# @cpr-reboot may not be used with postcopy, background-snapshot, 611eea1e5c9SSteve Sistare# or COLO. 612eea1e5c9SSteve Sistare# 613a87e6451SSteve Sistare# (since 8.2) 614eea1e5c9SSteve Sistare## 615eea1e5c9SSteve Sistare{ 'enum': 'MigMode', 6165fdbb1dfSHao Xiang 'data': [ 'normal', 'cpr-reboot' ] } 6175fdbb1dfSHao Xiang 6185fdbb1dfSHao Xiang## 6195fdbb1dfSHao Xiang# @ZeroPageDetection: 6205fdbb1dfSHao Xiang# 6215fdbb1dfSHao Xiang# @none: Do not perform zero page checking. 622303e6f54SHao Xiang# 623209e64d9SMarkus Armbruster# @legacy: Perform zero page checking in main migration thread. 624209e64d9SMarkus Armbruster# 625303e6f54SHao Xiang# @multifd: Perform zero page checking in multifd sender thread if 6265fdbb1dfSHao Xiang# multifd migration is enabled, else in the main migration thread 6275fdbb1dfSHao Xiang# as for @legacy. 6285fdbb1dfSHao Xiang# 629303e6f54SHao Xiang# Since: 9.0 6305fdbb1dfSHao Xiang## 6315fdbb1dfSHao Xiang{ 'enum': 'ZeroPageDetection', 6326e9f21a2SPeter Krempa 'data': [ 'none', 'legacy', 'multifd' ] } 6336e9f21a2SPeter Krempa 634a937b6aaSMarkus Armbruster## 635a937b6aaSMarkus Armbruster# @BitmapMigrationBitmapAliasTransform: 6366e9f21a2SPeter Krempa# 6376e9f21a2SPeter Krempa# @persistent: If present, the bitmap will be made persistent or 6386e9f21a2SPeter Krempa# transient depending on this parameter. 6396e9f21a2SPeter Krempa# 6406e9f21a2SPeter Krempa# Since: 6.0 6416e9f21a2SPeter Krempa## 6426e9f21a2SPeter Krempa{ 'struct': 'BitmapMigrationBitmapAliasTransform', 6436e9f21a2SPeter Krempa 'data': { 6446e9f21a2SPeter Krempa '*persistent': 'bool' 64531e4c354SMax Reitz } } 64631e4c354SMax Reitz 64731e4c354SMax Reitz## 64831e4c354SMax Reitz# @BitmapMigrationBitmapAlias: 64931e4c354SMax Reitz# 65031e4c354SMax Reitz# @name: The name of the bitmap. 65131e4c354SMax Reitz# 652a937b6aaSMarkus Armbruster# @alias: An alias name for migration (for example the bitmap name on 653a937b6aaSMarkus Armbruster# the opposite site). 6546e9f21a2SPeter Krempa# 65531e4c354SMax Reitz# @transform: Allows the modification of the migrated bitmap. (since 65631e4c354SMax Reitz# 6.0) 65731e4c354SMax Reitz# 65831e4c354SMax Reitz# Since: 5.2 65931e4c354SMax Reitz## 6606e9f21a2SPeter Krempa{ 'struct': 'BitmapMigrationBitmapAlias', 6616e9f21a2SPeter Krempa 'data': { 66231e4c354SMax Reitz 'name': 'str', 66331e4c354SMax Reitz 'alias': 'str', 66431e4c354SMax Reitz '*transform': 'BitmapMigrationBitmapAliasTransform' 66531e4c354SMax Reitz } } 66631e4c354SMax Reitz 66731e4c354SMax Reitz## 66831e4c354SMax Reitz# @BitmapMigrationNodeAlias: 66931e4c354SMax Reitz# 67031e4c354SMax Reitz# Maps a block node name and the bitmaps it has to aliases for dirty 67131e4c354SMax Reitz# bitmap migration. 672a937b6aaSMarkus Armbruster# 673a937b6aaSMarkus Armbruster# @node-name: A block node name. 67431e4c354SMax Reitz# 67531e4c354SMax Reitz# @alias: An alias block node name for migration (for example the node 67631e4c354SMax Reitz# name on the opposite site). 67731e4c354SMax Reitz# 67831e4c354SMax Reitz# @bitmaps: Mappings for the bitmaps on this node. 67931e4c354SMax Reitz# 68031e4c354SMax Reitz# Since: 5.2 68131e4c354SMax Reitz## 68231e4c354SMax Reitz{ 'struct': 'BitmapMigrationNodeAlias', 68331e4c354SMax Reitz 'data': { 68431e4c354SMax Reitz 'node-name': 'str', 68531e4c354SMax Reitz 'alias': 'str', 68631e4c354SMax Reitz 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 68748685a8eSMarkus Armbruster } } 68848685a8eSMarkus Armbruster 68948685a8eSMarkus Armbruster## 69048685a8eSMarkus Armbruster# @MigrationParameter: 691a937b6aaSMarkus Armbruster# 692a937b6aaSMarkus Armbruster# Migration parameters enumeration 693ee3d96baSDr. David Alan Gilbert# 694a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 695a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 696ee3d96baSDr. David Alan Gilbert# 697a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 698a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 699ee3d96baSDr. David Alan Gilbert# 700a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 701a937b6aaSMarkus Armbruster# migration (Since 4.0) 702ee3d96baSDr. David Alan Gilbert# 703a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 704a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 705a937b6aaSMarkus Armbruster# 706dc14a470SKeqian Zhu# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 707a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 708a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 70948685a8eSMarkus Armbruster# 71048685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 71148685a8eSMarkus Armbruster# throttled when migration auto-converge is activated. The 712a937b6aaSMarkus Armbruster# default value is 20. (Since 2.7) 713a937b6aaSMarkus Armbruster# 71448685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 715a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 716a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 717a937b6aaSMarkus Armbruster# 718a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 719a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 720a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 721a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 722a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 723a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 724a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 725a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 726a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 727cbbf8182SKeqian Zhu# traditional throttling, meanwhile the throttle increment won't 728a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 729a937b6aaSMarkus Armbruster# 5.1) 730a937b6aaSMarkus Armbruster# 731a937b6aaSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 732e8c5503aSMarkus Armbruster# for establishing a TLS connection over the migration data 733e8c5503aSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 734e8c5503aSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 735e8c5503aSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this to a 73648685a8eSMarkus Armbruster# non-empty string enables TLS for all migrations. An empty 737e8c5503aSMarkus Armbruster# string means that QEMU will use plain text mode for migration, 738e8c5503aSMarkus Armbruster# rather than TLS. (Since 2.7) 739e8c5503aSMarkus Armbruster# 740e8c5503aSMarkus Armbruster# @tls-hostname: migration target's hostname for validating the 741e8c5503aSMarkus Armbruster# server's x509 certificate identity. If empty, QEMU will use the 742e8c5503aSMarkus Armbruster# hostname from the migration URI, if any. A non-empty value is 743e8c5503aSMarkus Armbruster# required when using x509 based TLS credentials and the migration 744e8c5503aSMarkus Armbruster# URI does not include a hostname, such as fd: or exec: based 74548685a8eSMarkus Armbruster# migration. (Since 2.7) 746a937b6aaSMarkus Armbruster# 747a937b6aaSMarkus Armbruster# Note: empty value works only since 2.9. 748d2f1d29bSDaniel P. Berrange# 749d2f1d29bSDaniel P. Berrange# @tls-authz: ID of the 'authz' object subclass that provides access 750d2f1d29bSDaniel P. Berrange# control checking of the TLS x509 certificate distinguished name. 751d2f1d29bSDaniel P. Berrange# This object is only resolved at time of use, so can be deleted 75273c67f38SMarkus Armbruster# and recreated on the fly while the migration server is active. 75373c67f38SMarkus Armbruster# If missing, it will default to denying access (Since 4.0) 75448685a8eSMarkus Armbruster# 7558b239597SPeter Xu# @max-bandwidth: maximum speed for migration, in bytes per second. 7568b239597SPeter Xu# (Since 2.8) 757209e64d9SMarkus Armbruster# 758209e64d9SMarkus Armbruster# @avail-switchover-bandwidth: to set the available bandwidth that 759209e64d9SMarkus Armbruster# migration can use during switchover phase. NOTE! This does not 760209e64d9SMarkus Armbruster# limit the bandwidth during switchover, but only for calculations 761209e64d9SMarkus Armbruster# when making decisions to switchover. By default, this value is 762209e64d9SMarkus Armbruster# zero, which means QEMU will estimate the bandwidth 763209e64d9SMarkus Armbruster# automatically. This can be set when the estimated value is not 764209e64d9SMarkus Armbruster# accurate, while the user is able to guarantee such bandwidth is 7658b239597SPeter Xu# available when switching over. When specified correctly, this 766a937b6aaSMarkus Armbruster# can make the switchover decision much more accurate. 767a937b6aaSMarkus Armbruster# (Since 8.2) 76848685a8eSMarkus Armbruster# 769a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 770a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 77148685a8eSMarkus Armbruster# 772cbfd6c95SJuan Quintela# @x-checkpoint-delay: The delay time (in ms) between two COLO 773a937b6aaSMarkus Armbruster# checkpoints in periodic mode. (Since 2.8) 774a937b6aaSMarkus Armbruster# 7754075fb1cSJuan Quintela# @multifd-channels: Number of channels used to migrate data in 77673af8dd8SJuan Quintela# parallel. This is the same number that the number of sockets 777a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 77873af8dd8SJuan Quintela# 77973af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 780a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 781a937b6aaSMarkus Armbruster# (Since 2.11) 7827e555c6cSDr. David Alan Gilbert# 7834cbc9c7fSLi Qiang# @max-postcopy-bandwidth: Background transfer bandwidth during 784a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 785a937b6aaSMarkus Armbruster# (Since 3.0) 786ee3d96baSDr. David Alan Gilbert# 787a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 788a937b6aaSMarkus Armbruster# (Since 3.1) 78996eef042SJuan Quintela# 7909004db48SJuan Quintela# @multifd-compression: Which compression method to use. Defaults to 791a937b6aaSMarkus Armbruster# none. (Since 5.0) 792a937b6aaSMarkus Armbruster# 793a937b6aaSMarkus Armbruster# @multifd-zlib-level: Set the compression level to be used in live 794a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 7959004db48SJuan Quintela# where 0 means no compression, 1 means the best compression 7966a9ad154SJuan Quintela# speed, and 9 means best compression ratio which will consume 797a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 798a937b6aaSMarkus Armbruster# 799a937b6aaSMarkus Armbruster# @multifd-qatzip-level: Set the compression level to be used in live 800a937b6aaSMarkus Armbruster# migration. The level is an integer between 1 and 9, where 1 means 801abb6295bSLeonardo Bras# the best compression speed, and 9 means the best compression 80231e4c354SMax Reitz# ratio which will consume more CPU. Defaults to 1. (Since 9.2) 803a937b6aaSMarkus Armbruster# 804a937b6aaSMarkus Armbruster# @multifd-zstd-level: Set the compression level to be used in live 805a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 806a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 807a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 808a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 809a937b6aaSMarkus Armbruster# 810a937b6aaSMarkus Armbruster# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 811a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 812a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 813a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 814a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 815a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 816a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 81731e4c354SMax Reitz# and all further bitmap migration data will then be discarded. 8188abc8115SHyman Huang(黄勇)# Note that the destination does not know about bitmaps it does 819209e64d9SMarkus Armbruster# not receive, so there is no limitation or requirement regarding 820209e64d9SMarkus Armbruster# the number of bitmaps received, or how they are named, or on 8214d807857SHyman Huang(黄勇)# which nodes they are placed. By default (when this parameter 82209f9ec99SHyman Huang(黄勇)# has never been set), bitmap names are mapped to themselves. 82309f9ec99SHyman Huang(黄勇)# Nodes are mapped to their block device name if there is one, and 82409f9ec99SHyman Huang(黄勇)# to their node name otherwise. (Since 5.2) 825209e64d9SMarkus Armbruster# 826209e64d9SMarkus Armbruster# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 827eea1e5c9SSteve Sistare# limit during live migration. Should be in the range 1 to 8285fdbb1dfSHao Xiang# 1000ms. Defaults to 1000ms. (Since 8.1) 82970c25c92SHao Xiang# 8305fdbb1dfSHao Xiang# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 8315fdbb1dfSHao Xiang# Defaults to 1. (Since 8.1) 832b43b61d5SFabiano Rosas# 833b43b61d5SFabiano Rosas# @mode: Migration mode. See description in @MigMode. Default is 834b43b61d5SFabiano Rosas# 'normal'. (Since 8.2) 835b43b61d5SFabiano Rosas# 8369fb49daaSMarkus Armbruster# @zero-page-detection: Whether and how to detect zero pages. 837a937b6aaSMarkus Armbruster# See description in @ZeroPageDetection. Default is 'multifd'. 838209e64d9SMarkus Armbruster# (since 9.0) 839209e64d9SMarkus Armbruster# 8409fb49daaSMarkus Armbruster# @direct-io: Open migration files with O_DIRECT when possible. This 84148685a8eSMarkus Armbruster# only has effect if the @mapped-ram capability is enabled. 84248685a8eSMarkus Armbruster# (Since 9.1) 84348685a8eSMarkus Armbruster# 844ee3d96baSDr. David Alan Gilbert# Features: 845ee3d96baSDr. David Alan Gilbert# 846864128dfSJuan Quintela# @unstable: Members @x-checkpoint-delay and 84748685a8eSMarkus Armbruster# @x-vcpu-dirty-limit-period are experimental. 848cbbf8182SKeqian Zhu# 849d2f1d29bSDaniel P. Berrange# Since: 2.4 8508b239597SPeter Xu## 8519fb49daaSMarkus Armbruster{ 'enum': 'MigrationParameter', 852cbfd6c95SJuan Quintela 'data': ['announce-initial', 'announce-max', 8534cbc9c7fSLi Qiang 'announce-rounds', 'announce-step', 8549004db48SJuan Quintela 'throttle-trigger-threshold', 85531e4c354SMax Reitz 'cpu-throttle-initial', 'cpu-throttle-increment', 8564d807857SHyman Huang(黄勇) 'cpu-throttle-tailslow', 85709f9ec99SHyman Huang(黄勇) 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 858eea1e5c9SSteve Sistare 'avail-switchover-bandwidth', 'downtime-limit', 8595fdbb1dfSHao Xiang { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 860b43b61d5SFabiano Rosas 'multifd-channels', 861b43b61d5SFabiano Rosas 'xbzrle-cache-size', 'max-postcopy-bandwidth', 86248685a8eSMarkus Armbruster 'max-cpu-throttle', 'multifd-compression', 86348685a8eSMarkus Armbruster 'multifd-zlib-level', 'multifd-zstd-level', 86448685a8eSMarkus Armbruster 'multifd-qatzip-level', 86548685a8eSMarkus Armbruster 'block-bitmap-mapping', 866a937b6aaSMarkus Armbruster { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 867a937b6aaSMarkus Armbruster 'vcpu-dirty-limit', 868ee3d96baSDr. David Alan Gilbert 'mode', 869a937b6aaSMarkus Armbruster 'zero-page-detection', 870a937b6aaSMarkus Armbruster 'direct-io'] } 871ee3d96baSDr. David Alan Gilbert 872a937b6aaSMarkus Armbruster## 873a937b6aaSMarkus Armbruster# @MigrateSetParameters: 874ee3d96baSDr. David Alan Gilbert# 875a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 876a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 877ee3d96baSDr. David Alan Gilbert# 878a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 879a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 880a937b6aaSMarkus Armbruster# 881dc14a470SKeqian Zhu# @announce-rounds: Number of self-announce packets sent after 88248685a8eSMarkus Armbruster# migration (Since 4.0) 883a937b6aaSMarkus Armbruster# 884a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 88548685a8eSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 88648685a8eSMarkus Armbruster# 887a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 888a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 88948685a8eSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 890a937b6aaSMarkus Armbruster# 891a937b6aaSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 892a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 893a937b6aaSMarkus Armbruster# default value is 20. (Since 2.7) 894a937b6aaSMarkus Armbruster# 895a937b6aaSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 896a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 897a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 898a937b6aaSMarkus Armbruster# 899a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 900a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 901a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 902cbbf8182SKeqian Zhu# usually at tail stage. If this parameter is true, we will 90348685a8eSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 90448685a8eSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 90548685a8eSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 90648685a8eSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 907a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 908a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 909a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 910e8c5503aSMarkus Armbruster# 5.1) 91148685a8eSMarkus Armbruster# 912e8c5503aSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 913e8c5503aSMarkus Armbruster# for establishing a TLS connection over the migration data 914e8c5503aSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 915e8c5503aSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 916e8c5503aSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this to a 917e8c5503aSMarkus Armbruster# non-empty string enables TLS for all migrations. An empty 918e8c5503aSMarkus Armbruster# string means that QEMU will use plain text mode for migration, 919e8c5503aSMarkus Armbruster# rather than TLS. This is the default. (Since 2.7) 92048685a8eSMarkus Armbruster# 92166fcb9d6SPeter Xu# @tls-hostname: migration target's hostname for validating the 92266fcb9d6SPeter Xu# server's x509 certificate identity. If empty, QEMU will use the 923e8c5503aSMarkus Armbruster# hostname from the migration URI, if any. A non-empty value is 924e8c5503aSMarkus Armbruster# required when using x509 based TLS credentials and the migration 925e8c5503aSMarkus Armbruster# URI does not include a hostname, such as fd: or exec: based 92666fcb9d6SPeter Xu# migration. (Since 2.7) 92773c67f38SMarkus Armbruster# 92873c67f38SMarkus Armbruster# Note: empty value works only since 2.9. 92948685a8eSMarkus Armbruster# 9308b239597SPeter Xu# @tls-authz: ID of the 'authz' object subclass that provides access 9318b239597SPeter Xu# control checking of the TLS x509 certificate distinguished name. 932209e64d9SMarkus Armbruster# This object is only resolved at time of use, so can be deleted 933209e64d9SMarkus Armbruster# and recreated on the fly while the migration server is active. 934209e64d9SMarkus Armbruster# If missing, it will default to denying access (Since 4.0) 935209e64d9SMarkus Armbruster# 936209e64d9SMarkus Armbruster# @max-bandwidth: maximum speed for migration, in bytes per second. 937209e64d9SMarkus Armbruster# (Since 2.8) 938209e64d9SMarkus Armbruster# 939209e64d9SMarkus Armbruster# @avail-switchover-bandwidth: to set the available bandwidth that 9408b239597SPeter Xu# migration can use during switchover phase. NOTE! This does not 941a937b6aaSMarkus Armbruster# limit the bandwidth during switchover, but only for calculations 942a937b6aaSMarkus Armbruster# when making decisions to switchover. By default, this value is 94348685a8eSMarkus Armbruster# zero, which means QEMU will estimate the bandwidth 9448eb0a257SMarkus Armbruster# automatically. This can be set when the estimated value is not 9458eb0a257SMarkus Armbruster# accurate, while the user is able to guarantee such bandwidth is 94648685a8eSMarkus Armbruster# available when switching over. When specified correctly, this 947cbfd6c95SJuan Quintela# can make the switchover decision much more accurate. 948a937b6aaSMarkus Armbruster# (Since 8.2) 949a937b6aaSMarkus Armbruster# 9504075fb1cSJuan Quintela# @downtime-limit: set maximum tolerated downtime for migration. 95173af8dd8SJuan Quintela# maximum downtime in milliseconds (Since 2.8) 952a937b6aaSMarkus Armbruster# 95373af8dd8SJuan Quintela# @x-checkpoint-delay: The delay time (in ms) between two COLO 9547e555c6cSDr. David Alan Gilbert# checkpoints in periodic mode. (Since 2.8) 955a937b6aaSMarkus Armbruster# 956a937b6aaSMarkus Armbruster# @multifd-channels: Number of channels used to migrate data in 9577e555c6cSDr. David Alan Gilbert# parallel. This is the same number that the number of sockets 9584cbc9c7fSLi Qiang# used for migration. The default value is 2 (since 4.0) 9598eb0a257SMarkus Armbruster# 9608eb0a257SMarkus Armbruster# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 9614cbc9c7fSLi Qiang# needs to be a multiple of the target page size and a power of 2 962a937b6aaSMarkus Armbruster# (Since 2.11) 963a937b6aaSMarkus Armbruster# 96496eef042SJuan Quintela# @max-postcopy-bandwidth: Background transfer bandwidth during 9659004db48SJuan Quintela# postcopy. Defaults to 0 (unlimited). In bytes per second. 966a937b6aaSMarkus Armbruster# (Since 3.0) 967a937b6aaSMarkus Armbruster# 968a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 969a937b6aaSMarkus Armbruster# (Since 3.1) 9709004db48SJuan Quintela# 9716a9ad154SJuan Quintela# @multifd-compression: Which compression method to use. Defaults to 972a937b6aaSMarkus Armbruster# none. (Since 5.0) 973a937b6aaSMarkus Armbruster# 974a937b6aaSMarkus Armbruster# @multifd-zlib-level: Set the compression level to be used in live 975a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 9766a9ad154SJuan Quintela# where 0 means no compression, 1 means the best compression 97731e4c354SMax Reitz# speed, and 9 means best compression ratio which will consume 978a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 979a937b6aaSMarkus Armbruster# 980a937b6aaSMarkus Armbruster# @multifd-qatzip-level: Set the compression level to be used in live 981a937b6aaSMarkus Armbruster# migration. The level is an integer between 1 and 9, where 1 means 982a937b6aaSMarkus Armbruster# the best compression speed, and 9 means the best compression 983a937b6aaSMarkus Armbruster# ratio which will consume more CPU. Defaults to 1. (Since 9.2) 984a937b6aaSMarkus Armbruster# 985a937b6aaSMarkus Armbruster# @multifd-zstd-level: Set the compression level to be used in live 986a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 987a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 988a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 989a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 990a937b6aaSMarkus Armbruster# 991a937b6aaSMarkus Armbruster# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 99231e4c354SMax Reitz# aliases for the purpose of dirty bitmap migration. Such aliases 9938abc8115SHyman Huang(黄勇)# may for example be the corresponding names on the opposite site. 994209e64d9SMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 995209e64d9SMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 9964d807857SHyman Huang(黄勇)# will be ignored. On the destination, encountering an unmapped 99709f9ec99SHyman Huang(黄勇)# alias in the incoming migration stream will result in a report, 99809f9ec99SHyman Huang(黄勇)# and all further bitmap migration data will then be discarded. 99909f9ec99SHyman Huang(黄勇)# Note that the destination does not know about bitmaps it does 1000209e64d9SMarkus Armbruster# not receive, so there is no limitation or requirement regarding 1001209e64d9SMarkus Armbruster# the number of bitmaps received, or how they are named, or on 1002eea1e5c9SSteve Sistare# which nodes they are placed. By default (when this parameter 10035fdbb1dfSHao Xiang# has never been set), bitmap names are mapped to themselves. 100470c25c92SHao Xiang# Nodes are mapped to their block device name if there is one, and 10055fdbb1dfSHao Xiang# to their node name otherwise. (Since 5.2) 10065fdbb1dfSHao Xiang# 1007b43b61d5SFabiano Rosas# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1008b43b61d5SFabiano Rosas# limit during live migration. Should be in the range 1 to 1009b43b61d5SFabiano Rosas# 1000ms. Defaults to 1000ms. (Since 8.1) 1010b43b61d5SFabiano Rosas# 10119fb49daaSMarkus Armbruster# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1012a937b6aaSMarkus Armbruster# Defaults to 1. (Since 8.1) 1013209e64d9SMarkus Armbruster# 1014209e64d9SMarkus Armbruster# @mode: Migration mode. See description in @MigMode. Default is 10159fb49daaSMarkus Armbruster# 'normal'. (Since 8.2) 101656266c6dSMarkus Armbruster# 101756266c6dSMarkus Armbruster# @zero-page-detection: Whether and how to detect zero pages. 101856266c6dSMarkus Armbruster# See description in @ZeroPageDetection. Default is 'multifd'. 101948685a8eSMarkus Armbruster# (since 9.0) 102048685a8eSMarkus Armbruster# 102148685a8eSMarkus Armbruster# @direct-io: Open migration files with O_DIRECT when possible. This 1022ee3d96baSDr. David Alan Gilbert# only has effect if the @mapped-ram capability is enabled. 1023ee3d96baSDr. David Alan Gilbert# (Since 9.1) 1024ee3d96baSDr. David Alan Gilbert# 1025ee3d96baSDr. David Alan Gilbert# Features: 1026ec17de0aSMarkus Armbruster# 1027ec17de0aSMarkus Armbruster# @unstable: Members @x-checkpoint-delay and 1028ec17de0aSMarkus Armbruster# @x-vcpu-dirty-limit-period are experimental. 1029cbbf8182SKeqian Zhu# 103048685a8eSMarkus Armbruster# TODO: either fuse back into MigrationParameters, or make 103148685a8eSMarkus Armbruster# MigrationParameters members mandatory 1032d2f1d29bSDaniel P. Berrange# 1033ec17de0aSMarkus Armbruster# Since: 2.4 10348b239597SPeter Xu## 1035ec17de0aSMarkus Armbruster{ 'struct': 'MigrateSetParameters', 10369fb49daaSMarkus Armbruster 'data': { '*announce-initial': 'size', 10379fb49daaSMarkus Armbruster '*announce-max': 'size', 1038ec17de0aSMarkus Armbruster '*announce-rounds': 'size', 10397e555c6cSDr. David Alan Gilbert '*announce-step': 'size', 10404cbc9c7fSLi Qiang '*throttle-trigger-threshold': 'uint8', 1041ec17de0aSMarkus Armbruster '*cpu-throttle-initial': 'uint8', 10429004db48SJuan Quintela '*cpu-throttle-increment': 'uint8', 1043ec17de0aSMarkus Armbruster '*cpu-throttle-tailslow': 'bool', 1044ec17de0aSMarkus Armbruster '*tls-creds': 'StrOrNull', 10454d807857SHyman Huang(黄勇) '*tls-hostname': 'StrOrNull', 10464d807857SHyman Huang(黄勇) '*tls-authz': 'StrOrNull', 104709f9ec99SHyman Huang(黄勇) '*max-bandwidth': 'size', 1048eea1e5c9SSteve Sistare '*avail-switchover-bandwidth': 'size', 10495fdbb1dfSHao Xiang '*downtime-limit': 'uint64', 1050b43b61d5SFabiano Rosas '*x-checkpoint-delay': { 'type': 'uint32', 1051b43b61d5SFabiano Rosas 'features': [ 'unstable' ] }, 105248685a8eSMarkus Armbruster '*multifd-channels': 'uint8', 105348685a8eSMarkus Armbruster '*xbzrle-cache-size': 'size', 105448685a8eSMarkus Armbruster '*max-postcopy-bandwidth': 'size', 105548685a8eSMarkus Armbruster '*max-cpu-throttle': 'uint8', 105648685a8eSMarkus Armbruster '*multifd-compression': 'MultiFDCompression', 105748685a8eSMarkus Armbruster '*multifd-zlib-level': 'uint8', 105848685a8eSMarkus Armbruster '*multifd-qatzip-level': 'uint8', 105948685a8eSMarkus Armbruster '*multifd-zstd-level': 'uint8', 106014b48aaaSJohn Snow '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 106148685a8eSMarkus Armbruster '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 106248685a8eSMarkus Armbruster 'features': [ 'unstable' ] }, 1063864128dfSJuan Quintela '*vcpu-dirty-limit': 'uint64', 106437fa48a4SMarkus Armbruster '*mode': 'MigMode', 106548685a8eSMarkus Armbruster '*zero-page-detection': 'ZeroPageDetection', 106648685a8eSMarkus Armbruster '*direct-io': 'bool' } } 106748685a8eSMarkus Armbruster 106848685a8eSMarkus Armbruster## 106948685a8eSMarkus Armbruster# @migrate-set-parameters: 107048685a8eSMarkus Armbruster# 107148685a8eSMarkus Armbruster# Set various migration parameters. 107248685a8eSMarkus Armbruster# 107348685a8eSMarkus Armbruster# Since: 2.4 1074a937b6aaSMarkus Armbruster# 1075a937b6aaSMarkus Armbruster# .. qmp-example:: 1076ee3d96baSDr. David Alan Gilbert# 1077a937b6aaSMarkus Armbruster# -> { "execute": "migrate-set-parameters" , 1078a937b6aaSMarkus Armbruster# "arguments": { "multifd-channels": 5 } } 1079ee3d96baSDr. David Alan Gilbert# <- { "return": {} } 1080a937b6aaSMarkus Armbruster## 1081a937b6aaSMarkus Armbruster{ 'command': 'migrate-set-parameters', 'boxed': true, 1082ee3d96baSDr. David Alan Gilbert 'data': 'MigrateSetParameters' } 1083a937b6aaSMarkus Armbruster 1084a937b6aaSMarkus Armbruster## 1085ee3d96baSDr. David Alan Gilbert# @MigrationParameters: 1086a937b6aaSMarkus Armbruster# 1087a937b6aaSMarkus Armbruster# The optional members aren't actually optional. 1088a937b6aaSMarkus Armbruster# 1089dc14a470SKeqian Zhu# @announce-initial: Initial delay (in milliseconds) before sending 109048685a8eSMarkus Armbruster# the first announce (Since 4.0) 1091a937b6aaSMarkus Armbruster# 1092a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 109348685a8eSMarkus Armbruster# the announcement (Since 4.0) 109448685a8eSMarkus Armbruster# 1095a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 1096a937b6aaSMarkus Armbruster# migration (Since 4.0) 109748685a8eSMarkus Armbruster# 1098a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 1099a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 1100a937b6aaSMarkus Armbruster# 1101a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1102a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 1103a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 1104a937b6aaSMarkus Armbruster# 1105a937b6aaSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 1106a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. (Since 1107a937b6aaSMarkus Armbruster# 2.7) 1108a937b6aaSMarkus Armbruster# 1109a937b6aaSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 1110cbbf8182SKeqian Zhu# auto-converge detects that migration is not making progress. 111148685a8eSMarkus Armbruster# (Since 2.7) 111248685a8eSMarkus Armbruster# 111348685a8eSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 111448685a8eSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 1115a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 1116a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 1117e8c5503aSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 111848685a8eSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 1119e8c5503aSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 1120e8c5503aSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 1121e8c5503aSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 1122e8c5503aSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 1123e8c5503aSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 1124e8c5503aSMarkus Armbruster# 5.1) 1125e8c5503aSMarkus Armbruster# 112648685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 1127a937b6aaSMarkus Armbruster# for establishing a TLS connection over the migration data 1128a937b6aaSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 1129a937b6aaSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 1130d2f1d29bSDaniel P. Berrange# credentials must be for a 'server' endpoint. An empty string 113173c67f38SMarkus Armbruster# means that QEMU will use plain text mode for migration, rather 113273c67f38SMarkus Armbruster# than TLS. (Since 2.7) 113348685a8eSMarkus Armbruster# 11348b239597SPeter Xu# Note: 2.8 omits empty @tls-creds instead. 11358b239597SPeter Xu# 1136209e64d9SMarkus Armbruster# @tls-hostname: migration target's hostname for validating the 1137209e64d9SMarkus Armbruster# server's x509 certificate identity. If empty, QEMU will use the 1138209e64d9SMarkus Armbruster# hostname from the migration URI, if any. (Since 2.7) 1139209e64d9SMarkus Armbruster# 1140209e64d9SMarkus Armbruster# Note: 2.8 omits empty @tls-hostname instead. 1141209e64d9SMarkus Armbruster# 1142209e64d9SMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 1143209e64d9SMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 11448b239597SPeter Xu# (Since 4.0) 1145a937b6aaSMarkus Armbruster# 1146a937b6aaSMarkus Armbruster# @max-bandwidth: maximum speed for migration, in bytes per second. 114748685a8eSMarkus Armbruster# (Since 2.8) 1148a937b6aaSMarkus Armbruster# 1149a937b6aaSMarkus Armbruster# @avail-switchover-bandwidth: to set the available bandwidth that 115048685a8eSMarkus Armbruster# migration can use during switchover phase. NOTE! This does not 1151cbfd6c95SJuan Quintela# limit the bandwidth during switchover, but only for calculations 1152a937b6aaSMarkus Armbruster# when making decisions to switchover. By default, this value is 1153a937b6aaSMarkus Armbruster# zero, which means QEMU will estimate the bandwidth 11544075fb1cSJuan Quintela# automatically. This can be set when the estimated value is not 115573af8dd8SJuan Quintela# accurate, while the user is able to guarantee such bandwidth is 1156a937b6aaSMarkus Armbruster# available when switching over. When specified correctly, this 115773af8dd8SJuan Quintela# can make the switchover decision much more accurate. 11587e555c6cSDr. David Alan Gilbert# (Since 8.2) 1159a937b6aaSMarkus Armbruster# 1160a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 11617e555c6cSDr. David Alan Gilbert# maximum downtime in milliseconds (Since 2.8) 11624cbc9c7fSLi Qiang# 1163a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 11644cbc9c7fSLi Qiang# (Since 2.8) 11654cbc9c7fSLi Qiang# 1166a937b6aaSMarkus Armbruster# @multifd-channels: Number of channels used to migrate data in 1167a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 116896eef042SJuan Quintela# used for migration. The default value is 2 (since 4.0) 11699004db48SJuan Quintela# 1170a937b6aaSMarkus Armbruster# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1171a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 1172a937b6aaSMarkus Armbruster# (Since 2.11) 1173a937b6aaSMarkus Armbruster# 11749004db48SJuan Quintela# @max-postcopy-bandwidth: Background transfer bandwidth during 11756a9ad154SJuan Quintela# postcopy. Defaults to 0 (unlimited). In bytes per second. 1176a937b6aaSMarkus Armbruster# (Since 3.0) 1177a937b6aaSMarkus Armbruster# 1178a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1179a937b6aaSMarkus Armbruster# (Since 3.1) 11806a9ad154SJuan Quintela# 118131e4c354SMax Reitz# @multifd-compression: Which compression method to use. Defaults to 1182a937b6aaSMarkus Armbruster# none. (Since 5.0) 1183a937b6aaSMarkus Armbruster# 1184a937b6aaSMarkus Armbruster# @multifd-zlib-level: Set the compression level to be used in live 1185a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 1186a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1187a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 1188a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 1189a937b6aaSMarkus Armbruster# 1190a937b6aaSMarkus Armbruster# @multifd-qatzip-level: Set the compression level to be used in live 1191a937b6aaSMarkus Armbruster# migration. The level is an integer between 1 and 9, where 1 means 1192a937b6aaSMarkus Armbruster# the best compression speed, and 9 means the best compression 1193a937b6aaSMarkus Armbruster# ratio which will consume more CPU. Defaults to 1. (Since 9.2) 1194a937b6aaSMarkus Armbruster# 1195a937b6aaSMarkus Armbruster# @multifd-zstd-level: Set the compression level to be used in live 119631e4c354SMax Reitz# migration, the compression level is an integer between 0 and 20, 11978abc8115SHyman Huang(黄勇)# where 0 means no compression, 1 means the best compression 1198209e64d9SMarkus Armbruster# speed, and 20 means best compression ratio which will consume 1199209e64d9SMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 12004d807857SHyman Huang(黄勇)# 120109f9ec99SHyman Huang(黄勇)# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 120209f9ec99SHyman Huang(黄勇)# aliases for the purpose of dirty bitmap migration. Such aliases 120309f9ec99SHyman Huang(黄勇)# may for example be the corresponding names on the opposite site. 1204209e64d9SMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 1205209e64d9SMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1206eea1e5c9SSteve Sistare# will be ignored. On the destination, encountering an unmapped 12075fdbb1dfSHao Xiang# alias in the incoming migration stream will result in a report, 120870c25c92SHao Xiang# and all further bitmap migration data will then be discarded. 12095fdbb1dfSHao Xiang# Note that the destination does not know about bitmaps it does 12105fdbb1dfSHao Xiang# not receive, so there is no limitation or requirement regarding 1211b43b61d5SFabiano Rosas# the number of bitmaps received, or how they are named, or on 1212b43b61d5SFabiano Rosas# which nodes they are placed. By default (when this parameter 1213b43b61d5SFabiano Rosas# has never been set), bitmap names are mapped to themselves. 1214b43b61d5SFabiano Rosas# Nodes are mapped to their block device name if there is one, and 12159fb49daaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 1216a937b6aaSMarkus Armbruster# 1217209e64d9SMarkus Armbruster# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1218209e64d9SMarkus Armbruster# limit during live migration. Should be in the range 1 to 12199fb49daaSMarkus Armbruster# 1000ms. Defaults to 1000ms. (Since 8.1) 122048685a8eSMarkus Armbruster# 122148685a8eSMarkus Armbruster# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 122248685a8eSMarkus Armbruster# Defaults to 1. (Since 8.1) 1223ee3d96baSDr. David Alan Gilbert# 1224ee3d96baSDr. David Alan Gilbert# @mode: Migration mode. See description in @MigMode. Default is 1225ee3d96baSDr. David Alan Gilbert# 'normal'. (Since 8.2) 1226ee3d96baSDr. David Alan Gilbert# 1227dc14a470SKeqian Zhu# @zero-page-detection: Whether and how to detect zero pages. 1228741d4086SJuan Quintela# See description in @ZeroPageDetection. Default is 'multifd'. 1229741d4086SJuan Quintela# (since 9.0) 1230cbbf8182SKeqian Zhu# 123148685a8eSMarkus Armbruster# @direct-io: Open migration files with O_DIRECT when possible. This 123248685a8eSMarkus Armbruster# only has effect if the @mapped-ram capability is enabled. 1233d2f1d29bSDaniel P. Berrange# (Since 9.1) 1234741d4086SJuan Quintela# 12358b239597SPeter Xu# Features: 1236741d4086SJuan Quintela# 12379fb49daaSMarkus Armbruster# @unstable: Members @x-checkpoint-delay and 12389fb49daaSMarkus Armbruster# @x-vcpu-dirty-limit-period are experimental. 1239cbfd6c95SJuan Quintela# 12407e555c6cSDr. David Alan Gilbert# Since: 2.4 12414cbc9c7fSLi Qiang## 124296eef042SJuan Quintela{ 'struct': 'MigrationParameters', 12439004db48SJuan Quintela 'data': { '*announce-initial': 'size', 12446a9ad154SJuan Quintela '*announce-max': 'size', 124531e4c354SMax Reitz '*announce-rounds': 'size', 12464d807857SHyman Huang(黄勇) '*announce-step': 'size', 12474d807857SHyman Huang(黄勇) '*throttle-trigger-threshold': 'uint8', 124809f9ec99SHyman Huang(黄勇) '*cpu-throttle-initial': 'uint8', 1249eea1e5c9SSteve Sistare '*cpu-throttle-increment': 'uint8', 12505fdbb1dfSHao Xiang '*cpu-throttle-tailslow': 'bool', 1251b43b61d5SFabiano Rosas '*tls-creds': 'str', 1252b43b61d5SFabiano Rosas '*tls-hostname': 'str', 125348685a8eSMarkus Armbruster '*tls-authz': 'str', 125448685a8eSMarkus Armbruster '*max-bandwidth': 'size', 125548685a8eSMarkus Armbruster '*avail-switchover-bandwidth': 'size', 125648685a8eSMarkus Armbruster '*downtime-limit': 'uint64', 125748685a8eSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 125848685a8eSMarkus Armbruster 'features': [ 'unstable' ] }, 125948685a8eSMarkus Armbruster '*multifd-channels': 'uint8', 126048685a8eSMarkus Armbruster '*xbzrle-cache-size': 'size', 126148685a8eSMarkus Armbruster '*max-postcopy-bandwidth': 'size', 126248685a8eSMarkus Armbruster '*max-cpu-throttle': 'uint8', 126314b48aaaSJohn Snow '*multifd-compression': 'MultiFDCompression', 126448685a8eSMarkus Armbruster '*multifd-zlib-level': 'uint8', 126548685a8eSMarkus Armbruster '*multifd-qatzip-level': 'uint8', 126648685a8eSMarkus Armbruster '*multifd-zstd-level': 'uint8', 1267864128dfSJuan Quintela '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 126848685a8eSMarkus Armbruster '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 126948685a8eSMarkus Armbruster 'features': [ 'unstable' ] }, 127048685a8eSMarkus Armbruster '*vcpu-dirty-limit': 'uint64', 127148685a8eSMarkus Armbruster '*mode': 'MigMode', 127248685a8eSMarkus Armbruster '*zero-page-detection': 'ZeroPageDetection', 127348685a8eSMarkus Armbruster '*direct-io': 'bool' } } 127448685a8eSMarkus Armbruster 127548685a8eSMarkus Armbruster## 127648685a8eSMarkus Armbruster# @query-migrate-parameters: 127748685a8eSMarkus Armbruster# 127848685a8eSMarkus Armbruster# Returns information about the current migration parameters 127948685a8eSMarkus Armbruster# 128048685a8eSMarkus Armbruster# Returns: @MigrationParameters 1281a937b6aaSMarkus Armbruster# 1282a937b6aaSMarkus Armbruster# Since: 2.4 1283a937b6aaSMarkus Armbruster# 128448685a8eSMarkus Armbruster# .. qmp-example:: 128548685a8eSMarkus Armbruster# 128648685a8eSMarkus Armbruster# -> { "execute": "query-migrate-parameters" } 128714b48aaaSJohn Snow# <- { "return": { 128848685a8eSMarkus Armbruster# "multifd-channels": 2, 128948685a8eSMarkus Armbruster# "cpu-throttle-increment": 10, 129048685a8eSMarkus Armbruster# "cpu-throttle-initial": 20, 129148685a8eSMarkus Armbruster# "max-bandwidth": 33554432, 129248685a8eSMarkus Armbruster# "downtime-limit": 300 129348685a8eSMarkus Armbruster# } 129448685a8eSMarkus Armbruster# } 129548685a8eSMarkus Armbruster## 129648685a8eSMarkus Armbruster{ 'command': 'query-migrate-parameters', 129748685a8eSMarkus Armbruster 'returns': 'MigrationParameters' } 129848685a8eSMarkus Armbruster 129948685a8eSMarkus Armbruster## 130048685a8eSMarkus Armbruster# @migrate-start-postcopy: 130148685a8eSMarkus Armbruster# 130248685a8eSMarkus Armbruster# Followup to a migration command to switch the migration to postcopy 130314b48aaaSJohn Snow# mode. The postcopy-ram capability must be set on both source and 130448685a8eSMarkus Armbruster# destination before the original migration command. 130548685a8eSMarkus Armbruster# 130648685a8eSMarkus Armbruster# Since: 2.5 130748685a8eSMarkus Armbruster# 130848685a8eSMarkus Armbruster# .. qmp-example:: 130948685a8eSMarkus Armbruster# 131048685a8eSMarkus Armbruster# -> { "execute": "migrate-start-postcopy" } 131148685a8eSMarkus Armbruster# <- { "return": {} } 131248685a8eSMarkus Armbruster## 131348685a8eSMarkus Armbruster{ 'command': 'migrate-start-postcopy' } 131448685a8eSMarkus Armbruster 1315a937b6aaSMarkus Armbruster## 1316a937b6aaSMarkus Armbruster# @MIGRATION: 131748685a8eSMarkus Armbruster# 131848685a8eSMarkus Armbruster# Emitted when a migration event happens 131948685a8eSMarkus Armbruster# 132048685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 132148685a8eSMarkus Armbruster# 132214b48aaaSJohn Snow# Since: 2.4 132348685a8eSMarkus Armbruster# 132437fa48a4SMarkus Armbruster# .. qmp-example:: 132548685a8eSMarkus Armbruster# 132648685a8eSMarkus Armbruster# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 132748685a8eSMarkus Armbruster# "event": "MIGRATION", 132848685a8eSMarkus Armbruster# "data": {"status": "completed"} } 132948685a8eSMarkus Armbruster## 133048685a8eSMarkus Armbruster{ 'event': 'MIGRATION', 133148685a8eSMarkus Armbruster 'data': {'status': 'MigrationStatus'}} 133248685a8eSMarkus Armbruster 133348685a8eSMarkus Armbruster## 133448685a8eSMarkus Armbruster# @MIGRATION_PASS: 133548685a8eSMarkus Armbruster# 133648685a8eSMarkus Armbruster# Emitted from the source side of a migration at the start of each 1337a937b6aaSMarkus Armbruster# pass (when it syncs the dirty bitmap) 1338a937b6aaSMarkus Armbruster# 133948685a8eSMarkus Armbruster# @pass: An incrementing count (starting at 1 on the first pass) 134048685a8eSMarkus Armbruster# 134148685a8eSMarkus Armbruster# Since: 2.6 134248685a8eSMarkus Armbruster# 134348685a8eSMarkus Armbruster# .. qmp-example:: 134448685a8eSMarkus Armbruster# 134548685a8eSMarkus Armbruster# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 134648685a8eSMarkus Armbruster# "event": "MIGRATION_PASS", "data": {"pass": 2} } 134748685a8eSMarkus Armbruster## 134848685a8eSMarkus Armbruster{ 'event': 'MIGRATION_PASS', 134948685a8eSMarkus Armbruster 'data': { 'pass': 'int' } } 135048685a8eSMarkus Armbruster 135148685a8eSMarkus Armbruster## 135248685a8eSMarkus Armbruster# @COLOMessage: 135348685a8eSMarkus Armbruster# 135448685a8eSMarkus Armbruster# The message transmission between Primary side and Secondary side. 135548685a8eSMarkus Armbruster# 135648685a8eSMarkus Armbruster# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 135748685a8eSMarkus Armbruster# 135848685a8eSMarkus Armbruster# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 135948685a8eSMarkus Armbruster# checkpointing 136041b6b779SZhang Chen# 136148685a8eSMarkus Armbruster# @checkpoint-reply: SVM gets PVM's checkpoint request 136241b6b779SZhang Chen# 136348685a8eSMarkus Armbruster# @vmstate-send: VM's state will be sent by PVM. 136441b6b779SZhang Chen# 136548685a8eSMarkus Armbruster# @vmstate-size: The total size of VMstate. 136641b6b779SZhang Chen# 136748685a8eSMarkus Armbruster# @vmstate-received: VM's state has been received by SVM. 136848685a8eSMarkus Armbruster# 136948685a8eSMarkus Armbruster# @vmstate-loaded: VM's state has been loaded by SVM. 137048685a8eSMarkus Armbruster# 137141b6b779SZhang Chen# Since: 2.8 137248685a8eSMarkus Armbruster## 137348685a8eSMarkus Armbruster{ 'enum': 'COLOMessage', 137448685a8eSMarkus Armbruster 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 137548685a8eSMarkus Armbruster 'vmstate-send', 'vmstate-size', 'vmstate-received', 137648685a8eSMarkus Armbruster 'vmstate-loaded' ] } 137748685a8eSMarkus Armbruster 137848685a8eSMarkus Armbruster## 137948685a8eSMarkus Armbruster# @COLOMode: 138048685a8eSMarkus Armbruster# 138148685a8eSMarkus Armbruster# The COLO current mode. 138248685a8eSMarkus Armbruster# 138348685a8eSMarkus Armbruster# @none: COLO is disabled. 138448685a8eSMarkus Armbruster# 138548685a8eSMarkus Armbruster# @primary: COLO node in primary side. 1386a937b6aaSMarkus Armbruster# 1387a937b6aaSMarkus Armbruster# @secondary: COLO node in slave side. 138848685a8eSMarkus Armbruster# 138948685a8eSMarkus Armbruster# Since: 2.8 139048685a8eSMarkus Armbruster## 139148685a8eSMarkus Armbruster{ 'enum': 'COLOMode', 139248685a8eSMarkus Armbruster 'data': [ 'none', 'primary', 'secondary'] } 139348685a8eSMarkus Armbruster 139448685a8eSMarkus Armbruster## 13959ecff6d6Szhanghailiang# @FailoverStatus: 13969ecff6d6Szhanghailiang# 13979ecff6d6Szhanghailiang# An enumeration of COLO failover status 13989ecff6d6Szhanghailiang# 13999ecff6d6Szhanghailiang# @none: no failover has ever happened 14009ecff6d6Szhanghailiang# 14019ecff6d6Szhanghailiang# @require: got failover requirement but not handled 14029ecff6d6Szhanghailiang# 14039ecff6d6Szhanghailiang# @active: in the process of doing failover 14049ecff6d6Szhanghailiang# 14059ecff6d6Szhanghailiang# @completed: finish the process of failover 140614b48aaaSJohn Snow# 14079ecff6d6Szhanghailiang# @relaunch: restart the failover process, from 'none' -> 'completed' 14089ecff6d6Szhanghailiang# (Since 2.9) 14099ecff6d6Szhanghailiang# 14109ecff6d6Szhanghailiang# Since: 2.8 14119ecff6d6Szhanghailiang## 14129ecff6d6Szhanghailiang{ 'enum': 'FailoverStatus', 14139ecff6d6Szhanghailiang 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 14149ecff6d6Szhanghailiang 14159ecff6d6Szhanghailiang## 14169ecff6d6Szhanghailiang# @COLO_EXIT: 14173a43ac47SZhang Chen# 14189ecff6d6Szhanghailiang# Emitted when VM finishes COLO mode due to some errors happening or 1419a937b6aaSMarkus Armbruster# at the request of users. 1420a937b6aaSMarkus Armbruster# 14213a43ac47SZhang Chen# @mode: report COLO mode when COLO exited. 14229ecff6d6Szhanghailiang# 14233a43ac47SZhang Chen# @reason: describes the reason for the COLO exit. 14249ecff6d6Szhanghailiang# 14253a43ac47SZhang Chen# Since: 3.1 14263a43ac47SZhang Chen# 14273a43ac47SZhang Chen# .. qmp-example:: 14289ecff6d6Szhanghailiang# 14299ecff6d6Szhanghailiang# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 14309ecff6d6Szhanghailiang# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 14319ecff6d6Szhanghailiang## 14323a43ac47SZhang Chen{ 'event': 'COLO_EXIT', 14339ecff6d6Szhanghailiang 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 14349ecff6d6Szhanghailiang 143548685a8eSMarkus Armbruster## 143648685a8eSMarkus Armbruster# @COLOExitReason: 1437a937b6aaSMarkus Armbruster# 1438a937b6aaSMarkus Armbruster# The reason for a COLO exit. 1439a937b6aaSMarkus Armbruster# 1440a937b6aaSMarkus Armbruster# @none: failover has never happened. This state does not occur in 1441a937b6aaSMarkus Armbruster# the COLO_EXIT event, and is only visible in the result of 144248685a8eSMarkus Armbruster# query-colo-status. 14439fb49daaSMarkus Armbruster# 1444a937b6aaSMarkus Armbruster# @request: COLO exit is due to an external request. 14459fb49daaSMarkus Armbruster# 14469fb49daaSMarkus Armbruster# @error: COLO exit is due to an internal error. 144748685a8eSMarkus Armbruster# 144848685a8eSMarkus Armbruster# @processing: COLO is currently handling a failover (since 4.0). 144914b48aaaSJohn Snow# 145048685a8eSMarkus Armbruster# Since: 3.1 145148685a8eSMarkus Armbruster## 145248685a8eSMarkus Armbruster{ 'enum': 'COLOExitReason', 145348685a8eSMarkus Armbruster 'data': [ 'none', 'request', 'error' , 'processing' ] } 14549fb49daaSMarkus Armbruster 145551e47cf8SVladimir Sementsov-Ogievskiy## 145651e47cf8SVladimir Sementsov-Ogievskiy# @x-colo-lost-heartbeat: 145748685a8eSMarkus Armbruster# 145848685a8eSMarkus Armbruster# Tell qemu that heartbeat is lost, request it to do takeover 145948685a8eSMarkus Armbruster# procedures. If this command is sent to the PVM, the Primary side 146048685a8eSMarkus Armbruster# will exit COLO mode. If sent to the Secondary, the Secondary side 146148685a8eSMarkus Armbruster# will run failover work, then takes over server operation to become 146248685a8eSMarkus Armbruster# the service VM. 146301bed0ffSMarkus Armbruster# 146401bed0ffSMarkus Armbruster# Features: 146548685a8eSMarkus Armbruster# 14669bc6e893SMarkus Armbruster# @unstable: This command is experimental. 146748685a8eSMarkus Armbruster# 146814b48aaaSJohn Snow# Since: 2.8 146948685a8eSMarkus Armbruster# 147048685a8eSMarkus Armbruster# .. qmp-example:: 147148685a8eSMarkus Armbruster# 147248685a8eSMarkus Armbruster# -> { "execute": "x-colo-lost-heartbeat" } 147348685a8eSMarkus Armbruster# <- { "return": {} } 147448685a8eSMarkus Armbruster## 147548685a8eSMarkus Armbruster{ 'command': 'x-colo-lost-heartbeat', 147689cfc02cSDr. David Alan Gilbert 'features': [ 'unstable' ], 147789cfc02cSDr. David Alan Gilbert 'if': 'CONFIG_REPLICATION' } 147889cfc02cSDr. David Alan Gilbert 147989cfc02cSDr. David Alan Gilbert## 148089cfc02cSDr. David Alan Gilbert# @migrate_cancel: 148189cfc02cSDr. David Alan Gilbert# 148289cfc02cSDr. David Alan Gilbert# Cancel the current executing migration process. 14834ae65a52SAndrea Bolognani# 148414b48aaaSJohn Snow# .. note:: This command succeeds even if there is no migration 148589cfc02cSDr. David Alan Gilbert# process running. 148689cfc02cSDr. David Alan Gilbert# 148789cfc02cSDr. David Alan Gilbert# Since: 0.14 148889cfc02cSDr. David Alan Gilbert# 148989cfc02cSDr. David Alan Gilbert# .. qmp-example:: 149089cfc02cSDr. David Alan Gilbert# 149189cfc02cSDr. David Alan Gilbert# -> { "execute": "migrate_cancel" } 149289cfc02cSDr. David Alan Gilbert# <- { "return": {} } 1493e034f883SHet Gala## 1494e034f883SHet Gala{ 'command': 'migrate_cancel' } 1495e034f883SHet Gala 1496e034f883SHet Gala## 1497e034f883SHet Gala# @migrate-continue: 1498e034f883SHet Gala# 1499e034f883SHet Gala# Continue migration when it's in a paused state. 1500e034f883SHet Gala# 1501e034f883SHet Gala# @state: The state the migration is currently expected to be in 1502e034f883SHet Gala# 1503e034f883SHet Gala# Since: 2.11 1504e034f883SHet Gala# 150537507c14SMarkus Armbruster# .. qmp-example:: 1506e034f883SHet Gala# 1507e034f883SHet Gala# -> { "execute": "migrate-continue" , "arguments": 1508e034f883SHet Gala# { "state": "pre-switchover" } } 1509e034f883SHet Gala# <- { "return": {} } 1510e034f883SHet Gala## 1511e034f883SHet Gala{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 1512e034f883SHet Gala 1513e034f883SHet Gala## 1514e034f883SHet Gala# @MigrationAddressType: 1515e034f883SHet Gala# 1516e034f883SHet Gala# The migration stream transport mechanisms. 151737507c14SMarkus Armbruster# 1518e034f883SHet Gala# @socket: Migrate via socket. 1519e034f883SHet Gala# 1520e034f883SHet Gala# @exec: Direct the migration stream to another process. 1521e034f883SHet Gala# 1522e034f883SHet Gala# @rdma: Migrate via RDMA. 1523e034f883SHet Gala# 1524e034f883SHet Gala# @file: Direct the migration stream to a file. 1525e034f883SHet Gala# 1526e034f883SHet Gala# Since: 8.2 1527e034f883SHet Gala## 152837507c14SMarkus Armbruster{ 'enum': 'MigrationAddressType', 1529e034f883SHet Gala 'data': [ 'socket', 'exec', 'rdma', 'file' ] } 1530e034f883SHet Gala 1531e034f883SHet Gala## 1532e034f883SHet Gala# @FileMigrationArgs: 1533e034f883SHet Gala# 1534e034f883SHet Gala# @filename: The file to receive the migration stream 1535e034f883SHet Gala# 1536e034f883SHet Gala# @offset: The file offset where the migration stream will start 1537e034f883SHet Gala# 153889a2273bSMarkus Armbruster# Since: 8.2 153989a2273bSMarkus Armbruster## 154037507c14SMarkus Armbruster{ 'struct': 'FileMigrationArgs', 1541e034f883SHet Gala 'data': { 'filename': 'str', 1542e034f883SHet Gala 'offset': 'uint64' } } 1543e034f883SHet Gala 1544e034f883SHet Gala## 1545e034f883SHet Gala# @MigrationExecCommand: 1546e034f883SHet Gala# 1547e034f883SHet Gala# @args: command (list head) and arguments to execute. 1548e034f883SHet Gala# 1549e034f883SHet Gala# Since: 8.2 1550e034f883SHet Gala## 1551e034f883SHet Gala{ 'struct': 'MigrationExecCommand', 1552074dbce5SHet Gala 'data': {'args': [ 'str' ] } } 1553074dbce5SHet Gala 1554074dbce5SHet Gala## 1555074dbce5SHet Gala# @MigrationAddress: 1556074dbce5SHet Gala# 1557074dbce5SHet Gala# Migration endpoint configuration. 155837507c14SMarkus Armbruster# 1559074dbce5SHet Gala# @transport: The migration stream transport mechanism 1560074dbce5SHet Gala# 1561074dbce5SHet Gala# Since: 8.2 1562074dbce5SHet Gala## 1563074dbce5SHet Gala{ 'union': 'MigrationAddress', 1564074dbce5SHet Gala 'base': { 'transport' : 'MigrationAddressType'}, 1565074dbce5SHet Gala 'discriminator': 'transport', 1566074dbce5SHet Gala 'data': { 1567074dbce5SHet Gala 'socket': 'SocketAddress', 15684061c334SMichael Tokarev 'exec': 'MigrationExecCommand', 1569074dbce5SHet Gala 'rdma': 'InetSocketAddress', 1570074dbce5SHet Gala 'file': 'FileMigrationArgs' } } 1571074dbce5SHet Gala 157237507c14SMarkus Armbruster## 1573074dbce5SHet Gala# @MigrationChannelType: 1574074dbce5SHet Gala# 1575074dbce5SHet Gala# The migration channel-type request options. 1576074dbce5SHet Gala# 1577074dbce5SHet Gala# @main: Main outbound migration channel. 1578074dbce5SHet Gala# 1579074dbce5SHet Gala# Since: 8.1 158048685a8eSMarkus Armbruster## 158148685a8eSMarkus Armbruster{ 'enum': 'MigrationChannelType', 158248685a8eSMarkus Armbruster 'data': [ 'main' ] } 158348685a8eSMarkus Armbruster 158448685a8eSMarkus Armbruster## 158548685a8eSMarkus Armbruster# @MigrationChannel: 1586074dbce5SHet Gala# 1587074dbce5SHet Gala# Migration stream channel parameters. 1588074dbce5SHet Gala# 1589a937b6aaSMarkus Armbruster# @channel-type: Channel type for transferring packet information. 1590a937b6aaSMarkus Armbruster# 159148685a8eSMarkus Armbruster# @addr: Migration endpoint configuration on destination interface. 159251f63ec7SPeter Maydell# 15937a4da28bSPeter Xu# Since: 8.1 15949bc6e893SMarkus Armbruster## 159548685a8eSMarkus Armbruster{ 'struct': 'MigrationChannel', 1596d461c279SJohn Snow 'data': { 159748685a8eSMarkus Armbruster 'channel-type': 'MigrationChannelType', 15981ed1d4d6SMarkus Armbruster 'addr': 'MigrationAddress' } } 15991ed1d4d6SMarkus Armbruster 1600d461c279SJohn Snow## 160148685a8eSMarkus Armbruster# @migrate: 1602d461c279SJohn Snow# 160348685a8eSMarkus Armbruster# Migrates the current running guest to another Virtual Machine. 16041ed1d4d6SMarkus Armbruster# 1605d461c279SJohn Snow# @uri: the Uniform Resource Identifier of the destination VM 160648685a8eSMarkus Armbruster# 16071ed1d4d6SMarkus Armbruster# @channels: list of migration stream channels with each stream in the 16081ed1d4d6SMarkus Armbruster# list connected to a destination interface endpoint. 16091ed1d4d6SMarkus Armbruster# 1610074dbce5SHet Gala# @detach: this argument exists only for compatibility reasons and is 16111ed1d4d6SMarkus Armbruster# ignored by QEMU 16127d08424cSMarkus Armbruster# 1613074dbce5SHet Gala# @resume: resume one paused migration, default "off". (since 3.0) 1614074dbce5SHet Gala# 1615074dbce5SHet Gala# Since: 0.14 1616074dbce5SHet Gala# 161714b48aaaSJohn Snow# .. admonition:: Notes 161848685a8eSMarkus Armbruster# 161948685a8eSMarkus Armbruster# 1. The 'query-migrate' command should be used to check 162048685a8eSMarkus Armbruster# migration's progress and final result (this information is 16213cee17e7SHet Gala# provided by the 'status' member). 1622074dbce5SHet Gala# 1623074dbce5SHet Gala# 2. All boolean arguments default to false. 1624074dbce5SHet Gala# 1625074dbce5SHet Gala# 3. The user Monitor's "detach" argument is invalid in QMP and 1626074dbce5SHet Gala# should not be used. 1627074dbce5SHet Gala# 1628074dbce5SHet Gala# 4. The uri argument should have the Uniform Resource Identifier 1629074dbce5SHet Gala# of default destination VM. This connection will be bound to 1630074dbce5SHet Gala# default network. 1631074dbce5SHet Gala# 1632074dbce5SHet Gala# 5. For now, number of migration streams is restricted to one, 1633074dbce5SHet Gala# i.e. number of items in 'channels' list is just 1. 1634074dbce5SHet Gala# 1635074dbce5SHet Gala# 6. The 'uri' and 'channels' arguments are mutually exclusive; 1636074dbce5SHet Gala# exactly one of the two should be present. 1637074dbce5SHet Gala# 1638074dbce5SHet Gala# .. qmp-example:: 1639074dbce5SHet Gala# 1640074dbce5SHet Gala# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 1641074dbce5SHet Gala# <- { "return": {} } 1642074dbce5SHet Gala# 1643074dbce5SHet Gala# -> { "execute": "migrate", 1644074dbce5SHet Gala# "arguments": { 1645074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1646074dbce5SHet Gala# "addr": { "transport": "socket", 1647074dbce5SHet Gala# "type": "inet", 1648074dbce5SHet Gala# "host": "10.12.34.9", 1649074dbce5SHet Gala# "port": "1050" } } ] } } 1650074dbce5SHet Gala# <- { "return": {} } 1651074dbce5SHet Gala# 1652074dbce5SHet Gala# -> { "execute": "migrate", 1653074dbce5SHet Gala# "arguments": { 165448685a8eSMarkus Armbruster# "channels": [ { "channel-type": "main", 165548685a8eSMarkus Armbruster# "addr": { "transport": "exec", 165657fd4b4eSHet Gala# "args": [ "/bin/nc", "-p", "6000", 1657074dbce5SHet Gala# "/some/sock" ] } } ] } } 16587a4da28bSPeter Xu# <- { "return": {} } 165948685a8eSMarkus Armbruster# 166048685a8eSMarkus Armbruster# -> { "execute": "migrate", 166148685a8eSMarkus Armbruster# "arguments": { 166248685a8eSMarkus Armbruster# "channels": [ { "channel-type": "main", 1663a937b6aaSMarkus Armbruster# "addr": { "transport": "rdma", 1664a937b6aaSMarkus Armbruster# "host": "10.12.34.9", 166548685a8eSMarkus Armbruster# "port": "1050" } } ] } } 166648685a8eSMarkus Armbruster# <- { "return": {} } 166748685a8eSMarkus Armbruster# 166848685a8eSMarkus Armbruster# -> { "execute": "migrate", 1669074dbce5SHet Gala# "arguments": { 1670074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1671074dbce5SHet Gala# "addr": { "transport": "file", 1672dbea1c89SVladimir Sementsov-Ogievskiy# "filename": "/tmp/migfile", 1673dbea1c89SVladimir Sementsov-Ogievskiy# "offset": "0x1000" } } ] } } 167401bed0ffSMarkus Armbruster# <- { "return": {} } 167501bed0ffSMarkus Armbruster## 1676dbea1c89SVladimir Sementsov-Ogievskiy{ 'command': 'migrate', 167748685a8eSMarkus Armbruster 'data': {'*uri': 'str', 167848685a8eSMarkus Armbruster '*channels': [ 'MigrationChannel' ], 1679d461c279SJohn Snow '*detach': 'bool', '*resume': 'bool' } } 168048685a8eSMarkus Armbruster 16811ed1d4d6SMarkus Armbruster## 16821ed1d4d6SMarkus Armbruster# @migrate-incoming: 16831ed1d4d6SMarkus Armbruster# 168448685a8eSMarkus Armbruster# Start an incoming migration, the qemu must have been started with 1685a937b6aaSMarkus Armbruster# -incoming defer 1686a937b6aaSMarkus Armbruster# 168748685a8eSMarkus Armbruster# @uri: The Uniform Resource Identifier identifying the source or 168848685a8eSMarkus Armbruster# address to listen on 168948685a8eSMarkus Armbruster# 16903cee17e7SHet Gala# @channels: list of migration stream channels with each stream in the 16917d08424cSMarkus Armbruster# list connected to a destination interface endpoint. 1692074dbce5SHet Gala# 16933cee17e7SHet Gala# @exit-on-error: Exit on incoming migration failure. Default true. 1694074dbce5SHet Gala# When set to false, the failure triggers a MIGRATION event, and 1695074dbce5SHet Gala# error details could be retrieved with query-migrate. 169614b48aaaSJohn Snow# (since 9.1) 169748685a8eSMarkus Armbruster# 169848685a8eSMarkus Armbruster# Since: 2.3 16993cee17e7SHet Gala# 170048685a8eSMarkus Armbruster# .. admonition:: Notes 1701074dbce5SHet Gala# 17023cee17e7SHet Gala# 1. It's a bad idea to use a string for the uri, but it needs to 1703074dbce5SHet Gala# stay compatible with -incoming and the format of the uri is 1704074dbce5SHet Gala# already exposed above libvirt. 1705074dbce5SHet Gala# 1706074dbce5SHet Gala# 2. QEMU must be started with -incoming defer to allow 1707074dbce5SHet Gala# migrate-incoming to be used. 1708074dbce5SHet Gala# 1709074dbce5SHet Gala# 3. The uri format is the same as for -incoming 1710074dbce5SHet Gala# 17113cee17e7SHet Gala# 4. For now, number of migration streams is restricted to one, 1712074dbce5SHet Gala# i.e. number of items in 'channels' list is just 1. 1713074dbce5SHet Gala# 1714074dbce5SHet Gala# 5. The 'uri' and 'channels' arguments are mutually exclusive; 1715074dbce5SHet Gala# exactly one of the two should be present. 1716074dbce5SHet Gala# 1717074dbce5SHet Gala# .. qmp-example:: 1718074dbce5SHet Gala# 17193cee17e7SHet Gala# -> { "execute": "migrate-incoming", 1720074dbce5SHet Gala# "arguments": { "uri": "tcp:0:4446" } } 1721074dbce5SHet Gala# <- { "return": {} } 1722074dbce5SHet Gala# 1723074dbce5SHet Gala# -> { "execute": "migrate-incoming", 1724074dbce5SHet Gala# "arguments": { 1725074dbce5SHet Gala# "channels": [ { "channel-type": "main", 172648685a8eSMarkus Armbruster# "addr": { "transport": "socket", 1727074dbce5SHet Gala# "type": "inet", 1728074dbce5SHet Gala# "host": "10.12.34.9", 1729dbea1c89SVladimir Sementsov-Ogievskiy# "port": "1050" } } ] } } 1730dbea1c89SVladimir Sementsov-Ogievskiy# <- { "return": {} } 173148685a8eSMarkus Armbruster# 173248685a8eSMarkus Armbruster# -> { "execute": "migrate-incoming", 173348685a8eSMarkus Armbruster# "arguments": { 173448685a8eSMarkus Armbruster# "channels": [ { "channel-type": "main", 1735a937b6aaSMarkus Armbruster# "addr": { "transport": "exec", 1736a937b6aaSMarkus Armbruster# "args": [ "/bin/nc", "-p", "6000", 173748685a8eSMarkus Armbruster# "/some/sock" ] } } ] } } 173848685a8eSMarkus Armbruster# <- { "return": {} } 1739a937b6aaSMarkus Armbruster# 1740a937b6aaSMarkus Armbruster# -> { "execute": "migrate-incoming", 174148685a8eSMarkus Armbruster# "arguments": { 1742a937b6aaSMarkus Armbruster# "channels": [ { "channel-type": "main", 1743a937b6aaSMarkus Armbruster# "addr": { "transport": "rdma", 17445d6c599fSAnthony PERARD# "host": "10.12.34.9", 174548685a8eSMarkus Armbruster# "port": "1050" } } ] } } 174648685a8eSMarkus Armbruster# <- { "return": {} } 174714b48aaaSJohn Snow## 174848685a8eSMarkus Armbruster{ 'command': 'migrate-incoming', 174948685a8eSMarkus Armbruster 'data': {'*uri': 'str', 175048685a8eSMarkus Armbruster '*channels': [ 'MigrationChannel' ], 175148685a8eSMarkus Armbruster '*exit-on-error': 'bool' } } 175248685a8eSMarkus Armbruster 17535d6c599fSAnthony PERARD## 17545d6c599fSAnthony PERARD# @xen-save-devices-state: 175548685a8eSMarkus Armbruster# 175648685a8eSMarkus Armbruster# Save the state of all devices to file. The RAM and the block 175728af9ba2SPhilippe Mathieu-Daudé# devices of the VM are not saved by this command. 175828af9ba2SPhilippe Mathieu-Daudé# 175928af9ba2SPhilippe Mathieu-Daudé# @filename: the file to save the state of the devices to as binary 176028af9ba2SPhilippe Mathieu-Daudé# data. See xen-save-devices-state.txt for a description of the 176128af9ba2SPhilippe Mathieu-Daudé# binary format. 176228af9ba2SPhilippe Mathieu-Daudé# 176328af9ba2SPhilippe Mathieu-Daudé# @live: Optional argument to ask QEMU to treat this command as part 176428af9ba2SPhilippe Mathieu-Daudé# of a live migration. Default to true. (since 2.11) 176514b48aaaSJohn Snow# 176628af9ba2SPhilippe Mathieu-Daudé# Since: 1.1 176728af9ba2SPhilippe Mathieu-Daudé# 176828af9ba2SPhilippe Mathieu-Daudé# .. qmp-example:: 176928af9ba2SPhilippe Mathieu-Daudé# 177028af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-save-devices-state", 177128af9ba2SPhilippe Mathieu-Daudé# "arguments": { "filename": "/tmp/save" } } 177228af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 177328af9ba2SPhilippe Mathieu-Daudé## 177428af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-save-devices-state', 177528af9ba2SPhilippe Mathieu-Daudé 'data': {'filename': 'str', '*live':'bool' } } 1776a937b6aaSMarkus Armbruster 1777a937b6aaSMarkus Armbruster## 177828af9ba2SPhilippe Mathieu-Daudé# @xen-set-global-dirty-log: 177928af9ba2SPhilippe Mathieu-Daudé# 1780a937b6aaSMarkus Armbruster# Enable or disable the global dirty log mode. 1781a937b6aaSMarkus Armbruster# 178228af9ba2SPhilippe Mathieu-Daudé# @enable: true to enable, false to disable. 178328af9ba2SPhilippe Mathieu-Daudé# 178428af9ba2SPhilippe Mathieu-Daudé# Since: 1.3 178514b48aaaSJohn Snow# 178628af9ba2SPhilippe Mathieu-Daudé# .. qmp-example:: 178728af9ba2SPhilippe Mathieu-Daudé# 178828af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-set-global-dirty-log", 178928af9ba2SPhilippe Mathieu-Daudé# "arguments": { "enable": true } } 179028af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 179128af9ba2SPhilippe Mathieu-Daudé## 179228af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 179328af9ba2SPhilippe Mathieu-Daudé 179448685a8eSMarkus Armbruster## 179548685a8eSMarkus Armbruster# @xen-load-devices-state: 179648685a8eSMarkus Armbruster# 179748685a8eSMarkus Armbruster# Load the state of all devices from file. The RAM and the block 179848685a8eSMarkus Armbruster# devices of the VM are not loaded by this command. 179948685a8eSMarkus Armbruster# 180048685a8eSMarkus Armbruster# @filename: the file to load the state of the devices from as binary 180148685a8eSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 180273c67f38SMarkus Armbruster# binary format. 180373c67f38SMarkus Armbruster# 180448685a8eSMarkus Armbruster# Since: 2.7 180514b48aaaSJohn Snow# 180648685a8eSMarkus Armbruster# .. qmp-example:: 180748685a8eSMarkus Armbruster# 180848685a8eSMarkus Armbruster# -> { "execute": "xen-load-devices-state", 180948685a8eSMarkus Armbruster# "arguments": { "filename": "/tmp/resume" } } 181048685a8eSMarkus Armbruster# <- { "return": {} } 181148685a8eSMarkus Armbruster## 181248685a8eSMarkus Armbruster{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 181348685a8eSMarkus Armbruster 1814335d10cdSMarc-André Lureau## 18158a9f1e1dSMarc-André Lureau# @xen-set-replication: 181648685a8eSMarkus Armbruster# 181748685a8eSMarkus Armbruster# Enable or disable replication. 181848685a8eSMarkus Armbruster# 181948685a8eSMarkus Armbruster# @enable: true to enable, false to disable. 182048685a8eSMarkus Armbruster# 182148685a8eSMarkus Armbruster# @primary: true for primary or false for secondary. 182248685a8eSMarkus Armbruster# 182348685a8eSMarkus Armbruster# @failover: true to do failover, false to stop. Cannot be specified 1824a937b6aaSMarkus Armbruster# if 'enable' is true. Default value is false. 1825a937b6aaSMarkus Armbruster# 182648685a8eSMarkus Armbruster# .. qmp-example:: 182748685a8eSMarkus Armbruster# 182848685a8eSMarkus Armbruster# -> { "execute": "xen-set-replication", 182948685a8eSMarkus Armbruster# "arguments": {"enable": true, "primary": false} } 1830335d10cdSMarc-André Lureau# <- { "return": {} } 18318a9f1e1dSMarc-André Lureau# 183248685a8eSMarkus Armbruster# Since: 2.9 183348685a8eSMarkus Armbruster## 183448685a8eSMarkus Armbruster{ 'command': 'xen-set-replication', 183548685a8eSMarkus Armbruster 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 183648685a8eSMarkus Armbruster 'if': 'CONFIG_REPLICATION' } 183748685a8eSMarkus Armbruster 1838f4347129SAndrea Bolognani## 183948685a8eSMarkus Armbruster# @ReplicationStatus: 184014b48aaaSJohn Snow# 184148685a8eSMarkus Armbruster# The result format for 'query-xen-replication-status'. 184248685a8eSMarkus Armbruster# 184348685a8eSMarkus Armbruster# @error: true if an error happened, false if replication is normal. 184448685a8eSMarkus Armbruster# 184548685a8eSMarkus Armbruster# @desc: the human readable error description string, when @error is 184648685a8eSMarkus Armbruster# 'true'. 184748685a8eSMarkus Armbruster# 1848335d10cdSMarc-André Lureau# Since: 2.9 18498a9f1e1dSMarc-André Lureau## 185048685a8eSMarkus Armbruster{ 'struct': 'ReplicationStatus', 185148685a8eSMarkus Armbruster 'data': { 'error': 'bool', '*desc': 'str' }, 185248685a8eSMarkus Armbruster 'if': 'CONFIG_REPLICATION' } 185348685a8eSMarkus Armbruster 185448685a8eSMarkus Armbruster## 185548685a8eSMarkus Armbruster# @query-xen-replication-status: 185614b48aaaSJohn Snow# 185748685a8eSMarkus Armbruster# Query replication status while the vm is running. 185848685a8eSMarkus Armbruster# 185948685a8eSMarkus Armbruster# Returns: A @ReplicationStatus object showing the status. 186048685a8eSMarkus Armbruster# 186148685a8eSMarkus Armbruster# .. qmp-example:: 186248685a8eSMarkus Armbruster# 1863335d10cdSMarc-André Lureau# -> { "execute": "query-xen-replication-status" } 18648a9f1e1dSMarc-André Lureau# <- { "return": { "error": false } } 186502affd41SPeter Xu# 186602affd41SPeter Xu# Since: 2.9 1867f56c0065SZhang Chen## 1868f56c0065SZhang Chen{ 'command': 'query-xen-replication-status', 1869f56c0065SZhang Chen 'returns': 'ReplicationStatus', 1870f56c0065SZhang Chen 'if': 'CONFIG_REPLICATION' } 1871a937b6aaSMarkus Armbruster 1872a937b6aaSMarkus Armbruster## 1873f56c0065SZhang Chen# @xen-colo-do-checkpoint: 18745cc8f9ebSZhang Chen# 1875a937b6aaSMarkus Armbruster# Xen uses this command to notify replication to trigger a checkpoint. 1876a937b6aaSMarkus Armbruster# 18775ed0decaSZhang Chen# .. qmp-example:: 1878f56c0065SZhang Chen# 1879f56c0065SZhang Chen# -> { "execute": "xen-colo-do-checkpoint" } 1880ea3b23e5SZhang Chen# <- { "return": {} } 1881f56c0065SZhang Chen# 1882f56c0065SZhang Chen# Since: 2.9 18835cc8f9ebSZhang Chen## 188451e47cf8SVladimir Sementsov-Ogievskiy{ 'command': 'xen-colo-do-checkpoint', 188551e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 1886f56c0065SZhang Chen 1887f56c0065SZhang Chen## 1888f56c0065SZhang Chen# @COLOStatus: 1889f56c0065SZhang Chen# 1890f56c0065SZhang Chen# The result format for 'query-colo-status'. 1891f56c0065SZhang Chen# 1892f56c0065SZhang Chen# @mode: COLO running mode. If COLO is running, this field will 1893f56c0065SZhang Chen# return 'primary' or 'secondary'. 189414b48aaaSJohn Snow# 1895f56c0065SZhang Chen# @last-mode: COLO last running mode. If COLO is running, this field 1896f56c0065SZhang Chen# will return same like mode field, after failover we can use this 189751ec294dSVictor Toso# field to get last colo mode. (since 4.0) 1898f56c0065SZhang Chen# 1899ea3b23e5SZhang Chen# @reason: describes the reason for the COLO exit. 1900f56c0065SZhang Chen# 1901f56c0065SZhang Chen# Since: 3.1 190251e47cf8SVladimir Sementsov-Ogievskiy## 190351e47cf8SVladimir Sementsov-Ogievskiy{ 'struct': 'COLOStatus', 1904f56c0065SZhang Chen 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 1905f56c0065SZhang Chen 'reason': 'COLOExitReason' }, 190602affd41SPeter Xu 'if': 'CONFIG_REPLICATION' } 190702affd41SPeter Xu 190802affd41SPeter Xu## 190902affd41SPeter Xu# @query-colo-status: 191002affd41SPeter Xu# 191102affd41SPeter Xu# Query COLO status while the vm is running. 191214b48aaaSJohn Snow# 191302affd41SPeter Xu# Returns: A @COLOStatus object showing the status. 191402affd41SPeter Xu# 191502affd41SPeter Xu# .. qmp-example:: 191602affd41SPeter Xu# 191702affd41SPeter Xu# -> { "execute": "query-colo-status" } 191851f63ec7SPeter Maydell# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 191902affd41SPeter Xu# 1920b0ddeba2SMarc-André Lureau# Since: 3.1 1921b0ddeba2SMarc-André Lureau## 192202affd41SPeter Xu{ 'command': 'query-colo-status', 1923bfbf89c2SPeter Xu 'returns': 'COLOStatus', 1924bfbf89c2SPeter Xu 'if': 'CONFIG_REPLICATION' } 1925bfbf89c2SPeter Xu 1926bfbf89c2SPeter Xu## 1927bfbf89c2SPeter Xu# @migrate-recover: 1928bfbf89c2SPeter Xu# 192914b48aaaSJohn Snow# Provide a recovery migration stream URI. 1930bfbf89c2SPeter Xu# 1931bfbf89c2SPeter Xu# @uri: the URI to be used for the recovery of migration stream. 1932bfbf89c2SPeter Xu# 1933bfbf89c2SPeter Xu# .. qmp-example:: 193451f63ec7SPeter Maydell# 1935bfbf89c2SPeter Xu# -> { "execute": "migrate-recover", 1936bfbf89c2SPeter Xu# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 1937d328e6f3SJens Freimann# <- { "return": {} } 1938d328e6f3SJens Freimann# 1939d328e6f3SJens Freimann# Since: 3.0 1940d328e6f3SJens Freimann## 1941d328e6f3SJens Freimann{ 'command': 'migrate-recover', 194201bed0ffSMarkus Armbruster 'data': { 'uri': 'str' }, 194301bed0ffSMarkus Armbruster 'allow-oob': true } 194401bed0ffSMarkus Armbruster 1945d328e6f3SJens Freimann## 1946d328e6f3SJens Freimann# @migrate-pause: 1947d328e6f3SJens Freimann# 1948d328e6f3SJens Freimann# Pause a migration. Currently it only supports postcopy. 1949d328e6f3SJens Freimann# 195014b48aaaSJohn Snow# .. qmp-example:: 19514ae65a52SAndrea Bolognani# 19520df5e9a3SVictor Toso# -> { "execute": "migrate-pause" } 19530df5e9a3SVictor Toso# <- { "return": {} } 19540df5e9a3SVictor Toso# 1955d328e6f3SJens Freimann# Since: 3.0 1956d328e6f3SJens Freimann## 1957d328e6f3SJens Freimann{ 'command': 'migrate-pause', 'allow-oob': true } 19587df3aa30SChuan Zheng 19597df3aa30SChuan Zheng## 196071864eadSHyman Huang(黄勇)# @UNPLUG_PRIMARY: 196171864eadSHyman Huang(黄勇)# 196271864eadSHyman Huang(黄勇)# Emitted from source side of a migration when migration state is 196371864eadSHyman Huang(黄勇)# WAIT_UNPLUG. Device was unplugged by guest operating system. 196471864eadSHyman Huang(黄勇)# Device resources in QEMU are kept on standby to be able to re-plug 196571864eadSHyman Huang(黄勇)# it in case of migration failure. 196671864eadSHyman Huang(黄勇)# 196771864eadSHyman Huang(黄勇)# @device-id: QEMU device id of the unplugged device 1968f78d4ed7SHyman Huang(黄勇)# 196971864eadSHyman Huang(黄勇)# Since: 4.2 197071864eadSHyman Huang(黄勇)# 197171864eadSHyman Huang(黄勇)# .. qmp-example:: 197271864eadSHyman Huang(黄勇)# 197371864eadSHyman Huang(黄勇)# <- { "event": "UNPLUG_PRIMARY", 19747df3aa30SChuan Zheng# "data": { "device-id": "hostdev0" }, 19757df3aa30SChuan Zheng# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 19765034e3d4SAndrei Gudkov## 19777df3aa30SChuan Zheng{ 'event': 'UNPLUG_PRIMARY', 19785034e3d4SAndrei Gudkov 'data': { 'device-id': 'str' } } 19797df3aa30SChuan Zheng 19805034e3d4SAndrei Gudkov## 19817df3aa30SChuan Zheng# @DirtyRateVcpu: 19825034e3d4SAndrei Gudkov# 19837df3aa30SChuan Zheng# Dirty rate of vcpu. 19847df3aa30SChuan Zheng# 19857df3aa30SChuan Zheng# @id: vcpu index. 19867df3aa30SChuan Zheng# 19877df3aa30SChuan Zheng# @dirty-rate: dirty rate. 19884c437254SChuan Zheng# 19894c437254SChuan Zheng# Since: 6.2 199071864eadSHyman Huang(黄勇)## 199171864eadSHyman Huang(黄勇){ 'struct': 'DirtyRateVcpu', 19925034e3d4SAndrei Gudkov 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 19935034e3d4SAndrei Gudkov 199471864eadSHyman Huang(黄勇)## 19955034e3d4SAndrei Gudkov# @DirtyRateStatus: 199671864eadSHyman Huang(黄勇)# 19975034e3d4SAndrei Gudkov# Dirty page rate measurement status. 1998826b8bc8SHyman Huang(黄勇)# 19995034e3d4SAndrei Gudkov# @unstarted: measuring thread has not been started yet 200071864eadSHyman Huang(黄勇)# 2001f78d4ed7SHyman Huang(黄勇)# @measuring: measuring thread is running 200271864eadSHyman Huang(黄勇)# 200371864eadSHyman Huang(黄勇)# @measured: dirty page rate is measured and the results are available 2004826b8bc8SHyman Huang(黄勇)# 200571864eadSHyman Huang(黄勇)# Since: 5.2 200671864eadSHyman Huang(黄勇)## 200734a68001SAndrei Gudkov{ 'enum': 'DirtyRateStatus', 200834a68001SAndrei Gudkov 'data': [ 'unstarted', 'measuring', 'measured'] } 200934a68001SAndrei Gudkov 201034a68001SAndrei Gudkov## 201134a68001SAndrei Gudkov# @DirtyRateMeasureMode: 201234a68001SAndrei Gudkov# 201334a68001SAndrei Gudkov# Method used to measure dirty page rate. Differences between 201434a68001SAndrei Gudkov# available methods are explained in @calc-dirty-rate. 201537507c14SMarkus Armbruster# 201634a68001SAndrei Gudkov# @page-sampling: use page sampling 201734a68001SAndrei Gudkov# 201834a68001SAndrei Gudkov# @dirty-ring: use dirty ring 201934a68001SAndrei Gudkov# 202034a68001SAndrei Gudkov# @dirty-bitmap: use dirty bitmap 20214c437254SChuan Zheng# 20224c437254SChuan Zheng# Since: 6.2 20235034e3d4SAndrei Gudkov## 20244c437254SChuan Zheng{ 'enum': 'DirtyRateMeasureMode', 2025a937b6aaSMarkus Armbruster 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 20265034e3d4SAndrei Gudkov 20274c437254SChuan Zheng## 20285034e3d4SAndrei Gudkov# @TimeUnit: 20294c437254SChuan Zheng# 20304c437254SChuan Zheng# Specifies unit in which time-related value is specified. 20314c437254SChuan Zheng# 203234a68001SAndrei Gudkov# @second: value is in seconds 203334a68001SAndrei Gudkov# 203434a68001SAndrei Gudkov# @millisecond: value is in milliseconds 203534a68001SAndrei Gudkov# 20364c437254SChuan Zheng# Since: 8.2 20375034e3d4SAndrei Gudkov## 20385034e3d4SAndrei Gudkov{ 'enum': 'TimeUnit', 20397afa08cdSHyman Huang(黄勇) 'data': ['second', 'millisecond'] } 20405034e3d4SAndrei Gudkov 20410e21bf24SHyman Huang(黄勇)## 20425034e3d4SAndrei Gudkov# @DirtyRateInfo: 2043a937b6aaSMarkus Armbruster# 20440e21bf24SHyman Huang(黄勇)# Information about measured dirty page rate. 20454c437254SChuan Zheng# 20464c437254SChuan Zheng# @dirty-rate: an estimate of the dirty page rate of the VM in units 20474c437254SChuan Zheng# of MiB/s. Value is present only when @status is 'measured'. 2048b1a859cfSChuan Zheng# 20494c437254SChuan Zheng# @status: current status of dirty page rate measurements 20504c437254SChuan Zheng# 20517afa08cdSHyman Huang(黄勇)# @start-time: start time in units of second for calculation 205234a68001SAndrei Gudkov# 20530e21bf24SHyman Huang(黄勇)# @calc-time: time period for which dirty page rate was measured, 20540e21bf24SHyman Huang(黄勇)# expressed and rounded down to @calc-time-unit. 20550e21bf24SHyman Huang(黄勇)# 20564c437254SChuan Zheng# @calc-time-unit: time unit of @calc-time (Since 8.2) 20574c437254SChuan Zheng# 20584c437254SChuan Zheng# @sample-pages: number of sampled pages per GiB of guest memory. 20594c437254SChuan Zheng# Valid only in page-sampling mode (Since 6.1) 20605034e3d4SAndrei Gudkov# 20615034e3d4SAndrei Gudkov# @mode: mode that was used to measure dirty page rate (Since 6.2) 20624c437254SChuan Zheng# 20635034e3d4SAndrei Gudkov# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 20645034e3d4SAndrei Gudkov# specified (Since 6.2) 20655034e3d4SAndrei Gudkov# 20664c437254SChuan Zheng# Since: 5.2 20675034e3d4SAndrei Gudkov## 20685034e3d4SAndrei Gudkov{ 'struct': 'DirtyRateInfo', 20695034e3d4SAndrei Gudkov 'data': {'*dirty-rate': 'int64', 20705034e3d4SAndrei Gudkov 'status': 'DirtyRateStatus', 20715034e3d4SAndrei Gudkov 'start-time': 'int64', 20725034e3d4SAndrei Gudkov 'calc-time': 'int64', 20735034e3d4SAndrei Gudkov 'calc-time-unit': 'TimeUnit', 20745034e3d4SAndrei Gudkov 'sample-pages': 'uint64', 20757afa08cdSHyman Huang(黄勇) 'mode': 'DirtyRateMeasureMode', 20765034e3d4SAndrei Gudkov '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 20775034e3d4SAndrei Gudkov 20785034e3d4SAndrei Gudkov## 20795034e3d4SAndrei Gudkov# @calc-dirty-rate: 20805034e3d4SAndrei Gudkov# 20815034e3d4SAndrei Gudkov# Start measuring dirty page rate of the VM. Results can be retrieved 20825034e3d4SAndrei Gudkov# with @query-dirty-rate after measurements are completed. 20835034e3d4SAndrei Gudkov# 20845034e3d4SAndrei Gudkov# Dirty page rate is the number of pages changed in a given time 20855034e3d4SAndrei Gudkov# period expressed in MiB/s. The following methods of calculation are 20865034e3d4SAndrei Gudkov# available: 20875034e3d4SAndrei Gudkov# 208801bed0ffSMarkus Armbruster# 1. In page sampling mode, a random subset of pages are selected and 208901bed0ffSMarkus Armbruster# hashed twice: once at the beginning of measurement time period, 209034a68001SAndrei Gudkov# and once again at the end. If two hashes for some page are 209134a68001SAndrei Gudkov# different, the page is counted as changed. Since this method 209201bed0ffSMarkus Armbruster# relies on sampling and hashing, calculated dirty page rate is 209301bed0ffSMarkus Armbruster# only an estimate of its true value. Increasing @sample-pages 209401bed0ffSMarkus Armbruster# improves estimation quality at the cost of higher computational 209534a68001SAndrei Gudkov# overhead. 209601bed0ffSMarkus Armbruster# 209701bed0ffSMarkus Armbruster# 2. Dirty bitmap mode captures writes to memory (for example by 20985034e3d4SAndrei Gudkov# temporarily revoking write access to all pages) and counting page 20995034e3d4SAndrei Gudkov# faults. Information about modified pages is collected into a 21005034e3d4SAndrei Gudkov# bitmap, where each bit corresponds to one guest page. This mode 21015034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is *not* 21025034e3d4SAndrei Gudkov# set. 21035034e3d4SAndrei Gudkov# 21045034e3d4SAndrei Gudkov# 3. Dirty ring mode is similar to dirty bitmap mode, but the 21055034e3d4SAndrei Gudkov# information about modified pages is collected into ring buffer. 21065034e3d4SAndrei Gudkov# This mode tracks page modification per each vCPU separately. It 21070e21bf24SHyman Huang(黄勇)# requires that KVM accelerator property "dirty-ring-size" is set. 21084c437254SChuan Zheng# 21094c437254SChuan Zheng# @calc-time: time period for which dirty page rate is calculated. By 21106f07c59fSJohn Snow# default it is specified in seconds, but the unit can be set 21114ae65a52SAndrea Bolognani# explicitly with @calc-time-unit. Note that larger @calc-time 211237fa48a4SMarkus Armbruster# values will typically result in smaller dirty page rates because 21139f2b8488SJohn Snow# page dirtying is a one-time event. Once some page is counted as 211437fa48a4SMarkus Armbruster# dirty during @calc-time period, further writes to this page will 211534a68001SAndrei Gudkov# not increase dirty page rate anymore. 21166f07c59fSJohn Snow# 21176f07c59fSJohn Snow# @calc-time-unit: time unit in which @calc-time is specified. By 21186f07c59fSJohn Snow# default it is seconds. (Since 8.2) 21196f07c59fSJohn Snow# 212034a68001SAndrei Gudkov# @sample-pages: number of sampled pages per each GiB of guest memory. 212134a68001SAndrei Gudkov# Default value is 512. For 4KiB guest pages this corresponds to 212234a68001SAndrei Gudkov# sampling ratio of 0.2%. This argument is used only in page 212334a68001SAndrei Gudkov# sampling mode. (Since 6.1) 212434a68001SAndrei Gudkov# 21254c437254SChuan Zheng# @mode: mechanism for tracking dirty pages. Default value is 21267afa08cdSHyman Huang(黄勇)# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 212734a68001SAndrei Gudkov# (Since 6.1) 21280e21bf24SHyman Huang(黄勇)# 21290e21bf24SHyman Huang(黄勇)# Since: 5.2 21304c437254SChuan Zheng# 21314c437254SChuan Zheng# .. qmp-example:: 21324c437254SChuan Zheng# 21334c437254SChuan Zheng# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 21345034e3d4SAndrei Gudkov# "sample-pages": 512} } 21354c437254SChuan Zheng# <- { "return": {} } 213634a68001SAndrei Gudkov# 213734a68001SAndrei Gudkov# .. qmp-example:: 213834a68001SAndrei Gudkov# :annotated: 21394c437254SChuan Zheng# 21405034e3d4SAndrei Gudkov# Measure dirty rate using dirty bitmap for 500 milliseconds:: 2141a9eab6e2SJohn Snow# 2142a9eab6e2SJohn Snow# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, 21435034e3d4SAndrei Gudkov# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } 21445034e3d4SAndrei Gudkov# 2145320a6cccSAndrei Gudkov# <- { "return": {} } 214634a68001SAndrei Gudkov## 21475034e3d4SAndrei Gudkov{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 2148a9eab6e2SJohn Snow '*calc-time-unit': 'TimeUnit', 2149a9eab6e2SJohn Snow '*sample-pages': 'int', 21505034e3d4SAndrei Gudkov '*mode': 'DirtyRateMeasureMode'} } 21515034e3d4SAndrei Gudkov 2152320a6cccSAndrei Gudkov## 215334a68001SAndrei Gudkov# @query-dirty-rate: 21544c437254SChuan Zheng# 215534a68001SAndrei Gudkov# Query results of the most recent invocation of @calc-dirty-rate. 215634a68001SAndrei Gudkov# 21570f0d83a4SDaniel P. Berrangé# @calc-time-unit: time unit in which to report calculation time. 21580f0d83a4SDaniel P. Berrangé# By default it is reported in seconds. (Since 8.2) 2159f3b2e38cSHyman Huang(黄勇)# 2160f3b2e38cSHyman Huang(黄勇)# Since: 5.2 2161f3b2e38cSHyman Huang(黄勇)# 2162f3b2e38cSHyman Huang(黄勇)# .. qmp-example:: 2163f3b2e38cSHyman Huang(黄勇)# :title: Measurement is in progress 2164f3b2e38cSHyman Huang(黄勇)# 2165f3b2e38cSHyman Huang(黄勇)# <- {"status": "measuring", "sample-pages": 512, 2166f3b2e38cSHyman Huang(黄勇)# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2167f3b2e38cSHyman Huang(黄勇)# "calc-time-unit": "second"} 2168f3b2e38cSHyman Huang(黄勇)# 2169f3b2e38cSHyman Huang(黄勇)# .. qmp-example:: 2170f3b2e38cSHyman Huang(黄勇)# :title: Measurement has been completed 2171f3b2e38cSHyman Huang(黄勇)# 2172f3b2e38cSHyman Huang(黄勇)# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 2173f3b2e38cSHyman Huang(黄勇)# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2174f3b2e38cSHyman Huang(黄勇)# "calc-time-unit": "second"} 2175f3b2e38cSHyman Huang(黄勇)## 2176f3b2e38cSHyman Huang(黄勇){ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 2177f3b2e38cSHyman Huang(黄勇) 'returns': 'DirtyRateInfo' } 2178f3b2e38cSHyman Huang(黄勇) 2179f3b2e38cSHyman Huang(黄勇)## 2180f3b2e38cSHyman Huang(黄勇)# @DirtyLimitInfo: 2181f3b2e38cSHyman Huang(黄勇)# 2182a937b6aaSMarkus Armbruster# Dirty page rate limit information of a virtual CPU. 2183a937b6aaSMarkus Armbruster# 2184a937b6aaSMarkus Armbruster# @cpu-index: index of a virtual CPU. 2185f3b2e38cSHyman Huang(黄勇)# 2186f3b2e38cSHyman Huang(黄勇)# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 2187f3b2e38cSHyman Huang(黄勇)# CPU, 0 means unlimited. 2188f3b2e38cSHyman Huang(黄勇)# 2189f3b2e38cSHyman Huang(黄勇)# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 2190f3b2e38cSHyman Huang(黄勇)# 2191f3b2e38cSHyman Huang(黄勇)# Since: 7.1 219214b48aaaSJohn Snow## 219337fa48a4SMarkus Armbruster{ 'struct': 'DirtyLimitInfo', 219437fa48a4SMarkus Armbruster 'data': { 'cpu-index': 'int', 2195f3b2e38cSHyman Huang(黄勇) 'limit-rate': 'uint64', 2196f3b2e38cSHyman Huang(黄勇) 'current-rate': 'uint64' } } 219737fa48a4SMarkus Armbruster 2198f3b2e38cSHyman Huang(黄勇)## 2199f3b2e38cSHyman Huang(黄勇)# @set-vcpu-dirty-limit: 2200f3b2e38cSHyman Huang(黄勇)# 2201f3b2e38cSHyman Huang(黄勇)# Set the upper limit of dirty page rate for virtual CPUs. 2202f3b2e38cSHyman Huang(黄勇)# 2203f3b2e38cSHyman Huang(黄勇)# Requires KVM with accelerator property "dirty-ring-size" set. A 2204f3b2e38cSHyman Huang(黄勇)# virtual CPU's dirty page rate is a measure of its memory load. To 2205f3b2e38cSHyman Huang(黄勇)# observe dirty page rates, use @calc-dirty-rate. 2206f3b2e38cSHyman Huang(黄勇)# 2207f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 2208f3b2e38cSHyman Huang(黄勇)# 2209f3b2e38cSHyman Huang(黄勇)# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 2210f3b2e38cSHyman Huang(黄勇)# 2211f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2212f3b2e38cSHyman Huang(黄勇)# 2213f3b2e38cSHyman Huang(黄勇)# .. qmp-example:: 2214f3b2e38cSHyman Huang(黄勇)# 2215f3b2e38cSHyman Huang(黄勇)# -> {"execute": "set-vcpu-dirty-limit"} 221614b48aaaSJohn Snow# "arguments": { "dirty-rate": 200, 221737fa48a4SMarkus Armbruster# "cpu-index": 1 } } 221837fa48a4SMarkus Armbruster# <- { "return": {} } 2219f3b2e38cSHyman Huang(黄勇)## 222037fa48a4SMarkus Armbruster{ 'command': 'set-vcpu-dirty-limit', 2221f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int', 2222f3b2e38cSHyman Huang(黄勇) 'dirty-rate': 'uint64' } } 2223f3b2e38cSHyman Huang(黄勇) 2224f3b2e38cSHyman Huang(黄勇)## 2225f3b2e38cSHyman Huang(黄勇)# @cancel-vcpu-dirty-limit: 2226f3b2e38cSHyman Huang(黄勇)# 2227f3b2e38cSHyman Huang(黄勇)# Cancel the upper limit of dirty page rate for virtual CPUs. 2228a937b6aaSMarkus Armbruster# 2229a937b6aaSMarkus Armbruster# Cancel the dirty page limit for the vCPU which has been set with 2230f3b2e38cSHyman Huang(黄勇)# set-vcpu-dirty-limit command. Note that this command requires 2231f3b2e38cSHyman Huang(黄勇)# support from dirty ring, same as the "set-vcpu-dirty-limit". 2232f3b2e38cSHyman Huang(黄勇)# 223314b48aaaSJohn Snow# @cpu-index: index of a virtual CPU, default is all. 223437fa48a4SMarkus Armbruster# 223537fa48a4SMarkus Armbruster# Since: 7.1 223637fa48a4SMarkus Armbruster# 223737fa48a4SMarkus Armbruster# .. qmp-example:: 223837fa48a4SMarkus Armbruster# 2239f3b2e38cSHyman Huang(黄勇)# -> {"execute": "cancel-vcpu-dirty-limit"}, 2240f3b2e38cSHyman Huang(黄勇)# "arguments": { "cpu-index": 1 } } 2241f3b2e38cSHyman Huang(黄勇)# <- { "return": {} } 2242f3b2e38cSHyman Huang(黄勇)## 2243f3b2e38cSHyman Huang(黄勇){ 'command': 'cancel-vcpu-dirty-limit', 224467132620SJiang Jiacheng 'data': { '*cpu-index': 'int'} } 224567132620SJiang Jiacheng 224667132620SJiang Jiacheng## 224767132620SJiang Jiacheng# @query-vcpu-dirty-limit: 224867132620SJiang Jiacheng# 224967132620SJiang Jiacheng# Returns information about virtual CPU dirty page rate limits, if 225067132620SJiang Jiacheng# any. 225167132620SJiang Jiacheng# 225267132620SJiang Jiacheng# Since: 7.1 225367132620SJiang Jiacheng# 225467132620SJiang Jiacheng# .. qmp-example:: 225567132620SJiang Jiacheng# 225667132620SJiang Jiacheng# -> {"execute": "query-vcpu-dirty-limit"} 225767132620SJiang Jiacheng# <- {"return": [ 225867132620SJiang Jiacheng# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 225967132620SJiang Jiacheng# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 226067132620SJiang Jiacheng## 226167132620SJiang Jiacheng{ 'command': 'query-vcpu-dirty-limit', 226267132620SJiang Jiacheng 'returns': [ 'DirtyLimitInfo' ] } 2263e6c60bf0SMarkus Armbruster 226467132620SJiang Jiacheng## 226567132620SJiang Jiacheng# @MigrationThreadInfo: 226667132620SJiang Jiacheng# 226767132620SJiang Jiacheng# Information about migrationthreads 226867132620SJiang Jiacheng# 226967132620SJiang Jiacheng# @name: the name of migration thread 227067132620SJiang Jiacheng# 22710f0d83a4SDaniel P. Berrangé# @thread-id: ID of the underlying host thread 22720f0d83a4SDaniel P. Berrangé# 22730f0d83a4SDaniel P. Berrangé# Since: 7.2 22740f0d83a4SDaniel P. Berrangé## 22750f0d83a4SDaniel P. Berrangé{ 'struct': 'MigrationThreadInfo', 2276a937b6aaSMarkus Armbruster 'data': {'name': 'str', 22770f0d83a4SDaniel P. Berrangé 'thread-id': 'int'} } 2278a937b6aaSMarkus Armbruster 22790f0d83a4SDaniel P. Berrangé## 2280a937b6aaSMarkus Armbruster# @query-migrationthreads: 22810f0d83a4SDaniel P. Berrangé# 22820f0d83a4SDaniel P. Berrangé# Returns information of migration threads 22830f0d83a4SDaniel P. Berrangé# 22840f0d83a4SDaniel P. Berrangé# Returns: @MigrationThreadInfo 2285a937b6aaSMarkus Armbruster# 2286a937b6aaSMarkus Armbruster# Since: 7.2 22870f0d83a4SDaniel P. Berrangé## 2288a937b6aaSMarkus Armbruster{ 'command': 'query-migrationthreads', 2289a937b6aaSMarkus Armbruster 'returns': ['MigrationThreadInfo'] } 2290a937b6aaSMarkus Armbruster 22910f0d83a4SDaniel P. Berrangé## 2292a937b6aaSMarkus Armbruster# @snapshot-save: 2293a937b6aaSMarkus Armbruster# 22940f0d83a4SDaniel P. Berrangé# Save a VM snapshot 22950f0d83a4SDaniel P. Berrangé# 22960f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 229714b48aaaSJohn Snow# 22980f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to create 22990f0d83a4SDaniel P. Berrangé# 2300b1ca5322SFabian Holler# @vmstate: block device node name to save vmstate to 23010f0d83a4SDaniel P. Berrangé# 23020f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to save a snapshot to 23030f0d83a4SDaniel P. Berrangé# 23040f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot save is complete 23050f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 23060f0d83a4SDaniel P. Berrangé# to determine completion and to fetch details of any errors that 23070f0d83a4SDaniel P. Berrangé# arise. 23080f0d83a4SDaniel P. Berrangé# 23096e7a37ffSVictor Toso# Note that execution of the guest CPUs may be stopped during the time 23100f0d83a4SDaniel P. Berrangé# it takes to save the snapshot. A future version of QEMU may ensure 23110f0d83a4SDaniel P. Berrangé# CPUs are executing continuously. 23126e7a37ffSVictor Toso# 23130f0d83a4SDaniel P. Berrangé# It is strongly recommended that @devices contain all writable block 23146e7a37ffSVictor Toso# device nodes if a consistent snapshot is required. 23156e7a37ffSVictor Toso# 23166e7a37ffSVictor Toso# If @tag already exists, an error will be reported 23176e7a37ffSVictor Toso# 23180f0d83a4SDaniel P. Berrangé# .. qmp-example:: 23196e7a37ffSVictor Toso# 23200f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-save", 23210f0d83a4SDaniel P. Berrangé# "arguments": { 23226e7a37ffSVictor Toso# "job-id": "snapsave0", 23230f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 23240f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 23256e7a37ffSVictor Toso# "devices": ["disk0", "disk1"] 23260f0d83a4SDaniel P. Berrangé# } 23270f0d83a4SDaniel P. Berrangé# } 23280f0d83a4SDaniel P. Berrangé# <- { "return": { } } 23290f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 23300f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 23310f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapsave0"}} 23320f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 23330f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 23340f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapsave0"}} 23350f0d83a4SDaniel P. Berrangé# <- {"event": "STOP", 23360f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 23370f0d83a4SDaniel P. Berrangé# <- {"event": "RESUME", 23380f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 23390f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 23400f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 23410f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapsave0"}} 23420f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 23430f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 23440f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapsave0"}} 23450f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 23460f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 23470f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapsave0"}} 2348a937b6aaSMarkus Armbruster# -> {"execute": "query-jobs"} 23490f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 2350a937b6aaSMarkus Armbruster# "status": "concluded", 23510f0d83a4SDaniel P. Berrangé# "total-progress": 1, 2352a937b6aaSMarkus Armbruster# "type": "snapshot-save", 23530f0d83a4SDaniel P. Berrangé# "id": "snapsave0"}]} 23540f0d83a4SDaniel P. Berrangé# 23550f0d83a4SDaniel P. Berrangé# Since: 6.0 23560f0d83a4SDaniel P. Berrangé## 2357a937b6aaSMarkus Armbruster{ 'command': 'snapshot-save', 2358a937b6aaSMarkus Armbruster 'data': { 'job-id': 'str', 23590f0d83a4SDaniel P. Berrangé 'tag': 'str', 23600f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 23610f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 23620f0d83a4SDaniel P. Berrangé 2363a937b6aaSMarkus Armbruster## 2364a937b6aaSMarkus Armbruster# @snapshot-load: 2365a937b6aaSMarkus Armbruster# 23660f0d83a4SDaniel P. Berrangé# Load a VM snapshot 236714b48aaaSJohn Snow# 23680f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 23690f0d83a4SDaniel P. Berrangé# 2370b1ca5322SFabian Holler# @tag: name of the snapshot to load. 23710f0d83a4SDaniel P. Berrangé# 23720f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to load vmstate from 23730f0d83a4SDaniel P. Berrangé# 23740f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to load a snapshot from 23750f0d83a4SDaniel P. Berrangé# 23760f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot load is complete 23770f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 23780f0d83a4SDaniel P. Berrangé# to determine completion and to fetch details of any errors that 23796e7a37ffSVictor Toso# arise. 23800f0d83a4SDaniel P. Berrangé# 23810f0d83a4SDaniel P. Berrangé# Note that execution of the guest CPUs will be stopped during the 23826e7a37ffSVictor Toso# time it takes to load the snapshot. 23830f0d83a4SDaniel P. Berrangé# 23846e7a37ffSVictor Toso# It is strongly recommended that @devices contain all writable block 23856e7a37ffSVictor Toso# device nodes that can have changed since the original @snapshot-save 23866e7a37ffSVictor Toso# command execution. 23876e7a37ffSVictor Toso# 23880f0d83a4SDaniel P. Berrangé# .. qmp-example:: 23896e7a37ffSVictor Toso# 23900f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-load", 23910f0d83a4SDaniel P. Berrangé# "arguments": { 23926e7a37ffSVictor Toso# "job-id": "snapload0", 23930f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 23940f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 23956e7a37ffSVictor Toso# "devices": ["disk0", "disk1"] 23960f0d83a4SDaniel P. Berrangé# } 23970f0d83a4SDaniel P. Berrangé# } 23980f0d83a4SDaniel P. Berrangé# <- { "return": { } } 23990f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24000f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 24010f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapload0"}} 24020f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24030f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 24040f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapload0"}} 24050f0d83a4SDaniel P. Berrangé# <- {"event": "STOP", 24060f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 24070f0d83a4SDaniel P. Berrangé# <- {"event": "RESUME", 24080f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 24090f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24100f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 24110f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapload0"}} 24120f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24130f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 24140f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapload0"}} 24150f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24160f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 24170f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapload0"}} 2418a937b6aaSMarkus Armbruster# -> {"execute": "query-jobs"} 24190f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 2420a937b6aaSMarkus Armbruster# "status": "concluded", 24210f0d83a4SDaniel P. Berrangé# "total-progress": 1, 24220f0d83a4SDaniel P. Berrangé# "type": "snapshot-load", 24230f0d83a4SDaniel P. Berrangé# "id": "snapload0"}]} 24240f0d83a4SDaniel P. Berrangé# 2425a937b6aaSMarkus Armbruster# Since: 6.0 2426a937b6aaSMarkus Armbruster## 24270f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-load', 242814b48aaaSJohn Snow 'data': { 'job-id': 'str', 24290f0d83a4SDaniel P. Berrangé 'tag': 'str', 24300f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 2431b1ca5322SFabian Holler 'devices': ['str'] } } 24320f0d83a4SDaniel P. Berrangé 24330f0d83a4SDaniel P. Berrangé## 24340f0d83a4SDaniel P. Berrangé# @snapshot-delete: 24350f0d83a4SDaniel P. Berrangé# 24360f0d83a4SDaniel P. Berrangé# Delete a VM snapshot 24370f0d83a4SDaniel P. Berrangé# 24380f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 24396e7a37ffSVictor Toso# 24400f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to delete. 24410f0d83a4SDaniel P. Berrangé# 24426e7a37ffSVictor Toso# @devices: list of block device node names to delete a snapshot from 24430f0d83a4SDaniel P. Berrangé# 24440f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot delete is complete 24456e7a37ffSVictor Toso# when this command returns. The job commands / events must be used 24460f0d83a4SDaniel P. Berrangé# to determine completion and to fetch details of any errors that 24470f0d83a4SDaniel P. Berrangé# arise. 24486e7a37ffSVictor Toso# 24490f0d83a4SDaniel P. Berrangé# .. qmp-example:: 24500f0d83a4SDaniel P. Berrangé# 24516e7a37ffSVictor Toso# -> { "execute": "snapshot-delete", 24520f0d83a4SDaniel P. Berrangé# "arguments": { 24530f0d83a4SDaniel P. Berrangé# "job-id": "snapdelete0", 24540f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 24550f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 24560f0d83a4SDaniel P. Berrangé# } 24570f0d83a4SDaniel P. Berrangé# } 24580f0d83a4SDaniel P. Berrangé# <- { "return": { } } 24590f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24600f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 24610f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapdelete0"}} 24620f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24630f0d83a4SDaniel P. Berrangé# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 24640f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapdelete0"}} 24650f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 2466# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 2467# "data": {"status": "waiting", "id": "snapdelete0"}} 2468# <- {"event": "JOB_STATUS_CHANGE", 2469# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 2470# "data": {"status": "pending", "id": "snapdelete0"}} 2471# <- {"event": "JOB_STATUS_CHANGE", 2472# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 2473# "data": {"status": "concluded", "id": "snapdelete0"}} 2474# -> {"execute": "query-jobs"} 2475# <- {"return": [{"current-progress": 1, 2476# "status": "concluded", 2477# "total-progress": 1, 2478# "type": "snapshot-delete", 2479# "id": "snapdelete0"}]} 2480# 2481# Since: 6.0 2482## 2483{ 'command': 'snapshot-delete', 2484 'data': { 'job-id': 'str', 2485 'tag': 'str', 2486 'devices': ['str'] } } 2487