Re: [Qemu-devel] [PATCH] balloon: Fix documentation of the --balloon parameter and deprecate it

[Paolo Bonzini]

On 28/02/2018 06:38, Thomas Huth wrote:
> There are two issues with the documentation of the --balloon parameter:
> First, "--balloon none" is simply doing nothing. Even if a machine had a
> balloon device by default, this option is not disabling anything, it is
> simply ignored. Thus let's simply drop this option from the documentation
> to avoid to confuse the users (but keep the code in vl.c for backward
> compatibility).
> Second, the documentation claims that "--balloon virtio" is the default
> mode, but this is not true anymore since commit 382f074371f7dc32a34.
> Since that commit, the option also has no real use case anymore, since
> you can simply use "--device virtio-balloon" nowadays instead. Thus to
> simplify our complex parameter zoo a little bit, let's deprecate the
> the parameter now and tell the user to use "--device virtio-balloon"
> instead.
> 
> Fixes: 382f074371f7dc32a34c944c845b1698e83d8c36
> Signed-off-by: Thomas Huth <address@hidden>
> ---
>  qemu-doc.texi   |  5 +++++
>  qemu-options.hx | 11 ++++-------
>  vl.c            |  3 +++
>  3 files changed, 12 insertions(+), 7 deletions(-)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 8e35569..29c888d 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -2725,6 +2725,11 @@ enabled via the ``-machine usb=on'' argument.
>  
>  The ``-nodefconfig`` argument is a synonym for ``-no-user-config``.
>  
> address@hidden -balloon (since 2.12.0)
> +
> +The @option{--balloon virtio} argument has been superseded by
> address@hidden virtio-balloon}.
> +
>  @subsection -machine s390-squash-mcss=on|off (since 2.12.0)
>  
>  The ``s390-squash-mcss=on`` property has been obsoleted by allowing the
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 8ccd5dc..075eb0a 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -462,16 +462,13 @@ modprobe i810_audio clocking=48000
>  ETEXI
>  
>  DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
> -    "-balloon none   disable balloon device\n"
>      "-balloon virtio[,addr=str]\n"
> -    "                enable virtio balloon device (default)\n", 
> QEMU_ARCH_ALL)
> +    "                enable virtio balloon device (deprecated)\n", 
> QEMU_ARCH_ALL)
>  STEXI
> address@hidden -balloon none
> address@hidden -balloon
> -Disable balloon device.
>  @item -balloon virtio[,address@hidden
> -Enable virtio balloon device (default), optionally with PCI address
> address@hidden
> address@hidden -balloon
> +Enable virtio balloon device, optionally with PCI address @var{addr}. This
> +option is deprecated, use @option{--device virtio-balloon} instead.
>  ETEXI
>  
>  DEF("device", HAS_ARG, QEMU_OPTION_device,
> diff --git a/vl.c b/vl.c
> index 9e7235d..2729476 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2221,6 +2221,9 @@ static int balloon_parse(const char *arg)
>  {
>      QemuOpts *opts;
>  
> +    warn_report("This option is deprecated. "
> +                "Use '--device virtio-balloon' to enable the balloon 
> device.");
> +
>      if (strcmp(arg, "none") == 0) {
>          return 0;
>      }
> 

Queued, thanks.

Paolo