docs: reSTify virtio-balloon-stats documentation and move to docs/interop

The virtio-balloon-stats documentation might be useful for people that
are implementing software that talks to QEMU via QMP, so this should
reside in the docs/interop/ directory. While we're at it, also convert
the file to restructured text and mention it in the MAINTAINERS file.

Signed-off-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20220105115245.420945-1-thuth@redhat.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>

diff --git a/MAINTAINERS b/MAINTAINERS
index 6aa0335560ebac8d1b4ef334134573b177d2fd0d..c98a61caeeed7abbcd38c944457245022a0ca0c0 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1932,6 +1932,7 @@ virtio-balloon
 M: Michael S. Tsirkin <mst@redhat.com>
 M: David Hildenbrand <david@redhat.com>
 S: Maintained
+F: docs/interop/virtio-balloon-stats.rst
 F: hw/virtio/virtio-balloon*.c
 F: include/hw/virtio/virtio-balloon.h
 F: softmmu/balloon.c

diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index c59bac983407010e48e7a9f77c4af4dc63a78962..b7632acb7ba3792294f81398e82d32f728b259b1 100644 (file)
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -22,3 +22,4 @@ are useful for making QEMU interoperate with other software.
    vhost-user
    vhost-user-gpu
    vhost-vdpa
+   virtio-balloon-stats

diff --git a/docs/interop/virtio-balloon-stats.rst b/docs/interop/virtio-balloon-stats.rst
new file mode 100644 (file)
index 0000000..b9a6a6e
--- /dev/null
+++ b/docs/interop/virtio-balloon-stats.rst
@@ -0,0 +1,111 @@
+Virtio balloon memory statistics
+================================
+
+The virtio balloon driver supports guest memory statistics reporting. These
+statistics are available to QEMU users as QOM (QEMU Object Model) device
+properties via a polling mechanism.
+
+Before querying the available stats, clients first have to enable polling.
+This is done by writing a time interval value (in seconds) to the
+guest-stats-polling-interval property. This value can be:
+
+  > 0
+       enables polling in the specified interval. If polling is already
+       enabled, the polling time interval is changed to the new value
+
+  0
+       disables polling. Previous polled statistics are still valid and
+       can be queried.
+
+Once polling is enabled, the virtio-balloon device in QEMU will start
+polling the guest's balloon driver for new stats in the specified time
+interval.
+
+To retrieve those stats, clients have to query the guest-stats property,
+which will return a dictionary containing:
+
+  * A key named 'stats', containing all available stats. If the guest
+    doesn't support a particular stat, or if it couldn't be retrieved,
+    its value will be -1. Currently, the following stats are supported:
+
+      - stat-swap-in
+      - stat-swap-out
+      - stat-major-faults
+      - stat-minor-faults
+      - stat-free-memory
+      - stat-total-memory
+      - stat-available-memory
+      - stat-disk-caches
+      - stat-htlb-pgalloc
+      - stat-htlb-pgfail
+
+  * A key named last-update, which contains the last stats update
+    timestamp in seconds. Since this timestamp is generated by the host,
+    a buggy guest can't influence its value. The value is 0 if the guest
+    has not updated the stats (yet).
+
+It's also important to note the following:
+
+ - Previously polled statistics remain available even if the polling is
+   later disabled
+
+ - As noted above, if a guest doesn't support a particular stat its value
+   will always be -1. However, it's also possible that a guest temporarily
+   couldn't update one or even all stats. If this happens, just wait for
+   the next update
+
+ - Polling can be enabled even if the guest doesn't have stats support
+   or the balloon driver wasn't loaded in the guest. If this is the case
+   and stats are queried, last-update will be 0.
+
+ - The polling timer is only re-armed when the guest responds to the
+   statistics request. This means that if a (buggy) guest doesn't ever
+   respond to the request the timer will never be re-armed, which has
+   the same effect as disabling polling
+
+Here are a few examples. QEMU is started with ``-device virtio-balloon``,
+which generates ``/machine/peripheral-anon/device[1]`` as the QOM path for
+the balloon device.
+
+Enable polling with 2 seconds interval::
+
+  { "execute": "qom-set",
+               "arguments": { "path": "/machine/peripheral-anon/device[1]",
+               "property": "guest-stats-polling-interval", "value": 2 } }
+
+  { "return": {} }
+
+Change polling to 10 seconds::
+
+  { "execute": "qom-set",
+               "arguments": { "path": "/machine/peripheral-anon/device[1]",
+               "property": "guest-stats-polling-interval", "value": 10 } }
+
+  { "return": {} }
+
+Get stats::
+
+  { "execute": "qom-get",
+               "arguments": { "path": "/machine/peripheral-anon/device[1]",
+               "property": "guest-stats" } }
+  {
+    "return": {
+        "stats": {
+            "stat-swap-out": 0,
+            "stat-free-memory": 844943360,
+            "stat-minor-faults": 219028,
+            "stat-major-faults": 235,
+            "stat-total-memory": 1044406272,
+            "stat-swap-in": 0
+        },
+        "last-update": 1358529861
+    }
+  }
+
+Disable polling::
+
+  { "execute": "qom-set",
+               "arguments": { "path": "/machine/peripheral-anon/device[1]",
+               "property": "stats-polling-interval", "value": 0 } }
+
+  { "return": {} }

diff --git a/docs/virtio-balloon-stats.txt b/docs/virtio-balloon-stats.txt
deleted file mode 100644 (file)
index 1732cc8..0000000
--- a/docs/virtio-balloon-stats.txt
+++ /dev/null
@@ -1,109 +0,0 @@
-virtio balloon memory statistics
-================================
-
-The virtio balloon driver supports guest memory statistics reporting. These
-statistics are available to QEMU users as QOM (QEMU Object Model) device
-properties via a polling mechanism.
-
-Before querying the available stats, clients first have to enable polling.
-This is done by writing a time interval value (in seconds) to the
-guest-stats-polling-interval property. This value can be:
-
-  > 0  enables polling in the specified interval. If polling is already
-       enabled, the polling time interval is changed to the new value
-
-  0    disables polling. Previous polled statistics are still valid and
-       can be queried.
-
-Once polling is enabled, the virtio-balloon device in QEMU will start
-polling the guest's balloon driver for new stats in the specified time
-interval.
-
-To retrieve those stats, clients have to query the guest-stats property,
-which will return a dictionary containing:
-
-  o A key named 'stats', containing all available stats. If the guest
-    doesn't support a particular stat, or if it couldn't be retrieved,
-    its value will be -1. Currently, the following stats are supported:
-
-      - stat-swap-in
-      - stat-swap-out
-      - stat-major-faults
-      - stat-minor-faults
-      - stat-free-memory
-      - stat-total-memory
-      - stat-available-memory
-      - stat-disk-caches
-      - stat-htlb-pgalloc
-      - stat-htlb-pgfail
-
-  o A key named last-update, which contains the last stats update
-    timestamp in seconds. Since this timestamp is generated by the host,
-    a buggy guest can't influence its value. The value is 0 if the guest
-    has not updated the stats (yet).
-
-It's also important to note the following:
-
- - Previously polled statistics remain available even if the polling is
-   later disabled
-
- - As noted above, if a guest doesn't support a particular stat its value
-   will always be -1. However, it's also possible that a guest temporarily
-   couldn't update one or even all stats. If this happens, just wait for
-   the next update
-
- - Polling can be enabled even if the guest doesn't have stats support
-   or the balloon driver wasn't loaded in the guest. If this is the case
-   and stats are queried, last-update will be 0.
-
- - The polling timer is only re-armed when the guest responds to the
-   statistics request. This means that if a (buggy) guest doesn't ever
-   respond to the request the timer will never be re-armed, which has
-   the same effect as disabling polling
-
-Here are a few examples. QEMU is started with '-device virtio-balloon',
-which generates '/machine/peripheral-anon/device[1]' as the QOM path for
-the balloon device.
-
-Enable polling with 2 seconds interval:
-
-{ "execute": "qom-set",
-             "arguments": { "path": "/machine/peripheral-anon/device[1]",
-                        "property": "guest-stats-polling-interval", "value": 2 } }
-
-{ "return": {} }
-
-Change polling to 10 seconds:
-
-{ "execute": "qom-set",
-             "arguments": { "path": "/machine/peripheral-anon/device[1]",
-                        "property": "guest-stats-polling-interval", "value": 10 } }
-
-{ "return": {} }
-
-Get stats:
-
-{ "execute": "qom-get",
-  "arguments": { "path": "/machine/peripheral-anon/device[1]",
-  "property": "guest-stats" } }
-{
-    "return": {
-        "stats": {
-            "stat-swap-out": 0,
-            "stat-free-memory": 844943360,
-            "stat-minor-faults": 219028,
-            "stat-major-faults": 235,
-            "stat-total-memory": 1044406272,
-            "stat-swap-in": 0
-        },
-        "last-update": 1358529861
-    }
-}
-
-Disable polling:
-
-{ "execute": "qom-set",
-             "arguments": { "path": "/machine/peripheral-anon/device[1]",
-                        "property": "stats-polling-interval", "value": 0 } }
-
-{ "return": {} }