Patch

diff --git a/docs/virtio-balloon-stats.txt b/docs/virtio-balloon-stats.txt
new file mode 100644
index 0000000..103f404--- /dev/null+++ b/docs/virtio-balloon-stats.txt@@ -0,0 +1,104 @@+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++ 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++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, an error will be returned++ - 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 '-balloon virtio', 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": {} }