diff mbox series

[3/4] KVM: stats: Update documentation supporting stats mode and offset

Message ID 20210614025351.365284-4-jingzhangos@google.com (mailing list archive)
State New, archived
Headers show
Series Remove duplicated stats definitions for debugfs | expand

Commit Message

Jing Zhang June 14, 2021, 2:53 a.m. UTC
Update documentation to reflect that stats descriptor supports new
flags for read/write mode and an offset field is added in stats

Signed-off-by: Jing Zhang <jingzhangos@google.com>
 Documentation/virt/kvm/api.rst | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)
diff mbox series


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_MODE_SHIFT		12
+        #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)
 	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:
     The scale is based on power of 10. It is used for measurement of time and
     CPU clock cycles.
     The scale is based on power of 2. It is used for measurement of memory size.
+Bits 12-15 of ``flags`` encode the mode:
+    The corresponding statistics supports both read and write (clear).
+    The corresponding statistics supports read only.
+    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``.