| Message ID | 20210706180350.2838127-3-jingzhangos@google.com |
|---|---|
| State | New |
| Headers | show |
| Series | Linear and Logarithmic histogram statistics | expand |
On Tue, Jul 06, 2021 at 06:03:48PM +0000, Jing Zhang wrote: > Add documentations for linear and logarithmic histogram statistics. > Add binary stats capability text which is missing during merge of > the binary stats patch. > > Signed-off-by: Jing Zhang <jingzhangos@google.com> > --- > Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- > 1 file changed, 33 insertions(+), 3 deletions(-) > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > index 3b6e3b1628b4..948d33c26704 100644 > --- a/Documentation/virt/kvm/api.rst > +++ b/Documentation/virt/kvm/api.rst > @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. > #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) > #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) > #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST > > #define KVM_STATS_UNIT_SHIFT 4 > #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) > @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. > #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) > #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) > #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) > + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES > > #define KVM_STATS_BASE_SHIFT 8 > #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) > #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) > #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) > + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 > > struct kvm_stats_desc { > __u32 flags; > @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: > represents a peak value for a measurement, for example the maximum number > of items in a hash table bucket, the longest time waited and so on. > The corresponding ``size`` field for this type is always 1. > + * ``KVM_STATS_TYPE_LINEAR_HIST`` > + The statistics data is in the form of linear histogram. The number of > + buckets is specified by the ``size`` field. The size of buckets is specified > + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) > + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last > + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity > + value.) The bucket value indicates how many times the statistics data is in > + the bucket's range. > + * ``KVM_STATS_TYPE_LOG_HIST`` > + The statistics data is in the form of logarithmic histogram. The number of > + buckets is specified by the ``size`` field. The base of logarithm is > + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < > + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range > + of the first bucket is [0, 1), while the range of the last bucket is > + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many > + times the statistics data is in the bucket's range. > > Bits 4-7 of ``flags`` encode the unit: > * ``KVM_STATS_UNIT_NONE`` > @@ -5246,9 +5267,10 @@ unsigned 64bit data. > The ``offset`` field is the offset from the start of Data Block to the start of > the corresponding statistics data. > > -The ``unused`` field is reserved for future support for other types of > -statistics data, like log/linear histogram. Its value is always 0 for the types > -defined above. > +The ``hist_param`` field is used as a parameter for histogram statistics data. > +For linear histogram statistics data, it indicates the size of a bucket. For > +logarithmic histogram statistics data, it indicates the base of the logarithm. > +Only base of 2 is supported fo logarithmic histogram. > > The ``name`` field is the name string of the statistics data. The name string > starts at the end of ``struct kvm_stats_desc``. The maximum length including > @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset > of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace > the hypercalls whose corresponding bit is in the argument, and return > ENOSYS for the others. > + > +8.35 KVM_CAP_STATS_BINARY_FD > +---------------------------- > + > +:Architectures: all > + > +This capability indicates the feature that userspace can get a file descriptor > +for every VM and VCPU to read statistics data in binary format. This should probably be in a separate patch with a Fixes tag. Fixes: fdc09ddd4064 ("KVM: stats: Add documentation for binary statistics interface") > -- > 2.32.0.93.g670b81a890-goog >
On Wed, Jul 7, 2021 at 6:31 PM David Matlack <dmatlack@google.com> wrote: > > On Tue, Jul 06, 2021 at 06:03:48PM +0000, Jing Zhang wrote: > > Add documentations for linear and logarithmic histogram statistics. > > Add binary stats capability text which is missing during merge of > > the binary stats patch. > > > > Signed-off-by: Jing Zhang <jingzhangos@google.com> > > --- > > Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- > > 1 file changed, 33 insertions(+), 3 deletions(-) > > > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > > index 3b6e3b1628b4..948d33c26704 100644 > > --- a/Documentation/virt/kvm/api.rst > > +++ b/Documentation/virt/kvm/api.rst > > @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. > > #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) > > #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) > > #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST > > > > #define KVM_STATS_UNIT_SHIFT 4 > > #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) > > @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. > > #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) > > #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) > > #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) > > + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES > > > > #define KVM_STATS_BASE_SHIFT 8 > > #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) > > #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) > > #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) > > + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 > > > > struct kvm_stats_desc { > > __u32 flags; > > @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: > > represents a peak value for a measurement, for example the maximum number > > of items in a hash table bucket, the longest time waited and so on. > > The corresponding ``size`` field for this type is always 1. > > + * ``KVM_STATS_TYPE_LINEAR_HIST`` > > + The statistics data is in the form of linear histogram. The number of > > + buckets is specified by the ``size`` field. The size of buckets is specified > > + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) > > + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last > > + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity > > + value.) The bucket value indicates how many times the statistics data is in > > + the bucket's range. > > + * ``KVM_STATS_TYPE_LOG_HIST`` > > + The statistics data is in the form of logarithmic histogram. The number of > > + buckets is specified by the ``size`` field. The base of logarithm is > > + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < > > + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range > > + of the first bucket is [0, 1), while the range of the last bucket is > > + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many > > + times the statistics data is in the bucket's range. > > > > Bits 4-7 of ``flags`` encode the unit: > > * ``KVM_STATS_UNIT_NONE`` > > @@ -5246,9 +5267,10 @@ unsigned 64bit data. > > The ``offset`` field is the offset from the start of Data Block to the start of > > the corresponding statistics data. > > > > -The ``unused`` field is reserved for future support for other types of > > -statistics data, like log/linear histogram. Its value is always 0 for the types > > -defined above. > > +The ``hist_param`` field is used as a parameter for histogram statistics data. > > +For linear histogram statistics data, it indicates the size of a bucket. For > > +logarithmic histogram statistics data, it indicates the base of the logarithm. > > +Only base of 2 is supported fo logarithmic histogram. > > > > The ``name`` field is the name string of the statistics data. The name string > > starts at the end of ``struct kvm_stats_desc``. The maximum length including > > @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset > > of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace > > the hypercalls whose corresponding bit is in the argument, and return > > ENOSYS for the others. > > + > > +8.35 KVM_CAP_STATS_BINARY_FD > > +---------------------------- > > + > > +:Architectures: all > > + > > +This capability indicates the feature that userspace can get a file descriptor > > +for every VM and VCPU to read statistics data in binary format. > > This should probably be in a separate patch with a Fixes tag. > > Fixes: fdc09ddd4064 ("KVM: stats: Add documentation for binary statistics interface") > > > -- > > 2.32.0.93.g670b81a890-goog > > Thanks David. Jing
On Tue, Jul 06, 2021 at 06:03:48PM +0000, Jing Zhang wrote: > Add documentations for linear and logarithmic histogram statistics. > Add binary stats capability text which is missing during merge of > the binary stats patch. > > Signed-off-by: Jing Zhang <jingzhangos@google.com> > --- > Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- > 1 file changed, 33 insertions(+), 3 deletions(-) > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > index 3b6e3b1628b4..948d33c26704 100644 > --- a/Documentation/virt/kvm/api.rst > +++ b/Documentation/virt/kvm/api.rst > @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. > #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) > #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) > #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST > > #define KVM_STATS_UNIT_SHIFT 4 > #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) > @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. > #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) > #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) > #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) > + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES > > #define KVM_STATS_BASE_SHIFT 8 > #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) > #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) > #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) > + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 Should these FOO_MAX additions go in a separate commit too? > > struct kvm_stats_desc { > __u32 flags; > @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: > represents a peak value for a measurement, for example the maximum number > of items in a hash table bucket, the longest time waited and so on. > The corresponding ``size`` field for this type is always 1. > + * ``KVM_STATS_TYPE_LINEAR_HIST`` > + The statistics data is in the form of linear histogram. The number of > + buckets is specified by the ``size`` field. The size of buckets is specified > + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) Using 1-based indexes is a little jarring but maybe that's just me :). > + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last > + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity > + value.) The bucket value indicates how many times the statistics data is in > + the bucket's range. > + * ``KVM_STATS_TYPE_LOG_HIST`` > + The statistics data is in the form of logarithmic histogram. The number of > + buckets is specified by the ``size`` field. The base of logarithm is > + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < Should 1 be 2 here? The first bucket uses a slightly differen formula as you mention in the next sentence. Actually it may be clearer if you re-ordered the sentences a bit: The range of the first bucket is [0, 1), while the range of the last bucket is [pow(hist_param, size-1), +INF). Otherwise the Nth bucket (1-indexed) covers [pow(hist_param, N-2), pow(histparam, N-1)). > + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range > + of the first bucket is [0, 1), while the range of the last bucket is > + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many > + times the statistics data is in the bucket's range. > > Bits 4-7 of ``flags`` encode the unit: > * ``KVM_STATS_UNIT_NONE`` > @@ -5246,9 +5267,10 @@ unsigned 64bit data. > The ``offset`` field is the offset from the start of Data Block to the start of > the corresponding statistics data. > > -The ``unused`` field is reserved for future support for other types of > -statistics data, like log/linear histogram. Its value is always 0 for the types > -defined above. > +The ``hist_param`` field is used as a parameter for histogram statistics data. > +For linear histogram statistics data, it indicates the size of a bucket. For > +logarithmic histogram statistics data, it indicates the base of the logarithm. > +Only base of 2 is supported fo logarithmic histogram. s/fo/for/ > > The ``name`` field is the name string of the statistics data. The name string > starts at the end of ``struct kvm_stats_desc``. The maximum length including > @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset > of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace > the hypercalls whose corresponding bit is in the argument, and return > ENOSYS for the others. > + > +8.35 KVM_CAP_STATS_BINARY_FD > +---------------------------- > + > +:Architectures: all > + > +This capability indicates the feature that userspace can get a file descriptor > +for every VM and VCPU to read statistics data in binary format. > -- > 2.32.0.93.g670b81a890-goog >
On Thu, Jul 08, 2021 at 09:14:38PM +0000, David Matlack wrote: > On Tue, Jul 06, 2021 at 06:03:48PM +0000, Jing Zhang wrote: > > Add documentations for linear and logarithmic histogram statistics. > > Add binary stats capability text which is missing during merge of > > the binary stats patch. > > > > Signed-off-by: Jing Zhang <jingzhangos@google.com> > > --- > > Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- > > 1 file changed, 33 insertions(+), 3 deletions(-) > > > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > > index 3b6e3b1628b4..948d33c26704 100644 > > --- a/Documentation/virt/kvm/api.rst > > +++ b/Documentation/virt/kvm/api.rst > > @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. > > #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) > > #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) > > #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) > > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST > > > > #define KVM_STATS_UNIT_SHIFT 4 > > #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) > > @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. > > #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) > > #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) > > #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) > > + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES > > > > #define KVM_STATS_BASE_SHIFT 8 > > #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) > > #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) > > #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) > > + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 > > Should these FOO_MAX additions go in a separate commit too? > > > > > struct kvm_stats_desc { > > __u32 flags; > > @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: > > represents a peak value for a measurement, for example the maximum number > > of items in a hash table bucket, the longest time waited and so on. > > The corresponding ``size`` field for this type is always 1. > > + * ``KVM_STATS_TYPE_LINEAR_HIST`` > > + The statistics data is in the form of linear histogram. The number of > > + buckets is specified by the ``size`` field. The size of buckets is specified > > + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) > > Using 1-based indexes is a little jarring but maybe that's just me :). > > > + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last > > + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity > > + value.) The bucket value indicates how many times the statistics data is in > > + the bucket's range. > > + * ``KVM_STATS_TYPE_LOG_HIST`` > > + The statistics data is in the form of logarithmic histogram. The number of > > + buckets is specified by the ``size`` field. The base of logarithm is > > + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < > > Should 1 be 2 here? The first bucket uses a slightly differen formula as > you mention in the next sentence. Oops I see you used "<" instead of "<=" so what you have is correct. I think reordering the sentences would still be helpfull though. > > Actually it may be clearer if you re-ordered the sentences a bit: > > The range of the first bucket is [0, 1), while the range of the last > bucket is [pow(hist_param, size-1), +INF). Otherwise the Nth bucket > (1-indexed) covers [pow(hist_param, N-2), pow(histparam, N-1)). > > > + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range > > + of the first bucket is [0, 1), while the range of the last bucket is > > + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many > > + times the statistics data is in the bucket's range. > > > > Bits 4-7 of ``flags`` encode the unit: > > * ``KVM_STATS_UNIT_NONE`` > > @@ -5246,9 +5267,10 @@ unsigned 64bit data. > > The ``offset`` field is the offset from the start of Data Block to the start of > > the corresponding statistics data. > > > > -The ``unused`` field is reserved for future support for other types of > > -statistics data, like log/linear histogram. Its value is always 0 for the types > > -defined above. > > +The ``hist_param`` field is used as a parameter for histogram statistics data. > > +For linear histogram statistics data, it indicates the size of a bucket. For > > +logarithmic histogram statistics data, it indicates the base of the logarithm. > > +Only base of 2 is supported fo logarithmic histogram. > > s/fo/for/ > > > > > The ``name`` field is the name string of the statistics data. The name string > > starts at the end of ``struct kvm_stats_desc``. The maximum length including > > @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset > > of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace > > the hypercalls whose corresponding bit is in the argument, and return > > ENOSYS for the others. > > + > > +8.35 KVM_CAP_STATS_BINARY_FD > > +---------------------------- > > + > > +:Architectures: all > > + > > +This capability indicates the feature that userspace can get a file descriptor > > +for every VM and VCPU to read statistics data in binary format. > > -- > > 2.32.0.93.g670b81a890-goog > >
On Thu, Jul 8, 2021 at 4:16 PM David Matlack <dmatlack@google.com> wrote: > > On Thu, Jul 08, 2021 at 09:14:38PM +0000, David Matlack wrote: > > On Tue, Jul 06, 2021 at 06:03:48PM +0000, Jing Zhang wrote: > > > Add documentations for linear and logarithmic histogram statistics. > > > Add binary stats capability text which is missing during merge of > > > the binary stats patch. > > > > > > Signed-off-by: Jing Zhang <jingzhangos@google.com> > > > --- > > > Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- > > > 1 file changed, 33 insertions(+), 3 deletions(-) > > > > > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > > > index 3b6e3b1628b4..948d33c26704 100644 > > > --- a/Documentation/virt/kvm/api.rst > > > +++ b/Documentation/virt/kvm/api.rst > > > @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. > > > #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) > > > #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) > > > #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) > > > + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) > > > + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) > > > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST > > > > > > #define KVM_STATS_UNIT_SHIFT 4 > > > #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) > > > @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. > > > #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) > > > #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) > > > #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) > > > + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES > > > > > > #define KVM_STATS_BASE_SHIFT 8 > > > #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) > > > #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) > > > #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) > > > + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 > > > > Should these FOO_MAX additions go in a separate commit too? > > > > > > > > struct kvm_stats_desc { > > > __u32 flags; > > > @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: > > > represents a peak value for a measurement, for example the maximum number > > > of items in a hash table bucket, the longest time waited and so on. > > > The corresponding ``size`` field for this type is always 1. > > > + * ``KVM_STATS_TYPE_LINEAR_HIST`` > > > + The statistics data is in the form of linear histogram. The number of > > > + buckets is specified by the ``size`` field. The size of buckets is specified > > > + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) > > > > Using 1-based indexes is a little jarring but maybe that's just me :). > > > > > + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last > > > + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity > > > + value.) The bucket value indicates how many times the statistics data is in > > > + the bucket's range. > > > + * ``KVM_STATS_TYPE_LOG_HIST`` > > > + The statistics data is in the form of logarithmic histogram. The number of > > > + buckets is specified by the ``size`` field. The base of logarithm is > > > + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < > > > > Should 1 be 2 here? The first bucket uses a slightly differen formula as > > you mention in the next sentence. > > Oops I see you used "<" instead of "<=" so what you have is correct. I > think reordering the sentences would still be helpfull though. > Sure, will reorder the sentences as you suggested. > > > > Actually it may be clearer if you re-ordered the sentences a bit: > > > > The range of the first bucket is [0, 1), while the range of the last > > bucket is [pow(hist_param, size-1), +INF). Otherwise the Nth bucket > > (1-indexed) covers [pow(hist_param, N-2), pow(histparam, N-1)). > > > > > + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range > > > + of the first bucket is [0, 1), while the range of the last bucket is > > > + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many > > > + times the statistics data is in the bucket's range. > > > > > > Bits 4-7 of ``flags`` encode the unit: > > > * ``KVM_STATS_UNIT_NONE`` > > > @@ -5246,9 +5267,10 @@ unsigned 64bit data. > > > The ``offset`` field is the offset from the start of Data Block to the start of > > > the corresponding statistics data. > > > > > > -The ``unused`` field is reserved for future support for other types of > > > -statistics data, like log/linear histogram. Its value is always 0 for the types > > > -defined above. > > > +The ``hist_param`` field is used as a parameter for histogram statistics data. > > > +For linear histogram statistics data, it indicates the size of a bucket. For > > > +logarithmic histogram statistics data, it indicates the base of the logarithm. > > > +Only base of 2 is supported fo logarithmic histogram. > > > > s/fo/for/ > > > > > > > > The ``name`` field is the name string of the statistics data. The name string > > > starts at the end of ``struct kvm_stats_desc``. The maximum length including > > > @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset > > > of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace > > > the hypercalls whose corresponding bit is in the argument, and return > > > ENOSYS for the others. > > > + > > > +8.35 KVM_CAP_STATS_BINARY_FD > > > +---------------------------- > > > + > > > +:Architectures: all > > > + > > > +This capability indicates the feature that userspace can get a file descriptor > > > +for every VM and VCPU to read statistics data in binary format. > > > -- > > > 2.32.0.93.g670b81a890-goog > > >
On 08/07/21 01:31, David Matlack wrote: >> + >> +8.35 KVM_CAP_STATS_BINARY_FD >> +---------------------------- >> + >> +:Architectures: all >> + >> +This capability indicates the feature that userspace can get a file descriptor >> +for every VM and VCPU to read statistics data in binary format. > This should probably be in a separate patch with a Fixes tag. Generally this chapter (which is probably incomplete, though) only includes capabilities for which KVM_CHECK_EXTENSION can return a value other than 0 or 1. So there is no need to include KVM_CAP_STATS_BINARY_FD. Paolo
On Wed, Jul 28, 2021 at 5:42 AM Paolo Bonzini <pbonzini@redhat.com> wrote: > > On 08/07/21 01:31, David Matlack wrote: > >> + > >> +8.35 KVM_CAP_STATS_BINARY_FD > >> +---------------------------- > >> + > >> +:Architectures: all > >> + > >> +This capability indicates the feature that userspace can get a file descriptor > >> +for every VM and VCPU to read statistics data in binary format. > > This should probably be in a separate patch with a Fixes tag. > > Generally this chapter (which is probably incomplete, though) only > includes capabilities for which KVM_CHECK_EXTENSION can return a value > other than 0 or 1. So there is no need to include KVM_CAP_STATS_BINARY_FD. Got it. Will drop this change. > > Paolo > Thanks, Jing
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 3b6e3b1628b4..948d33c26704 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -5171,6 +5171,9 @@ by a string of size ``name_size``. #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) #define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) + #define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) + #define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST #define KVM_STATS_UNIT_SHIFT 4 #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) @@ -5178,11 +5181,13 @@ by a string of size ``name_size``. #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES #define KVM_STATS_BASE_SHIFT 8 #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) #define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) #define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) + #define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 struct kvm_stats_desc { __u32 flags; @@ -5214,6 +5219,22 @@ Bits 0-3 of ``flags`` encode the type: represents a peak value for a measurement, for example the maximum number of items in a hash table bucket, the longest time waited and so on. The corresponding ``size`` field for this type is always 1. + * ``KVM_STATS_TYPE_LINEAR_HIST`` + The statistics data is in the form of linear histogram. The number of + buckets is specified by the ``size`` field. The size of buckets is specified + by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) + is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last + bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity + value.) The bucket value indicates how many times the statistics data is in + the bucket's range. + * ``KVM_STATS_TYPE_LOG_HIST`` + The statistics data is in the form of logarithmic histogram. The number of + buckets is specified by the ``size`` field. The base of logarithm is + specified by the ``hist_param`` field. The range of the Nth bucket (1 < N < + ``size``) is [pow(``hist_param``, N-2), pow(``hist_param``, N-1)). The range + of the first bucket is [0, 1), while the range of the last bucket is + [pow(``hist_param``, ``size``-2), +INF). The bucket value indicates how many + times the statistics data is in the bucket's range. Bits 4-7 of ``flags`` encode the unit: * ``KVM_STATS_UNIT_NONE`` @@ -5246,9 +5267,10 @@ unsigned 64bit data. The ``offset`` field is the offset from the start of Data Block to the start of the corresponding statistics data. -The ``unused`` field is reserved for future support for other types of -statistics data, like log/linear histogram. Its value is always 0 for the types -defined above. +The ``hist_param`` field is used as a parameter for histogram statistics data. +For linear histogram statistics data, it indicates the size of a bucket. For +logarithmic histogram statistics data, it indicates the base of the logarithm. +Only base of 2 is supported fo logarithmic histogram. The ``name`` field is the name string of the statistics data. The name string starts at the end of ``struct kvm_stats_desc``. The maximum length including @@ -7182,3 +7204,11 @@ The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace the hypercalls whose corresponding bit is in the argument, and return ENOSYS for the others. + +8.35 KVM_CAP_STATS_BINARY_FD +---------------------------- + +:Architectures: all + +This capability indicates the feature that userspace can get a file descriptor +for every VM and VCPU to read statistics data in binary format.
Add documentations for linear and logarithmic histogram statistics. Add binary stats capability text which is missing during merge of the binary stats patch. Signed-off-by: Jing Zhang <jingzhangos@google.com> --- Documentation/virt/kvm/api.rst | 36 +++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-)