{ 'struct': 'MigrationStats',
'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
- 'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
- 'mbps' : 'number', 'dirty-sync-count' : 'int',
- 'postcopy-requests' : 'int', 'page-size' : 'int',
- 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64',
- 'precopy-bytes' : 'uint64', 'downtime-bytes' : 'uint64',
- 'postcopy-bytes' : 'uint64',
- 'dirty-sync-missed-zero-copy' : 'uint64' } }
+ 'normal-bytes': 'int', 'dirty-pages-rate': 'int',
+ 'mbps': 'number', 'dirty-sync-count': 'int',
+ 'postcopy-requests': 'int', 'page-size': 'int',
+ 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64',
+ 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64',
+ 'postcopy-bytes': 'uint64',
+ 'dirty-sync-missed-zero-copy': 'uint64' } }
##
# @XBZRLECacheStats:
'*cpu-throttle-percentage': 'int',
'*error-desc': 'str',
'*blocked-reasons': ['str'],
- '*postcopy-blocktime' : 'uint32',
+ '*postcopy-blocktime': 'uint32',
'*postcopy-vcpu-blocktime': ['uint32'],
'*compression': 'CompressionStats',
'*socket-address': ['SocketAddress'] } }
# Since: 1.2
##
{ 'struct': 'MigrationCapabilityStatus',
- 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
+ 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } }
##
# @migrate-set-capabilities:
# Since: 2.9
##
{ 'command': 'xen-set-replication',
- 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' },
+ 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' },
'if': 'CONFIG_REPLICATION' }
##
##
# @DirtyRateStatus:
#
-# An enumeration of dirtyrate status.
+# Dirty page rate measurement status.
#
-# @unstarted: the dirtyrate thread has not been started.
+# @unstarted: measuring thread has not been started yet
#
-# @measuring: the dirtyrate thread is measuring.
+# @measuring: measuring thread is running
#
-# @measured: the dirtyrate thread has measured and results are
-# available.
+# @measured: dirty page rate is measured and the results are available
#
# Since: 5.2
##
##
# @DirtyRateMeasureMode:
#
-# An enumeration of mode of measuring dirtyrate.
+# Method used to measure dirty page rate. Differences between
+# available methods are explained in @calc-dirty-rate.
#
-# @page-sampling: calculate dirtyrate by sampling pages.
+# @page-sampling: use page sampling
#
-# @dirty-ring: calculate dirtyrate by dirty ring.
+# @dirty-ring: use dirty ring
#
-# @dirty-bitmap: calculate dirtyrate by dirty bitmap.
+# @dirty-bitmap: use dirty bitmap
#
# Since: 6.2
##
##
# @DirtyRateInfo:
#
-# Information about current dirty page rate of vm.
+# Information about measured dirty page rate.
#
# @dirty-rate: an estimate of the dirty page rate of the VM in units
-# of MB/s, present only when estimating the rate has completed.
+# of MiB/s. Value is present only when @status is 'measured'.
#
-# @status: status containing dirtyrate query status includes
-# 'unstarted' or 'measuring' or 'measured'
+# @status: current status of dirty page rate measurements
#
# @start-time: start time in units of second for calculation
#
-# @calc-time: time in units of second for sample dirty pages
+# @calc-time: time period for which dirty page rate was measured
+# (in seconds)
#
-# @sample-pages: page count per GB for sample dirty pages the default
-# value is 512 (since 6.1)
+# @sample-pages: number of sampled pages per GiB of guest memory.
+# Valid only in page-sampling mode (Since 6.1)
#
-# @mode: mode containing method of calculate dirtyrate includes
-# 'page-sampling' and 'dirty-ring' (Since 6.2)
+# @mode: mode that was used to measure dirty page rate (Since 6.2)
#
-# @vcpu-dirty-rate: dirtyrate for each vcpu if dirty-ring mode
+# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was
# specified (Since 6.2)
#
# Since: 5.2
##
# @calc-dirty-rate:
#
-# start calculating dirty page rate for vm
-#
-# @calc-time: time in units of second for sample dirty pages
-#
-# @sample-pages: page count per GB for sample dirty pages the default
-# value is 512 (since 6.1)
-#
-# @mode: mechanism of calculating dirtyrate includes 'page-sampling'
-# and 'dirty-ring' (Since 6.1)
+# Start measuring dirty page rate of the VM. Results can be retrieved
+# with @query-dirty-rate after measurements are completed.
+#
+# Dirty page rate is the number of pages changed in a given time
+# period expressed in MiB/s. The following methods of calculation are
+# available:
+#
+# 1. In page sampling mode, a random subset of pages are selected and
+# hashed twice: once at the beginning of measurement time period,
+# and once again at the end. If two hashes for some page are
+# different, the page is counted as changed. Since this method
+# relies on sampling and hashing, calculated dirty page rate is
+# only an estimate of its true value. Increasing @sample-pages
+# improves estimation quality at the cost of higher computational
+# overhead.
+#
+# 2. Dirty bitmap mode captures writes to memory (for example by
+# temporarily revoking write access to all pages) and counting page
+# faults. Information about modified pages is collected into a
+# bitmap, where each bit corresponds to one guest page. This mode
+# requires that KVM accelerator property "dirty-ring-size" is *not*
+# set.
+#
+# 3. Dirty ring mode is similar to dirty bitmap mode, but the
+# information about modified pages is collected into ring buffer.
+# This mode tracks page modification per each vCPU separately. It
+# requires that KVM accelerator property "dirty-ring-size" is set.
+#
+# @calc-time: time period in units of second for which dirty page rate
+# is calculated. Note that larger @calc-time values will
+# typically result in smaller dirty page rates because page
+# dirtying is a one-time event. Once some page is counted as
+# dirty during @calc-time period, further writes to this page will
+# not increase dirty page rate anymore.
+#
+# @sample-pages: number of sampled pages per each GiB of guest memory.
+# Default value is 512. For 4KiB guest pages this corresponds to
+# sampling ratio of 0.2%. This argument is used only in page
+# sampling mode. (Since 6.1)
+#
+# @mode: mechanism for tracking dirty pages. Default value is
+# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'.
+# (Since 6.1)
#
# Since: 5.2
#
##
# @query-dirty-rate:
#
-# query dirty page rate in units of MB/s for vm
+# Query results of the most recent invocation of @calc-dirty-rate.
#
# Since: 5.2
+#
+# Examples:
+#
+# 1. Measurement is in progress:
+#
+# <- {"status": "measuring", "sample-pages": 512,
+# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10}
+#
+# 2. Measurement has been completed:
+#
+# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
+# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10}
##
{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' }
projects / mirror_qemu.git / commitdiff