Re: [PATCH v7 3/4] KVM: stats: Add documentation for statistics data binary interface
Hi Fuad,
On Mon, Jun 14, 2021 at 2:57 AM Fuad Tabba wrote:
>
> Hi Jing,
>
>
> On Thu, Jun 3, 2021 at 10:14 PM Jing Zhang wrote:
> >
> > Update KVM API documentation for binary statistics.
> >
> > Reviewed-by: David Matlack
> > Reviewed-by: Ricardo Koller
> > Signed-off-by: Jing Zhang
> > ---
> > Documentation/virt/kvm/api.rst | 180 +
> > 1 file changed, 180 insertions(+)
> >
> > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> > index 7fcb2fd38f42..550bfbdf611b 100644
> > --- a/Documentation/virt/kvm/api.rst
> > +++ b/Documentation/virt/kvm/api.rst
> > @@ -5034,6 +5034,178 @@ see KVM_XEN_VCPU_SET_ATTR above.
> > The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
> > with the KVM_XEN_VCPU_GET_ATTR ioctl.
> >
> > +4.130 KVM_GET_STATS_FD
> > +-
>
> nit: missing one - (to match the subtitle length)
>
> > +
> > +:Capability: KVM_CAP_STATS_BINARY_FD
> > +:Architectures: all
> > +:Type: vm ioctl, vcpu ioctl
> > +:Parameters: none
> > +:Returns: statistics file descriptor on success, < 0 on error
> > +
> > +Errors:
> > +
> > + == ==
> > + ENOMEM if the fd could not be created due to lack of memory
> > + EMFILE if the number of opened files exceeds the limit
> > + == ==
> > +
> > +The file descriptor can be used to read VM/vCPU statistics data in binary
> > +format. The file data is organized into three blocks as below:
> > ++-+
> > +| Header|
> > ++-+
> > +| Descriptors |
> > ++-+
> > +| Stats Data |
> > ++-+
> > +
> > +The Header block is always at the start of the file. It is only needed to
> > be
> > +read one time for the lifetime of the file descriptor.
> > +It is in the form of ``struct kvm_stats_header`` as below::
> > +
> > + #define KVM_STATS_ID_MAXLEN 64
> > +
> > + struct kvm_stats_header {
> > + char id[KVM_STATS_ID_MAXLEN];
> > + __u32 name_size;
> > + __u32 count;
> > + __u32 desc_offset;
> > + __u32 data_offset;
> > + };
> > +
> > +The ``id`` field is identification for the corresponding KVM statistics.
> > For
> > +VM statistics, it is in the form of "kvm-{kvm pid}", like "kvm-12345". For
> > +VCPU statistics, it is in the form of "kvm-{kvm pid}/vcpu-{vcpu id}", like
> > +"kvm-12345/vcpu-12".
> > +
> > +The ``name_size`` field is the size (byte) of the statistics name string
> > +(including trailing '\0') appended to the end of every statistics
> > descriptor.
> > +
> > +The ``count`` field is the number of statistics.
> > +
> > +The ``desc_offset`` field is the offset of the Descriptors block from the
> > start
> > +of the file indicated by the file descriptor.
> > +
> > +The ``data_offset`` field is the offset of the Stats Data block from the
> > start
> > +of the file indicated by the file descriptor.
> > +
> > +The Descriptors block is only needed to be read once for the lifetime of
> > the
> > +file descriptor. It is an array of ``struct kvm_stats_desc`` as shown in
> > +below code block::
> > +
> > + #define KVM_STATS_TYPE_SHIFT0
> > + #define KVM_STATS_TYPE_MASK (0xF <<
> > KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_CUMULATIVE (0x0 <<
> > KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_INSTANT (0x1 <<
> > KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_INSTANT
> > +
> > + #define KVM_STATS_UNIT_SHIFT4
> > + #define KVM_STATS_UNIT_MASK (0xF <<
> > KVM_STATS_UNIT_SHIFT)
> > + #define KVM_STATS_UNIT_NONE (0x0 <<
> > KVM_STATS_UNIT_SHIFT)
> > + #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_SHIFT8
> > + #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;
> > + __s16 exponent;
> > + __u16 size;
> > + __u32 unused1;
> > + __u32 unused2;
> > + char name[0];
> > + };
> > +
> > +The ``flags`` field contains the type and unit of the statistics data
> > described
> > +by this descriptor. The
Re: [PATCH v7 3/4] KVM: stats: Add documentation for statistics data binary interface
Hi Jing,
On Thu, Jun 3, 2021 at 10:14 PM Jing Zhang wrote:
>
> Update KVM API documentation for binary statistics.
>
> Reviewed-by: David Matlack
> Reviewed-by: Ricardo Koller
> Signed-off-by: Jing Zhang
> ---
> Documentation/virt/kvm/api.rst | 180 +
> 1 file changed, 180 insertions(+)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 7fcb2fd38f42..550bfbdf611b 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -5034,6 +5034,178 @@ see KVM_XEN_VCPU_SET_ATTR above.
> The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
> with the KVM_XEN_VCPU_GET_ATTR ioctl.
>
> +4.130 KVM_GET_STATS_FD
> +-
nit: missing one - (to match the subtitle length)
> +
> +:Capability: KVM_CAP_STATS_BINARY_FD
> +:Architectures: all
> +:Type: vm ioctl, vcpu ioctl
> +:Parameters: none
> +:Returns: statistics file descriptor on success, < 0 on error
> +
> +Errors:
> +
> + == ==
> + ENOMEM if the fd could not be created due to lack of memory
> + EMFILE if the number of opened files exceeds the limit
> + == ==
> +
> +The file descriptor can be used to read VM/vCPU statistics data in binary
> +format. The file data is organized into three blocks as below:
> ++-+
> +| Header|
> ++-+
> +| Descriptors |
> ++-+
> +| Stats Data |
> ++-+
> +
> +The Header block is always at the start of the file. It is only needed to be
> +read one time for the lifetime of the file descriptor.
> +It is in the form of ``struct kvm_stats_header`` as below::
> +
> + #define KVM_STATS_ID_MAXLEN 64
> +
> + struct kvm_stats_header {
> + char id[KVM_STATS_ID_MAXLEN];
> + __u32 name_size;
> + __u32 count;
> + __u32 desc_offset;
> + __u32 data_offset;
> + };
> +
> +The ``id`` field is identification for the corresponding KVM statistics. For
> +VM statistics, it is in the form of "kvm-{kvm pid}", like "kvm-12345". For
> +VCPU statistics, it is in the form of "kvm-{kvm pid}/vcpu-{vcpu id}", like
> +"kvm-12345/vcpu-12".
> +
> +The ``name_size`` field is the size (byte) of the statistics name string
> +(including trailing '\0') appended to the end of every statistics descriptor.
> +
> +The ``count`` field is the number of statistics.
> +
> +The ``desc_offset`` field is the offset of the Descriptors block from the
> start
> +of the file indicated by the file descriptor.
> +
> +The ``data_offset`` field is the offset of the Stats Data block from the
> start
> +of the file indicated by the file descriptor.
> +
> +The Descriptors block is only needed to be read once for the lifetime of the
> +file descriptor. It is an array of ``struct kvm_stats_desc`` as shown in
> +below code block::
> +
> + #define KVM_STATS_TYPE_SHIFT0
> + #define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
> + #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
> + #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
> + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_INSTANT
> +
> + #define KVM_STATS_UNIT_SHIFT4
> + #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
> + #define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
> + #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_SHIFT8
> + #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;
> + __s16 exponent;
> + __u16 size;
> + __u32 unused1;
> + __u32 unused2;
> + char name[0];
> + };
> +
> +The ``flags`` field contains the type and unit of the statistics data
> described
> +by this descriptor. The following flags are supported:
> +
> +Bits 0-3 of ``flags`` encode the type:
> + * ``KVM_STATS_TYPE_CUMULATIVE``
> +The statistics data is cumulative. The value of data can only be
> increased.
> +Most of the counters used in KVM are of this type.
> +The corresponding ``count`` filed for this type is always 1.
filed -> field
> + *
Re: [PATCH v7 3/4] KVM: stats: Add documentation for statistics data binary interface
On 6/3/21 2:14 PM, Jing Zhang wrote:
Update KVM API documentation for binary statistics.
Reviewed-by: David Matlack
Reviewed-by: Ricardo Koller
Signed-off-by: Jing Zhang
---
Documentation/virt/kvm/api.rst | 180 +
1 file changed, 180 insertions(+)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 7fcb2fd38f42..550bfbdf611b 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -5034,6 +5034,178 @@ see KVM_XEN_VCPU_SET_ATTR above.
The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
with the KVM_XEN_VCPU_GET_ATTR ioctl.
+4.130 KVM_GET_STATS_FD
+-
+
+:Capability: KVM_CAP_STATS_BINARY_FD
+:Architectures: all
+:Type: vm ioctl, vcpu ioctl
+:Parameters: none
+:Returns: statistics file descriptor on success, < 0 on error
+
+Errors:
+
+ == ==
+ ENOMEM if the fd could not be created due to lack of memory
+ EMFILE if the number of opened files exceeds the limit
+ == ==
+
+The file descriptor can be used to read VM/vCPU statistics data in binary
+format. The file data is organized into three blocks as below:
++-+
+| Header|
++-+
+| Descriptors |
++-+
+| Stats Data |
++-+
+
+The Header block is always at the start of the file. It is only needed to be
+read one time for the lifetime of the file descriptor.
+It is in the form of ``struct kvm_stats_header`` as below::
+
+ #define KVM_STATS_ID_MAXLEN 64
+
+ struct kvm_stats_header {
+ char id[KVM_STATS_ID_MAXLEN];
+ __u32 name_size;
+ __u32 count;
+ __u32 desc_offset;
+ __u32 data_offset;
+ };
+
+The ``id`` field is identification for the corresponding KVM statistics. For
+VM statistics, it is in the form of "kvm-{kvm pid}", like "kvm-12345". For
+VCPU statistics, it is in the form of "kvm-{kvm pid}/vcpu-{vcpu id}", like
+"kvm-12345/vcpu-12".
Currently, KVM debugfs shows VCPUs as "vcpuXX" where is XX is the id.
Should we follow the same convention ?
+
+The ``name_size`` field is the size (byte) of the statistics name string
+(including trailing '\0') appended to the end of every statistics descriptor.
+
+The ``count`` field is the number of statistics.
+
+The ``desc_offset`` field is the offset of the Descriptors block from the start
+of the file indicated by the file descriptor.
+
+The ``data_offset`` field is the offset of the Stats Data block from the start
+of the file indicated by the file descriptor.
+
+The Descriptors block is only needed to be read once for the lifetime of the
+file descriptor. It is an array of ``struct kvm_stats_desc`` as shown in
+below code block::
+
+ #define KVM_STATS_TYPE_SHIFT0
+ #define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_INSTANT
+
+ #define KVM_STATS_UNIT_SHIFT4
+ #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
+ #define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
+ #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_SHIFT8
+ #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;
+ __s16 exponent;
+ __u16 size;
+ __u32 unused1;
+ __u32 unused2;
+ char name[0];
+ };
+
+The ``flags`` field contains the type and unit of the statistics data described
+by this descriptor. The following flags are supported:
+
+Bits 0-3 of ``flags`` encode the type:
+ * ``KVM_STATS_TYPE_CUMULATIVE``
+The statistics data is cumulative. The value of data can only be increased.
+Most of the counters used in KVM are of this type.
+The corresponding ``count`` filed for this type is always 1.
+ * ``KVM_STATS_TYPE_INSTANT``
+The statistics data is instantaneous. Its value can be increased or
+decreased. This type is usually used as a measurement of some resources,
+like the number of dirty pages, the number of large
Re: [PATCH v7 3/4] KVM: stats: Add documentation for statistics data binary interface
On Mon, Jun 7, 2021 at 2:23 PM Krish Sadhukhan
wrote:
>
>
> On 6/3/21 2:14 PM, Jing Zhang wrote:
> > Update KVM API documentation for binary statistics.
> >
> > Reviewed-by: David Matlack
> > Reviewed-by: Ricardo Koller
> > Signed-off-by: Jing Zhang
> > ---
> > Documentation/virt/kvm/api.rst | 180 +
> > 1 file changed, 180 insertions(+)
> >
> > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> > index 7fcb2fd38f42..550bfbdf611b 100644
> > --- a/Documentation/virt/kvm/api.rst
> > +++ b/Documentation/virt/kvm/api.rst
> > @@ -5034,6 +5034,178 @@ see KVM_XEN_VCPU_SET_ATTR above.
> > The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
> > with the KVM_XEN_VCPU_GET_ATTR ioctl.
> >
> > +4.130 KVM_GET_STATS_FD
> > +-
> > +
> > +:Capability: KVM_CAP_STATS_BINARY_FD
> > +:Architectures: all
> > +:Type: vm ioctl, vcpu ioctl
> > +:Parameters: none
> > +:Returns: statistics file descriptor on success, < 0 on error
> > +
> > +Errors:
> > +
> > + == ==
> > + ENOMEM if the fd could not be created due to lack of memory
> > + EMFILE if the number of opened files exceeds the limit
> > + == ==
> > +
> > +The file descriptor can be used to read VM/vCPU statistics data in binary
> > +format. The file data is organized into three blocks as below:
> > ++-+
> > +| Header|
> > ++-+
> > +| Descriptors |
> > ++-+
> > +| Stats Data |
> > ++-+
> > +
> > +The Header block is always at the start of the file. It is only needed to
> > be
> > +read one time for the lifetime of the file descriptor.
> > +It is in the form of ``struct kvm_stats_header`` as below::
> > +
> > + #define KVM_STATS_ID_MAXLEN 64
> > +
> > + struct kvm_stats_header {
> > + char id[KVM_STATS_ID_MAXLEN];
> > + __u32 name_size;
> > + __u32 count;
> > + __u32 desc_offset;
> > + __u32 data_offset;
> > + };
> > +
> > +The ``id`` field is identification for the corresponding KVM statistics.
> > For
> > +VM statistics, it is in the form of "kvm-{kvm pid}", like "kvm-12345". For
> > +VCPU statistics, it is in the form of "kvm-{kvm pid}/vcpu-{vcpu id}", like
> > +"kvm-12345/vcpu-12".
>
> Currently, KVM debugfs shows VCPUs as "vcpuXX" where is XX is the id.
> Should we follow the same convention ?
It looks more clear to be like vcpu-xx. Let's keep it this way. Thanks.
> > +
> > +The ``name_size`` field is the size (byte) of the statistics name string
> > +(including trailing '\0') appended to the end of every statistics
> > descriptor.
> > +
> > +The ``count`` field is the number of statistics.
> > +
> > +The ``desc_offset`` field is the offset of the Descriptors block from the
> > start
> > +of the file indicated by the file descriptor.
> > +
> > +The ``data_offset`` field is the offset of the Stats Data block from the
> > start
> > +of the file indicated by the file descriptor.
> > +
> > +The Descriptors block is only needed to be read once for the lifetime of
> > the
> > +file descriptor. It is an array of ``struct kvm_stats_desc`` as shown in
> > +below code block::
> > +
> > + #define KVM_STATS_TYPE_SHIFT0
> > + #define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
> > + #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_INSTANT
> > +
> > + #define KVM_STATS_UNIT_SHIFT4
> > + #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
> > + #define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
> > + #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_SHIFT8
> > + #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;
> > + __s16 exponent;
> > + __u16 size;
> > + __u32 unused1;
> > + __u32 unused2;
> > + char name[0];
> > + };
> > +
> > +The ``flags`` field contains the type and unit of the statistics data
> > described
> > +by this descriptor. The following flags are
[PATCH v7 3/4] KVM: stats: Add documentation for statistics data binary interface
Update KVM API documentation for binary statistics.
Reviewed-by: David Matlack
Reviewed-by: Ricardo Koller
Signed-off-by: Jing Zhang
---
Documentation/virt/kvm/api.rst | 180 +
1 file changed, 180 insertions(+)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 7fcb2fd38f42..550bfbdf611b 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -5034,6 +5034,178 @@ see KVM_XEN_VCPU_SET_ATTR above.
The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
with the KVM_XEN_VCPU_GET_ATTR ioctl.
+4.130 KVM_GET_STATS_FD
+-
+
+:Capability: KVM_CAP_STATS_BINARY_FD
+:Architectures: all
+:Type: vm ioctl, vcpu ioctl
+:Parameters: none
+:Returns: statistics file descriptor on success, < 0 on error
+
+Errors:
+
+ == ==
+ ENOMEM if the fd could not be created due to lack of memory
+ EMFILE if the number of opened files exceeds the limit
+ == ==
+
+The file descriptor can be used to read VM/vCPU statistics data in binary
+format. The file data is organized into three blocks as below:
++-+
+| Header|
++-+
+| Descriptors |
++-+
+| Stats Data |
++-+
+
+The Header block is always at the start of the file. It is only needed to be
+read one time for the lifetime of the file descriptor.
+It is in the form of ``struct kvm_stats_header`` as below::
+
+ #define KVM_STATS_ID_MAXLEN 64
+
+ struct kvm_stats_header {
+ char id[KVM_STATS_ID_MAXLEN];
+ __u32 name_size;
+ __u32 count;
+ __u32 desc_offset;
+ __u32 data_offset;
+ };
+
+The ``id`` field is identification for the corresponding KVM statistics. For
+VM statistics, it is in the form of "kvm-{kvm pid}", like "kvm-12345". For
+VCPU statistics, it is in the form of "kvm-{kvm pid}/vcpu-{vcpu id}", like
+"kvm-12345/vcpu-12".
+
+The ``name_size`` field is the size (byte) of the statistics name string
+(including trailing '\0') appended to the end of every statistics descriptor.
+
+The ``count`` field is the number of statistics.
+
+The ``desc_offset`` field is the offset of the Descriptors block from the start
+of the file indicated by the file descriptor.
+
+The ``data_offset`` field is the offset of the Stats Data block from the start
+of the file indicated by the file descriptor.
+
+The Descriptors block is only needed to be read once for the lifetime of the
+file descriptor. It is an array of ``struct kvm_stats_desc`` as shown in
+below code block::
+
+ #define KVM_STATS_TYPE_SHIFT0
+ #define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
+ #define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_INSTANT
+
+ #define KVM_STATS_UNIT_SHIFT4
+ #define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
+ #define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
+ #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_SHIFT8
+ #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;
+ __s16 exponent;
+ __u16 size;
+ __u32 unused1;
+ __u32 unused2;
+ char name[0];
+ };
+
+The ``flags`` field contains the type and unit of the statistics data described
+by this descriptor. The following flags are supported:
+
+Bits 0-3 of ``flags`` encode the type:
+ * ``KVM_STATS_TYPE_CUMULATIVE``
+The statistics data is cumulative. The value of data can only be increased.
+Most of the counters used in KVM are of this type.
+The corresponding ``count`` filed for this type is always 1.
+ * ``KVM_STATS_TYPE_INSTANT``
+The statistics data is instantaneous. Its value can be increased or
+decreased. This type is usually used as a measurement of some resources,
+like the number of dirty pages, the number of large pages, etc.
+The corresponding ``count`` field for this type is always 1.
+
+Bits 4-7 of ``flags`` encode the unit:
+ * ``KVM_STATS_UNIT_NONE``
+There
