Update documentation to reflect that stats descriptor supports new
flags for read/write mode and an offset field is added in stats
descriptor.
Signed-off-by: Jing Zhang <jingzhangos@xxxxxxxxxx>
---
Documentation/virt/kvm/api.rst | 33 ++++++++++++++++++++++++++-------
1 file changed, 26 insertions(+), 7 deletions(-)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index d1ad30212726..67979700a90e 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -5160,12 +5160,19 @@ below code block::
#define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT)
#define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2
+ #define KVM_STATS_MODE_SHIFT 12
+ #define KVM_STATS_MODE_MASK (0xF << KVM_STATS_MODE_SHIFT)
+ #define KVM_STATS_MODE_RW (0x0 << KVM_STATS_MODE_SHIFT)
+ #define KVM_STATS_MODE_READ (0x1 << KVM_STATS_MODE_SHIFT)
+ #define KVM_STATS_MODE_WRITE (0x2 << KVM_STATS_MODE_SHIFT)
+ #define KVM_STATS_MODE_MAX KVM_STATS_MODE_WRITE
+
struct kvm_stats_desc {
__u32 flags;
__s16 exponent;
__u16 size;
- __u32 unused1;
- __u32 unused2;
+ __u32 offset;
+ __u32 unused;
char name[0];
};
@@ -5212,23 +5219,35 @@ Bits 4-7 of ``flags`` encode the unit:
value is 200, ``exponent`` is 4, we can get the number of CPU clock cycles
by ``value * pow(10, exponent) = 200 * pow(10, 4) = 2000000``.
-Bits 7-11 of ``flags`` encode the base:
+Bits 8-11 of ``flags`` encode the base:
* ``KVM_STATS_BASE_POW10``
The scale is based on power of 10. It is used for measurement of time and
CPU clock cycles.
* ``KVM_STATS_BASE_POW2``
The scale is based on power of 2. It is used for measurement of memory size.
+Bits 12-15 of ``flags`` encode the mode:
+ * ``KVM_STATS_MODE_RW``
+ The corresponding statistics supports both read and write (clear).
+ * ``KVM_STATS_MODE_READ``
+ The corresponding statistics supports read only.
+ * ``KVM_STATS_MODE_WRITE``
+ The corresponding statistics supports write only. (Not used for now, added
+ for completeness)
+
The ``exponent`` field is the scale of corresponding statistics data. For
example, if the unit is ``KVM_STATS_UNIT_BYTES``, the base is
``KVM_STATS_BASE_POW2``, the ``exponent`` is 10, then we know that the real
unit of the statistics data is KBytes a.k.a pow(2, 10) = 1024 bytes.
-The ``size`` field is the number of values of this statistics data. It is in the
-unit of ``unsigned long`` for VM or ``__u64`` for VCPU.
+The ``size`` field is the number of values (u64) of this statistics data. Its
+value is usually 1 for most of simple statistics.
+
+The ``offset`` field is the offset from the start of Data Block to the start of
+the corresponding statistics data.
-The ``unused1`` and ``unused2`` fields are reserved for future
-support for other types of statistics data, like log/linear histogram.
+The ``unused`` fields are reserved for future support for other types of
+statistics data, like log/linear histogram.
The ``name`` field points to the name string of the statistics data. The name
string starts at the end of ``struct kvm_stats_desc``.
--
2.32.0.272.g935e593368-goog
