From 14dc58e3e0b12595e407502b93a8bb7e69621cbb Mon Sep 17 00:00:00 2001 From: Thomas Huth Date: Wed, 5 Jan 2022 12:52:45 +0100 Subject: [PATCH] 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 Message-Id: <20220105115245.420945-1-thuth@redhat.com> Reviewed-by: Michael S. Tsirkin Signed-off-by: Michael S. Tsirkin --- MAINTAINERS | 1 + docs/interop/index.rst | 1 + .../virtio-balloon-stats.rst} | 58 ++++++++++--------- 3 files changed, 32 insertions(+), 28 deletions(-) rename docs/{virtio-balloon-stats.txt => interop/virtio-balloon-stats.rst} (66%) diff --git a/MAINTAINERS b/MAINTAINERS index 6aa0335560..c98a61caee 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1932,6 +1932,7 @@ virtio-balloon M: Michael S. Tsirkin M: David Hildenbrand 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 c59bac9834..b7632acb7b 100644 --- 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/virtio-balloon-stats.txt b/docs/interop/virtio-balloon-stats.rst similarity index 66% rename from docs/virtio-balloon-stats.txt rename to docs/interop/virtio-balloon-stats.rst index 1732cc8c8a..b9a6a6edb2 100644 --- a/docs/virtio-balloon-stats.txt +++ b/docs/interop/virtio-balloon-stats.rst @@ -1,4 +1,4 @@ -virtio balloon memory statistics +Virtio balloon memory statistics ================================ The virtio balloon driver supports guest memory statistics reporting. These @@ -9,10 +9,12 @@ 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 + > 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 + 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 @@ -22,7 +24,7 @@ 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 + * 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: @@ -37,7 +39,7 @@ which will return a dictionary containing: - stat-htlb-pgalloc - stat-htlb-pgfail - o A key named last-update, which contains the last stats update + * 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). @@ -61,32 +63,32 @@ It's also important to note the following: 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 +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: +Enable polling with 2 seconds interval:: -{ "execute": "qom-set", - "arguments": { "path": "/machine/peripheral-anon/device[1]", - "property": "guest-stats-polling-interval", "value": 2 } } + { "execute": "qom-set", + "arguments": { "path": "/machine/peripheral-anon/device[1]", + "property": "guest-stats-polling-interval", "value": 2 } } -{ "return": {} } + { "return": {} } -Change polling to 10 seconds: +Change polling to 10 seconds:: -{ "execute": "qom-set", - "arguments": { "path": "/machine/peripheral-anon/device[1]", - "property": "guest-stats-polling-interval", "value": 10 } } + { "execute": "qom-set", + "arguments": { "path": "/machine/peripheral-anon/device[1]", + "property": "guest-stats-polling-interval", "value": 10 } } -{ "return": {} } + { "return": {} } -Get stats: +Get stats:: -{ "execute": "qom-get", - "arguments": { "path": "/machine/peripheral-anon/device[1]", - "property": "guest-stats" } } -{ + { "execute": "qom-get", + "arguments": { "path": "/machine/peripheral-anon/device[1]", + "property": "guest-stats" } } + { "return": { "stats": { "stat-swap-out": 0, @@ -98,12 +100,12 @@ Get stats: }, "last-update": 1358529861 } -} + } -Disable polling: +Disable polling:: -{ "execute": "qom-set", - "arguments": { "path": "/machine/peripheral-anon/device[1]", - "property": "stats-polling-interval", "value": 0 } } + { "execute": "qom-set", + "arguments": { "path": "/machine/peripheral-anon/device[1]", + "property": "stats-polling-interval", "value": 0 } } -{ "return": {} } + { "return": {} }