[PATCH] qapi: better docs for calc-dirty-rate and friends

[Andrei Gudkov]

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 <gudkov.andrei@huawei.com>
---
 qapi/migration.json | 107 +++++++++++++++++++++++++++++++-------------
 1 file changed, 77 insertions(+), 30 deletions(-)

diff --git a/qapi/migration.json b/qapi/migration.json
index 179af0c4d8..19b51444b5 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1735,14 +1735,14 @@
 ##
 # @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
 ##
@@ -1752,13 +1752,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
 ##
@@ -1768,26 +1769,25 @@
 ##
 # @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 in units of second for which dirty page
+#     rate was measured
 #
-# @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 each GiB of guest
+#     memory.  Value is 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
-#     specified (Since 6.2)
+# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode
+#     was specified (Since 6.2)
 #
 # Since: 5.2
 ##
@@ -1803,15 +1803,50 @@
 ##
 # @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)
+# Starts 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 in the beginning of measurement time
+#    period, another one -- in 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 the estimation of its true value.  Setting
+#    @sample-pages to higher value improves estimation quality but
+#    at the cost of higher computational overhead.
+#
+# 2. Dirty bitmap mode captures writes to memory by temporarily
+#    revoking write access to all pages and counting page faults.
+#    Information about modified pages is collected into bitmap,
+#    where each bit corresponds to one guest page.  This mode
+#    requires that KVM accelerator property "dirty-ring-size=N"
+#    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=N"
+#    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
 #
@@ -1828,9 +1863,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' }
 
-- 
2.30.2