From 5034e3d4e8324691581f269d49fc28f20c8a62de Mon Sep 17 00:00:00 2001 From: Andrei Gudkov Date: Tue, 23 May 2023 18:19:56 +0300 Subject: qapi: better docs for calc-dirty-rate and friends Rewrote calc-dirty-rate documentation. Briefly described different modes of dirty page rate measurement. Added some examples. Fixed obvious grammar errors. Signed-off-by: Andrei Gudkov Message-Id: Acked-by: Markus Armbruster Acked-by: Peter Xu [Prose tweaked and spacing corrected, as per review] Signed-off-by: Markus Armbruster --- qapi/migration.json | 103 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 74 insertions(+), 29 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 47dfef0..52ff5be 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1745,14 +1745,13 @@ ## # @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 ## @@ -1762,13 +1761,14 @@ ## # @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 ## @@ -1778,25 +1778,24 @@ ## # @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 @@ -1813,15 +1812,49 @@ ## # @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 # @@ -1838,9 +1871,21 @@ ## # @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' } -- cgit v1.1 From fd658a7b8cf1091ae2914655add4511865d7edc0 Mon Sep 17 00:00:00 2001 From: Juan Quintela Date: Mon, 12 Jun 2023 21:16:04 +0200 Subject: migration.json: Don't use space before colon So all the file is consistent. Signed-off-by: Juan Quintela Message-Id: <20230612191604.2219-1-quintela@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/migration.json | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 52ff5be..2a6565a 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -67,13 +67,13 @@ { '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: @@ -264,7 +264,7 @@ '*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'] } } @@ -526,7 +526,7 @@ # Since: 1.2 ## { 'struct': 'MigrationCapabilityStatus', - 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } } + 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } ## # @migrate-set-capabilities: @@ -1577,7 +1577,7 @@ # Since: 2.9 ## { 'command': 'xen-set-replication', - 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' }, + 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 'if': 'CONFIG_REPLICATION' } ## -- cgit v1.1