Re: [PATCH v3 3/9] qapi/misc.json: Correct balloon documentation

[David Hildenbrand <david@redhat.com>]

On 25.05.20 17:06, Philippe Mathieu-Daudé wrote:
> The documentation incorrectly uses the "size of the balloon"
> description when it should be "logical size of the VM". Fix it.
> 
> The relation between both values is:
> 
>   logical_vm_size = vm_ram_size - balloon_size
> 
> Reported-by: David Hildenbrand <david@redhat.com>
> Suggested-by: David Hildenbrand <david@redhat.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> ---
>  qapi/misc.json | 13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
> 
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 2c48ffaa62..446fc8ff83 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -191,7 +191,8 @@
>  #
>  # Information about the guest balloon device.
>  #
> -# @actual: the number of bytes the balloon currently contains
> +# @actual: the logical size of the VM in bytes
> +#          Formula used: logical_vm_size = vm_ram_size - balloon_size
>  #
>  # Since: 0.14.0
>  #
> @@ -227,7 +228,8 @@
>  # Emitted when the guest changes the actual BALLOON level. This value is

Side note: I have no idea what an "actual BALLOON level" is. "When the
guest changes the balloon size, and thereby, the logical size of the
VM". But it's unrelated to your changes ...

>  # equivalent to the @actual field return by the 'query-balloon' command
>  #
> -# @actual: actual level of the guest memory balloon in bytes
> +# @actual: the logical size of the VM in bytes
> +#          Formula used: logical_vm_size = vm_ram_size - balloon_size
>  #
>  # Note: this event is rate-limited.
>  #
> @@ -756,7 +758,10 @@
>  #
>  # Request the balloon driver to change its balloon size.
>  #
> -# @value: the target size of the balloon in bytes
> +# @value: the target logical size of the VM in bytes
> +#         We can deduce the size of the balloon using this formula:
> +#            logical_vm_size = vm_ram_size - balloon_size
> +#         From it we have: balloon_size = vm_ram_size - @value
>  #
>  # Returns: - Nothing on success
>  #          - If the balloon driver is enabled but not functional because the KVM
> @@ -774,6 +779,8 @@
>  # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
>  # <- { "return": {} }
>  #
> +# With a 2.5GiB guest this command inflated the ballon to 3GiB.

s/ballon/balloon/

> +#
>  ##
>  { 'command': 'balloon', 'data': {'value': 'int'} }
>  
> 

Thanks!

Reviewed-by: David Hildenbrand <david@redhat.com>

-- 
Thanks,

David / dhildenb