Re: [Qemu-devel] [PATCH v3 2/2] docs: document deprecated features in appendix

[Thomas Huth]

On 04.07.2017 13:14, Daniel P. Berrange wrote:
> The deprecation of features in QEMU is totally adhoc currently,
> with no way for the user to get a list of what is deprecated
> in each release. This adds an appendix to the doc that records
> when each deprecation was made and provides text explaining
> what to use instead, if anything.
> 
> Since there has been no formal policy around removal of deprecated
> features in the past, any deprecations prior to 2.10.0 are to be
> treated as if they had been made at the 2.10.0 release. Thus the
> earliest that existing deprecations will be deleted is the start
> of the 2.12.0 cycle.
> 
> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
>  qemu-doc.texi | 167 
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 167 insertions(+)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 27781e4..ba5170c 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -39,6 +39,7 @@
>  * QEMU User space emulator::
>  * Implementation notes::
>  * Support lifetime::
> +* Deprecated features::
>  * License::
>  * Index::
>  @end menu
> @@ -3054,6 +3055,172 @@ support machine types from many previous versions.
[...]
> address@hidden -monitor default=on (since 2.4.0)
> +
> +The ``default'' option to the ``-monitor'' argument is
> +now ignored. When multiple monitors were enabled, it
> +indicated which monitor would receive log messages
> +from the audio subsystem.

The audio subsystem was just the last user. There were other subsystems
using it before, see e.g. commit 027a79c373954920d5 or commit
02d16089802234f.

[...]
> address@hidden -net vlan (since 2.9.0)
> +
> +The ``-net van=NN'' argument is partially replaced with the
> +new ``-netdev'' argument. The remaining use cases will no
> +longer be directly supported in QEMU

Add a period after the last sentence?

> address@hidden -drive if=scsi (since 2.9.0)
> +
> +The ``-drive if=scsi'' argument is replaced by the the
> +``-device BUS-TYPE'' argument combined with ``-drive if=none''.
> +
> address@hidden -net dump (since 2.10.0)
> +
> +The ``--net dump'' argument is now a synonym for setting the
> +``-object filter-dump'' argument instead.

Technically, it's not a synonym, but a replacement ;-)
("-net dump" uses the "vlan" concept, while "-object filter-dump" works
with "-netdev" instead)

> address@hidden -hdachs (since 2.10.0)
> +
> +The ``-hdachs'' argument is now a synonym for setting
> +the ``cyls'', ``heads'', ``secs'', and ``trans'' properties
> +on the ``ide-hd'' device using the ``-device'' argument.
> +The new syntax allows different settings to be provided
> +per disk.
> +
> address@hidden -usbdevice (since 2.10.0)
> +
> +The ``-usbdevice DEV'' argument is now a synonym for setting
> +the ``-device usb-DEV'' argument instead. The deprecated syntax
> +would automatically enable USB support on the machine type.
> +If using the new syntax, USB support must be explicitly
> +enabled via the ``-machine usb=on'' argument.
> +
> address@hidden qemu-img command line arguments
> +
> address@hidden convert -s (since 2.0.0)
> +
> +The ``convert -s snapshot_id_or_name'' argument is obsoleted
> +by the ``convert -l snapshot_param'' argument instead.
> +
> address@hidden System emulator human monitor commands
> +
> address@hidden usb_add (since 2.10.0)
> +
> +The ``usb_add'' command is replaced by the ``device_add'' command.
> +
> address@hidden usb_del (since 2.10.0)
> +
> +The ``usb_del'' command is replaced by the ``device_del'' command.
> +
> address@hidden System emulator devices
> +
> address@hidden ivshmem (since 2.6.0)
> +
> +The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
> +or ``ivshmem-doorbell`` device types.
> +
> address@hidden spapr-pci-vfio-host-bridge (since 2.6.0)
> +
> +The ``spapr-pci-vfio-host-bridge'' device type is replaced by
> +the ``spapr-pci-host-bridge'' device type.
> +
>  @node License
>  @appendix License

 Thomas