Proxmox-Port/qemu
1
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2025-08-15 05:06:56 +00:00
Code Issues Actions Packages Projects Releases Wiki 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: Michael S. Tsirkin <mst@redhat.com>
M: David Hildenbrand <david@redhat.com> M: David Hildenbrand <david@redhat.com>
S: Maintained S: Maintained
F: docs/interop/virtio-balloon-stats.rst
F: hw/virtio/virtio-balloon*.c F: hw/virtio/virtio-balloon*.c
F: include/hw/virtio/virtio-balloon.h F: include/hw/virtio/virtio-balloon.h
F: softmmu/balloon.c 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
vhost-user-gpu vhost-user-gpu
vhost-vdpa vhost-vdpa
virtio-balloon-stats

24
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 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 This is done by writing a time interval value (in seconds) to the
guest-stats-polling-interval property. This value can be: 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 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. can be queried.
Once polling is enabled, the virtio-balloon device in QEMU will start 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, To retrieve those stats, clients have to query the guest-stats property,
which will return a dictionary containing: 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, doesn't support a particular stat, or if it couldn't be retrieved,
its value will be -1. Currently, the following stats are supported: 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-pgalloc
- stat-htlb-pgfail - 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, 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 a buggy guest can't influence its value. The value is 0 if the guest
has not updated the stats (yet). has not updated the stats (yet).
@ -61,11 +63,11 @@ It's also important to note the following:
respond to the request the timer will never be re-armed, which has respond to the request the timer will never be re-armed, which has
the same effect as disabling polling the same effect as disabling polling
Here are a few examples. QEMU is started with '-device virtio-balloon', Here are a few examples. QEMU is started with ``-device virtio-balloon``,
which generates '/machine/peripheral-anon/device[1]' as the QOM path for which generates ``/machine/peripheral-anon/device[1]`` as the QOM path for
the balloon device. the balloon device.
Enable polling with 2 seconds interval: Enable polling with 2 seconds interval::
{ "execute": "qom-set", { "execute": "qom-set",
"arguments": { "path": "/machine/peripheral-anon/device[1]", "arguments": { "path": "/machine/peripheral-anon/device[1]",
@ -73,7 +75,7 @@ Enable polling with 2 seconds interval:
{ "return": {} } { "return": {} }
Change polling to 10 seconds: Change polling to 10 seconds::
{ "execute": "qom-set", { "execute": "qom-set",
"arguments": { "path": "/machine/peripheral-anon/device[1]", "arguments": { "path": "/machine/peripheral-anon/device[1]",
@ -81,7 +83,7 @@ Change polling to 10 seconds:
{ "return": {} } { "return": {} }
Get stats: Get stats::
{ "execute": "qom-get", { "execute": "qom-get",
"arguments": { "path": "/machine/peripheral-anon/device[1]", "arguments": { "path": "/machine/peripheral-anon/device[1]",
@ -100,7 +102,7 @@ Get stats:
} }
} }
Disable polling: Disable polling::
{ "execute": "qom-set", { "execute": "qom-set",
"arguments": { "path": "/machine/peripheral-anon/device[1]", "arguments": { "path": "/machine/peripheral-anon/device[1]",