"Maciej S. Szmigiero" <m...@maciej.szmigiero.name> writes:
> From: "Maciej S. Szmigiero" <maciej.szmigi...@oracle.com>
>
> Used by the hv-balloon driver for (optional) guest memory status reports.
Inhowfar optional? What enables / triggers it?
Use case for the event?
Could a status event make sense for other balloon drivers as well?
> Signed-off-by: Maciej S. Szmigiero <maciej.szmigi...@oracle.com>
> ---
> qapi/machine.json | 25 +++++++++++++++++++++++++
> 1 file changed, 25 insertions(+)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 5ede977cf2bc..9649616b9ed2 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1113,6 +1113,31 @@
> { 'event': 'BALLOON_CHANGE',
> 'data': { 'actual': 'int' } }
>
> +##
> +# @HV_BALLOON_STATUS_REPORT:
> +#
> +# Emitted when the hv-balloon driver receives a "STATUS" message from
> +# the guest.
Aha, the event is triggered by the guest. It must therefore be
rate-limited, just like BALLOON_CHANGE. To do that, add it to
monitor_qapi_event_conf[] in monitor/monitor.c, and document it as noted
below.
> +#
> +# @commited: the amount of memory in use inside the guest plus the amount
> +# of the memory unusable inside the guest (ballooned out,
> +# offline, etc.)
> +#
> +# @available: the amount of the memory inside the guest available for new
> +# allocations ("free")
Spelling: committed. Remember to update the example, too.
Please format like
# @committed: the amount of memory in use inside the guest plus the
# amount of the memory unusable inside the guest (ballooned out,
# offline, etc.)
#
# @available: the amount of the memory inside the guest available for
# new allocations ("free")
to blend in with recent commit a937b6aa739 (qapi: Reformat doc comments
to conform to current conventions).
> +#
To document rate-limiting, add:
# Note: this event is rate-limited.
#
> +# Since: TBD
> +#
> +# Example:
> +#
> +# <- { "event": "HV_BALLOON_STATUS_REPORT",
> +# "data": { "commited": 816640000, "available": 3333054464 },
> +# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
> +#
> +##
> +{ 'event': 'HV_BALLOON_STATUS_REPORT',
> + 'data': { 'commited': 'size', 'available': 'size' } }
> +
> ##
> # @MemoryInfo:
> #
An event is commonly paired with a query command, so that QMP clients
can resynchronize state after missing events, e.g. when reconnecting
after a client restart.
query-balloon isn't such a query: it returns less than the event.
If a paired query doesn't make sense, explain why.
