the accounting choices are not necessarily intuitive, especially
comparing Linux with BSD, so clarify the current state of things.

Mark which counters are actually used on Linux and BSD,
and how they are accumulated into the libvirt statistics.

Signed-off-by: Claudio Fontana <cfontana@suse.de>
---
 include/libvirt/libvirt-host.h | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h
index 398b40c35a..4d4f1c02df 100644
--- a/include/libvirt/libvirt-host.h
+++ b/include/libvirt/libvirt-host.h
@@ -223,6 +223,9 @@ typedef enum {
  * Macro for the cumulative CPU time which was spent by the kernel,
  * since the node booting up (in nanoseconds).
  *
+ * Linux: this statistic includes kernel + irq + softirq time.
+ * BSD: this statistic includes only CP_SYS. CP_INTR is accounted separately.
+ *
  * Since: 0.9.3
  */
 # define VIR_NODE_CPU_STATS_KERNEL "kernel"
@@ -233,6 +236,8 @@ typedef enum {
  * The cumulative CPU time which was spent by user processes,
  * since the node booting up (in nanoseconds).
  *
+ * Linux, BSD: this statistic includes user + nice time.
+ *
  * Since: 0.9.3
  */
 # define VIR_NODE_CPU_STATS_USER "user"
@@ -243,6 +248,8 @@ typedef enum {
  * The cumulative idle CPU time,
  * since the node booting up (in nanoseconds).
  *
+ * Linux, BSD
+ *
  * Since: 0.9.3
  */
 # define VIR_NODE_CPU_STATS_IDLE "idle"
@@ -253,6 +260,8 @@ typedef enum {
  * The cumulative I/O wait CPU time,
  * since the node booting up (in nanoseconds).
  *
+ * Linux-only.
+ *
  * Since: 0.9.3
  */
 # define VIR_NODE_CPU_STATS_IOWAIT "iowait"
@@ -263,6 +272,9 @@ typedef enum {
  * The cumulative interrupt CPU time,
  * since the node booting up (in nanoseconds).
  *
+ * BSD-only.
+ * Note that on Linux, interrupt CPU time is accounted as part of "kernel".
+ *
  * Since: 1.2.2
  */
 # define VIR_NODE_CPU_STATS_INTR "intr"
@@ -273,6 +285,9 @@ typedef enum {
  * The cumulative CPU time spent running guest virtual CPUs,
  * since the node booting up (in nanoseconds).
  *
+ * Linux-only.
+ * Note that on BSD, guest CPU time is accounted as part of CP_SYS alias "kernel"
+ *
  * Since: 11.8.0
  */
 # define VIR_NODE_CPU_STATS_GUEST "guest"
-- 
2.35.3