From nobody Mon Apr 29 16:37:06 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1500028118184422.92236700024284; Fri, 14 Jul 2017 03:28:38 -0700 (PDT) Received: from localhost ([::1]:36792 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVxpt-0000Jc-1Y for importer@patchew.org; Fri, 14 Jul 2017 06:28:37 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:44230) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVxdk-0005Xf-0O for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dVxdi-0007J1-St for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:03 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46010) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dVxdi-0007Ik-JM for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:02 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 93C8183F43; Fri, 14 Jul 2017 10:16:01 +0000 (UTC) Received: from t460.redhat.com (ovpn-117-13.ams2.redhat.com [10.36.117.13]) by smtp.corp.redhat.com (Postfix) with ESMTP id 93F0170BA2; Fri, 14 Jul 2017 10:15:58 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 93C8183F43 Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=berrange@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 93C8183F43 From: "Daniel P. Berrange" To: qemu-devel@nongnu.org Date: Fri, 14 Jul 2017 11:15:48 +0100 Message-Id: <20170714101549.28665-2-berrange@redhat.com> In-Reply-To: <20170714101549.28665-1-berrange@redhat.com> References: <20170714101549.28665-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Fri, 14 Jul 2017 10:16:01 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v4 1/2] docs: document support lifetime for features X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Eduardo Habkost , Markus Armbruster , Stefan Hajnoczi , Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 --- qemu-doc.texi | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/qemu-doc.texi b/qemu-doc.texi index 48af5155c7..f067015d4b 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 @@ -3128,6 +3129,42 @@ Run the emulation in single step mode. =20 @include qemu-tech.texi =20 +@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 =20 --=20 2.13.0 From nobody Mon Apr 29 16:37:06 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1500027878805336.78617722591514; Fri, 14 Jul 2017 03:24:38 -0700 (PDT) Received: from localhost ([::1]:36768 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVxm1-0005Ec-Fq for importer@patchew.org; Fri, 14 Jul 2017 06:24:37 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:44276) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVxdo-0005bu-DF for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dVxdm-0007NZ-QQ for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:08 -0400 Received: from mx1.redhat.com ([209.132.183.28]:42384) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dVxdm-0007NL-Gd for qemu-devel@nongnu.org; Fri, 14 Jul 2017 06:16:06 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 81E4E8E92A; Fri, 14 Jul 2017 10:16:05 +0000 (UTC) Received: from t460.redhat.com (ovpn-117-13.ams2.redhat.com [10.36.117.13]) by smtp.corp.redhat.com (Postfix) with ESMTP id E08F770BB6; Fri, 14 Jul 2017 10:16:01 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 81E4E8E92A Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=berrange@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 81E4E8E92A From: "Daniel P. Berrange" To: qemu-devel@nongnu.org Date: Fri, 14 Jul 2017 11:15:49 +0100 Message-Id: <20170714101549.28665-3-berrange@redhat.com> In-Reply-To: <20170714101549.28665-1-berrange@redhat.com> References: <20170714101549.28665-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Fri, 14 Jul 2017 10:16:05 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v4 2/2] docs: document deprecated features in appendix X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Eduardo Habkost , Markus Armbruster , Stefan Hajnoczi , Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 --- qemu-doc.texi | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 168 insertions(+) diff --git a/qemu-doc.texi b/qemu-doc.texi index f067015d4b..c06cab26b7 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 @@ -3165,6 +3166,173 @@ 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. =20 +@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=3Don|off (since 1.3.0) + +The ``boot=3Don|off'' option to the ``-drive'' argument is +ignored. Applications should use the ``bootindex=3DN'' 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=3Dslew''. + +@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=3Ddiscard''. + +@subsection -no-kvm-irqchip (since 1.3.0) + +The ``-no-kvm-irqchip'' argument is now a synonym for +setting ``-machine kernel_irqchip=3Doff''. + +@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=3Dtcg''. + +@subsection -monitor default=3Don (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 various subsystems. This feature is no longer +required as messages are now only sent to the monitor +in response to explicitly monitor commands. + +@subsection -vnc tls (since 2.5.0) + +The ``-vnc tls'' argument is now a synonym for setting +``-object tls-creds-anon,id=3Dtls0'' combined with +``-vnc tls-creds=3Dtls0' + +@subsection -vnc x509 (since 2.5.0) + +The ``-vnc x509=3D/path/to/certs'' argument is now a +synonym for setting +``-object tls-creds-x509,dir=3D/path/to/certs,id=3Dtls0,verify-peer=3Dno'' +combined with ``-vnc tls-creds=3Dtls0' + +@subsection -vnc x509verify (since 2.5.0) + +The ``-vnc x509verify=3D/path/to/certs'' argument is now a +synonym for setting +``-object tls-creds-x509,dir=3D/path/to/certs,id=3Dtls0,verify-peer=3Dyes'' +combined with ``-vnc tls-creds=3Dtls0' + +@subsection -tftp (since 2.6.0) + +The ``-tftp /some/dir'' argument is now a synonym for setting +the ``-netdev user,tftp=3D/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=3D/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=3DARGS'' 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=3D/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=3DARGS'' argument instead. + +@subsection -net vlan (since 2.9.0) + +The ``-net van=3DNN'' argument is partially replaced with the +new ``-netdev'' argument. The remaining use cases will no +longer be directly supported in QEMU. + +@subsection -drive if=3Dscsi (since 2.9.0) + +The ``-drive if=3Dscsi'' argument is replaced by the the +``-device BUS-TYPE'' argument combined with ``-drive if=3Dnone''. + +@subsection -net dump (since 2.10.0) + +The ``--net dump'' argument is now replaced with the +``-object filter-dump'' argument which works in combination +with the modern ``-netdev`` backends 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=3Don'' 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 =20 --=20 2.13.0