[Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Daniel P. Berrange]

This is a followup to

  v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
  v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.html

The goal is to clarify to users & app developers what they can expect
from QEMU in terms of feature lifecycle & any deprecation policy should
it be neccessary to remove features.

The list of features marked as deprecated was determined by looking at
the QEMU source for the word "deprecated'. It was then compared with
the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval

Key differences with the wiki page that Thomas wrote up vs patch 2
in this series

 - Deprecated features are given a fixed lifespan of 2 releases,
   rather than listing deletion at a future "major" v3.0.0 release. 
   This ensures that applications like libvirt have a predictable 
   fixed amount of time to react to deprecations.

 - Only lists features which are currently officially deprecated,
   no list of possible future candidates. The wiki page is probably
   a good place to maintain a list of future possible deprecations.
   To turn them into actual deprecations, a patch to the QEMU doc
   can then be posted & reviewed in the normal manner.

 - Not listing the '-6' and '-e' args to qemu-img create. Those
   were never deprecations, because the functionality was
   immediately turned into a fatal error. I sent a patch to
   just delete them straight away, as they've been unconditionlly
   broken for 7 years now which is enough :-) 

    https://lists.gnu.org/archive/html/qemu-devel/2017-07/msg00616.html

Changed in v3:

 - Rename appendix to "Deprecated features" (Markus)
 - List all currently deprecated features
 - Document that deprecated features will be removed after
   2 releases of being deprecated
 - Clarify that clock for removing historically deprecated
   features starts with the forthcoming release.

Changed in v2:

 - Split into 2 patches so we can consider each suggested addition
   independantly.

Daniel P. Berrange (2):
  docs: document support lifetime for features
  docs: document deprecated features in appendix

 qemu-doc.texi | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)

-- 
2.9.4

[Qemu-devel] [PATCH v3 1/2] docs: document support lifetime for features

[Daniel P. Berrange]

There is currently no explicit guidance on the duration of support
for features such as versioned machine types, which have a finite
useful lifespan. Thus apps / users cannot predict how much time
they might be able to use a feature for, before it is removed (if
ever).

This adds a new appendix that lists items which have finite lifecycles,
such as machine types. For items which are generally expected to be
supported indefinitely, it sets out the policy around deprecation
and removal, should it be needed.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
---
 qemu-doc.texi | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/qemu-doc.texi b/qemu-doc.texi
index 21079fd..27781e4 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -38,6 +38,7 @@
 * QEMU Guest Agent::
 * QEMU User space emulator::
 * Implementation notes::
+* Support lifetime::
 * License::
 * Index::
 @end menu
@@ -3017,6 +3018,42 @@ Run the emulation in single step mode.
 
 @include qemu-tech.texi
 
+@node Support lifetime
+@appendix Support lifetime
+
+In general features are intended to be supported indefinitely once
+introduced into QEMU.
+
+In the event that a feature needs to be removed, it will be listed
+in the ``Deprecated features'' appendix of this document. The feature
+will remain functional for 2 major releases prior to actual removal.
+
+Deprecated features may also generate warnings on the console when
+QEMU starts up, or if activated via a monitor command, however,
+this is not a mandatory requirement.
+
+Certain features have an inherently finite lifetime, and thus
+will be removed on a fixed schedule, without following the normal
+deprecation process. Such features are listed in the sections
+that follow.
+
+@node Machine types
+@section Machine types
+
+For architectures which aim to support live migration compatibility
+across releases, each release will introduce a new versioned machine
+type. For example, the 2.8.0 release introduced machine types
+``pc-i440fx-2.8'' and ``pc-q35-2.8' 'for the x86_64/i686 architectures.
+
+To allow live migration of a guest running on a 2.8.0 release to a
+2.9.0, the QEMU 2.9.0 version must support the ``pc-i440fx-2.8'' and
+``pc-q35-2.8''.  To allow users live migrating VMs to skip multiple
+intermediate releases when upgrading, new releases of QEMU will
+support machine types from many previous versions.
+
+The supported lifetime for versioned machine types is 12 releases,
+which is equivalent to 4 years worth of previous QEMU releases.
+
 @node License
 @appendix License
 
-- 
2.9.4

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

[Daniel P. Berrange]

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 <berrange@redhat.com>
---
 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.
 The supported lifetime for versioned machine types is 12 releases,
 which is equivalent to 4 years worth of previous QEMU releases.
 
+@node Deprecated features
+@appendix Deprecated features
+
+The following sections provide a list of all features currently
+marked as deprecated.
+
+Prior to the 2.10.0 release there was no official policy on how
+long features would be deprecated prior to their removal, nor
+any documented list of which features were deprecated. Thus
+any features deprecated prior to 2.10.0 will be treated as if
+they were first deprecated in the 2.10.0 release.
+
+@section System emulator command line arguments
+
+@subsection -drive boot=on|off (since 1.3.0)
+
+The ``boot=on|off'' option to the ``-drive'' argument is
+ignored. Applications should use the ``bootindex=N'' parameter
+to set an absolute ordering between devices instead.
+
+@subsection -tdf (since 1.3.0)
+
+The ``-tdf'' argument is ignored. The behaviour implemented
+by this argument is now the default when using the KVM PIT,
+but can be requested explicitly using
+``-global kvm-pit.lost_tick_policy=slew''.
+
+@subsection -no-kvm-pit-reinjection (since 1.3.0)
+
+The ``-no-kvm-pit-reinjection'' argument is now a
+synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
+
+@subsection -no-kvm-irqchip (since 1.3.0)
+
+The ``-no-kvm-irqchip'' argument is now a synonym for
+setting ``-machine kernel_irqchip=off''.
+
+@subsection -no-kvm-pit (since 1.3.0)
+
+The ``-no-kvm-pit'' argument is ignored. It is no longer
+possible to disable the KVM PIT directly.
+
+@subsection -no-kvm (since 1.3.0)
+
+The ``-no-kvm'' argument is now a synonym for setting
+``-machine accel=tcg''.
+
+@subsection -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. This logging facility has
+now been removed, so there is no need to mark a monitor
+as being the default.
+
+@subsection -vnc tls (since 2.5.0)
+
+The ``-vnc tls'' argument is now a synonym for setting
+``-object tls-creds-anon,id=tls0'' combined with
+``-vnc tls-creds=tls0'
+
+@subsection -vnc x509 (since 2.5.0)
+
+The ``-vnc x509=/path/to/certs'' argument is now a
+synonym for setting
+``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
+combined with ``-vnc tls-creds=tls0'
+
+@subsection -vnc x509verify (since 2.5.0)
+
+The ``-vnc x509verify=/path/to/certs'' argument is now a
+synonym for setting
+``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
+combined with ``-vnc tls-creds=tls0'
+
+@subsection -tftp (since 2.6.0)
+
+The ``-tftp /some/dir'' argument is now a synonym for setting
+the ``-netdev user,tftp=/some/dir' argument. The new syntax
+allows different settings to be provided per NIC.
+
+@subsection -bootp (since 2.6.0)
+
+The ``-bootp /some/file'' argument is now a synonym for setting
+the ``-netdev user,bootp=/some/file' argument. The new syntax
+allows different settings to be provided per NIC.
+
+@subsection -redir (since 2.6.0)
+
+The ``-redir ARGS'' argument is now a synonym for setting
+the ``-netdev user,hostfwd=ARGS'' argument instead. The new
+syntax allows different settings to be provided per NIC.
+
+@subsection -smb (since 2.6.0)
+
+The ``-smb /some/dir'' argument is now a synonym for setting
+the ``-netdev user,smb=/some/dir'' argument instead. The new
+syntax allows different settings to be provided per NIC.
+
+@subsection -net channel (since 2.6.0)
+
+The ``--net channel,ARGS'' argument is now a synonym for setting
+the ``-netdev user,guestfwd=ARGS'' argument instead.
+
+@subsection -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
+
+@subsection -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''.
+
+@subsection -net dump (since 2.10.0)
+
+The ``--net dump'' argument is now a synonym for setting the
+``-object filter-dump'' argument instead.
+
+@subsection -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.
+
+@subsection -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.
+
+@section qemu-img command line arguments
+
+@subsection convert -s (since 2.0.0)
+
+The ``convert -s snapshot_id_or_name'' argument is obsoleted
+by the ``convert -l snapshot_param'' argument instead.
+
+@section System emulator human monitor commands
+
+@subsection usb_add (since 2.10.0)
+
+The ``usb_add'' command is replaced by the ``device_add'' command.
+
+@subsection usb_del (since 2.10.0)
+
+The ``usb_del'' command is replaced by the ``device_del'' command.
+
+@section System emulator devices
+
+@subsection ivshmem (since 2.6.0)
+
+The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
+or ``ivshmem-doorbell`` device types.
+
+@subsection 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
 
-- 
2.9.4

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Peter Maydell]

On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
> This is a followup to
>
>   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
>   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.html
>
> The goal is to clarify to users & app developers what they can expect
> from QEMU in terms of feature lifecycle & any deprecation policy should
> it be neccessary to remove features.
>
> The list of features marked as deprecated was determined by looking at
> the QEMU source for the word "deprecated'. It was then compared with
> the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
>
> Key differences with the wiki page that Thomas wrote up vs patch 2
> in this series
>
>  - Deprecated features are given a fixed lifespan of 2 releases,
>    rather than listing deletion at a future "major" v3.0.0 release.
>    This ensures that applications like libvirt have a predictable
>    fixed amount of time to react to deprecations.

That's 8 months. Is that enough time for QEMU versions to get into
distros and out to users? (I don't necessarily think it's too short,
but it seems worth thinking about.)

thanks
-- PMM

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Daniel P. Berrange]

On Tue, Jul 04, 2017 at 01:00:54PM +0100, Peter Maydell wrote:
> On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
> > This is a followup to
> >
> >   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
> >   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.html
> >
> > The goal is to clarify to users & app developers what they can expect
> > from QEMU in terms of feature lifecycle & any deprecation policy should
> > it be neccessary to remove features.
> >
> > The list of features marked as deprecated was determined by looking at
> > the QEMU source for the word "deprecated'. It was then compared with
> > the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
> >
> > Key differences with the wiki page that Thomas wrote up vs patch 2
> > in this series
> >
> >  - Deprecated features are given a fixed lifespan of 2 releases,
> >    rather than listing deletion at a future "major" v3.0.0 release.
> >    This ensures that applications like libvirt have a predictable
> >    fixed amount of time to react to deprecations.
> 
> That's 8 months. Is that enough time for QEMU versions to get into
> distros and out to users? (I don't necessarily think it's too short,
> but it seems worth thinking about.)

If someone is consuming QEMU via a distro that releases every 6 months
(eg Fedora/Ubuntu), then by the time they see the deprcation message
there may not be much time left before feature deletion. On the flipside
they will not be suspectible to the feature deletion, until the next
major release of their distro, another 6 months after that. This does,
however, not provide much time for them to object to feature removal
to try to convince us to un-deprecate the feature.

If someone is consuming QEMU directly from upstream, it is hard to
answer, because they might rebase to newer QEMU frequently, or they
may stick on a release forever. People in the latter group though
would have a very long time before being impacted by any delation,
while people in the former group would see the deprecation reasonably
early.

If we publicise the deprecations in release notes, that gives a more
visible heads up to people than we've ever had in the past. So even
if they're not consuming new QEMU releases any time soon, they still
stand a chance of hearing about the planned feature removal and
planning ahead.

>From libvirt POV, we track QEMU activity quite closely and release
libvirt once a month, so that leaves libvirt developers 8 releases
in which to get a fix done to stop using the deprecated feature,
so I think that's acceptable for libvirt.


I think 2 releases is the minimum acceptable window of deprecation,
but I also wouldn't object if we wanted to make it 3 release, so
there's a nice clear "1 year" grace period before deletion. That
would make it slightly more likely that users of distros would
see the warning before the feature has actually been deleted.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Thomas Huth]

On 04.07.2017 13:14, Daniel P. Berrange wrote:
[...]
>  - Not listing the '-6' and '-e' args to qemu-img create. Those
>    were never deprecations, because the functionality was
>    immediately turned into a fatal error.
How did you come to that conclusion? As far as I can see, the -6 option
has been added by commit ec36ba14748e140dda2 and that was part of QEMU
v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
part of QEMU v0.14.

 Thomas

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Daniel P. Berrange]

On Tue, Jul 04, 2017 at 02:21:28PM +0200, Thomas Huth wrote:
> On 04.07.2017 13:14, Daniel P. Berrange wrote:
> [...]
> >  - Not listing the '-6' and '-e' args to qemu-img create. Those
> >    were never deprecations, because the functionality was
> >    immediately turned into a fatal error.
> How did you come to that conclusion? As far as I can see, the -6 option
> has been added by commit ec36ba14748e140dda2 and that was part of QEMU
> v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
> part of QEMU v0.14.

A 'deprecation' message implies that the functionality continues to
work, but the user gets a warning that its going away. In this case
the user gets a warning, and the functionality is unusable - qemu-img
just exits immediately. This isn't deprecation in any normal sense,
it is just immediate feature removal with an message telling you it
has already been deleted :-(

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Thomas Huth]

On 04.07.2017 14:27, Daniel P. Berrange wrote:
> On Tue, Jul 04, 2017 at 02:21:28PM +0200, Thomas Huth wrote:
>> On 04.07.2017 13:14, Daniel P. Berrange wrote:
>> [...]
>>>  - Not listing the '-6' and '-e' args to qemu-img create. Those
>>>    were never deprecations, because the functionality was
>>>    immediately turned into a fatal error.
>> How did you come to that conclusion? As far as I can see, the -6 option
>> has been added by commit ec36ba14748e140dda2 and that was part of QEMU
>> v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
>> part of QEMU v0.14.
> 
> A 'deprecation' message implies that the functionality continues to
> work, but the user gets a warning that its going away. In this case
> the user gets a warning, and the functionality is unusable - qemu-img
> just exits immediately. This isn't deprecation in any normal sense,
> it is just immediate feature removal with an message telling you it
> has already been deleted :-(

Ah, right, of course ... I somehow read your original sentence that the
functionality would have been added in one release cycle and also
removed again in the same cycle, that's why I was confused, but it makes
sense now. So yes, should be fine to remove this code immediately now.

 Thomas

Re: [Qemu-devel] [PATCH v3 1/2] docs: document support lifetime for features

[Thomas Huth]

On 04.07.2017 13:14, Daniel P. Berrange wrote:
> There is currently no explicit guidance on the duration of support
> for features such as versioned machine types, which have a finite
> useful lifespan. Thus apps / users cannot predict how much time
> they might be able to use a feature for, before it is removed (if
> ever).
> 
> This adds a new appendix that lists items which have finite lifecycles,
> such as machine types. For items which are generally expected to be
> supported indefinitely, it sets out the policy around deprecation
> and removal, should it be needed.

Great, thanks for tackling this!

> Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
> ---
>  qemu-doc.texi | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 21079fd..27781e4 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -38,6 +38,7 @@
>  * QEMU Guest Agent::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Support lifetime::
>  * License::
>  * Index::
>  @end menu
> @@ -3017,6 +3018,42 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> +@node Support lifetime
> +@appendix Support lifetime
> +
> +In general features are intended to be supported indefinitely once
> +introduced into QEMU.
> +
> +In the event that a feature needs to be removed, it will be listed
> +in the ``Deprecated features'' appendix of this document. The feature
> +will remain functional for 2 major releases prior to actual removal.

Maybe say "at least for two major releases" instead? Sometimes we might
forget to remove it in time, or we might decide to keep it alive a
little bit longer in case it was once an important feature...

> +Deprecated features may also generate warnings on the console when
> +QEMU starts up, or if activated via a monitor command, however,
> +this is not a mandatory requirement.
> +
> +Certain features have an inherently finite lifetime, and thus
> +will be removed on a fixed schedule, without following the normal
> +deprecation process. Such features are listed in the sections
> +that follow.
> +
> +@node Machine types
> +@section Machine types
> +
> +For architectures which aim to support live migration compatibility
> +across releases, each release will introduce a new versioned machine
> +type. For example, the 2.8.0 release introduced machine types
> +``pc-i440fx-2.8'' and ``pc-q35-2.8' 'for the x86_64/i686 architectures.

Space at wrong location --------------^

> +To allow live migration of a guest running on a 2.8.0 release to a
> +2.9.0, the QEMU 2.9.0 version must support the ``pc-i440fx-2.8'' and
> +``pc-q35-2.8''.  To allow users live migrating VMs to skip multiple
> +intermediate releases when upgrading, new releases of QEMU will
> +support machine types from many previous versions.
> +
> +The supported lifetime for versioned machine types is 12 releases,

Maybe rather "The minimum supported lifetime ..." ? In case we decide to
support it longer for any reasons...

 Thomas

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 <berrange@redhat.com>
> ---
>  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.
[...]
> +@subsection -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.

[...]
> +@subsection -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?

> +@subsection -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''.
> +
> +@subsection -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)

> +@subsection -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.
> +
> +@subsection -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.
> +
> +@section qemu-img command line arguments
> +
> +@subsection convert -s (since 2.0.0)
> +
> +The ``convert -s snapshot_id_or_name'' argument is obsoleted
> +by the ``convert -l snapshot_param'' argument instead.
> +
> +@section System emulator human monitor commands
> +
> +@subsection usb_add (since 2.10.0)
> +
> +The ``usb_add'' command is replaced by the ``device_add'' command.
> +
> +@subsection usb_del (since 2.10.0)
> +
> +The ``usb_del'' command is replaced by the ``device_del'' command.
> +
> +@section System emulator devices
> +
> +@subsection ivshmem (since 2.6.0)
> +
> +The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
> +or ``ivshmem-doorbell`` device types.
> +
> +@subsection 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

Re: [Qemu-devel] [PATCH v3 0/2] Document deprecated features & support lifecycle

[Thomas Huth]

On 04.07.2017 14:16, Daniel P. Berrange wrote:
> On Tue, Jul 04, 2017 at 01:00:54PM +0100, Peter Maydell wrote:
>> On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
>>> This is a followup to
>>>
>>>   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
>>>   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.html
>>>
>>> The goal is to clarify to users & app developers what they can expect
>>> from QEMU in terms of feature lifecycle & any deprecation policy should
>>> it be neccessary to remove features.
>>>
>>> The list of features marked as deprecated was determined by looking at
>>> the QEMU source for the word "deprecated'. It was then compared with
>>> the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
>>>
>>> Key differences with the wiki page that Thomas wrote up vs patch 2
>>> in this series
>>>
>>>  - Deprecated features are given a fixed lifespan of 2 releases,
>>>    rather than listing deletion at a future "major" v3.0.0 release.
>>>    This ensures that applications like libvirt have a predictable
>>>    fixed amount of time to react to deprecations.
>>
>> That's 8 months. Is that enough time for QEMU versions to get into
>> distros and out to users? (I don't necessarily think it's too short,
>> but it seems worth thinking about.)
[...]
> I think 2 releases is the minimum acceptable window of deprecation,
> but I also wouldn't object if we wanted to make it 3 release, so
> there's a nice clear "1 year" grace period before deletion. That
> would make it slightly more likely that users of distros would
> see the warning before the feature has actually been deleted.

Last time we discussed this, nobody insisted on 3 releases, so I think
we should start with 2 releases. If somebody complains later that this
is too short, we can still bump it to 3 releases instead.

 Thomas

Re: [Qemu-devel] [PATCH v3 1/2] docs: document support lifetime for features

[Daniel P. Berrange]

On Tue, Jul 04, 2017 at 02:43:29PM +0200, Thomas Huth wrote:
> On 04.07.2017 13:14, Daniel P. Berrange wrote:
> > There is currently no explicit guidance on the duration of support
> > for features such as versioned machine types, which have a finite
> > useful lifespan. Thus apps / users cannot predict how much time
> > they might be able to use a feature for, before it is removed (if
> > ever).
> > 
> > This adds a new appendix that lists items which have finite lifecycles,
> > such as machine types. For items which are generally expected to be
> > supported indefinitely, it sets out the policy around deprecation
> > and removal, should it be needed.
> 
> Great, thanks for tackling this!
> 
> > Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
> > ---
> >  qemu-doc.texi | 37 +++++++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> > 
> > diff --git a/qemu-doc.texi b/qemu-doc.texi
> > index 21079fd..27781e4 100644
> > --- a/qemu-doc.texi
> > +++ b/qemu-doc.texi
> > @@ -38,6 +38,7 @@
> >  * QEMU Guest Agent::
> >  * QEMU User space emulator::
> >  * Implementation notes::
> > +* Support lifetime::
> >  * License::
> >  * Index::
> >  @end menu
> > @@ -3017,6 +3018,42 @@ Run the emulation in single step mode.
> >  
> >  @include qemu-tech.texi
> >  
> > +@node Support lifetime
> > +@appendix Support lifetime
> > +
> > +In general features are intended to be supported indefinitely once
> > +introduced into QEMU.
> > +
> > +In the event that a feature needs to be removed, it will be listed
> > +in the ``Deprecated features'' appendix of this document. The feature
> > +will remain functional for 2 major releases prior to actual removal.
> 
> Maybe say "at least for two major releases" instead? Sometimes we might
> forget to remove it in time, or we might decide to keep it alive a
> little bit longer in case it was once an important feature...

FWIW, I explicitly avoided saying "at least" when I wrote this. I
want to make deletion of deprecated features a clearly defined process
where we don't have to re-open the debate of whether its ok to now
delete it. 


> > +Deprecated features may also generate warnings on the console when
> > +QEMU starts up, or if activated via a monitor command, however,
> > +this is not a mandatory requirement.
> > +
> > +Certain features have an inherently finite lifetime, and thus
> > +will be removed on a fixed schedule, without following the normal
> > +deprecation process. Such features are listed in the sections
> > +that follow.
> > +
> > +@node Machine types
> > +@section Machine types
> > +
> > +For architectures which aim to support live migration compatibility
> > +across releases, each release will introduce a new versioned machine
> > +type. For example, the 2.8.0 release introduced machine types
> > +``pc-i440fx-2.8'' and ``pc-q35-2.8' 'for the x86_64/i686 architectures.
> 
> Space at wrong location --------------^

Opps.

> 
> > +To allow live migration of a guest running on a 2.8.0 release to a
> > +2.9.0, the QEMU 2.9.0 version must support the ``pc-i440fx-2.8'' and
> > +``pc-q35-2.8''.  To allow users live migrating VMs to skip multiple
> > +intermediate releases when upgrading, new releases of QEMU will
> > +support machine types from many previous versions.
> > +
> > +The supported lifetime for versioned machine types is 12 releases,
> 
> Maybe rather "The minimum supported lifetime ..." ? In case we decide to
> support it longer for any reasons...

Same point as above - I feel its important to set a clear fixed timeframe
to avoid re-opening debate each time we come to delete something.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Daniel P. Berrange]

On Tue, Jul 04, 2017 at 02:59:27PM +0200, Thomas Huth wrote:
> 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 <berrange@redhat.com>
> > ---
> >  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.
> [...]
> > +@subsection -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.

Ah, right, I'll clarify it.

> [...]
> > +@subsection -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?

Yes

> 
> > +@subsection -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''.
> > +
> > +@subsection -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)

Oh, right, I misunderstood that


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|