OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

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

Browse Source 
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>
This commit is contained in:
Thomas Huth 2022-01-05 12:52:45 +01:00 committed by Michael S. Tsirkin
parent 44bff3767c
commit 14dc58e3e0
3 changed files with 32 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
MAINTAINERS
View File

@ -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

1
docs/interop/index.rst
View File

@ -22,3 +22,4 @@ are useful for making QEMU interoperate with other software.
vhost-user
vhost-user-gpu
vhost-vdpa
virtio-balloon-stats

58
docs/virtio-balloon-stats.txt → docs/interop/virtio-balloon-stats.rst
View File

@ -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": {} }