Re: [virtio-dev] [PATCH] balloon: document deflate on oom

[James Bottomley <jbottomley@odin.com>]

On Tue, 2015-04-28 at 22:46 +0200, Michael S. Tsirkin wrote:
> Document the new option, and also clarify behaviour
> without it.
> 
> In particular, I noticed that actual field is not the
> actual number of pages in the balloon as
> driver might do inflate followed by deflate.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  content.tex | 25 +++++++++++++++++++++++--
>  1 file changed, 23 insertions(+), 2 deletions(-)
> 
> diff --git a/content.tex b/content.tex
> index 036f38c..98d5486 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -4390,6 +4390,9 @@ guest memory statistics to the host.
>  
>  \item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
>      memory statistics is present.
> +\item[VIRTIO_BALLOON_F_DEFLATE_ON_OOM (2) ] Deflate balloon on
> +    OOM.
> +
>  \end{description}
>  
>  \drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
> @@ -4489,10 +4492,25 @@ requests by using the descriptor.
>  
>  \drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
>  The driver SHOULD supply pages to the balloon when \field{num_pages} is
> -greater than \field{actual}.
> +greater than the actual number of pages in the balloon.
>  
>  The driver MAY use pages from the balloon when \field{num_pages} is
> -less than \field{actual}.
> +less than the actual number of pages in the balloon.
> +
> +The driver MAY supply pages to the balloon when \field{num_pages} is
> +greater than or equal to the actual number of pages in the balloon.
> +
> +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the
> +driver MUST NOT use pages from the balloon when \field{num_pages}
> +is less than or equal to the actual number of pages in the
> +balloon.
> +
> +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the
> +driver MAY use pages from the balloon when \field{num_pages}
> +is less than or equal to the actual number of pages in the
> +balloon if this is required for system stability
> +(e.g. if memory is required by applications running within
> + the guest).
>  
>  The driver MUST use the deflateq to inform the device of pages that it
>  wants to use from the balloon.
> @@ -4517,6 +4535,9 @@ request.
>  The driver MUST update \field{actual} after changing the number
>  of pages in the balloon.
>  
> +The driver MAY update \field{actual} once after multiple
> +inflate and deflate operations.
> +

That's almost what I have, but not quite.

One of the main changes about VIRTIO_BALLOON_F_DEFLATE_ON_OOM is that if
it is negotiated, the guest may initiate deflation on its own (without
receiving and interrupt from the host).  To my mind, that necessitates
changes to section 5.5.6 which begins "The device is driven by the
receipt of a configuration change interrupt."

James