[Qemu-devel] [RFC 3/3] docs: document virtio-balloon stats

[Luiz Capitulino <lcapitulino@redhat.com>]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/virtio-balloon-stats.txt | 73 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/virtio-balloon-stats.txt

diff --git a/docs/virtio-balloon-stats.txt b/docs/virtio-balloon-stats.txt
new file mode 100644
index 0000000..7e7ddc4
--- /dev/null
+++ b/docs/virtio-balloon-stats.txt
@@ -0,0 +1,73 @@
+virtio balloon memory statistics
+================================
+
+The virtio balloon driver supports guest memory statistics reporting. These
+statistics are available to QEMU users as QOM (QEMU Obejct Model) device
+properties via a polling mechanism.
+
+Basically, clients have to enable polling. Then they can query the available
+statistics.
+
+There are two control properties and six memory statistics from the guest.
+
+The control properties are:
+
+ o stats-polling-interval: a value greater than zero enables polling
+   in the specified interval (in seconds). When value equals zero,
+   polling is disabled. If polling is already enabled and a value
+   greater than zero is written, the polling interval time is changed
+
+ o stats-last-update: last stats update timestamp, in seconds
+
+The memory statistics are:
+
+ o stat-swap-in
+ o stat-swap-out
+ o stat-major-faults
+ o stat-minor-faults
+ o stat-free-memory
+ o stat-total-memory
+
+All values are in bytes. A value of -1 means that the statistic isn't
+available right now.
+
+Here are a few examples. The virtio-balloon device is assumed to be in the
+'/machine/peripheral-anon/device[1]' QOM path.
+
+Enable polling with 2 seconds interval:
+
+{ "execute": "qom-set",
+             "arguments": { "path": "/machine/peripheral-anon/device[1]",
+			 "property": "stats-polling-interval", "value": 2 } }
+
+{ "return": {} }
+
+Change polling to 10 seconds:
+
+{ "execute": "qom-set",
+             "arguments": { "path": "/machine/peripheral-anon/device[1]",
+			 "property": "stats-polling-interval", "value": 10 } }
+
+{ "return": {} }
+
+Get last update timestamp and free memory stat:
+
+{ "execute": "qom-get",
+  "arguments": { "path": "/machine/peripheral-anon/device[1]",
+  "property": "stats-last-update" } }
+
+{ "return": 1354629634 }
+
+{ "execute": "qom-get",
+  "arguments": { "path": "/machine/peripheral-anon/device[1]",
+  "property": "stat-free-memory" } }
+
+{ "return": 845115392 }
+
+Disable polling:
+
+{ "execute": "qom-set",
+             "arguments": { "path": "/machine/peripheral-anon/device[1]",
+			 "property": "stats-polling-interval", "value": 0 } }
+
+{ "return": {} }
-- 
1.8.0