On Thu, May 25, 2023 at 03:08:35PM +0200, Markus Armbruster wrote: > Andrei Gudkov <[email protected]> writes: > > > 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 <[email protected]> > > --- > > 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'. > > For consistency, please put two spaces between setences. > > > # > > -# @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 > > Maybe > > # @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 each GiB of guest > > per GiB > > > +# memory. Value is valid only in page-sampling mode (Since 6.1) > > Suggest "Valid only in ..." > > > # > > -# @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 > > Imperative mood: "Start measuring ..." > > > +# 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 > > Suggest "once at the beginning" > > > +# period, another one -- in the end. If two hashes for some page > > Suggest ", and once again at the end". > > > +# 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 > > Suggest "Increasing @sample-pages improves estimation quality at the > cost ..." > > > +# 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. > > Comma before "and". > > > +# Information about modified pages is collected into bitmap, > > "into a bitmap" > > > +# where each bit corresponds to one guest page. This mode > > +# requires that KVM accelerator property "dirty-ring-size=N" > > Suggest just "dirty-ring-size" (omit "=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. > > Either "for each vCPU" or "per vCPU". > > > +# It requires that KVM accelerator property "dirty-ring-size=N" > > +# is set. > > Suggest just "dirty-ring-size" (omit "=N"). > > > +# > > +# @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. > > Please indent one more, for consistency. > > > +# > > +# @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) > > Two spaces between '.' and '(', please. > > > +# > > +# @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' } > > This is *sooo* much better than before. Thank you! > > An R-by from a migration maintainer would be nice. > > If you agree with my suggestions, I can apply them in my tree, saving > you a respin. Let me know.
Yes, sure. Please include also suggestion about wr-protect from Peter. Thanks. > > Acked-by: Markus Armbruster <[email protected]>
