| Message ID | 20210614212155.1670777-4-jingzhangos@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | KVM statistics data fd-based binary interface | expand |
On Mon, Jun 14, 2021 at 09:21:53PM +0000, Jing Zhang wrote: > Update KVM API documentation for binary statistics. You should write more here. See my comment at the bottom... > > Reviewed-by: David Matlack <dmatlack@google.com> > Reviewed-by: Ricardo Koller <ricarkol@google.com> > Reviewed-by: Krish Sadhukhan <krish.sadhukhan@oracle.com> > Reviewed-by: Fuad Tabba <tabba@google.com> > Signed-off-by: Jing Zhang <jingzhangos@google.com> > --- > Documentation/virt/kvm/api.rst | 177 ++++++++++++++++++++++++++++++++- > 1 file changed, 176 insertions(+), 1 deletion(-) > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > index e328caa35d6c..35ee52dbec89 100644 > --- a/Documentation/virt/kvm/api.rst > +++ b/Documentation/virt/kvm/api.rst > @@ -5034,7 +5034,6 @@ 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.131 KVM_GET_SREGS2 > ------------------ > > @@ -5081,6 +5080,174 @@ Writes special registers into the vcpu. > See KVM_GET_SREGS2 for the data structures. > This ioctl (when supported) replaces the KVM_SET_SREGS. > > +4.133 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 { > + __u32 name_size; > + __u32 count; > + __u32 desc_offset; > + __u32 data_offset; > + char id[0]; > + }; > + > +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_SHIFT 0 > + #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_SHIFT 4 > + #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_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; > + __s16 exponent; > + __u16 size; > + __u32 offset; > + __u32 unused; > + 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`` field 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 is no unit for the value of statistics data. This usually means that > + the value is a simple counter of an event. > + * ``KVM_STATS_UNIT_BYTES`` > + It indicates that the statistics data is used to measure memory size, in the > + unit of Byte, KiByte, MiByte, GiByte, etc. The unit of the data is > + determined by the ``exponent`` field in the descriptor. The > + ``KVM_STATS_BASE_POW2`` flag is valid in this case. The unit of the data is > + determined by ``pow(2, exponent)``. For example, if value is 10, > + ``exponent`` is 20, which means the unit of statistics data is MiByte, we > + can get the statistics data in the unit of Byte by > + ``value * pow(2, exponent) = 10 * pow(2, 20) = 10 MiByte`` which is > + 10 * 1024 * 1024 Bytes. > + * ``KVM_STATS_UNIT_SECONDS`` > + It indicates that the statistics data is used to measure time/latency, in > + the unit of nanosecond, microsecond, millisecond and second. The unit of the > + data is determined by the ``exponent`` field in the descriptor. The > + ``KVM_STATS_BASE_POW10`` flag is valid in this case. The unit of the data > + is determined by ``pow(10, exponent)``. For example, if value is 2000000, > + ``exponent`` is -6, which means the unit of statistics data is microsecond, > + we can get the statistics data in the unit of second by > + ``value * pow(10, exponent) = 2000000 * pow(10, -6) = 2 seconds``. > + * ``KVM_STATS_UNIT_CYCLES`` > + It indicates that the statistics data is used to measure CPU clock cycles. > + The ``KVM_STATS_BASE_POW10`` flag is valid in this case. For example, if > + 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 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. > + > +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 (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 ``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``. > +The maximum length (including trailing '\0') is indicated by ``name_size`` > +in ``struct kvm_stats_header``. > + > +The Stats Data block contains an array of data values of type ``struct > +kvm_vm_stats_data`` or ``struct kvm_vcpu_stats_data``. It would be read by > +userspace periodically to pull statistics data. > +The order of data value in Stats Data block is the same as the order of > +descriptors in Descriptors block. > + * Statistics data for VM/VCPU:: > + > + struct kvm_stats_data { > + __u64 value[0]; > + }; I forgot to comment on this one, sorry for the delay. Why are you "inventing" your own schema format here for this? Why not use a well-known or at least well-designed/implemented one that we have in userspace already? There are a few that I would love to see in the kernel, varlink being the best example. We have kernel examples of this and I would consider using that as a transport for sysfs-like data in the future, but never got around to it. So again, why reinvent the wheel to create a custom api when you could use an existing one? thanks, greg k-h
On 16/06/21 17:21, Greg KH wrote: > I forgot to comment on this one, sorry for the delay. > > Why are you "inventing" your own schema format here for this? Why not > use a well-known or at least well-designed/implemented one that we have > in userspace already? > > There are a few that I would love to see in the kernel, varlink being > the best example. We have kernel examples of this and I would consider > using that as a transport for sysfs-like data in the future, but never > got around to it. Thanks, that's a good observation, and it's a problem that the rationale and the design process didn't end up in either the documentation or the commit message (only the outcome did). In order to fix that, this is going to be quite a long message. Varlink comprises both a schema and an encoding, and each has its own problems. For the encoding of the data, varlink is really just using JSON and it is really just the wrong tool here. The first few problems that come to mind are: - varlink structs are encoded as JSON dictionaries. Therefore, every time userspace reads the fields, the kernel has to include the field names as JSON dictionary keys. This means that a lot of time is spent writing buffers, and on the receiving side parsing them. - because numeric data has to be converted to ASCII the output doesn't have fixed offsets, so it is not possible to make an efficient implementation of pread. - even though Varlink specifies that int is "usually int64", a little-known gem is that JSON behavior for numbers not representable as a double (i.e. exceeding 2^53) is implementation-defined; implementations can and will mess up values outside that range. This problem is not specific to this KVM stats usecase; varlink's schema specification really is at odds with its encoding specification. For the schema, there are some specific problems with varlink, but also a more generic issue. The specific problems are: - the schema doesn't include the length of arrays. This makes it hard to compute in advance lengths and offsets of fields (even ignoring the fact that data is not binary, which I'll get to later) - the schema also is not extensible with user annotations. In our case that would be mostly the unit in which the value is expressed. The main problem with the various available serialization formats is that their schema languages are designed to be compiled with a code generator. Here instead the schema is transmitted from the kernel to userspace. Userspace is not really supposed to know what a value means or even that if it exists. Userspace takes care of collecting the data from the kernel, but ultimately there will be a human that knows what e.g. "io_exits" or "req_event" means, and they will ask for the current value, or a plot over time, of a specific statistic. Now, unlike most other schema languages, varlink does not require precompiling the schema in its C bindings. However, this was mostly just the authors not bothering to write a C code generator---they did write one for Rust, for example. When using the "official" varlink C bindings, you hardly use the schema at all. Something similar to the above issues is quite common in other formats. For example, FlatBuffers[2]'s schema language[1] does have annotations (which it calls metadata), but then we would still have to invent some standard annotations and teach programs about them. However, the deal breaker is that again there is no way to transmit the schema from the server to the client, and that users are supposed to precompile the schema using a code generator. All that said, what we _could_ do is serialize the schema as JSON instead of using a binary format, like so: [{ "name": "exits", "kind": "cumulative", "count": 1 }, { "name": "halt_poll_fail_ns", "kind": "cumulative", "unit": "seconds", "scale": {"base": "pow2", exponent: -9}, "count": 1 }, ...] while keeping the actual statistics as an array of u64 values just like in these patches. The JSON representation of the schema would be always the same, so it could be treated as fixed-size and an efficient implementation of pread would be possible. And once the schema is JSON, there could be a *meta*-schema expressed using the varlink language: # compare to struct kvm_stats_desc, included after my sig # for reference type StatsDescriptor { name: string, kind: (cumulative, instant, peak), unit: ?(bytes, seconds, cycles), scale: ?(base: (pow2, pow10), exponent: int), count: int } type StatsSchema { name: string, stats: []StatsDescriptor } Varlink would *not* be used in the kernel, because Varlink isreally just JSON. The above ten lines (plus comments) would be dropped in Documentation/ as a .varlink file; they would be a convenient way to describe (to either a human or a program) how to parse the JSON schema. There would then be another problem, namely how to include the varlink schema in the generated documentation, since right now there are for example no sphinx bindings for varlink. Nevertheless, if you think it's better to have the schema as JSON instead of binary, according to the above varlink meta-schema, then we can look into it. Thanks, Paolo >> + struct kvm_stats_desc { >> + __u32 flags; >> + __s16 exponent; >> + __u16 size; >> + __u32 offset; >> + __u32 unused; >> + char name[0]; >> + };
On Wed, Jun 16, 2021 at 06:59:15PM +0200, Paolo Bonzini wrote: > On 16/06/21 17:21, Greg KH wrote: > > I forgot to comment on this one, sorry for the delay. > > > > Why are you "inventing" your own schema format here for this? Why not > > use a well-known or at least well-designed/implemented one that we have > > in userspace already? > > > > There are a few that I would love to see in the kernel, varlink being > > the best example. We have kernel examples of this and I would consider > > using that as a transport for sysfs-like data in the future, but never > > got around to it. > > Thanks, that's a good observation, and it's a problem that the rationale and > the design process didn't end up in either the documentation or the commit > message (only the outcome did). In order to fix that, this is going to be > quite a long message. > > Varlink comprises both a schema and an encoding, and each has its own > problems. For the encoding of the data, varlink is really just using JSON > and it is really just the wrong tool here. The first few problems that come > to mind are: > > - varlink structs are encoded as JSON dictionaries. Therefore, every time > userspace reads the fields, the kernel has to include the field names as > JSON dictionary keys. This means that a lot of time is spent writing > buffers, and on the receiving side parsing them. Has this been measured? Years ago when I messed with this, it was in the noise as JSON parsing is really fast these days. > - because numeric data has to be converted to ASCII the output doesn't have > fixed offsets, so it is not possible to make an efficient implementation of > pread. efficient where? In the kernel? > - even though Varlink specifies that int is "usually int64", a little-known > gem is that JSON behavior for numbers not representable as a double (i.e. > exceeding 2^53) is implementation-defined; implementations can and will mess > up values outside that range. This problem is not specific to this KVM > stats usecase; varlink's schema specification really is at odds with its > encoding specification. That's interesting, do the varlink developers know this? And we can say "for the kernel int will be int64" and be done with it, so this shouldn't be that big of an issue. > For the schema, there are some specific problems with varlink, but also a > more generic issue. The specific problems are: > > - the schema doesn't include the length of arrays. This makes it hard to > compute in advance lengths and offsets of fields (even ignoring the fact > that data is not binary, which I'll get to later) Do you care in advance? > - the schema also is not extensible with user annotations. In our case that > would be mostly the unit in which the value is expressed. units would be nice, I agree. > The main problem with the various available serialization formats is that > their schema languages are designed to be compiled with a code generator. > Here instead the schema is transmitted from the kernel to userspace. > Userspace is not really supposed to know what a value means or even that if > it exists. Userspace takes care of collecting the data from the kernel, but > ultimately there will be a human that knows what e.g. "io_exits" or > "req_event" means, and they will ask for the current value, or a plot over > time, of a specific statistic. > > Now, unlike most other schema languages, varlink does not require > precompiling the schema in its C bindings. However, this was mostly just > the authors not bothering to write a C code generator---they did write one > for Rust, for example. When using the "official" varlink C bindings, you > hardly use the schema at all. I don't think the kernel implementation needs this, you can just specify the schema "on the fly" and it should work. Or maybe I'm wrong, it's been a few years. > Something similar to the above issues is quite common in other formats. For > example, FlatBuffers[2]'s schema language[1] does have annotations (which it > calls metadata), but then we would still have to invent some standard > annotations and teach programs about them. However, the deal breaker is > that again there is no way to transmit the schema from the server to the > client, and that users are supposed to precompile the schema using a code > generator. Again, I didn't think this was an issue with the kernel implementation in that the userspace side could determine the schema by the data coming from the kernel, it wouldn't have to "know" about it ahead of time. But I could be wrong. > All that said, what we _could_ do is serialize the schema as JSON instead of > using a binary format, like so: > > [{ > "name": "exits", > "kind": "cumulative", > "count": 1 > }, { > "name": "halt_poll_fail_ns", > "kind": "cumulative", > "unit": "seconds", > "scale": {"base": "pow2", exponent: -9}, > "count": 1 > }, ...] > > while keeping the actual statistics as an array of u64 values just like in > these patches. The JSON representation of the schema would be always the > same, so it could be treated as fixed-size and an efficient implementation > of pread would be possible. And once the schema is JSON, there could be a > *meta*-schema expressed using the varlink language: > > # compare to struct kvm_stats_desc, included after my sig > # for reference > type StatsDescriptor { > name: string, > kind: (cumulative, instant, peak), > unit: ?(bytes, seconds, cycles), > scale: ?(base: (pow2, pow10), exponent: int), > count: int > } > > type StatsSchema { > name: string, > stats: []StatsDescriptor > } > > Varlink would *not* be used in the kernel, because Varlink isreally just > JSON. The above ten lines (plus comments) would be dropped in > Documentation/ as a .varlink file; they would be a convenient way to > describe (to either a human or a program) how to parse the JSON schema. > > There would then be another problem, namely how to include the varlink > schema in the generated documentation, since right now there are for example > no sphinx bindings for varlink. Nevertheless, if you think it's better to > have the schema as JSON instead of binary, according to the above varlink > meta-schema, then we can look into it. It should be in some standard format. I'm not wed to varlink, but I thought it solved some of your issues here with userspace not knowing the schema ahead of time which is the key as it will change over time and the kernel should be 'self-describing'. If not, and it sounds like you have looked into it, or at least the userspace side, then that's fine. But you should write up a justification somewhere why you didn't use an existing format (what about the netlink format?) in at least the changelog, like you did here. As you will be stuck with this api for the next 20+ years, it's good to be confident in it :) maybe someday we can get varlink into the tree, as I still think it would be better than the ad-hoc implementations we currently have. thanks, greg k-h
On 16/06/21 20:18, Greg KH wrote: > On Wed, Jun 16, 2021 at 06:59:15PM +0200, Paolo Bonzini wrote: >> - varlink structs are encoded as JSON dictionaries. Therefore, every time >> userspace reads the fields, the kernel has to include the field names as >> JSON dictionary keys. This means that a lot of time is spent writing >> buffers, and on the receiving side parsing them. > > Has this been measured? Years ago when I messed with this, it was in > the noise as JSON parsing is really fast these days. Yes, parsing is really fast. However, the work doesn't end at building an in-memory representation. An efficient representation (and a schema that is negotiated in advance) makes it possible to do this work as late and as little as possible, instead of doing it on every fetch of the statistics. For cloud vendors running virtual machines, they want to consolidate housekeeping tasks on as few CPUs as possible (because housekeeping CPUs cannot be billed to the customers), and every millisecond really counts. ASCII is inviting, but things like Protobufs, FlatBuffers, Cap'n'Proto are all binary because all those hidden costs do exist. >> - because numeric data has to be converted to ASCII the output doesn't have >> fixed offsets, so it is not possible to make an efficient implementation of >> pread. > > efficient where? In the kernel? Yes, Jing's patches can just do a quick copy_to_user if pread does not access the schema. And it's very simple code too. >> - even though Varlink specifies that int is "usually int64", a little-known >> gem is that JSON behavior for numbers not representable as a double (i.e. >> exceeding 2^53) is implementation-defined > > That's interesting, do the varlink developers know this? And we can say > "for the kernel int will be int64" and be done with it, so this > shouldn't be that big of an issue. Well yeah, but there's still the problem of what the other side thinks. In the end varlink's interesting because it's just JSON, meaning there's plenty of parsers available---but they all too often don't separate int vs. double. We had this issue with projects talking to QEMU (which has been using JSON the same way as varlink for ten years or so) and JSON parsers returning an overflow for 2^64-1 (because it rounds to 2^64) or an incorrect value. I'm not saying it's a showstopper, it's just an unavoidable ugliness if you pick JSON. >> For the schema, there are some specific problems with varlink, but also a >> more generic issue. The specific problems are: >> >> - the schema doesn't include the length of arrays. This makes it hard to >> compute in advance lengths and offsets of fields (even ignoring the fact >> that data is not binary, which I'll get to later) > > Do you care in advance? Yes, once we add for example histograms we would like to include in the schema the size and number of the buckets. > Again, I didn't think this was an issue with the kernel implementation > in that the userspace side could determine the schema by the data coming > from the kernel, it wouldn't have to "know" about it ahead of time. > But I could be wrong. No, you're right. The C implementations are really just very thin wrappers over JSON. There's very little "Varlink"ness in them. However the interesting part of the schema are the metadata--the unit, whether something is an instant vs. a cumulative value, the bucket size when we add histograms. These things are obviously not included in the data and must be communicated separately. Userspace tools could also use a schema to validate user requests ("record the halt_poll_fail_ns every second"). >> All that said, what we _could_ do is serialize the schema as JSON >> instead of using a binary format > > It should be in some standard format. If not, and it sounds like you > have looked into it, or at least the userspace side, then that's fine. > But you should write up a justification somewhere why you didn't use an > existing format (what about the netlink format?) I guess you're talking about NETLINK_GENERIC, that also has the issue that the schema (the attributes) is not dynamic but rather part of the uAPI. We explicitly don't want them to be stable, they're like tracepoints in that respect and that's why we took ideas from trace-cmd. Anyway, as a start Jing will summarize all these discussions in v10. Thanks, Paolo
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index e328caa35d6c..35ee52dbec89 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -5034,7 +5034,6 @@ 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.131 KVM_GET_SREGS2 ------------------ @@ -5081,6 +5080,174 @@ Writes special registers into the vcpu. See KVM_GET_SREGS2 for the data structures. This ioctl (when supported) replaces the KVM_SET_SREGS. +4.133 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 { + __u32 name_size; + __u32 count; + __u32 desc_offset; + __u32 data_offset; + char id[0]; + }; + +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_SHIFT 0 + #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_SHIFT 4 + #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_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; + __s16 exponent; + __u16 size; + __u32 offset; + __u32 unused; + 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`` field 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 is no unit for the value of statistics data. This usually means that + the value is a simple counter of an event. + * ``KVM_STATS_UNIT_BYTES`` + It indicates that the statistics data is used to measure memory size, in the + unit of Byte, KiByte, MiByte, GiByte, etc. The unit of the data is + determined by the ``exponent`` field in the descriptor. The + ``KVM_STATS_BASE_POW2`` flag is valid in this case. The unit of the data is + determined by ``pow(2, exponent)``. For example, if value is 10, + ``exponent`` is 20, which means the unit of statistics data is MiByte, we + can get the statistics data in the unit of Byte by + ``value * pow(2, exponent) = 10 * pow(2, 20) = 10 MiByte`` which is + 10 * 1024 * 1024 Bytes. + * ``KVM_STATS_UNIT_SECONDS`` + It indicates that the statistics data is used to measure time/latency, in + the unit of nanosecond, microsecond, millisecond and second. The unit of the + data is determined by the ``exponent`` field in the descriptor. The + ``KVM_STATS_BASE_POW10`` flag is valid in this case. The unit of the data + is determined by ``pow(10, exponent)``. For example, if value is 2000000, + ``exponent`` is -6, which means the unit of statistics data is microsecond, + we can get the statistics data in the unit of second by + ``value * pow(10, exponent) = 2000000 * pow(10, -6) = 2 seconds``. + * ``KVM_STATS_UNIT_CYCLES`` + It indicates that the statistics data is used to measure CPU clock cycles. + The ``KVM_STATS_BASE_POW10`` flag is valid in this case. For example, if + 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 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. + +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 (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 ``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``. +The maximum length (including trailing '\0') is indicated by ``name_size`` +in ``struct kvm_stats_header``. + +The Stats Data block contains an array of data values of type ``struct +kvm_vm_stats_data`` or ``struct kvm_vcpu_stats_data``. It would be read by +userspace periodically to pull statistics data. +The order of data value in Stats Data block is the same as the order of +descriptors in Descriptors block. + * Statistics data for VM/VCPU:: + + struct kvm_stats_data { + __u64 value[0]; + }; 5. The kvm_run structure ======================== @@ -6969,3 +7136,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 create get a file +descriptor for every VM and VCPU to read statistics data in binary format.