[PATCH 0/4] docs: Miscellaneous rST conversions

[PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

This patchset converts some texi files used in qemu-doc.texi to rST:

 * docs/security.texi
 * qemu-tech.texi
 * qemu-deprecated.texi

which all end up as sections of the "system" manual.

In all cases, these pieces of the documentation are part of
the qemu-doc HTML file, but not included in the qemu.1 manpage,
so they are just a straightforward format conversion.

security and deprecated are pure conversions with only
changes to the formatting, not to the contents.

For qemu-tech.texi, a large part of it was an extremely out of
date and partial attempt to document the limitations of our
CPU emulation. Apart from a change to the Xtensa section in
2012, no part of the actual text seems to have been updated
since 2008. I judged it better to simply dump this rather
than carry it over. Creating an actually accurate section
about the limitations of the various guest architectures
is probably easier done from scratch if we want it and are
prepared to actually keep it up to date this time...

thanks
-- PMM

Peter Maydell (4):
  docs: Convert security.texi to rST format
  docs: Remove the "CPU emulation" part of the "Implementation notes"
  docs: Convert 'managed start up options' docs to rST
  docs: Convert qemu-deprecated.texi to rST

 Makefile                                    |   6 +-
 MAINTAINERS                                 |   2 +-
 docs/system/deprecated.rst                  | 446 ++++++++++++++++++++
 docs/system/index.rst                       |   3 +
 docs/system/managed-startup.rst             |  35 ++
 docs/{security.texi => system/security.rst} |  82 ++--
 qemu-deprecated.texi                        | 386 -----------------
 qemu-doc.texi                               |  10 -
 qemu-tech.texi                              | 195 ---------
 9 files changed, 532 insertions(+), 633 deletions(-)
 create mode 100644 docs/system/deprecated.rst
 create mode 100644 docs/system/managed-startup.rst
 rename docs/{security.texi => system/security.rst} (77%)
 delete mode 100644 qemu-deprecated.texi
 delete mode 100644 qemu-tech.texi

-- 
2.20.1

[PATCH 1/4] docs: Convert security.texi to rST format

[Peter Maydell]

security.texi is included from qemu-doc.texi but is not used
in the qemu.1 manpage. So we can do a straightforward conversion
of the contents, which go into the system manual.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                                    |  2 +-
 docs/system/index.rst                       |  1 +
 docs/{security.texi => system/security.rst} | 82 +++++++++++----------
 qemu-doc.texi                               |  3 -
 4 files changed, 46 insertions(+), 42 deletions(-)
 rename docs/{security.texi => system/security.rst} (77%)

diff --git a/Makefile b/Makefile
index aa9cc0b5847..5f0f803b471 100644
--- a/Makefile
+++ b/Makefile
@@ -1117,7 +1117,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
 	qemu-tech.texi qemu-option-trace.texi \
 	qemu-deprecated.texi qemu-monitor.texi \
 	qemu-monitor-info.texi \
-	docs/qemu-cpu-models.texi docs/security.texi
+	docs/qemu-cpu-models.texi
 
 docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
     docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
diff --git a/docs/system/index.rst b/docs/system/index.rst
index f66e6ea585c..794e5d8de03 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -15,3 +15,4 @@ Contents:
    :maxdepth: 2
 
    qemu-block-drivers
+   security
diff --git a/docs/security.texi b/docs/system/security.rst
similarity index 77%
rename from docs/security.texi
rename to docs/system/security.rst
index 0d6b30edfc0..f2092c8768b 100644
--- a/docs/security.texi
+++ b/docs/system/security.rst
@@ -1,19 +1,22 @@
-@node Security
-@chapter Security
+Security
+========
 
-@section Overview
+Overview
+--------
 
 This chapter explains the security requirements that QEMU is designed to meet
 and principles for securely deploying QEMU.
 
-@section Security Requirements
+Security Requirements
+---------------------
 
 QEMU supports many different use cases, some of which have stricter security
 requirements than others.  The community has agreed on the overall security
 requirements that users may depend on.  These requirements define what is
 considered supported from a security perspective.
 
-@subsection Virtualization Use Case
+Virtualization Use Case
+'''''''''''''''''''''''
 
 The virtualization use case covers cloud and virtual private server (VPS)
 hosting, as well as traditional data center and desktop virtualization.  These
@@ -23,18 +26,17 @@ safely on the physical CPU at close-to-native speed.
 The following entities are untrusted, meaning that they may be buggy or
 malicious:
 
-@itemize
-@item Guest
-@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
-@item Network protocols (e.g. NBD, live migration)
-@item User-supplied files (e.g. disk images, kernels, device trees)
-@item Passthrough devices (e.g. PCI, USB)
-@end itemize
+- Guest
+- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
+- Network protocols (e.g. NBD, live migration)
+- User-supplied files (e.g. disk images, kernels, device trees)
+- Passthrough devices (e.g. PCI, USB)
 
 Bugs affecting these entities are evaluated on whether they can cause damage in
 real-world use cases and treated as security bugs if this is the case.
 
-@subsection Non-virtualization Use Case
+Non-virtualization Use Case
+'''''''''''''''''''''''''''
 
 The non-virtualization use case covers emulation using the Tiny Code Generator
 (TCG).  In principle the TCG and device emulation code used in conjunction with
@@ -47,12 +49,14 @@ Bugs affecting the non-virtualization use case are not considered security
 bugs at this time.  Users with non-virtualization use cases must not rely on
 QEMU to provide guest isolation or any security guarantees.
 
-@section Architecture
+Architecture
+------------
 
 This section describes the design principles that ensure the security
 requirements are met.
 
-@subsection Guest Isolation
+Guest Isolation
+'''''''''''''''
 
 Guest isolation is the confinement of guest code to the virtual machine.  When
 guest code gains control of execution on the host this is called escaping the
@@ -71,7 +75,8 @@ malicious guest must not gain control of other guests or access their data.
 Disk image files and network traffic must be protected from other guests unless
 explicitly shared between them by the user.
 
-@subsection Principle of Least Privilege
+Principle of Least Privilege
+''''''''''''''''''''''''''''
 
 The principle of least privilege states that each component only has access to
 the privileges necessary for its function.  In the case of QEMU this means that
@@ -84,7 +89,7 @@ the guest.
 
 Following the principle of least privilege immediately fulfills guest isolation
 requirements.  For example, guest A only has access to its own disk image file
-@code{a.img} and not guest B's disk image file @code{b.img}.
+``a.img`` and not guest B's disk image file ``b.img``.
 
 In reality certain resources are inaccessible to the guest but must be
 available to QEMU to perform its function.  For example, host system calls are
@@ -95,7 +100,8 @@ New features must be designed to follow the principle of least privilege.
 Should this not be possible for technical reasons, the security risk must be
 clearly documented so users are aware of the trade-off of enabling the feature.
 
-@subsection Isolation mechanisms
+Isolation mechanisms
+''''''''''''''''''''
 
 Several isolation mechanisms are available to realize this architecture of
 guest isolation and the principle of least privilege.  With the exception of
@@ -105,46 +111,46 @@ described briefly for Linux here.
 
 The fundamental isolation mechanism is that QEMU processes must run as
 unprivileged users.  Sometimes it seems more convenient to launch QEMU as
-root to give it access to host devices (e.g. @code{/dev/net/tun}) but this poses a
+root to give it access to host devices (e.g. ``/dev/net/tun``) but this poses a
 huge security risk.  File descriptor passing can be used to give an otherwise
 unprivileged QEMU process access to host devices without running QEMU as root.
 It is also possible to launch QEMU as a non-root user and configure UNIX groups
-for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes.
+for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
 Some Linux distros already ship with UNIX groups for these devices by default.
 
-@itemize
-@item SELinux and AppArmor make it possible to confine processes beyond the
-traditional UNIX process and file permissions model.  They restrict the QEMU
-process from accessing processes and files on the host system that are not
-needed by QEMU.
+- SELinux and AppArmor make it possible to confine processes beyond the
+  traditional UNIX process and file permissions model.  They restrict the QEMU
+  process from accessing processes and files on the host system that are not
+  needed by QEMU.
 
-@item Resource limits and cgroup controllers provide throughput and utilization
-limits on key resources such as CPU time, memory, and I/O bandwidth.
+- Resource limits and cgroup controllers provide throughput and utilization
+  limits on key resources such as CPU time, memory, and I/O bandwidth.
 
-@item Linux namespaces can be used to make process, file system, and other system
-resources unavailable to QEMU.  A namespaced QEMU process is restricted to only
-those resources that were granted to it.
+- Linux namespaces can be used to make process, file system, and other system
+  resources unavailable to QEMU.  A namespaced QEMU process is restricted to only
+  those resources that were granted to it.
 
-@item Linux seccomp is available via the QEMU @option{--sandbox} option.  It disables
-system calls that are not needed by QEMU, thereby reducing the host kernel
-attack surface.
-@end itemize
+- Linux seccomp is available via the QEMU ``--sandbox`` option.  It disables
+  system calls that are not needed by QEMU, thereby reducing the host kernel
+  attack surface.
 
-@section Sensitive configurations
+Sensitive configurations
+------------------------
 
 There are aspects of QEMU that can have security implications which users &
 management applications must be aware of.
 
-@subsection Monitor console (QMP and HMP)
+Monitor console (QMP and HMP)
+'''''''''''''''''''''''''''''
 
 The monitor console (whether used with QMP or HMP) provides an interface
 to dynamically control many aspects of QEMU's runtime operation. Many of the
 commands exposed will instruct QEMU to access content on the host file system
 and/or trigger spawning of external processes.
 
-For example, the @code{migrate} command allows for the spawning of arbitrary
+For example, the ``migrate`` command allows for the spawning of arbitrary
 processes for the purpose of tunnelling the migration data stream. The
-@code{blockdev-add} command instructs QEMU to open arbitrary files, exposing
+``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
 their content to the guest as a virtual disk.
 
 Unless QEMU is otherwise confined using technologies such as SELinux, AppArmor,
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 33b9597b1dc..c11b1a5d5ad 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -40,7 +40,6 @@
 * QEMU System emulator for non PC targets::
 * QEMU User space emulator::
 * System requirements::
-* Security::
 * Implementation notes::
 * Deprecated features::
 * Recently removed features::
@@ -2836,8 +2835,6 @@ added with Linux 4.5 which is supported by the major distros. And even
 if RHEL7 has kernel 3.10, KVM there has the required functionality there
 to make it close to a 4.5 or newer kernel.
 
-@include docs/security.texi
-
 @include qemu-tech.texi
 
 @include qemu-deprecated.texi
-- 
2.20.1

[PATCH 2/4] docs: Remove the "CPU emulation" part of the "Implementation notes"

[Peter Maydell]

The "CPU emulation" part of the "Implementation notes" in
qemu-tech.texi looks like it is documenting what features of various
CPUs we do or don't emulate.  However:
 * it covers only six of our 21 guest architectures
 * the last time anybody updated it for actual content was in
   2011/2012 for Xtensa; the content for the other five
   architectures is even older, being from 2008 or before!

What we have is out of date, misleading and incomplete.
Just delete this part of the document rather than trying to
convert it to rST.

(It would be nice eventually to have documentation of the
scope and limitations of our emulation; but we will want to
separate out the generic "system emulation" information from
the parts that are specific to linux-user anyway, as they will
be in different manuals.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 qemu-tech.texi | 153 -------------------------------------------------
 1 file changed, 153 deletions(-)

diff --git a/qemu-tech.texi b/qemu-tech.texi
index 0380de77b62..35da6a40af1 100644
--- a/qemu-tech.texi
+++ b/qemu-tech.texi
@@ -2,162 +2,9 @@
 @appendix Implementation notes
 
 @menu
-* CPU emulation::
 * Managed start up options::
 @end menu
 
-@node CPU emulation
-@section CPU emulation
-
-@menu
-* x86::     x86 and x86-64 emulation
-* ARM::     ARM emulation
-* MIPS::    MIPS emulation
-* PPC::     PowerPC emulation
-* SPARC::   Sparc32 and Sparc64 emulation
-* Xtensa::  Xtensa emulation
-@end menu
-
-@node x86
-@subsection x86 and x86-64 emulation
-
-QEMU x86 target features:
-
-@itemize
-
-@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
-LDT/GDT and IDT are emulated. VM86 mode is also supported to run
-DOSEMU. There is some support for MMX/3DNow!, SSE, SSE2, SSE3, SSSE3,
-and SSE4 as well as x86-64 SVM.
-
-@item Support of host page sizes bigger than 4KB in user mode emulation.
-
-@item QEMU can emulate itself on x86.
-
-@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
-It can be used to test other x86 virtual CPUs.
-
-@end itemize
-
-Current QEMU limitations:
-
-@itemize
-
-@item Limited x86-64 support.
-
-@item IPC syscalls are missing.
-
-@item The x86 segment limits and access rights are not tested at every
-memory access (yet). Hopefully, very few OSes seem to rely on that for
-normal use.
-
-@end itemize
-
-@node ARM
-@subsection ARM emulation
-
-@itemize
-
-@item Full ARM 7 user emulation.
-
-@item NWFPE FPU support included in user Linux emulation.
-
-@item Can run most ARM Linux binaries.
-
-@end itemize
-
-@node MIPS
-@subsection MIPS emulation
-
-@itemize
-
-@item The system emulation allows full MIPS32/MIPS64 Release 2 emulation,
-including privileged instructions, FPU and MMU, in both little and big
-endian modes.
-
-@item The Linux userland emulation can run many 32 bit MIPS Linux binaries.
-
-@end itemize
-
-Current QEMU limitations:
-
-@itemize
-
-@item Self-modifying code is not always handled correctly.
-
-@item 64 bit userland emulation is not implemented.
-
-@item The system emulation is not complete enough to run real firmware.
-
-@item The watchpoint debug facility is not implemented.
-
-@end itemize
-
-@node PPC
-@subsection PowerPC emulation
-
-@itemize
-
-@item Full PowerPC 32 bit emulation, including privileged instructions,
-FPU and MMU.
-
-@item Can run most PowerPC Linux binaries.
-
-@end itemize
-
-@node SPARC
-@subsection Sparc32 and Sparc64 emulation
-
-@itemize
-
-@item Full SPARC V8 emulation, including privileged
-instructions, FPU and MMU. SPARC V9 emulation includes most privileged
-and VIS instructions, FPU and I/D MMU. Alignment is fully enforced.
-
-@item Can run most 32-bit SPARC Linux binaries, SPARC32PLUS Linux binaries and
-some 64-bit SPARC Linux binaries.
-
-@end itemize
-
-Current QEMU limitations:
-
-@itemize
-
-@item IPC syscalls are missing.
-
-@item Floating point exception support is buggy.
-
-@item Atomic instructions are not correctly implemented.
-
-@item There are still some problems with Sparc64 emulators.
-
-@end itemize
-
-@node Xtensa
-@subsection Xtensa emulation
-
-@itemize
-
-@item Core Xtensa ISA emulation, including most options: code density,
-loop, extended L32R, 16- and 32-bit multiplication, 32-bit division,
-MAC16, miscellaneous operations, boolean, FP coprocessor, coprocessor
-context, debug, multiprocessor synchronization,
-conditional store, exceptions, relocatable vectors, unaligned exception,
-interrupts (including high priority and timer), hardware alignment,
-region protection, region translation, MMU, windowed registers, thread
-pointer, processor ID.
-
-@item Not implemented options: data/instruction cache (including cache
-prefetch and locking), XLMI, processor interface. Also options not
-covered by the core ISA (e.g. FLIX, wide branches) are not implemented.
-
-@item Can run most Xtensa Linux binaries.
-
-@item New core configuration that requires no additional instructions
-may be created from overlay with minimal amount of hand-written code.
-
-@end itemize
-
 @node Managed start up options
 @section Managed start up options
 
-- 
2.20.1

[PATCH 3/4] docs: Convert 'managed start up options' docs to rST

[Peter Maydell]

The only remaining content in qemu-tech.texi is a few paragraphs
about managed start up options; move them to a new rST document
in the system manual.

In the process we fix one typo and format more option and
command names as literal text, but make no significant
changes to the content.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                        |  2 +-
 docs/system/index.rst           |  1 +
 docs/system/managed-startup.rst | 35 +++++++++++++++++++++++++++
 qemu-doc.texi                   |  3 ---
 qemu-tech.texi                  | 42 ---------------------------------
 5 files changed, 37 insertions(+), 46 deletions(-)
 create mode 100644 docs/system/managed-startup.rst
 delete mode 100644 qemu-tech.texi

diff --git a/Makefile b/Makefile
index 5f0f803b471..28749d20401 100644
--- a/Makefile
+++ b/Makefile
@@ -1114,7 +1114,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
 
 qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
 	qemu-options.texi \
-	qemu-tech.texi qemu-option-trace.texi \
+	qemu-option-trace.texi \
 	qemu-deprecated.texi qemu-monitor.texi \
 	qemu-monitor-info.texi \
 	docs/qemu-cpu-models.texi
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 794e5d8de03..887bef92f40 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -14,5 +14,6 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   managed-startup
    qemu-block-drivers
    security
diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.rst
new file mode 100644
index 00000000000..9bcf98ea790
--- /dev/null
+++ b/docs/system/managed-startup.rst
@@ -0,0 +1,35 @@
+Managed start up options
+========================
+
+In system mode emulation, it's possible to create a VM in a paused
+state using the ``-S`` command line option. In this state the machine
+is completely initialized according to command line options and ready
+to execute VM code but VCPU threads are not executing any code. The VM
+state in this paused state depends on the way QEMU was started. It
+could be in:
+
+- initial state (after reset/power on state)
+- with direct kernel loading, the initial state could be amended to execute
+  code loaded by QEMU in the VM's RAM and with incoming migration
+- with incoming migration, initial state will be amended with the migrated
+  machine state after migration completes
+
+This paused state is typically used by users to query machine state and/or
+additionally configure the machine (by hotplugging devices) in runtime before
+allowing VM code to run.
+
+However, at the ``-S`` pause point, it's impossible to configure options
+that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or
+cold plug devices. The experimental ``--preconfig`` command line option
+allows pausing QEMU before the initial VM creation, in a "preconfig" state,
+where additional queries and configuration can be performed via QMP
+before moving on to the resulting configuration startup. In the
+preconfig state, QEMU only allows a limited set of commands over the
+QMP monitor, where the commands do not depend on an initialized
+machine, including but not limited to:
+
+- ``qmp_capabilities``
+- ``query-qmp-schema``
+- ``query-commands``
+- ``query-status``
+- ``x-exit-preconfig``
diff --git a/qemu-doc.texi b/qemu-doc.texi
index c11b1a5d5ad..7798e072a1c 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -40,7 +40,6 @@
 * QEMU System emulator for non PC targets::
 * QEMU User space emulator::
 * System requirements::
-* Implementation notes::
 * Deprecated features::
 * Recently removed features::
 * Supported build platforms::
@@ -2835,8 +2834,6 @@ added with Linux 4.5 which is supported by the major distros. And even
 if RHEL7 has kernel 3.10, KVM there has the required functionality there
 to make it close to a 4.5 or newer kernel.
 
-@include qemu-tech.texi
-
 @include qemu-deprecated.texi
 
 @node Supported build platforms
diff --git a/qemu-tech.texi b/qemu-tech.texi
deleted file mode 100644
index 35da6a40af1..00000000000
--- a/qemu-tech.texi
+++ /dev/null
@@ -1,42 +0,0 @@
-@node Implementation notes
-@appendix Implementation notes
-
-@menu
-* Managed start up options::
-@end menu
-
-@node Managed start up options
-@section Managed start up options
-
-In system mode emulation, it's possible to create a VM in a paused state using
-the -S command line option. In this state the machine is completely initialized
-according to command line options and ready to execute VM code but VCPU threads
-are not executing any code. The VM state in this paused state depends on the way
-QEMU was started. It could be in:
-@table @asis
-@item initial state (after reset/power on state)
-@item with direct kernel loading, the initial state could be amended to execute
-code loaded by QEMU in the VM's RAM and with incoming migration
-@item with incoming migration, initial state will by amended with the migrated
-machine state after migration completes.
-@end table
-
-This paused state is typically used by users to query machine state and/or
-additionally configure the machine (by hotplugging devices) in runtime before
-allowing VM code to run.
-
-However, at the -S pause point, it's impossible to configure options that affect
-initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The
-experimental --preconfig command line option  allows pausing QEMU
-before the initial VM creation, in a ``preconfig'' state, where additional
-queries and configuration can be performed via QMP before moving on to
-the resulting configuration startup. In the preconfig state, QEMU only allows
-a limited set of commands over the QMP monitor, where the commands do not
-depend on an initialized machine, including but not limited to:
-@table @asis
-@item qmp_capabilities
-@item query-qmp-schema
-@item query-commands
-@item query-status
-@item x-exit-preconfig
-@end table
-- 
2.20.1

[PATCH 4/4] docs: Convert qemu-deprecated.texi to rST

[Peter Maydell]

Convert the documentation of deprecated features to rST.

We put the whole of this document into the system manual, though
technically a few parts of it apply to qemu-img or qemu-nbd which are
otherwise documented in tools/.

We only make formatting fixes, except for one use of 'appendix' which
we change to 'section' because this isn't an appendix in the Sphinx
manual.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                   |   2 +-
 MAINTAINERS                |   2 +-
 docs/system/deprecated.rst | 446 +++++++++++++++++++++++++++++++++++++
 docs/system/index.rst      |   1 +
 qemu-deprecated.texi       | 386 --------------------------------
 qemu-doc.texi              |   4 -
 6 files changed, 449 insertions(+), 392 deletions(-)
 create mode 100644 docs/system/deprecated.rst
 delete mode 100644 qemu-deprecated.texi

diff --git a/Makefile b/Makefile
index 28749d20401..ec4a4be8355 100644
--- a/Makefile
+++ b/Makefile
@@ -1115,7 +1115,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
 qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
 	qemu-options.texi \
 	qemu-option-trace.texi \
-	qemu-deprecated.texi qemu-monitor.texi \
+	qemu-monitor.texi \
 	qemu-monitor-info.texi \
 	docs/qemu-cpu-models.texi
 
diff --git a/MAINTAINERS b/MAINTAINERS
index 195dd58cac1..546f2b83017 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2787,7 +2787,7 @@ F: contrib/gitdm/*
 
 Incompatible changes
 R: libvir-list@redhat.com
-F: qemu-deprecated.texi
+F: docs/system/deprecated.rst
 
 Build System
 ------------
diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
new file mode 100644
index 00000000000..1eaa559079b
--- /dev/null
+++ b/docs/system/deprecated.rst
@@ -0,0 +1,446 @@
+Deprecated features
+===================
+
+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 this section. The feature will remain functional
+for 2 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.
+
+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.
+
+What follows is a list of all features currently marked as
+deprecated.
+
+System emulator command line arguments
+--------------------------------------
+
+``-machine enforce-config-section=on|off`` (since 3.1)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``enforce-config-section`` parameter is replaced by the
+``-global migration.send-configuration={on|off}`` option.
+
+``-no-kvm`` (since 1.3.0)
+'''''''''''''''''''''''''
+
+The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
+
+``-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.
+
+``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The 'file' driver for drives is no longer appropriate for character or host
+devices and will only accept regular files (S_IFREG). The correct driver
+for these file types is 'host_cdrom' or 'host_device' as appropriate.
+
+``-net ...,name=``\ *name* (since 3.1)
+''''''''''''''''''''''''''''''''''''''
+
+The ``name`` parameter of the ``-net`` option is a synonym
+for the ``id`` parameter, which should now be used instead.
+
+``-smp`` (invalid topologies) (since 3.1)
+'''''''''''''''''''''''''''''''''''''''''
+
+CPU topology properties should describe whole machine topology including
+possible CPUs.
+
+However, historically it was possible to start QEMU with an incorrect topology
+where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
+which could lead to an incorrect topology enumeration by the guest.
+Support for invalid topologies will be removed, the user must ensure
+topologies described with -smp include all possible cpus, i.e.
+*sockets* * *cores* * *threads* = *maxcpus*.
+
+``-vnc acl`` (since 4.0.0)
+''''''''''''''''''''''''''
+
+The ``acl`` option to the ``-vnc`` argument has been replaced
+by the ``tls-authz`` and ``sasl-authz`` options.
+
+``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``-audiodev`` argument is now the preferred way to specify audio
+backend settings instead of environment variables.  To ease migration to
+the new format, the ``-audiodev-help`` option can be used to convert
+the current values of the environment variables to ``-audiodev`` options.
+
+Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+When not using the deprecated legacy audio config, each sound card
+should specify an ``audiodev=`` property.  Additionally, when using
+vnc, you should specify an ``audiodev=`` propery if you plan to
+transmit audio through the VNC protocol.
+
+``-mon ...,control=readline,pretty=on|off`` (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``pretty=on|off`` switch has no effect for HMP monitors, but is
+silently ignored. Using the switch with HMP monitors will become an
+error in the future.
+
+``-realtime`` (since 4.1)
+'''''''''''''''''''''''''
+
+The ``-realtime mlock=on|off`` argument has been replaced by the
+``-overcommit mem-lock=on|off`` argument.
+
+``-numa node,mem=``\ *size* (since 4.1)
+'''''''''''''''''''''''''''''''''''''''
+
+The parameter ``mem`` of ``-numa node`` is used to assign a part of
+guest RAM to a NUMA node. But when using it, it's impossible to manage specified
+RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
+so guest end-ups with the fake NUMA configuration with suboptiomal performance.
+However since 2014 there is an alternative way to assign RAM to a NUMA node
+using parameter ``memdev``, which does the same as ``mem`` and adds
+means to actualy manage node RAM on the host side. Use parameter ``memdev``
+with *memory-backend-ram* backend as an replacement for parameter ``mem``
+to achieve the same fake NUMA effect or a properly configured
+*memory-backend-file* backend to actually benefit from NUMA configuration.
+In future new machine versions will not accept the option but it will still
+work with old machine types. User can check QAPI schema to see if the legacy
+option is supported by looking at MachineInfo::numa-mem-supported property.
+
+``-numa`` node (without memory specified) (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Splitting RAM by default between NUMA nodes has the same issues as ``mem``
+parameter described above with the difference that the role of the user plays
+QEMU using implicit generic or board specific splitting rule.
+Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
+it's supported by used machine type) to define mapping explictly instead.
+
+``-mem-path`` fallback to RAM (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''
+
+Currently if guest RAM allocation from file pointed by ``mem-path``
+fails, QEMU falls back to allocating from RAM, which might result
+in unpredictable behavior since the backing file specified by the user
+is ignored. In the future, users will be responsible for making sure
+the backing storage specified with ``-mem-path`` can actually provide
+the guest RAM configured with ``-m`` and QEMU will fail to start up if
+RAM allocation is unsuccessful.
+
+RISC-V ``-bios`` (since 4.1)
+''''''''''''''''''''''''''''
+
+QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
+RISC-V virt machine and sifive_u machine.
+
+QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
+default will change in a future QEMU release, so please prepare now. All users
+of the virt or sifive_u machine must change their command line usage.
+
+QEMU 4.1 has three options, please migrate to one of these three:
+ 1. ``-bios none`` - This is the current default behavior if no -bios option
+      is included. QEMU will not automatically load any firmware. It is up
+      to the user to load all the images they need.
+ 2. ``-bios default`` - In a future QEMU release this will become the default
+      behaviour if no -bios option is specified. This option will load the
+      default OpenSBI firmware automatically. The firmware is included with
+      the QEMU release and no user interaction is required. All a user needs
+      to do is specify the kernel they want to boot with the -kernel option
+ 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
+
+``-tb-size`` option (since 5.0)
+'''''''''''''''''''''''''''''''
+
+QEMU 5.0 introduced an alternative syntax to specify the size of the translation
+block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
+previously available ``-tb-size`` option.
+
+``-show-cursor`` option (since 5.0)
+'''''''''''''''''''''''''''''''''''
+
+Use ``-display sdl,show-cursor=on`` or
+ ``-display gtk,show-cursor=on`` instead.
+
+QEMU Machine Protocol (QMP) commands
+------------------------------------
+
+``change`` (since 2.5.0)
+''''''''''''''''''''''''
+
+Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
+
+``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``migrate-set-parameters`` instead.
+
+``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
+
+``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
+the query-block command is deprecated. Two new boolean fields,
+``recording`` and ``busy`` effectively replace it.
+
+``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
+the query-block command is itself now deprecated. The ``dirty-bitmaps``
+field of the ``BlockDeviceInfo`` struct should be used instead, which is the
+type of the ``inserted`` field in query-block replies, as well as the
+type of array items in query-named-block-nodes.
+
+Since the ``dirty-bitmaps`` field is optionally present in both the old and
+new locations, clients must use introspection to learn where to anticipate
+the field if/when it does appear in command output.
+
+``query-cpus`` (since 2.12.0)
+'''''''''''''''''''''''''''''
+
+The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
+
+``query-cpus-fast`` ``arch`` output member (since 3.0.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``arch`` output member of the ``query-cpus-fast`` command is
+replaced by the ``target`` output member.
+
+``cpu-add`` (since 4.0)
+'''''''''''''''''''''''
+
+Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
+documentation of ``query-hotpluggable-cpus`` for additional
+details.
+
+``query-events`` (since 4.0)
+''''''''''''''''''''''''''''
+
+The ``query-events`` command has been superseded by the more powerful
+and accurate ``query-qmp-schema`` command.
+
+chardev client socket with ``wait`` option (since 4.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Character devices creating sockets in client mode should not specify
+the 'wait' field, which is only applicable to sockets in server mode
+
+Human Monitor Protocol (HMP) commands
+-------------------------------------
+
+The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
+'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
+
+``cpu-add`` (since 4.0)
+'''''''''''''''''''''''
+
+Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
+documentation of ``query-hotpluggable-cpus`` for additional details.
+
+``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
+``acl_remove`` commands are deprecated with no replacement. Authorization
+for VNC should be performed using the pluggable QAuthZ objects.
+
+Guest Emulator ISAs
+-------------------
+
+RISC-V ISA privledge specification version 1.09.1 (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
+QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
+should be used instead of the 1.09.1 version.
+
+System emulator CPUS
+--------------------
+
+RISC-V ISA CPUs (since 4.1)
+'''''''''''''''''''''''''''
+
+The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
+four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
+``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
+option when using the ``rv32`` or ``rv64`` CPUs.
+
+RISC-V ISA CPUs (since 4.1)
+'''''''''''''''''''''''''''
+
+The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
+``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
+via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
+
+System emulator devices
+-----------------------
+
+``ide-drive`` (since 4.2)
+'''''''''''''''''''''''''
+
+The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
+'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
+
+``scsi-disk`` (since 4.2)
+'''''''''''''''''''''''''
+
+The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
+'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
+
+System emulator machines
+------------------------
+
+mips ``r4k`` platform (since 5.0)
+'''''''''''''''''''''''''''''''''
+
+This machine type is very old and unmaintained. Users should use the ``malta``
+machine type instead.
+
+``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+These machine types are very old and likely can not be used for live migration
+from old QEMU versions anymore. A newer machine type should be used instead.
+
+``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+The version specific Spike machines have been deprecated in favour of the
+generic ``spike`` machine. If you need to specify an older version of the RISC-V
+spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
+
+Device options
+--------------
+
+Emulated device options
+'''''''''''''''''''''''
+
+``-device virtio-blk,scsi=on|off`` (since 5.0.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
+and later do not support it because the virtio-scsi device was introduced for
+full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
+
+Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
+alias.
+
+Block device options
+''''''''''''''''''''
+
+``"backing": ""`` (since 2.12.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to prevent QEMU from automatically opening an image's backing
+chain, use ``"backing": null`` instead.
+
+``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Options for ``rbd`` should be specified according to its runtime options,
+like other block drivers.  Legacy parsing of keyvalue pair encoded
+filenames is useful to open images with the old format for backing files;
+These image files should be updated to use the current format.
+
+Example of legacy encoding::
+
+  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
+
+The above, converted to the current supported format::
+
+  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
+
+Related binaries
+----------------
+
+``qemu-img convert -n -o`` (since 4.2.0)
+''''''''''''''''''''''''''''''''''''''''
+
+All options specified in ``-o`` are image creation options, so
+they have no effect when used with ``-n`` to skip image creation.
+Silently ignored options can be confusing, so this combination of
+options will be made an error in future versions.
+
+Backwards compatibility
+-----------------------
+
+Runnability guarantee of CPU models (since 4.1.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+Previous versions of QEMU never changed existing CPU models in
+ways that introduced additional host software or hardware
+requirements to the VM.  This allowed management software to
+safely change the machine type of an existing VM without
+introducing new requirements ("runnability guarantee").  This
+prevented CPU models from being updated to include CPU
+vulnerability mitigations, leaving guests vulnerable in the
+default configuration.
+
+The CPU model runnability guarantee won't apply anymore to
+existing CPU models.  Management software that needs runnability
+guarantees must resolve the CPU model aliases using te
+``alias-of`` field returned by the ``query-cpu-definitions`` QMP
+command.
+
+While those guarantees are kept, the return value of
+``query-cpu-definitions`` will have existing CPU model aliases
+point to a version that doesn't break runnability guarantees
+(specifically, version 1 of those CPU models).  In future QEMU
+versions, aliases will point to newer CPU model versions
+depending on the machine type, so management software must
+resolve CPU model aliases before starting a virtual machine.
+
+
+Recently removed features
+=========================
+
+What follows is a record of recently removed, formerly deprecated
+features that serves as a record for users who have encountered
+trouble after a recent upgrade.
+
+QEMU Machine Protocol (QMP) commands
+------------------------------------
+
+``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The "autoload" parameter has been ignored since 2.12.0. All bitmaps
+are automatically loaded from qcow2 images.
+
+Related binaries
+----------------
+
+``qemu-nbd --partition`` (removed in 5.0.0)
+'''''''''''''''''''''''''''''''''''''''''''
+
+The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
+could only handle MBR partitions, and never correctly handled logical
+partitions beyond partition 5.  Exporting a partition can still be
+done by utilizing the ``--image-opts`` option with a raw blockdev
+using the ``offset`` and ``size`` parameters layered on top of
+any other existing blockdev. For example, if partition 1 is 100MiB
+long starting at 1MiB, the old command::
+
+  qemu-nbd -t -P 1 -f qcow2 file.qcow2
+
+can be rewritten as::
+
+  qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 887bef92f40..7d09abca954 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -14,6 +14,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   deprecated
    managed-startup
    qemu-block-drivers
    security
diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
deleted file mode 100644
index 0671c26c806..00000000000
--- a/qemu-deprecated.texi
+++ /dev/null
@@ -1,386 +0,0 @@
-@node Deprecated features
-@appendix Deprecated features
-
-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 this appendix. The feature will remain functional
-for 2 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.
-
-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.
-
-What follows is a list of all features currently marked as
-deprecated.
-
-@section System emulator command line arguments
-
-@subsection -machine enforce-config-section=on|off (since 3.1)
-
-The @option{enforce-config-section} parameter is replaced by the
-@option{-global migration.send-configuration=@var{on|off}} option.
-
-@subsection -no-kvm (since 1.3.0)
-
-The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''.
-
-@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.
-
-@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
-
-The 'file' driver for drives is no longer appropriate for character or host
-devices and will only accept regular files (S_IFREG). The correct driver
-for these file types is 'host_cdrom' or 'host_device' as appropriate.
-
-@subsection -net ...,name=@var{name} (since 3.1)
-
-The @option{name} parameter of the @option{-net} option is a synonym
-for the @option{id} parameter, which should now be used instead.
-
-@subsection -smp (invalid topologies) (since 3.1)
-
-CPU topology properties should describe whole machine topology including
-possible CPUs.
-
-However, historically it was possible to start QEMU with an incorrect topology
-where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}},
-which could lead to an incorrect topology enumeration by the guest.
-Support for invalid topologies will be removed, the user must ensure
-topologies described with -smp include all possible cpus, i.e.
-  @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
-
-@subsection -vnc acl (since 4.0.0)
-
-The @code{acl} option to the @code{-vnc} argument has been replaced
-by the @code{tls-authz} and @code{sasl-authz} options.
-
-@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
-
-The ``-audiodev'' argument is now the preferred way to specify audio
-backend settings instead of environment variables.  To ease migration to
-the new format, the ``-audiodev-help'' option can be used to convert
-the current values of the environment variables to ``-audiodev'' options.
-
-@subsection Creating sound card devices and vnc without audiodev= property (since 4.2)
-
-When not using the deprecated legacy audio config, each sound card
-should specify an @code{audiodev=} property.  Additionally, when using
-vnc, you should specify an @code{audiodev=} propery if you plan to
-transmit audio through the VNC protocol.
-
-@subsection -mon ...,control=readline,pretty=on|off (since 4.1)
-
-The @code{pretty=on|off} switch has no effect for HMP monitors, but is
-silently ignored. Using the switch with HMP monitors will become an
-error in the future.
-
-@subsection -realtime (since 4.1)
-
-The @code{-realtime mlock=on|off} argument has been replaced by the
-@code{-overcommit mem-lock=on|off} argument.
-
-@subsection -numa node,mem=@var{size} (since 4.1)
-
-The parameter @option{mem} of @option{-numa node} is used to assign a part of
-guest RAM to a NUMA node. But when using it, it's impossible to manage specified
-RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
-so guest end-ups with the fake NUMA configuration with suboptiomal performance.
-However since 2014 there is an alternative way to assign RAM to a NUMA node
-using parameter @option{memdev}, which does the same as @option{mem} and adds
-means to actualy manage node RAM on the host side. Use parameter @option{memdev}
-with @var{memory-backend-ram} backend as an replacement for parameter @option{mem}
-to achieve the same fake NUMA effect or a properly configured
-@var{memory-backend-file} backend to actually benefit from NUMA configuration.
-In future new machine versions will not accept the option but it will still
-work with old machine types. User can check QAPI schema to see if the legacy
-option is supported by looking at MachineInfo::numa-mem-supported property.
-
-@subsection -numa node (without memory specified) (since 4.1)
-
-Splitting RAM by default between NUMA nodes has the same issues as @option{mem}
-parameter described above with the difference that the role of the user plays
-QEMU using implicit generic or board specific splitting rule.
-Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if
-it's supported by used machine type) to define mapping explictly instead.
-
-@subsection -mem-path fallback to RAM (since 4.1)
-Currently if guest RAM allocation from file pointed by @option{mem-path}
-fails, QEMU falls back to allocating from RAM, which might result
-in unpredictable behavior since the backing file specified by the user
-is ignored. In the future, users will be responsible for making sure
-the backing storage specified with @option{-mem-path} can actually provide
-the guest RAM configured with @option{-m} and QEMU will fail to start up if
-RAM allocation is unsuccessful.
-
-@subsection RISC-V -bios (since 4.1)
-
-QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
-RISC-V virt machine and sifive_u machine.
-
-QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
-default will change in a future QEMU release, so please prepare now. All users
-of the virt or sifive_u machine must change their command line usage.
-
-QEMU 4.1 has three options, please migrate to one of these three:
- 1. ``-bios none`` - This is the current default behavior if no -bios option
-      is included. QEMU will not automatically load any firmware. It is up
-      to the user to load all the images they need.
- 2. ``-bios default`` - In a future QEMU release this will become the default
-      behaviour if no -bios option is specified. This option will load the
-      default OpenSBI firmware automatically. The firmware is included with
-      the QEMU release and no user interaction is required. All a user needs
-      to do is specify the kernel they want to boot with the -kernel option
- 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
-
-@subsection -tb-size option (since 5.0)
-
-QEMU 5.0 introduced an alternative syntax to specify the size of the translation
-block cache, @option{-accel tcg,tb-size=}.  The new syntax deprecates the
-previously available @option{-tb-size} option.
-
-@subsection -show-cursor option (since 5.0)
-
-Use @option{-display sdl,show-cursor=on} or
- @option{-display gtk,show-cursor=on} instead.
-
-@section QEMU Machine Protocol (QMP) commands
-
-@subsection change (since 2.5.0)
-
-Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
-
-@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
-
-Use ``migrate-set-parameters'' instead.
-
-@subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
-
-Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
-
-@subsection query-block result field dirty-bitmaps[i].status (since 4.0)
-
-The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
-the query-block command is deprecated. Two new boolean fields,
-``recording'' and ``busy'' effectively replace it.
-
-@subsection query-block result field dirty-bitmaps (Since 4.2)
-
-The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
-the query-block command is itself now deprecated. The ``dirty-bitmaps``
-field of the ``BlockDeviceInfo`` struct should be used instead, which is the
-type of the ``inserted`` field in query-block replies, as well as the
-type of array items in query-named-block-nodes.
-
-Since the ``dirty-bitmaps`` field is optionally present in both the old and
-new locations, clients must use introspection to learn where to anticipate
-the field if/when it does appear in command output.
-
-@subsection query-cpus (since 2.12.0)
-
-The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
-
-@subsection query-cpus-fast "arch" output member (since 3.0.0)
-
-The ``arch'' output member of the ``query-cpus-fast'' command is
-replaced by the ``target'' output member.
-
-@subsection cpu-add (since 4.0)
-
-Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
-documentation of ``query-hotpluggable-cpus'' for additional
-details.
-
-@subsection query-events (since 4.0)
-
-The ``query-events'' command has been superseded by the more powerful
-and accurate ``query-qmp-schema'' command.
-
-@subsection chardev client socket with 'wait' option (since 4.0)
-
-Character devices creating sockets in client mode should not specify
-the 'wait' field, which is only applicable to sockets in server mode
-
-@section Human Monitor Protocol (HMP) commands
-
-@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
-
-The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
-'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
-
-@subsection cpu-add (since 4.0)
-
-Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
-documentation of ``query-hotpluggable-cpus'' for additional details.
-
-@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
-
-The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
-``acl_remove'' commands are deprecated with no replacement. Authorization
-for VNC should be performed using the pluggable QAuthZ objects.
-
-@section Guest Emulator ISAs
-
-@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
-
-The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
-QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
-should be used instead of the 1.09.1 version.
-
-@section System emulator CPUS
-
-@subsection RISC-V ISA CPUs (since 4.1)
-
-The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
-four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
-``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
-option when using the ``rv32`` or ``rv64`` CPUs.
-
-@subsection RISC-V ISA CPUs (since 4.1)
-
-The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
-``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
-via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
-
-@section System emulator devices
-
-@subsection ide-drive (since 4.2)
-
-The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
-'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
-
-@subsection scsi-disk (since 4.2)
-
-The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
-'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
-
-@section System emulator machines
-
-@subsection mips r4k platform (since 5.0)
-
-This machine type is very old and unmaintained. Users should use the 'malta'
-machine type instead.
-
-@subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
-
-These machine types are very old and likely can not be used for live migration
-from old QEMU versions anymore. A newer machine type should be used instead.
-
-@subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
-
-The version specific Spike machines have been deprecated in favour of the
-generic ``spike`` machine. If you need to specify an older version of the RISC-V
-spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
-
-@section Device options
-
-@subsection Emulated device options
-
-@subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
-
-The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
-and later do not support it because the virtio-scsi device was introduced for
-full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
-
-Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an
-alias.
-
-@subsection Block device options
-
-@subsubsection "backing": "" (since 2.12.0)
-
-In order to prevent QEMU from automatically opening an image's backing
-chain, use ``"backing": null'' instead.
-
-@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
-
-Options for ``rbd'' should be specified according to its runtime options,
-like other block drivers.  Legacy parsing of keyvalue pair encoded
-filenames is useful to open images with the old format for backing files;
-These image files should be updated to use the current format.
-
-Example of legacy encoding:
-
-@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
-
-The above, converted to the current supported format:
-
-@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
-
-@section Related binaries
-
-@subsection qemu-img convert -n -o (since 4.2.0)
-
-All options specified in @option{-o} are image creation options, so
-they have no effect when used with @option{-n} to skip image creation.
-Silently ignored options can be confusing, so this combination of
-options will be made an error in future versions.
-
-@section Backwards compatibility
-
-@subsection Runnability guarantee of CPU models (since 4.1.0)
-
-Previous versions of QEMU never changed existing CPU models in
-ways that introduced additional host software or hardware
-requirements to the VM.  This allowed management software to
-safely change the machine type of an existing VM without
-introducing new requirements ("runnability guarantee").  This
-prevented CPU models from being updated to include CPU
-vulnerability mitigations, leaving guests vulnerable in the
-default configuration.
-
-The CPU model runnability guarantee won't apply anymore to
-existing CPU models.  Management software that needs runnability
-guarantees must resolve the CPU model aliases using te
-``alias-of'' field returned by the ``query-cpu-definitions'' QMP
-command.
-
-While those guarantees are kept, the return value of
-``query-cpu-definitions'' will have existing CPU model aliases
-point to a version that doesn't break runnability guarantees
-(specifically, version 1 of those CPU models).  In future QEMU
-versions, aliases will point to newer CPU model versions
-depending on the machine type, so management software must
-resolve CPU model aliases before starting a virtual machine.
-
-
-@node Recently removed features
-@appendix Recently removed features
-
-What follows is a record of recently removed, formerly deprecated
-features that serves as a record for users who have encountered
-trouble after a recent upgrade.
-
-@section QEMU Machine Protocol (QMP) commands
-
-@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
-
-The "autoload" parameter has been ignored since 2.12.0. All bitmaps
-are automatically loaded from qcow2 images.
-
-@section Related binaries
-
-@subsection qemu-nbd --partition (removed in 5.0.0)
-
-The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
-could only handle MBR partitions, and never correctly handled logical
-partitions beyond partition 5.  Exporting a partition can still be
-done by utilizing the @option{--image-opts} option with a raw blockdev
-using the @code{offset} and @code{size} parameters layered on top of
-any other existing blockdev. For example, if partition 1 is 100MiB
-long starting at 1MiB, the old command:
-
-@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
-
-can be rewritten as:
-
-@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2}
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 7798e072a1c..6bb1fd54c03 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -40,8 +40,6 @@
 * QEMU System emulator for non PC targets::
 * QEMU User space emulator::
 * System requirements::
-* Deprecated features::
-* Recently removed features::
 * Supported build platforms::
 * License::
 * Index::
@@ -2834,8 +2832,6 @@ added with Linux 4.5 which is supported by the major distros. And even
 if RHEL7 has kernel 3.10, KVM there has the required functionality there
 to make it close to a 4.5 or newer kernel.
 
-@include qemu-deprecated.texi
-
 @node Supported build platforms
 @appendix Supported build platforms
 
-- 
2.20.1

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini]

On 25/02/20 16:41, Peter Maydell wrote:
> This patchset converts some texi files used in qemu-doc.texi to rST:
> 
>  * docs/security.texi
>  * qemu-tech.texi
>  * qemu-deprecated.texi
> 
> which all end up as sections of the "system" manual.
> 
> In all cases, these pieces of the documentation are part of
> the qemu-doc HTML file, but not included in the qemu.1 manpage,
> so they are just a straightforward format conversion.
> 
> security and deprecated are pure conversions with only
> changes to the formatting, not to the contents.
> 
> For qemu-tech.texi, a large part of it was an extremely out of
> date and partial attempt to document the limitations of our
> CPU emulation. Apart from a change to the Xtensa section in
> 2012, no part of the actual text seems to have been updated
> since 2008. I judged it better to simply dump this rather
> than carry it over. Creating an actually accurate section
> about the limitations of the various guest architectures
> is probably easier done from scratch if we want it and are
> prepared to actually keep it up to date this time...

I assume these are not meant to be applied now, except patch 2?
For what it's worth, security.texi can be converted just fine with:

makeinfo -o - --docbook security.texi  | pandoc -f docbook -t rst

Paolo

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Tue, 25 Feb 2020 at 17:01, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 25/02/20 16:41, Peter Maydell wrote:
> > This patchset converts some texi files used in qemu-doc.texi to rST:
> >
> >  * docs/security.texi
> >  * qemu-tech.texi
> >  * qemu-deprecated.texi
> >
> > which all end up as sections of the "system" manual.
> >
> > In all cases, these pieces of the documentation are part of
> > the qemu-doc HTML file, but not included in the qemu.1 manpage,
> > so they are just a straightforward format conversion.
> >
> > security and deprecated are pure conversions with only
> > changes to the formatting, not to the contents.
> >
> > For qemu-tech.texi, a large part of it was an extremely out of
> > date and partial attempt to document the limitations of our
> > CPU emulation. Apart from a change to the Xtensa section in
> > 2012, no part of the actual text seems to have been updated
> > since 2008. I judged it better to simply dump this rather
> > than carry it over. Creating an actually accurate section
> > about the limitations of the various guest architectures
> > is probably easier done from scratch if we want it and are
> > prepared to actually keep it up to date this time...
>
> I assume these are not meant to be applied now, except patch 2?

No, I intended them to be reviewable and applied now. Why
do you think we should wait?

thanks
-- PMM

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini]

On 25/02/20 18:11, Peter Maydell wrote:
>> I assume these are not meant to be applied now, except patch 2?
> No, I intended them to be reviewable and applied now. Why
> do you think we should wait?

Because they remove information from qemu-doc.texi.  I think it's
feasible to do a mass conversion quite soon, within a single pull
request, the only important part that is missing is the hxtool conversion.

(See also the patches I posted today, which take the opposite direction
of making qemu-doc.texi's structure more like what we'll have in the end
in docs/system).

Paolo

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Tue, 25 Feb 2020 at 17:48, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 25/02/20 18:11, Peter Maydell wrote:
> >> I assume these are not meant to be applied now, except patch 2?
> > No, I intended them to be reviewable and applied now. Why
> > do you think we should wait?
>
> Because they remove information from qemu-doc.texi.  I think it's
> feasible to do a mass conversion quite soon, within a single pull
> request, the only important part that is missing is the hxtool conversion.

My assumption was that we would attack this by:
 * converting chunks of the documentation which are in qemu-doc.texi
   but which aren't in the qemu.1 manpage (basically in the way this
   series is doing)
 * get the qapidoc generation conversion reviewed and into
   master (since at the moment it outputs into files included
   from qemu-doc)
 * convert the manpage parts; we have the machinery for dealing
   with the hxtool files, it just needs a little more work

> (See also the patches I posted today, which take the opposite direction
> of making qemu-doc.texi's structure more like what we'll have in the end
> in docs/system).

This ought to make it easier to do the conversion of the
various subparts, right?

Incidentally:
> makeinfo -o - --docbook security.texi  | pandoc -f docbook -t rst

security texi was the really easy one here. I had to do more
manual formatting fixups on qemu-deprecated.texi which I'm
sceptical would have worked out as nicely done automatically.

The automatic conversion rune also doesn't seem to get quotes
and apostrophes right: it has turned "guest B's disk image" into
something with a smartquote character in it, for instance.

thanks
-- PMM

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini]

On 25/02/20 18:59, Peter Maydell wrote:
> My assumption was that we would attack this by:
>  * converting chunks of the documentation which are in qemu-doc.texi
>    but which aren't in the qemu.1 manpage (basically in the way this
>    series is doing)
>  * get the qapidoc generation conversion reviewed and into
>    master (since at the moment it outputs into files included
>    from qemu-doc)

The QAPI docs are in other manuals in docs/interop/, aren't they?

>  * convert the manpage parts; we have the machinery for dealing
>    with the hxtool files, it just needs a little more work
>
>> (See also the patches I posted today, which take the opposite direction
>> of making qemu-doc.texi's structure more like what we'll have in the end
>> in docs/system).
> 
> This ought to make it easier to do the conversion of the
> various subparts, right?

Right, and easier to review as well; I called it "the opposite
direction" because the editing is done in Texinfo format and the rST
conversion becomes relatively trivial.  This would make it possible to
do the conversion in a branch and pull it all at once (apart from
qapidoc and possibly other small changes like removing obsolete parts).

> Incidentally:
>> makeinfo -o - --docbook security.texi  | pandoc -f docbook -t rst
> security texi was the really easy one here. I had to do more
> manual formatting fixups on qemu-deprecated.texi which I'm
> sceptical would have worked out as nicely done automatically.

The automated conversion of qemu-deprecated.texi is indeed bad because
the titles in the source are missing @code{...} to activate monospaced
characters.

> The automatic conversion rune also doesn't seem to get quotes
> and apostrophes right: it has turned "guest B's disk image" into
> something with a smartquote character in it, for instance.

We probably don't want smartquotes at all, so you'd use "-t rst+smart"
as the destination.  Also pandoc does not use the "::" at the end of the
previous paragraph.  That can be fixed with for example

  perl -e '$/=undef; $_ = <>; s/:\n\n::/::/g; print'

In general the result is more than acceptable, and I'd rather get a
quick-and-slightly-dirty conversion done quickly than do everything
manually but risk missing 5.0.

Paolo

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Tue, 25 Feb 2020 at 18:28, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 25/02/20 18:59, Peter Maydell wrote:
> > My assumption was that we would attack this by:
> >  * converting chunks of the documentation which are in qemu-doc.texi
> >    but which aren't in the qemu.1 manpage (basically in the way this
> >    series is doing)
> >  * get the qapidoc generation conversion reviewed and into
> >    master (since at the moment it outputs into files included
> >    from qemu-doc)
>
> The QAPI docs are in other manuals in docs/interop/, aren't they?

Yes, but until we complete the conversion we can't get
rid of the qemu-doc.html output, because that's where the
HTML output from the QAPI doc generation goes.

> > Incidentally:
> >> makeinfo -o - --docbook security.texi  | pandoc -f docbook -t rst
> > security texi was the really easy one here. I had to do more
> > manual formatting fixups on qemu-deprecated.texi which I'm
> > sceptical would have worked out as nicely done automatically.
>
> The automated conversion of qemu-deprecated.texi is indeed bad because
> the titles in the source are missing @code{...} to activate monospaced
> characters.

To be fair on the automated conversion, the markup in the
source texinfo here is suboptimal :-)

> > The automatic conversion rune also doesn't seem to get quotes
> > and apostrophes right: it has turned "guest B's disk image" into
> > something with a smartquote character in it, for instance.
>
> We probably don't want smartquotes at all, so you'd use "-t rst+smart"
> as the destination.  Also pandoc does not use the "::" at the end of the
> previous paragraph.  That can be fixed with for example
>
>   perl -e '$/=undef; $_ = <>; s/:\n\n::/::/g; print'
>
> In general the result is more than acceptable, and I'd rather get a
> quick-and-slightly-dirty conversion done quickly than do everything
> manually but risk missing 5.0.

Yeah, seems like a good plan. If the autoconversion works out
then I think the main thing which makes "do all this for 5.0"
at risk currently is that the qapidoc conversion series needs
review and might need overhauling based on that review: it
doesn't take many cycles of review-and-fix to push close to
the softfreeze deadline.

What do you want to do with this patchset?

thanks
-- PMM

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini]

[-- Attachment #1: Type: text/plain, Size: 1257 bytes --]

Il mar 25 feb 2020, 19:57 Peter Maydell <peter.maydell@linaro.org> ha
scritto:

> > The QAPI docs are in other manuals in docs/interop/, aren't they?
>
> Yes, but until we complete the conversion we can't get
> rid of the qemu-doc.html output, because that's where the
> HTML output from the QAPI doc generation goes.
>

Right.

> In general the result is more than acceptable, and I'd rather get a
> > quick-and-slightly-dirty conversion done quickly than do everything
> > manually but risk missing 5.0.
>
> Yeah, seems like a good plan. If the autoconversion works out
> then I think the main thing which makes "do all this for 5.0"
> at risk currently is that the qapidoc conversion series needs
> review and might need overhauling based on that review: it
> doesn't take many cycles of review-and-fix to push close to
> the softfreeze deadline.
>
> What do you want to do with this patchset?
>

This could go in independently. It would make Kashyap's series conflict,
but I have already rebased it on top.

Perhaps we could have the files in both .texi and (automatically converted)
.rst versions at the same time in the tree for a short period. If that's
okay for you, I can post tomorrow a series to do that.

Paolo

[-- Attachment #2: Type: text/html, Size: 2018 bytes --]

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Tue, 25 Feb 2020 at 19:10, Paolo Bonzini <pbonzini@redhat.com> wrote:
> This could go in independently. It would make Kashyap's series
> conflict, but I have already rebased it on top.

I'm happy to collect up 'docs' patches for pullreqs (and fix up
conflicts etc as they arise) if that helps in getting things into
the tree.

I feel like we're working a bit at cross purposes here so maybe
we'd benefit from just nailing down who's going to do what and
in which order?

My current thought on ordering is something like:
 * commit this
 * commit Kashyap's series
 * commit (an adjusted version of) your split-out-the-texi series
 * (automated) conversion of more texi -- all in one series I guess ?
 * ???
 * profit

but I'm not very strongly attached to that.

> Perhaps we could have the files in both .texi and (automatically
> converted) .rst versions at the same time in the tree for a short
> period. If that's okay for you, I can post tomorrow a series to do that.

My instinct is to say that that's a bit dangerous as it means
we might end up with changes to the "wrong" version of the
two files. Would it let us do the conversion faster or
more conveniently ?

thanks
-- PMM

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini]

[-- Attachment #1: Type: text/plain, Size: 1773 bytes --]

Il mar 25 feb 2020, 20:50 Peter Maydell <peter.maydell@linaro.org> ha
scritto:

> On Tue, 25 Feb 2020 at 19:10, Paolo Bonzini <pbonzini@redhat.com> wrote:
> I feel like we're working a bit at cross purposes here so maybe
> we'd benefit from just nailing down who's going to do what and
> in which order?
>

I am not going to do much more than what I posted today, basically only the
automated conversion.

>
> My current thought on ordering is something like:
>  * commit this
>  * commit Kashyap's series
>  * commit (an adjusted version of) your split-out-the-texi series
>  * (automated) conversion of more texi -- all in one series I guess ?
>  * ???
>  * profit
>
> but I'm not very strongly attached to that.
>

The main issue with this series and Kashyap's is that if we don't manage to
get everything done in 5.0 we have a mutilated qemu-doc. Then either we
keep it mutilated or we scramble to undo the work. So I would agree to
commit the series in this order, but without the removal of the .texi files.

> Perhaps we could have the files in both .texi and (automatically
> > converted) .rst versions at the same time in the tree for a short
> > period. If that's okay for you, I can post tomorrow a series to do that.
>
> My instinct is to say that that's a bit dangerous as it means
> we might end up with changes to the "wrong" version of the
> two files. Would it let us do the conversion faster or
> more conveniently ?
>

It would be a kind of "insurance" against being late, basically. Doc
changes are rare enough that we could manage it, I think (and as long as
code review catches changes to only one version of the docs, no bitrot is
possible since we would build both).

Paolo


> thanks
> -- PMM
>
>

[-- Attachment #2: Type: text/html, Size: 2967 bytes --]

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Tue, 25 Feb 2020 at 20:10, Paolo Bonzini <pbonzini@redhat.com> wrote:
> The main issue with this series and Kashyap's is that if we don't manage to get
> everything done in 5.0 we have a mutilated qemu-doc. Then either we keep it
> mutilated or we scramble to undo the work. So I would agree to commit the
> series in this order, but without the removal of the .texi files.

Kashyap's set is in the same ballpark as what we've currently
converted (notably it's pretty much equivalent to the qemu-block-drivers
conversion in that it takes what was part of qemu-doc plus a manpage
and turns it into part of the system manual plus a manpage).
It's also the most awkward to try to keep the texi around for, because
the makefile runes for the texi want to generate the manpage too.
So I think I would argue for taking that as-is, including removal of the
texi files.

I agree that it would be good to avoid a half-converted qemu-doc;
if people think keeping two parallel doc files until we're sure we
can do the conversion is useful insurance I'm happy to go along
with that.

If we ended up with "we managed all the conversion except for
the qapi json doc comments parts" would we be ok with having a
qemu-doc.html that just contained those, and all the actual docs
transitioning to rST for this release? Or would we want to roll
back the rST for the main qemu-doc parts too in that situation?

thanks
-- PMM

Re: [PATCH 4/4] docs: Convert qemu-deprecated.texi to rST

[Alistair Francis]

On Tue, Feb 25, 2020 at 7:41 AM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Convert the documentation of deprecated features to rST.
>
> We put the whole of this document into the system manual, though
> technically a few parts of it apply to qemu-img or qemu-nbd which are
> otherwise documented in tools/.
>
> We only make formatting fixes, except for one use of 'appendix' which
> we change to 'section' because this isn't an appendix in the Sphinx
> manual.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

Alistair

> ---
>  Makefile                   |   2 +-
>  MAINTAINERS                |   2 +-
>  docs/system/deprecated.rst | 446 +++++++++++++++++++++++++++++++++++++
>  docs/system/index.rst      |   1 +
>  qemu-deprecated.texi       | 386 --------------------------------
>  qemu-doc.texi              |   4 -
>  6 files changed, 449 insertions(+), 392 deletions(-)
>  create mode 100644 docs/system/deprecated.rst
>  delete mode 100644 qemu-deprecated.texi
>
> diff --git a/Makefile b/Makefile
> index 28749d20401..ec4a4be8355 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1115,7 +1115,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
>  qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
>         qemu-options.texi \
>         qemu-option-trace.texi \
> -       qemu-deprecated.texi qemu-monitor.texi \
> +       qemu-monitor.texi \
>         qemu-monitor-info.texi \
>         docs/qemu-cpu-models.texi
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 195dd58cac1..546f2b83017 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2787,7 +2787,7 @@ F: contrib/gitdm/*
>
>  Incompatible changes
>  R: libvir-list@redhat.com
> -F: qemu-deprecated.texi
> +F: docs/system/deprecated.rst
>
>  Build System
>  ------------
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> new file mode 100644
> index 00000000000..1eaa559079b
> --- /dev/null
> +++ b/docs/system/deprecated.rst
> @@ -0,0 +1,446 @@
> +Deprecated features
> +===================
> +
> +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 this section. The feature will remain functional
> +for 2 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.
> +
> +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.
> +
> +What follows is a list of all features currently marked as
> +deprecated.
> +
> +System emulator command line arguments
> +--------------------------------------
> +
> +``-machine enforce-config-section=on|off`` (since 3.1)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``enforce-config-section`` parameter is replaced by the
> +``-global migration.send-configuration={on|off}`` option.
> +
> +``-no-kvm`` (since 1.3.0)
> +'''''''''''''''''''''''''
> +
> +The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
> +
> +``-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.
> +
> +``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The 'file' driver for drives is no longer appropriate for character or host
> +devices and will only accept regular files (S_IFREG). The correct driver
> +for these file types is 'host_cdrom' or 'host_device' as appropriate.
> +
> +``-net ...,name=``\ *name* (since 3.1)
> +''''''''''''''''''''''''''''''''''''''
> +
> +The ``name`` parameter of the ``-net`` option is a synonym
> +for the ``id`` parameter, which should now be used instead.
> +
> +``-smp`` (invalid topologies) (since 3.1)
> +'''''''''''''''''''''''''''''''''''''''''
> +
> +CPU topology properties should describe whole machine topology including
> +possible CPUs.
> +
> +However, historically it was possible to start QEMU with an incorrect topology
> +where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
> +which could lead to an incorrect topology enumeration by the guest.
> +Support for invalid topologies will be removed, the user must ensure
> +topologies described with -smp include all possible cpus, i.e.
> +*sockets* * *cores* * *threads* = *maxcpus*.
> +
> +``-vnc acl`` (since 4.0.0)
> +''''''''''''''''''''''''''
> +
> +The ``acl`` option to the ``-vnc`` argument has been replaced
> +by the ``tls-authz`` and ``sasl-authz`` options.
> +
> +``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``-audiodev`` argument is now the preferred way to specify audio
> +backend settings instead of environment variables.  To ease migration to
> +the new format, the ``-audiodev-help`` option can be used to convert
> +the current values of the environment variables to ``-audiodev`` options.
> +
> +Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +When not using the deprecated legacy audio config, each sound card
> +should specify an ``audiodev=`` property.  Additionally, when using
> +vnc, you should specify an ``audiodev=`` propery if you plan to
> +transmit audio through the VNC protocol.
> +
> +``-mon ...,control=readline,pretty=on|off`` (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``pretty=on|off`` switch has no effect for HMP monitors, but is
> +silently ignored. Using the switch with HMP monitors will become an
> +error in the future.
> +
> +``-realtime`` (since 4.1)
> +'''''''''''''''''''''''''
> +
> +The ``-realtime mlock=on|off`` argument has been replaced by the
> +``-overcommit mem-lock=on|off`` argument.
> +
> +``-numa node,mem=``\ *size* (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''
> +
> +The parameter ``mem`` of ``-numa node`` is used to assign a part of
> +guest RAM to a NUMA node. But when using it, it's impossible to manage specified
> +RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
> +so guest end-ups with the fake NUMA configuration with suboptiomal performance.
> +However since 2014 there is an alternative way to assign RAM to a NUMA node
> +using parameter ``memdev``, which does the same as ``mem`` and adds
> +means to actualy manage node RAM on the host side. Use parameter ``memdev``
> +with *memory-backend-ram* backend as an replacement for parameter ``mem``
> +to achieve the same fake NUMA effect or a properly configured
> +*memory-backend-file* backend to actually benefit from NUMA configuration.
> +In future new machine versions will not accept the option but it will still
> +work with old machine types. User can check QAPI schema to see if the legacy
> +option is supported by looking at MachineInfo::numa-mem-supported property.
> +
> +``-numa`` node (without memory specified) (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Splitting RAM by default between NUMA nodes has the same issues as ``mem``
> +parameter described above with the difference that the role of the user plays
> +QEMU using implicit generic or board specific splitting rule.
> +Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
> +it's supported by used machine type) to define mapping explictly instead.
> +
> +``-mem-path`` fallback to RAM (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''
> +
> +Currently if guest RAM allocation from file pointed by ``mem-path``
> +fails, QEMU falls back to allocating from RAM, which might result
> +in unpredictable behavior since the backing file specified by the user
> +is ignored. In the future, users will be responsible for making sure
> +the backing storage specified with ``-mem-path`` can actually provide
> +the guest RAM configured with ``-m`` and QEMU will fail to start up if
> +RAM allocation is unsuccessful.
> +
> +RISC-V ``-bios`` (since 4.1)
> +''''''''''''''''''''''''''''
> +
> +QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
> +RISC-V virt machine and sifive_u machine.
> +
> +QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
> +default will change in a future QEMU release, so please prepare now. All users
> +of the virt or sifive_u machine must change their command line usage.
> +
> +QEMU 4.1 has three options, please migrate to one of these three:
> + 1. ``-bios none`` - This is the current default behavior if no -bios option
> +      is included. QEMU will not automatically load any firmware. It is up
> +      to the user to load all the images they need.
> + 2. ``-bios default`` - In a future QEMU release this will become the default
> +      behaviour if no -bios option is specified. This option will load the
> +      default OpenSBI firmware automatically. The firmware is included with
> +      the QEMU release and no user interaction is required. All a user needs
> +      to do is specify the kernel they want to boot with the -kernel option
> + 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
> +
> +``-tb-size`` option (since 5.0)
> +'''''''''''''''''''''''''''''''
> +
> +QEMU 5.0 introduced an alternative syntax to specify the size of the translation
> +block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
> +previously available ``-tb-size`` option.
> +
> +``-show-cursor`` option (since 5.0)
> +'''''''''''''''''''''''''''''''''''
> +
> +Use ``-display sdl,show-cursor=on`` or
> + ``-display gtk,show-cursor=on`` instead.
> +
> +QEMU Machine Protocol (QMP) commands
> +------------------------------------
> +
> +``change`` (since 2.5.0)
> +''''''''''''''''''''''''
> +
> +Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
> +
> +``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Use ``migrate-set-parameters`` instead.
> +
> +``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
> +
> +``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
> +the query-block command is deprecated. Two new boolean fields,
> +``recording`` and ``busy`` effectively replace it.
> +
> +``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
> +the query-block command is itself now deprecated. The ``dirty-bitmaps``
> +field of the ``BlockDeviceInfo`` struct should be used instead, which is the
> +type of the ``inserted`` field in query-block replies, as well as the
> +type of array items in query-named-block-nodes.
> +
> +Since the ``dirty-bitmaps`` field is optionally present in both the old and
> +new locations, clients must use introspection to learn where to anticipate
> +the field if/when it does appear in command output.
> +
> +``query-cpus`` (since 2.12.0)
> +'''''''''''''''''''''''''''''
> +
> +The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
> +
> +``query-cpus-fast`` ``arch`` output member (since 3.0.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``arch`` output member of the ``query-cpus-fast`` command is
> +replaced by the ``target`` output member.
> +
> +``cpu-add`` (since 4.0)
> +'''''''''''''''''''''''
> +
> +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
> +documentation of ``query-hotpluggable-cpus`` for additional
> +details.
> +
> +``query-events`` (since 4.0)
> +''''''''''''''''''''''''''''
> +
> +The ``query-events`` command has been superseded by the more powerful
> +and accurate ``query-qmp-schema`` command.
> +
> +chardev client socket with ``wait`` option (since 4.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Character devices creating sockets in client mode should not specify
> +the 'wait' field, which is only applicable to sockets in server mode
> +
> +Human Monitor Protocol (HMP) commands
> +-------------------------------------
> +
> +The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
> +'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
> +
> +``cpu-add`` (since 4.0)
> +'''''''''''''''''''''''
> +
> +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
> +documentation of ``query-hotpluggable-cpus`` for additional details.
> +
> +``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
> +``acl_remove`` commands are deprecated with no replacement. Authorization
> +for VNC should be performed using the pluggable QAuthZ objects.
> +
> +Guest Emulator ISAs
> +-------------------
> +
> +RISC-V ISA privledge specification version 1.09.1 (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
> +QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
> +should be used instead of the 1.09.1 version.
> +
> +System emulator CPUS
> +--------------------
> +
> +RISC-V ISA CPUs (since 4.1)
> +'''''''''''''''''''''''''''
> +
> +The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
> +four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
> +``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
> +option when using the ``rv32`` or ``rv64`` CPUs.
> +
> +RISC-V ISA CPUs (since 4.1)
> +'''''''''''''''''''''''''''
> +
> +The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
> +``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
> +via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
> +
> +System emulator devices
> +-----------------------
> +
> +``ide-drive`` (since 4.2)
> +'''''''''''''''''''''''''
> +
> +The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
> +'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
> +
> +``scsi-disk`` (since 4.2)
> +'''''''''''''''''''''''''
> +
> +The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
> +'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
> +
> +System emulator machines
> +------------------------
> +
> +mips ``r4k`` platform (since 5.0)
> +'''''''''''''''''''''''''''''''''
> +
> +This machine type is very old and unmaintained. Users should use the ``malta``
> +machine type instead.
> +
> +``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +These machine types are very old and likely can not be used for live migration
> +from old QEMU versions anymore. A newer machine type should be used instead.
> +
> +``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
> +''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The version specific Spike machines have been deprecated in favour of the
> +generic ``spike`` machine. If you need to specify an older version of the RISC-V
> +spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
> +
> +Device options
> +--------------
> +
> +Emulated device options
> +'''''''''''''''''''''''
> +
> +``-device virtio-blk,scsi=on|off`` (since 5.0.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
> +and later do not support it because the virtio-scsi device was introduced for
> +full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
> +
> +Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
> +alias.
> +
> +Block device options
> +''''''''''''''''''''
> +
> +``"backing": ""`` (since 2.12.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In order to prevent QEMU from automatically opening an image's backing
> +chain, use ``"backing": null`` instead.
> +
> +``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Options for ``rbd`` should be specified according to its runtime options,
> +like other block drivers.  Legacy parsing of keyvalue pair encoded
> +filenames is useful to open images with the old format for backing files;
> +These image files should be updated to use the current format.
> +
> +Example of legacy encoding::
> +
> +  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
> +
> +The above, converted to the current supported format::
> +
> +  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
> +
> +Related binaries
> +----------------
> +
> +``qemu-img convert -n -o`` (since 4.2.0)
> +''''''''''''''''''''''''''''''''''''''''
> +
> +All options specified in ``-o`` are image creation options, so
> +they have no effect when used with ``-n`` to skip image creation.
> +Silently ignored options can be confusing, so this combination of
> +options will be made an error in future versions.
> +
> +Backwards compatibility
> +-----------------------
> +
> +Runnability guarantee of CPU models (since 4.1.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Previous versions of QEMU never changed existing CPU models in
> +ways that introduced additional host software or hardware
> +requirements to the VM.  This allowed management software to
> +safely change the machine type of an existing VM without
> +introducing new requirements ("runnability guarantee").  This
> +prevented CPU models from being updated to include CPU
> +vulnerability mitigations, leaving guests vulnerable in the
> +default configuration.
> +
> +The CPU model runnability guarantee won't apply anymore to
> +existing CPU models.  Management software that needs runnability
> +guarantees must resolve the CPU model aliases using te
> +``alias-of`` field returned by the ``query-cpu-definitions`` QMP
> +command.
> +
> +While those guarantees are kept, the return value of
> +``query-cpu-definitions`` will have existing CPU model aliases
> +point to a version that doesn't break runnability guarantees
> +(specifically, version 1 of those CPU models).  In future QEMU
> +versions, aliases will point to newer CPU model versions
> +depending on the machine type, so management software must
> +resolve CPU model aliases before starting a virtual machine.
> +
> +
> +Recently removed features
> +=========================
> +
> +What follows is a record of recently removed, formerly deprecated
> +features that serves as a record for users who have encountered
> +trouble after a recent upgrade.
> +
> +QEMU Machine Protocol (QMP) commands
> +------------------------------------
> +
> +``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The "autoload" parameter has been ignored since 2.12.0. All bitmaps
> +are automatically loaded from qcow2 images.
> +
> +Related binaries
> +----------------
> +
> +``qemu-nbd --partition`` (removed in 5.0.0)
> +'''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
> +could only handle MBR partitions, and never correctly handled logical
> +partitions beyond partition 5.  Exporting a partition can still be
> +done by utilizing the ``--image-opts`` option with a raw blockdev
> +using the ``offset`` and ``size`` parameters layered on top of
> +any other existing blockdev. For example, if partition 1 is 100MiB
> +long starting at 1MiB, the old command::
> +
> +  qemu-nbd -t -P 1 -f qcow2 file.qcow2
> +
> +can be rewritten as::
> +
> +  qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 887bef92f40..7d09abca954 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -14,6 +14,7 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>
> +   deprecated
>     managed-startup
>     qemu-block-drivers
>     security
> diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
> deleted file mode 100644
> index 0671c26c806..00000000000
> --- a/qemu-deprecated.texi
> +++ /dev/null
> @@ -1,386 +0,0 @@
> -@node Deprecated features
> -@appendix Deprecated features
> -
> -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 this appendix. The feature will remain functional
> -for 2 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.
> -
> -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.
> -
> -What follows is a list of all features currently marked as
> -deprecated.
> -
> -@section System emulator command line arguments
> -
> -@subsection -machine enforce-config-section=on|off (since 3.1)
> -
> -The @option{enforce-config-section} parameter is replaced by the
> -@option{-global migration.send-configuration=@var{on|off}} option.
> -
> -@subsection -no-kvm (since 1.3.0)
> -
> -The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''.
> -
> -@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.
> -
> -@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
> -
> -The 'file' driver for drives is no longer appropriate for character or host
> -devices and will only accept regular files (S_IFREG). The correct driver
> -for these file types is 'host_cdrom' or 'host_device' as appropriate.
> -
> -@subsection -net ...,name=@var{name} (since 3.1)
> -
> -The @option{name} parameter of the @option{-net} option is a synonym
> -for the @option{id} parameter, which should now be used instead.
> -
> -@subsection -smp (invalid topologies) (since 3.1)
> -
> -CPU topology properties should describe whole machine topology including
> -possible CPUs.
> -
> -However, historically it was possible to start QEMU with an incorrect topology
> -where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}},
> -which could lead to an incorrect topology enumeration by the guest.
> -Support for invalid topologies will be removed, the user must ensure
> -topologies described with -smp include all possible cpus, i.e.
> -  @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
> -
> -@subsection -vnc acl (since 4.0.0)
> -
> -The @code{acl} option to the @code{-vnc} argument has been replaced
> -by the @code{tls-authz} and @code{sasl-authz} options.
> -
> -@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
> -
> -The ``-audiodev'' argument is now the preferred way to specify audio
> -backend settings instead of environment variables.  To ease migration to
> -the new format, the ``-audiodev-help'' option can be used to convert
> -the current values of the environment variables to ``-audiodev'' options.
> -
> -@subsection Creating sound card devices and vnc without audiodev= property (since 4.2)
> -
> -When not using the deprecated legacy audio config, each sound card
> -should specify an @code{audiodev=} property.  Additionally, when using
> -vnc, you should specify an @code{audiodev=} propery if you plan to
> -transmit audio through the VNC protocol.
> -
> -@subsection -mon ...,control=readline,pretty=on|off (since 4.1)
> -
> -The @code{pretty=on|off} switch has no effect for HMP monitors, but is
> -silently ignored. Using the switch with HMP monitors will become an
> -error in the future.
> -
> -@subsection -realtime (since 4.1)
> -
> -The @code{-realtime mlock=on|off} argument has been replaced by the
> -@code{-overcommit mem-lock=on|off} argument.
> -
> -@subsection -numa node,mem=@var{size} (since 4.1)
> -
> -The parameter @option{mem} of @option{-numa node} is used to assign a part of
> -guest RAM to a NUMA node. But when using it, it's impossible to manage specified
> -RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
> -so guest end-ups with the fake NUMA configuration with suboptiomal performance.
> -However since 2014 there is an alternative way to assign RAM to a NUMA node
> -using parameter @option{memdev}, which does the same as @option{mem} and adds
> -means to actualy manage node RAM on the host side. Use parameter @option{memdev}
> -with @var{memory-backend-ram} backend as an replacement for parameter @option{mem}
> -to achieve the same fake NUMA effect or a properly configured
> -@var{memory-backend-file} backend to actually benefit from NUMA configuration.
> -In future new machine versions will not accept the option but it will still
> -work with old machine types. User can check QAPI schema to see if the legacy
> -option is supported by looking at MachineInfo::numa-mem-supported property.
> -
> -@subsection -numa node (without memory specified) (since 4.1)
> -
> -Splitting RAM by default between NUMA nodes has the same issues as @option{mem}
> -parameter described above with the difference that the role of the user plays
> -QEMU using implicit generic or board specific splitting rule.
> -Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if
> -it's supported by used machine type) to define mapping explictly instead.
> -
> -@subsection -mem-path fallback to RAM (since 4.1)
> -Currently if guest RAM allocation from file pointed by @option{mem-path}
> -fails, QEMU falls back to allocating from RAM, which might result
> -in unpredictable behavior since the backing file specified by the user
> -is ignored. In the future, users will be responsible for making sure
> -the backing storage specified with @option{-mem-path} can actually provide
> -the guest RAM configured with @option{-m} and QEMU will fail to start up if
> -RAM allocation is unsuccessful.
> -
> -@subsection RISC-V -bios (since 4.1)
> -
> -QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
> -RISC-V virt machine and sifive_u machine.
> -
> -QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
> -default will change in a future QEMU release, so please prepare now. All users
> -of the virt or sifive_u machine must change their command line usage.
> -
> -QEMU 4.1 has three options, please migrate to one of these three:
> - 1. ``-bios none`` - This is the current default behavior if no -bios option
> -      is included. QEMU will not automatically load any firmware. It is up
> -      to the user to load all the images they need.
> - 2. ``-bios default`` - In a future QEMU release this will become the default
> -      behaviour if no -bios option is specified. This option will load the
> -      default OpenSBI firmware automatically. The firmware is included with
> -      the QEMU release and no user interaction is required. All a user needs
> -      to do is specify the kernel they want to boot with the -kernel option
> - 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
> -
> -@subsection -tb-size option (since 5.0)
> -
> -QEMU 5.0 introduced an alternative syntax to specify the size of the translation
> -block cache, @option{-accel tcg,tb-size=}.  The new syntax deprecates the
> -previously available @option{-tb-size} option.
> -
> -@subsection -show-cursor option (since 5.0)
> -
> -Use @option{-display sdl,show-cursor=on} or
> - @option{-display gtk,show-cursor=on} instead.
> -
> -@section QEMU Machine Protocol (QMP) commands
> -
> -@subsection change (since 2.5.0)
> -
> -Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
> -
> -@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
> -
> -Use ``migrate-set-parameters'' instead.
> -
> -@subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
> -
> -Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
> -
> -@subsection query-block result field dirty-bitmaps[i].status (since 4.0)
> -
> -The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
> -the query-block command is deprecated. Two new boolean fields,
> -``recording'' and ``busy'' effectively replace it.
> -
> -@subsection query-block result field dirty-bitmaps (Since 4.2)
> -
> -The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
> -the query-block command is itself now deprecated. The ``dirty-bitmaps``
> -field of the ``BlockDeviceInfo`` struct should be used instead, which is the
> -type of the ``inserted`` field in query-block replies, as well as the
> -type of array items in query-named-block-nodes.
> -
> -Since the ``dirty-bitmaps`` field is optionally present in both the old and
> -new locations, clients must use introspection to learn where to anticipate
> -the field if/when it does appear in command output.
> -
> -@subsection query-cpus (since 2.12.0)
> -
> -The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
> -
> -@subsection query-cpus-fast "arch" output member (since 3.0.0)
> -
> -The ``arch'' output member of the ``query-cpus-fast'' command is
> -replaced by the ``target'' output member.
> -
> -@subsection cpu-add (since 4.0)
> -
> -Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
> -documentation of ``query-hotpluggable-cpus'' for additional
> -details.
> -
> -@subsection query-events (since 4.0)
> -
> -The ``query-events'' command has been superseded by the more powerful
> -and accurate ``query-qmp-schema'' command.
> -
> -@subsection chardev client socket with 'wait' option (since 4.0)
> -
> -Character devices creating sockets in client mode should not specify
> -the 'wait' field, which is only applicable to sockets in server mode
> -
> -@section Human Monitor Protocol (HMP) commands
> -
> -@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
> -
> -The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
> -'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
> -
> -@subsection cpu-add (since 4.0)
> -
> -Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
> -documentation of ``query-hotpluggable-cpus'' for additional details.
> -
> -@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
> -
> -The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
> -``acl_remove'' commands are deprecated with no replacement. Authorization
> -for VNC should be performed using the pluggable QAuthZ objects.
> -
> -@section Guest Emulator ISAs
> -
> -@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
> -
> -The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
> -QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
> -should be used instead of the 1.09.1 version.
> -
> -@section System emulator CPUS
> -
> -@subsection RISC-V ISA CPUs (since 4.1)
> -
> -The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
> -four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
> -``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
> -option when using the ``rv32`` or ``rv64`` CPUs.
> -
> -@subsection RISC-V ISA CPUs (since 4.1)
> -
> -The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
> -``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
> -via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
> -
> -@section System emulator devices
> -
> -@subsection ide-drive (since 4.2)
> -
> -The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
> -'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
> -
> -@subsection scsi-disk (since 4.2)
> -
> -The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
> -'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
> -
> -@section System emulator machines
> -
> -@subsection mips r4k platform (since 5.0)
> -
> -This machine type is very old and unmaintained. Users should use the 'malta'
> -machine type instead.
> -
> -@subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
> -
> -These machine types are very old and likely can not be used for live migration
> -from old QEMU versions anymore. A newer machine type should be used instead.
> -
> -@subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
> -
> -The version specific Spike machines have been deprecated in favour of the
> -generic ``spike`` machine. If you need to specify an older version of the RISC-V
> -spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
> -
> -@section Device options
> -
> -@subsection Emulated device options
> -
> -@subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
> -
> -The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
> -and later do not support it because the virtio-scsi device was introduced for
> -full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
> -
> -Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an
> -alias.
> -
> -@subsection Block device options
> -
> -@subsubsection "backing": "" (since 2.12.0)
> -
> -In order to prevent QEMU from automatically opening an image's backing
> -chain, use ``"backing": null'' instead.
> -
> -@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
> -
> -Options for ``rbd'' should be specified according to its runtime options,
> -like other block drivers.  Legacy parsing of keyvalue pair encoded
> -filenames is useful to open images with the old format for backing files;
> -These image files should be updated to use the current format.
> -
> -Example of legacy encoding:
> -
> -@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
> -
> -The above, converted to the current supported format:
> -
> -@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
> -
> -@section Related binaries
> -
> -@subsection qemu-img convert -n -o (since 4.2.0)
> -
> -All options specified in @option{-o} are image creation options, so
> -they have no effect when used with @option{-n} to skip image creation.
> -Silently ignored options can be confusing, so this combination of
> -options will be made an error in future versions.
> -
> -@section Backwards compatibility
> -
> -@subsection Runnability guarantee of CPU models (since 4.1.0)
> -
> -Previous versions of QEMU never changed existing CPU models in
> -ways that introduced additional host software or hardware
> -requirements to the VM.  This allowed management software to
> -safely change the machine type of an existing VM without
> -introducing new requirements ("runnability guarantee").  This
> -prevented CPU models from being updated to include CPU
> -vulnerability mitigations, leaving guests vulnerable in the
> -default configuration.
> -
> -The CPU model runnability guarantee won't apply anymore to
> -existing CPU models.  Management software that needs runnability
> -guarantees must resolve the CPU model aliases using te
> -``alias-of'' field returned by the ``query-cpu-definitions'' QMP
> -command.
> -
> -While those guarantees are kept, the return value of
> -``query-cpu-definitions'' will have existing CPU model aliases
> -point to a version that doesn't break runnability guarantees
> -(specifically, version 1 of those CPU models).  In future QEMU
> -versions, aliases will point to newer CPU model versions
> -depending on the machine type, so management software must
> -resolve CPU model aliases before starting a virtual machine.
> -
> -
> -@node Recently removed features
> -@appendix Recently removed features
> -
> -What follows is a record of recently removed, formerly deprecated
> -features that serves as a record for users who have encountered
> -trouble after a recent upgrade.
> -
> -@section QEMU Machine Protocol (QMP) commands
> -
> -@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
> -
> -The "autoload" parameter has been ignored since 2.12.0. All bitmaps
> -are automatically loaded from qcow2 images.
> -
> -@section Related binaries
> -
> -@subsection qemu-nbd --partition (removed in 5.0.0)
> -
> -The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
> -could only handle MBR partitions, and never correctly handled logical
> -partitions beyond partition 5.  Exporting a partition can still be
> -done by utilizing the @option{--image-opts} option with a raw blockdev
> -using the @code{offset} and @code{size} parameters layered on top of
> -any other existing blockdev. For example, if partition 1 is 100MiB
> -long starting at 1MiB, the old command:
> -
> -@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
> -
> -can be rewritten as:
> -
> -@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2}
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 7798e072a1c..6bb1fd54c03 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -40,8 +40,6 @@
>  * QEMU System emulator for non PC targets::
>  * QEMU User space emulator::
>  * System requirements::
> -* Deprecated features::
> -* Recently removed features::
>  * Supported build platforms::
>  * License::
>  * Index::
> @@ -2834,8 +2832,6 @@ added with Linux 4.5 which is supported by the major distros. And even
>  if RHEL7 has kernel 3.10, KVM there has the required functionality there
>  to make it close to a 4.5 or newer kernel.
>
> -@include qemu-deprecated.texi
> -
>  @node Supported build platforms
>  @appendix Supported build platforms
>
> --
> 2.20.1
>
>

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 25 Feb 2020 at 17:48, Paolo Bonzini <pbonzini@redhat.com> wrote:
>>
>> On 25/02/20 18:11, Peter Maydell wrote:
>> >> I assume these are not meant to be applied now, except patch 2?
>> > No, I intended them to be reviewable and applied now. Why
>> > do you think we should wait?
>>
>> Because they remove information from qemu-doc.texi.  I think it's
>> feasible to do a mass conversion quite soon, within a single pull
>> request, the only important part that is missing is the hxtool conversion.
>
> My assumption was that we would attack this by:
>  * converting chunks of the documentation which are in qemu-doc.texi
>    but which aren't in the qemu.1 manpage (basically in the way this
>    series is doing)
>  * get the qapidoc generation conversion reviewed and into
>    master (since at the moment it outputs into files included
>    from qemu-doc)

Not true.  QAPI doc comments go into *separate* manuals, the "QEMU QMP
reference" (docs/interop/qemu-qmp-ref.*), and the "QEMU Guest Agent
protocol reference" (docs/interop/qemu-ga-ref.*).

In more detail: scripts/qapi-gen.py generates
docs/interop/qemu-qmp-qapi.texi from qapi/qapi-schema.json, and
docs/interop/qemu-ga-qapi.texi from qga/qapi-schema.json.  These are
included into docs/interop/qemu-qmp-ref.texi and
docs/interop/qemu-ga-ref.texi, respectively.

>  * convert the manpage parts; we have the machinery for dealing
>    with the hxtool files, it just needs a little more work
[...]

Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell]

On Wed, 26 Feb 2020 at 07:50, Markus Armbruster <armbru@redhat.com> wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> >  * get the qapidoc generation conversion reviewed and into
> >    master (since at the moment it outputs into files included
> >    from qemu-doc)
>
> Not true.  QAPI doc comments go into *separate* manuals, the "QEMU QMP
> reference" (docs/interop/qemu-qmp-ref.*), and the "QEMU Guest Agent
> protocol reference" (docs/interop/qemu-ga-ref.*).

So it does. I think I must have just assumed it was included
in qemu-doc because just about everything else is. That
makes things easier as the process of converting qemu-doc
and the conversion of the QAPI doc comments can be
handled separately without interdependencies.

thanks
-- PMM

Re: [PATCH 4/4] docs: Convert qemu-deprecated.texi to rST

[Aleksandar Markovic]

[-- Attachment #1: Type: text/plain, Size: 39971 bytes --]

On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@linaro.org>
wrote:

> > Convert the documentation of deprecated features to rST.
>
>

s/depcreated/deprecated

at two places below (unless there is (and suitable in the context) an
english word "depcreated", that is not known to me).

Aleksandar


> We put the whole of this document into the system manual, though
> technically a few parts of it apply to qemu-img or qemu-nbd which are
> otherwise documented in tools/.
>
> We only make formatting fixes, except for one use of 'appendix' which
> we change to 'section' because this isn't an appendix in the Sphinx
> manual.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  Makefile                   |   2 +-
>  MAINTAINERS                |   2 +-
>  docs/system/deprecated.rst | 446 +++++++++++++++++++++++++++++++++++++
>  docs/system/index.rst      |   1 +
>  qemu-deprecated.texi       | 386 --------------------------------
>  qemu-doc.texi              |   4 -
>  6 files changed, 449 insertions(+), 392 deletions(-)
>  create mode 100644 docs/system/deprecated.rst
>  delete mode 100644 qemu-deprecated.texi
>
> diff --git a/Makefile b/Makefile
> index 28749d20401..ec4a4be8355 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1115,7 +1115,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt
> docs/interop/qemu-ga-ref.txt
>  qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
>         qemu-options.texi \
>         qemu-option-trace.texi \
> -       qemu-deprecated.texi qemu-monitor.texi \
> +       qemu-monitor.texi \
>         qemu-monitor-info.texi \
>         docs/qemu-cpu-models.texi
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 195dd58cac1..546f2b83017 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2787,7 +2787,7 @@ F: contrib/gitdm/*
>
>  Incompatible changes
>  R: libvir-list@redhat.com
> -F: qemu-deprecated.texi
> +F: docs/system/deprecated.rst
>
>  Build System
>  ------------
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> new file mode 100644
> index 00000000000..1eaa559079b
> --- /dev/null
> +++ b/docs/system/deprecated.rst
> @@ -0,0 +1,446 @@
> +Deprecated features
> +===================
> +
> +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 this section. The feature will remain functional
> +for 2 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.
> +
> +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.
> +
> +What follows is a list of all features currently marked as
> +deprecated.
> +
> +System emulator command line arguments
> +--------------------------------------
> +
> +``-machine enforce-config-section=on|off`` (since 3.1)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``enforce-config-section`` parameter is replaced by the
> +``-global migration.send-configuration={on|off}`` option.
> +
> +``-no-kvm`` (since 1.3.0)
> +'''''''''''''''''''''''''
> +
> +The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
> +
> +``-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.
> +
> +``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The 'file' driver for drives is no longer appropriate for character or
> host
> +devices and will only accept regular files (S_IFREG). The correct driver
> +for these file types is 'host_cdrom' or 'host_device' as appropriate.
> +
> +``-net ...,name=``\ *name* (since 3.1)
> +''''''''''''''''''''''''''''''''''''''
> +
> +The ``name`` parameter of the ``-net`` option is a synonym
> +for the ``id`` parameter, which should now be used instead.
> +
> +``-smp`` (invalid topologies) (since 3.1)
> +'''''''''''''''''''''''''''''''''''''''''
> +
> +CPU topology properties should describe whole machine topology including
> +possible CPUs.
> +
> +However, historically it was possible to start QEMU with an incorrect
> topology
> +where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
> +which could lead to an incorrect topology enumeration by the guest.
> +Support for invalid topologies will be removed, the user must ensure
> +topologies described with -smp include all possible cpus, i.e.
> +*sockets* * *cores* * *threads* = *maxcpus*.
> +
> +``-vnc acl`` (since 4.0.0)
> +''''''''''''''''''''''''''
> +
> +The ``acl`` option to the ``-vnc`` argument has been replaced
> +by the ``tls-authz`` and ``sasl-authz`` options.
> +
> +``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``-audiodev`` argument is now the preferred way to specify audio
> +backend settings instead of environment variables.  To ease migration to
> +the new format, the ``-audiodev-help`` option can be used to convert
> +the current values of the environment variables to ``-audiodev`` options.
> +
> +Creating sound card devices and vnc without ``audiodev=`` property (since
> 4.2)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> '''''''''''''''''''
> +
> +When not using the deprecated legacy audio config, each sound card
> +should specify an ``audiodev=`` property.  Additionally, when using
> +vnc, you should specify an ``audiodev=`` propery if you plan to
> +transmit audio through the VNC protocol.
> +
> +``-mon ...,control=readline,pretty=on|off`` (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``pretty=on|off`` switch has no effect for HMP monitors, but is
> +silently ignored. Using the switch with HMP monitors will become an
> +error in the future.
> +
> +``-realtime`` (since 4.1)
> +'''''''''''''''''''''''''
> +
> +The ``-realtime mlock=on|off`` argument has been replaced by the
> +``-overcommit mem-lock=on|off`` argument.
> +
> +``-numa node,mem=``\ *size* (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''
> +
> +The parameter ``mem`` of ``-numa node`` is used to assign a part of
> +guest RAM to a NUMA node. But when using it, it's impossible to manage
> specified
> +RAM chunk on the host side (like bind it to a host node, setting bind
> policy, ...),
> +so guest end-ups with the fake NUMA configuration with suboptiomal
> performance.
> +However since 2014 there is an alternative way to assign RAM to a NUMA
> node
> +using parameter ``memdev``, which does the same as ``mem`` and adds
> +means to actualy manage node RAM on the host side. Use parameter
> ``memdev``
> +with *memory-backend-ram* backend as an replacement for parameter ``mem``
> +to achieve the same fake NUMA effect or a properly configured
> +*memory-backend-file* backend to actually benefit from NUMA configuration.
> +In future new machine versions will not accept the option but it will
> still
> +work with old machine types. User can check QAPI schema to see if the
> legacy
> +option is supported by looking at MachineInfo::numa-mem-supported
> property.
> +
> +``-numa`` node (without memory specified) (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Splitting RAM by default between NUMA nodes has the same issues as ``mem``
> +parameter described above with the difference that the role of the user
> plays
> +QEMU using implicit generic or board specific splitting rule.
> +Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
> +it's supported by used machine type) to define mapping explictly instead.
> +
> +``-mem-path`` fallback to RAM (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''
> +
> +Currently if guest RAM allocation from file pointed by ``mem-path``
> +fails, QEMU falls back to allocating from RAM, which might result
> +in unpredictable behavior since the backing file specified by the user
> +is ignored. In the future, users will be responsible for making sure
> +the backing storage specified with ``-mem-path`` can actually provide
> +the guest RAM configured with ``-m`` and QEMU will fail to start up if
> +RAM allocation is unsuccessful.
> +
> +RISC-V ``-bios`` (since 4.1)
> +''''''''''''''''''''''''''''
> +
> +QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for
> the
> +RISC-V virt machine and sifive_u machine.
> +
> +QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
> +default will change in a future QEMU release, so please prepare now. All
> users
> +of the virt or sifive_u machine must change their command line usage.
> +
> +QEMU 4.1 has three options, please migrate to one of these three:
> + 1. ``-bios none`` - This is the current default behavior if no -bios
> option
> +      is included. QEMU will not automatically load any firmware. It is up
> +      to the user to load all the images they need.
> + 2. ``-bios default`` - In a future QEMU release this will become the
> default
> +      behaviour if no -bios option is specified. This option will load the
> +      default OpenSBI firmware automatically. The firmware is included
> with
> +      the QEMU release and no user interaction is required. All a user
> needs
> +      to do is specify the kernel they want to boot with the -kernel
> option
> + 3. ``-bios <file>`` - Tells QEMU to load the specified file as the
> firmwrae.
> +
> +``-tb-size`` option (since 5.0)
> +'''''''''''''''''''''''''''''''
> +
> +QEMU 5.0 introduced an alternative syntax to specify the size of the
> translation
> +block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
> +previously available ``-tb-size`` option.
> +
> +``-show-cursor`` option (since 5.0)
> +'''''''''''''''''''''''''''''''''''
> +
> +Use ``-display sdl,show-cursor=on`` or
> + ``-display gtk,show-cursor=on`` instead.
> +
> +QEMU Machine Protocol (QMP) commands
> +------------------------------------
> +
> +``change`` (since 2.5.0)
> +''''''''''''''''''''''''
> +
> +Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
> +
> +``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Use ``migrate-set-parameters`` instead.
> +
> +``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> '''''''''''''''
> +
> +Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
> +
> +``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
> +the query-block command is deprecated. Two new boolean fields,
> +``recording`` and ``busy`` effectively replace it.
> +
> +``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
> +the query-block command is itself now deprecated. The ``dirty-bitmaps``
> +field of the ``BlockDeviceInfo`` struct should be used instead, which is
> the
> +type of the ``inserted`` field in query-block replies, as well as the
> +type of array items in query-named-block-nodes.
> +
> +Since the ``dirty-bitmaps`` field is optionally present in both the old
> and
> +new locations, clients must use introspection to learn where to anticipate
> +the field if/when it does appear in command output.
> +
> +``query-cpus`` (since 2.12.0)
> +'''''''''''''''''''''''''''''
> +
> +The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
> +
> +``query-cpus-fast`` ``arch`` output member (since 3.0.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``arch`` output member of the ``query-cpus-fast`` command is
> +replaced by the ``target`` output member.
> +
> +``cpu-add`` (since 4.0)
> +'''''''''''''''''''''''
> +
> +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
> +documentation of ``query-hotpluggable-cpus`` for additional
> +details.
> +
> +``query-events`` (since 4.0)
> +''''''''''''''''''''''''''''
> +
> +The ``query-events`` command has been superseded by the more powerful
> +and accurate ``query-qmp-schema`` command.
> +
> +chardev client socket with ``wait`` option (since 4.0)
> +''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Character devices creating sockets in client mode should not specify
> +the 'wait' field, which is only applicable to sockets in server mode
> +
> +Human Monitor Protocol (HMP) commands
> +-------------------------------------
> +
> +The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since
> 3.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> '''''''''''''''''
> +
> +The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
> +'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
> +
> +``cpu-add`` (since 4.0)
> +'''''''''''''''''''''''
> +
> +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
> +documentation of ``query-hotpluggable-cpus`` for additional details.
> +
> +``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove``
> (since 4.0.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> '''''''''''''''''''''''''''
> +
> +The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
> +``acl_remove`` commands are deprecated with no replacement. Authorization
> +for VNC should be performed using the pluggable QAuthZ objects.
> +
> +Guest Emulator ISAs
> +-------------------
> +
> +RISC-V ISA privledge specification version 1.09.1 (since 4.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
> +QEMU supports both the newer version 1.10.0 and the ratified version
> 1.11.0, these
> +should be used instead of the 1.09.1 version.
> +
> +System emulator CPUS
> +--------------------
> +
> +RISC-V ISA CPUs (since 4.1)
> +'''''''''''''''''''''''''''
> +
> +The RISC-V cpus with the ISA version in the CPU name have been
> depcreated. The
> +four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``,
> ``rv64gcsu-v1.9.1`` and
> +``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU
> ``priv_spec``
> +option when using the ``rv32`` or ``rv64`` CPUs.
> +
> +RISC-V ISA CPUs (since 4.1)
> +'''''''''''''''''''''''''''
> +
> +The RISC-V no MMU cpus have been depcreated. The two CPUs:
> ``rv32imacu-nommu`` and
> +``rv64imacu-nommu`` should no longer be used. Instead the MMU status can
> be specified
> +via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
> +
> +System emulator devices
> +-----------------------
> +
> +``ide-drive`` (since 4.2)
> +'''''''''''''''''''''''''
> +
> +The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
> +'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
> +
> +``scsi-disk`` (since 4.2)
> +'''''''''''''''''''''''''
> +
> +The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
> +'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
> +
> +System emulator machines
> +------------------------
> +
> +mips ``r4k`` platform (since 5.0)
> +'''''''''''''''''''''''''''''''''
> +
> +This machine type is very old and unmaintained. Users should use the
> ``malta``
> +machine type instead.
> +
> +``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +These machine types are very old and likely can not be used for live
> migration
> +from old QEMU versions anymore. A newer machine type should be used
> instead.
> +
> +``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
> +''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The version specific Spike machines have been deprecated in favour of the
> +generic ``spike`` machine. If you need to specify an older version of the
> RISC-V
> +spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line
> argument.
> +
> +Device options
> +--------------
> +
> +Emulated device options
> +'''''''''''''''''''''''
> +
> +``-device virtio-blk,scsi=on|off`` (since 5.0.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.
> VIRTIO 1.0
> +and later do not support it because the virtio-scsi device was introduced
> for
> +full SCSI support.  Use virtio-scsi instead when SCSI passthrough is
> required.
> +
> +Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which
> is an
> +alias.
> +
> +Block device options
> +''''''''''''''''''''
> +
> +``"backing": ""`` (since 2.12.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In order to prevent QEMU from automatically opening an image's backing
> +chain, use ``"backing": null`` instead.
> +
> +``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Options for ``rbd`` should be specified according to its runtime options,
> +like other block drivers.  Legacy parsing of keyvalue pair encoded
> +filenames is useful to open images with the old format for backing files;
> +These image files should be updated to use the current format.
> +
> +Example of legacy encoding::
> +
> +  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
> +
> +The above, converted to the current supported format::
> +
> +  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
> +
> +Related binaries
> +----------------
> +
> +``qemu-img convert -n -o`` (since 4.2.0)
> +''''''''''''''''''''''''''''''''''''''''
> +
> +All options specified in ``-o`` are image creation options, so
> +they have no effect when used with ``-n`` to skip image creation.
> +Silently ignored options can be confusing, so this combination of
> +options will be made an error in future versions.
> +
> +Backwards compatibility
> +-----------------------
> +
> +Runnability guarantee of CPU models (since 4.1.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Previous versions of QEMU never changed existing CPU models in
> +ways that introduced additional host software or hardware
> +requirements to the VM.  This allowed management software to
> +safely change the machine type of an existing VM without
> +introducing new requirements ("runnability guarantee").  This
> +prevented CPU models from being updated to include CPU
> +vulnerability mitigations, leaving guests vulnerable in the
> +default configuration.
> +
> +The CPU model runnability guarantee won't apply anymore to
> +existing CPU models.  Management software that needs runnability
> +guarantees must resolve the CPU model aliases using te
> +``alias-of`` field returned by the ``query-cpu-definitions`` QMP
> +command.
> +
> +While those guarantees are kept, the return value of
> +``query-cpu-definitions`` will have existing CPU model aliases
> +point to a version that doesn't break runnability guarantees
> +(specifically, version 1 of those CPU models).  In future QEMU
> +versions, aliases will point to newer CPU model versions
> +depending on the machine type, so management software must
> +resolve CPU model aliases before starting a virtual machine.
> +
> +
> +Recently removed features
> +=========================
> +
> +What follows is a record of recently removed, formerly deprecated
> +features that serves as a record for users who have encountered
> +trouble after a recent upgrade.
> +
> +QEMU Machine Protocol (QMP) commands
> +------------------------------------
> +
> +``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +The "autoload" parameter has been ignored since 2.12.0. All bitmaps
> +are automatically loaded from qcow2 images.
> +
> +Related binaries
> +----------------
> +
> +``qemu-nbd --partition`` (removed in 5.0.0)
> +'''''''''''''''''''''''''''''''''''''''''''
> +
> +The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
> +could only handle MBR partitions, and never correctly handled logical
> +partitions beyond partition 5.  Exporting a partition can still be
> +done by utilizing the ``--image-opts`` option with a raw blockdev
> +using the ``offset`` and ``size`` parameters layered on top of
> +any other existing blockdev. For example, if partition 1 is 100MiB
> +long starting at 1MiB, the old command::
> +
> +  qemu-nbd -t -P 1 -f qcow2 file.qcow2
> +
> +can be rewritten as::
> +
> +  qemu-nbd -t --image-opts driver=raw,offset=1M,size=
> 100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 887bef92f40..7d09abca954 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -14,6 +14,7 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>
> +   deprecated
>     managed-startup
>     qemu-block-drivers
>     security
> diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
> deleted file mode 100644
> index 0671c26c806..00000000000
> --- a/qemu-deprecated.texi
> +++ /dev/null
> @@ -1,386 +0,0 @@
> -@node Deprecated features
> -@appendix Deprecated features
> -
> -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 this appendix. The feature will remain functional
> -for 2 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.
> -
> -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.
> -
> -What follows is a list of all features currently marked as
> -deprecated.
> -
> -@section System emulator command line arguments
> -
> -@subsection -machine enforce-config-section=on|off (since 3.1)
> -
> -The @option{enforce-config-section} parameter is replaced by the
> -@option{-global migration.send-configuration=@var{on|off}} option.
> -
> -@subsection -no-kvm (since 1.3.0)
> -
> -The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''.
> -
> -@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.
> -
> -@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
> -
> -The 'file' driver for drives is no longer appropriate for character or
> host
> -devices and will only accept regular files (S_IFREG). The correct driver
> -for these file types is 'host_cdrom' or 'host_device' as appropriate.
> -
> -@subsection -net ...,name=@var{name} (since 3.1)
> -
> -The @option{name} parameter of the @option{-net} option is a synonym
> -for the @option{id} parameter, which should now be used instead.
> -
> -@subsection -smp (invalid topologies) (since 3.1)
> -
> -CPU topology properties should describe whole machine topology including
> -possible CPUs.
> -
> -However, historically it was possible to start QEMU with an incorrect
> topology
> -where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} <
> @var{maxcpus}},
> -which could lead to an incorrect topology enumeration by the guest.
> -Support for invalid topologies will be removed, the user must ensure
> -topologies described with -smp include all possible cpus, i.e.
> -  @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
> -
> -@subsection -vnc acl (since 4.0.0)
> -
> -The @code{acl} option to the @code{-vnc} argument has been replaced
> -by the @code{tls-authz} and @code{sasl-authz} options.
> -
> -@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
> -
> -The ``-audiodev'' argument is now the preferred way to specify audio
> -backend settings instead of environment variables.  To ease migration to
> -the new format, the ``-audiodev-help'' option can be used to convert
> -the current values of the environment variables to ``-audiodev'' options.
> -
> -@subsection Creating sound card devices and vnc without audiodev=
> property (since 4.2)
> -
> -When not using the deprecated legacy audio config, each sound card
> -should specify an @code{audiodev=} property.  Additionally, when using
> -vnc, you should specify an @code{audiodev=} propery if you plan to
> -transmit audio through the VNC protocol.
> -
> -@subsection -mon ...,control=readline,pretty=on|off (since 4.1)
> -
> -The @code{pretty=on|off} switch has no effect for HMP monitors, but is
> -silently ignored. Using the switch with HMP monitors will become an
> -error in the future.
> -
> -@subsection -realtime (since 4.1)
> -
> -The @code{-realtime mlock=on|off} argument has been replaced by the
> -@code{-overcommit mem-lock=on|off} argument.
> -
> -@subsection -numa node,mem=@var{size} (since 4.1)
> -
> -The parameter @option{mem} of @option{-numa node} is used to assign a
> part of
> -guest RAM to a NUMA node. But when using it, it's impossible to manage
> specified
> -RAM chunk on the host side (like bind it to a host node, setting bind
> policy, ...),
> -so guest end-ups with the fake NUMA configuration with suboptiomal
> performance.
> -However since 2014 there is an alternative way to assign RAM to a NUMA
> node
> -using parameter @option{memdev}, which does the same as @option{mem} and
> adds
> -means to actualy manage node RAM on the host side. Use parameter
> @option{memdev}
> -with @var{memory-backend-ram} backend as an replacement for parameter
> @option{mem}
> -to achieve the same fake NUMA effect or a properly configured
> -@var{memory-backend-file} backend to actually benefit from NUMA
> configuration.
> -In future new machine versions will not accept the option but it will
> still
> -work with old machine types. User can check QAPI schema to see if the
> legacy
> -option is supported by looking at MachineInfo::numa-mem-supported
> property.
> -
> -@subsection -numa node (without memory specified) (since 4.1)
> -
> -Splitting RAM by default between NUMA nodes has the same issues as
> @option{mem}
> -parameter described above with the difference that the role of the user
> plays
> -QEMU using implicit generic or board specific splitting rule.
> -Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem}
> (if
> -it's supported by used machine type) to define mapping explictly instead.
> -
> -@subsection -mem-path fallback to RAM (since 4.1)
> -Currently if guest RAM allocation from file pointed by @option{mem-path}
> -fails, QEMU falls back to allocating from RAM, which might result
> -in unpredictable behavior since the backing file specified by the user
> -is ignored. In the future, users will be responsible for making sure
> -the backing storage specified with @option{-mem-path} can actually provide
> -the guest RAM configured with @option{-m} and QEMU will fail to start up
> if
> -RAM allocation is unsuccessful.
> -
> -@subsection RISC-V -bios (since 4.1)
> -
> -QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for
> the
> -RISC-V virt machine and sifive_u machine.
> -
> -QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
> -default will change in a future QEMU release, so please prepare now. All
> users
> -of the virt or sifive_u machine must change their command line usage.
> -
> -QEMU 4.1 has three options, please migrate to one of these three:
> - 1. ``-bios none`` - This is the current default behavior if no -bios
> option
> -      is included. QEMU will not automatically load any firmware. It is up
> -      to the user to load all the images they need.
> - 2. ``-bios default`` - In a future QEMU release this will become the
> default
> -      behaviour if no -bios option is specified. This option will load the
> -      default OpenSBI firmware automatically. The firmware is included
> with
> -      the QEMU release and no user interaction is required. All a user
> needs
> -      to do is specify the kernel they want to boot with the -kernel
> option
> - 3. ``-bios <file>`` - Tells QEMU to load the specified file as the
> firmwrae.
> -
> -@subsection -tb-size option (since 5.0)
> -
> -QEMU 5.0 introduced an alternative syntax to specify the size of the
> translation
> -block cache, @option{-accel tcg,tb-size=}.  The new syntax deprecates the
> -previously available @option{-tb-size} option.
> -
> -@subsection -show-cursor option (since 5.0)
> -
> -Use @option{-display sdl,show-cursor=on} or
> - @option{-display gtk,show-cursor=on} instead.
> -
> -@section QEMU Machine Protocol (QMP) commands
> -
> -@subsection change (since 2.5.0)
> -
> -Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
> -
> -@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
> -
> -Use ``migrate-set-parameters'' instead.
> -
> -@subsection migrate-set-cache-size and query-migrate-cache-size (since
> 2.11.0)
> -
> -Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
> -
> -@subsection query-block result field dirty-bitmaps[i].status (since 4.0)
> -
> -The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
> -the query-block command is deprecated. Two new boolean fields,
> -``recording'' and ``busy'' effectively replace it.
> -
> -@subsection query-block result field dirty-bitmaps (Since 4.2)
> -
> -The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
> -the query-block command is itself now deprecated. The ``dirty-bitmaps``
> -field of the ``BlockDeviceInfo`` struct should be used instead, which is
> the
> -type of the ``inserted`` field in query-block replies, as well as the
> -type of array items in query-named-block-nodes.
> -
> -Since the ``dirty-bitmaps`` field is optionally present in both the old
> and
> -new locations, clients must use introspection to learn where to anticipate
> -the field if/when it does appear in command output.
> -
> -@subsection query-cpus (since 2.12.0)
> -
> -The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
> -
> -@subsection query-cpus-fast "arch" output member (since 3.0.0)
> -
> -The ``arch'' output member of the ``query-cpus-fast'' command is
> -replaced by the ``target'' output member.
> -
> -@subsection cpu-add (since 4.0)
> -
> -Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
> -documentation of ``query-hotpluggable-cpus'' for additional
> -details.
> -
> -@subsection query-events (since 4.0)
> -
> -The ``query-events'' command has been superseded by the more powerful
> -and accurate ``query-qmp-schema'' command.
> -
> -@subsection chardev client socket with 'wait' option (since 4.0)
> -
> -Character devices creating sockets in client mode should not specify
> -the 'wait' field, which is only applicable to sockets in server mode
> -
> -@section Human Monitor Protocol (HMP) commands
> -
> -@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove'
> (since 3.1)
> -
> -The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
> -'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
> -
> -@subsection cpu-add (since 4.0)
> -
> -Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
> -documentation of ``query-hotpluggable-cpus'' for additional details.
> -
> -@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since
> 4.0.0)
> -
> -The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
> -``acl_remove'' commands are deprecated with no replacement. Authorization
> -for VNC should be performed using the pluggable QAuthZ objects.
> -
> -@section Guest Emulator ISAs
> -
> -@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
> -
> -The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
> -QEMU supports both the newer version 1.10.0 and the ratified version
> 1.11.0, these
> -should be used instead of the 1.09.1 version.
> -
> -@section System emulator CPUS
> -
> -@subsection RISC-V ISA CPUs (since 4.1)
> -
> -The RISC-V cpus with the ISA version in the CPU name have been
> depcreated. The
> -four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``,
> ``rv64gcsu-v1.9.1`` and
> -``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU
> ``priv_spec``
> -option when using the ``rv32`` or ``rv64`` CPUs.
> -
> -@subsection RISC-V ISA CPUs (since 4.1)
> -
> -The RISC-V no MMU cpus have been depcreated. The two CPUs:
> ``rv32imacu-nommu`` and
> -``rv64imacu-nommu`` should no longer be used. Instead the MMU status can
> be specified
> -via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
> -
> -@section System emulator devices
> -
> -@subsection ide-drive (since 4.2)
> -
> -The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
> -'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
> -
> -@subsection scsi-disk (since 4.2)
> -
> -The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
> -'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
> -
> -@section System emulator machines
> -
> -@subsection mips r4k platform (since 5.0)
> -
> -This machine type is very old and unmaintained. Users should use the
> 'malta'
> -machine type instead.
> -
> -@subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
> -
> -These machine types are very old and likely can not be used for live
> migration
> -from old QEMU versions anymore. A newer machine type should be used
> instead.
> -
> -@subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
> -
> -The version specific Spike machines have been deprecated in favour of the
> -generic ``spike`` machine. If you need to specify an older version of the
> RISC-V
> -spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line
> argument.
> -
> -@section Device options
> -
> -@subsection Emulated device options
> -
> -@subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
> -
> -The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.
> VIRTIO 1.0
> -and later do not support it because the virtio-scsi device was introduced
> for
> -full SCSI support.  Use virtio-scsi instead when SCSI passthrough is
> required.
> -
> -Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which
> is an
> -alias.
> -
> -@subsection Block device options
> -
> -@subsubsection "backing": "" (since 2.12.0)
> -
> -In order to prevent QEMU from automatically opening an image's backing
> -chain, use ``"backing": null'' instead.
> -
> -@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
> -
> -Options for ``rbd'' should be specified according to its runtime options,
> -like other block drivers.  Legacy parsing of keyvalue pair encoded
> -filenames is useful to open images with the old format for backing files;
> -These image files should be updated to use the current format.
> -
> -Example of legacy encoding:
> -
> -@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
> -
> -The above, converted to the current supported format:
> -
> -@code{json:@{"file.driver":"rbd", "file.pool":"rbd",
> "file.image":"name"@}}
> -
> -@section Related binaries
> -
> -@subsection qemu-img convert -n -o (since 4.2.0)
> -
> -All options specified in @option{-o} are image creation options, so
> -they have no effect when used with @option{-n} to skip image creation.
> -Silently ignored options can be confusing, so this combination of
> -options will be made an error in future versions.
> -
> -@section Backwards compatibility
> -
> -@subsection Runnability guarantee of CPU models (since 4.1.0)
> -
> -Previous versions of QEMU never changed existing CPU models in
> -ways that introduced additional host software or hardware
> -requirements to the VM.  This allowed management software to
> -safely change the machine type of an existing VM without
> -introducing new requirements ("runnability guarantee").  This
> -prevented CPU models from being updated to include CPU
> -vulnerability mitigations, leaving guests vulnerable in the
> -default configuration.
> -
> -The CPU model runnability guarantee won't apply anymore to
> -existing CPU models.  Management software that needs runnability
> -guarantees must resolve the CPU model aliases using te
> -``alias-of'' field returned by the ``query-cpu-definitions'' QMP
> -command.
> -
> -While those guarantees are kept, the return value of
> -``query-cpu-definitions'' will have existing CPU model aliases
> -point to a version that doesn't break runnability guarantees
> -(specifically, version 1 of those CPU models).  In future QEMU
> -versions, aliases will point to newer CPU model versions
> -depending on the machine type, so management software must
> -resolve CPU model aliases before starting a virtual machine.
> -
> -
> -@node Recently removed features
> -@appendix Recently removed features
> -
> -What follows is a record of recently removed, formerly deprecated
> -features that serves as a record for users who have encountered
> -trouble after a recent upgrade.
> -
> -@section QEMU Machine Protocol (QMP) commands
> -
> -@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
> -
> -The "autoload" parameter has been ignored since 2.12.0. All bitmaps
> -are automatically loaded from qcow2 images.
> -
> -@section Related binaries
> -
> -@subsection qemu-nbd --partition (removed in 5.0.0)
> -
> -The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
> -could only handle MBR partitions, and never correctly handled logical
> -partitions beyond partition 5.  Exporting a partition can still be
> -done by utilizing the @option{--image-opts} option with a raw blockdev
> -using the @code{offset} and @code{size} parameters layered on top of
> -any other existing blockdev. For example, if partition 1 is 100MiB
> -long starting at 1MiB, the old command:
> -
> -@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
> -
> -can be rewritten as:
> -
> -@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=
> 100M,file.driver=qcow2,file.file.driver=file,file.file.
> filename=file.qcow2}
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 7798e072a1c..6bb1fd54c03 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -40,8 +40,6 @@
>  * QEMU System emulator for non PC targets::
>  * QEMU User space emulator::
>  * System requirements::
> -* Deprecated features::
> -* Recently removed features::
>  * Supported build platforms::
>  * License::
>  * Index::
> @@ -2834,8 +2832,6 @@ added with Linux 4.5 which is supported by the major
> distros. And even
>  if RHEL7 has kernel 3.10, KVM there has the required functionality there
>  to make it close to a 4.5 or newer kernel.
>
> -@include qemu-deprecated.texi
> -
>  @node Supported build platforms
>  @appendix Supported build platforms
>
> --
> 2.20.1
>
>
>

[-- Attachment #2: Type: text/html, Size: 52452 bytes --]

Re: [PATCH 2/4] docs: Remove the "CPU emulation" part of the "Implementation notes"

[Aleksandar Markovic]

[-- Attachment #1: Type: text/plain, Size: 5768 bytes --]

On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@linaro.org>
wrote:

> The "CPU emulation" part of the "Implementation notes" in
> qemu-tech.texi looks like it is documenting what features of various
> CPUs we do or don't emulate.  However:
>  * it covers only six of our 21 guest architectures
>  * the last time anybody updated it for actual content was in
>    2011/2012 for Xtensa; the content for the other five
>    architectures is even older, being from 2008 or before!
>
> What we have is out of date, misleading and incomplete.
> Just delete this part of the document rather than trying to
> convert it to rST.
>
> (It would be nice eventually to have documentation of the
> scope and limitations of our emulation; but we will want to
> separate out the generic "system emulation" information from
> the parts that are specific to linux-user anyway, as they will
> be in different manuals.)
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---


I agree with the intent and the outcome of this patch, including the last
paragraph in braces.

FWIW:

Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com>


 qemu-tech.texi | 153 -------------------------------------------------
>  1 file changed, 153 deletions(-)
>
> diff --git a/qemu-tech.texi b/qemu-tech.texi
> index 0380de77b62..35da6a40af1 100644
> --- a/qemu-tech.texi
> +++ b/qemu-tech.texi
> @@ -2,162 +2,9 @@
>  @appendix Implementation notes
>
>  @menu
> -* CPU emulation::
>  * Managed start up options::
>  @end menu
>
> -@node CPU emulation
> -@section CPU emulation
> -
> -@menu
> -* x86::     x86 and x86-64 emulation
> -* ARM::     ARM emulation
> -* MIPS::    MIPS emulation
> -* PPC::     PowerPC emulation
> -* SPARC::   Sparc32 and Sparc64 emulation
> -* Xtensa::  Xtensa emulation
> -@end menu
> -
> -@node x86
> -@subsection x86 and x86-64 emulation
> -
> -QEMU x86 target features:
> -
> -@itemize
> -
> -@item The virtual x86 CPU supports 16 bit and 32 bit addressing with
> segmentation.
> -LDT/GDT and IDT are emulated. VM86 mode is also supported to run
> -DOSEMU. There is some support for MMX/3DNow!, SSE, SSE2, SSE3, SSSE3,
> -and SSE4 as well as x86-64 SVM.
> -
> -@item Support of host page sizes bigger than 4KB in user mode emulation.
> -
> -@item QEMU can emulate itself on x86.
> -
> -@item An extensive Linux x86 CPU test program is included
> @file{tests/test-i386}.
> -It can be used to test other x86 virtual CPUs.
> -
> -@end itemize
> -
> -Current QEMU limitations:
> -
> -@itemize
> -
> -@item Limited x86-64 support.
> -
> -@item IPC syscalls are missing.
> -
> -@item The x86 segment limits and access rights are not tested at every
> -memory access (yet). Hopefully, very few OSes seem to rely on that for
> -normal use.
> -
> -@end itemize
> -
> -@node ARM
> -@subsection ARM emulation
> -
> -@itemize
> -
> -@item Full ARM 7 user emulation.
> -
> -@item NWFPE FPU support included in user Linux emulation.
> -
> -@item Can run most ARM Linux binaries.
> -
> -@end itemize
> -
> -@node MIPS
> -@subsection MIPS emulation
> -
> -@itemize
> -
> -@item The system emulation allows full MIPS32/MIPS64 Release 2 emulation,
> -including privileged instructions, FPU and MMU, in both little and big
> -endian modes.
> -
> -@item The Linux userland emulation can run many 32 bit MIPS Linux
> binaries.
> -
> -@end itemize
> -
> -Current QEMU limitations:
> -
> -@itemize
> -
> -@item Self-modifying code is not always handled correctly.
> -
> -@item 64 bit userland emulation is not implemented.
> -
> -@item The system emulation is not complete enough to run real firmware.
> -
> -@item The watchpoint debug facility is not implemented.
> -
> -@end itemize
> -
> -@node PPC
> -@subsection PowerPC emulation
> -
> -@itemize
> -
> -@item Full PowerPC 32 bit emulation, including privileged instructions,
> -FPU and MMU.
> -
> -@item Can run most PowerPC Linux binaries.
> -
> -@end itemize
> -
> -@node SPARC
> -@subsection Sparc32 and Sparc64 emulation
> -
> -@itemize
> -
> -@item Full SPARC V8 emulation, including privileged
> -instructions, FPU and MMU. SPARC V9 emulation includes most privileged
> -and VIS instructions, FPU and I/D MMU. Alignment is fully enforced.
> -
> -@item Can run most 32-bit SPARC Linux binaries, SPARC32PLUS Linux
> binaries and
> -some 64-bit SPARC Linux binaries.
> -
> -@end itemize
> -
> -Current QEMU limitations:
> -
> -@itemize
> -
> -@item IPC syscalls are missing.
> -
> -@item Floating point exception support is buggy.
> -
> -@item Atomic instructions are not correctly implemented.
> -
> -@item There are still some problems with Sparc64 emulators.
> -
> -@end itemize
> -
> -@node Xtensa
> -@subsection Xtensa emulation
> -
> -@itemize
> -
> -@item Core Xtensa ISA emulation, including most options: code density,
> -loop, extended L32R, 16- and 32-bit multiplication, 32-bit division,
> -MAC16, miscellaneous operations, boolean, FP coprocessor, coprocessor
> -context, debug, multiprocessor synchronization,
> -conditional store, exceptions, relocatable vectors, unaligned exception,
> -interrupts (including high priority and timer), hardware alignment,
> -region protection, region translation, MMU, windowed registers, thread
> -pointer, processor ID.
> -
> -@item Not implemented options: data/instruction cache (including cache
> -prefetch and locking), XLMI, processor interface. Also options not
> -covered by the core ISA (e.g. FLIX, wide branches) are not implemented.
> -
> -@item Can run most Xtensa Linux binaries.
> -
> -@item New core configuration that requires no additional instructions
> -may be created from overlay with minimal amount of hand-written code.
> -
> -@end itemize
> -
>  @node Managed start up options
>  @section Managed start up options
>
> --
> 2.20.1
>
>
>

[-- Attachment #2: Type: text/html, Size: 6911 bytes --]

Re: [PATCH 1/4] docs: Convert security.texi to rST format

[Aleksandar Markovic]

[-- Attachment #1: Type: text/plain, Size: 10367 bytes --]

On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@linaro.org>
wrote:

> security.texi is included from qemu-doc.texi but is not used
> in the qemu.1 manpage. So we can do a straightforward conversion
> of the contents, which go into the system manual.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---


FWIW:

Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com>


>  Makefile                                    |  2 +-
>  docs/system/index.rst                       |  1 +
>  docs/{security.texi => system/security.rst} | 82 +++++++++++----------
>  qemu-doc.texi                               |  3 -
>  4 files changed, 46 insertions(+), 42 deletions(-)
>  rename docs/{security.texi => system/security.rst} (77%)
>
> diff --git a/Makefile b/Makefile
> index aa9cc0b5847..5f0f803b471 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1117,7 +1117,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf
> qemu-doc.txt: \
>         qemu-tech.texi qemu-option-trace.texi \
>         qemu-deprecated.texi qemu-monitor.texi \
>         qemu-monitor-info.texi \
> -       docs/qemu-cpu-models.texi docs/security.texi
> +       docs/qemu-cpu-models.texi
>
>  docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
>      docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index f66e6ea585c..794e5d8de03 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -15,3 +15,4 @@ Contents:
>     :maxdepth: 2
>
>     qemu-block-drivers
> +   security
> diff --git a/docs/security.texi b/docs/system/security.rst
> similarity index 77%
> rename from docs/security.texi
> rename to docs/system/security.rst
> index 0d6b30edfc0..f2092c8768b 100644
> --- a/docs/security.texi
> +++ b/docs/system/security.rst
> @@ -1,19 +1,22 @@
> -@node Security
> -@chapter Security
> +Security
> +========
>
> -@section Overview
> +Overview
> +--------
>
>  This chapter explains the security requirements that QEMU is designed to
> meet
>  and principles for securely deploying QEMU.
>
> -@section Security Requirements
> +Security Requirements
> +---------------------
>
>  QEMU supports many different use cases, some of which have stricter
> security
>  requirements than others.  The community has agreed on the overall
> security
>  requirements that users may depend on.  These requirements define what is
>  considered supported from a security perspective.
>
> -@subsection Virtualization Use Case
> +Virtualization Use Case
> +'''''''''''''''''''''''
>
>  The virtualization use case covers cloud and virtual private server (VPS)
>  hosting, as well as traditional data center and desktop virtualization.
> These
> @@ -23,18 +26,17 @@ safely on the physical CPU at close-to-native speed.
>  The following entities are untrusted, meaning that they may be buggy or
>  malicious:
>
> -@itemize
> -@item Guest
> -@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
> -@item Network protocols (e.g. NBD, live migration)
> -@item User-supplied files (e.g. disk images, kernels, device trees)
> -@item Passthrough devices (e.g. PCI, USB)
> -@end itemize
> +- Guest
> +- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
> +- Network protocols (e.g. NBD, live migration)
> +- User-supplied files (e.g. disk images, kernels, device trees)
> +- Passthrough devices (e.g. PCI, USB)
>
>  Bugs affecting these entities are evaluated on whether they can cause
> damage in
>  real-world use cases and treated as security bugs if this is the case.
>
> -@subsection Non-virtualization Use Case
> +Non-virtualization Use Case
> +'''''''''''''''''''''''''''
>
>  The non-virtualization use case covers emulation using the Tiny Code
> Generator
>  (TCG).  In principle the TCG and device emulation code used in
> conjunction with
> @@ -47,12 +49,14 @@ Bugs affecting the non-virtualization use case are not
> considered security
>  bugs at this time.  Users with non-virtualization use cases must not rely
> on
>  QEMU to provide guest isolation or any security guarantees.
>
> -@section Architecture
> +Architecture
> +------------
>
>  This section describes the design principles that ensure the security
>  requirements are met.
>
> -@subsection Guest Isolation
> +Guest Isolation
> +'''''''''''''''
>
>  Guest isolation is the confinement of guest code to the virtual machine.
> When
>  guest code gains control of execution on the host this is called escaping
> the
> @@ -71,7 +75,8 @@ malicious guest must not gain control of other guests or
> access their data.
>  Disk image files and network traffic must be protected from other guests
> unless
>  explicitly shared between them by the user.
>
> -@subsection Principle of Least Privilege
> +Principle of Least Privilege
> +''''''''''''''''''''''''''''
>
>  The principle of least privilege states that each component only has
> access to
>  the privileges necessary for its function.  In the case of QEMU this
> means that
> @@ -84,7 +89,7 @@ the guest.
>
>  Following the principle of least privilege immediately fulfills guest
> isolation
>  requirements.  For example, guest A only has access to its own disk image
> file
> -@code{a.img} and not guest B's disk image file @code{b.img}.
> +``a.img`` and not guest B's disk image file ``b.img``.
>
>  In reality certain resources are inaccessible to the guest but must be
>  available to QEMU to perform its function.  For example, host system
> calls are
> @@ -95,7 +100,8 @@ New features must be designed to follow the principle
> of least privilege.
>  Should this not be possible for technical reasons, the security risk must
> be
>  clearly documented so users are aware of the trade-off of enabling the
> feature.
>
> -@subsection Isolation mechanisms
> +Isolation mechanisms
> +''''''''''''''''''''
>
>  Several isolation mechanisms are available to realize this architecture of
>  guest isolation and the principle of least privilege.  With the exception
> of
> @@ -105,46 +111,46 @@ described briefly for Linux here.
>
>  The fundamental isolation mechanism is that QEMU processes must run as
>  unprivileged users.  Sometimes it seems more convenient to launch QEMU as
> -root to give it access to host devices (e.g. @code{/dev/net/tun}) but
> this poses a
> +root to give it access to host devices (e.g. ``/dev/net/tun``) but this
> poses a
>  huge security risk.  File descriptor passing can be used to give an
> otherwise
>  unprivileged QEMU process access to host devices without running QEMU as
> root.
>  It is also possible to launch QEMU as a non-root user and configure UNIX
> groups
> -for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device
> nodes.
> +for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
>  Some Linux distros already ship with UNIX groups for these devices by
> default.
>
> -@itemize
> -@item SELinux and AppArmor make it possible to confine processes beyond
> the
> -traditional UNIX process and file permissions model.  They restrict the
> QEMU
> -process from accessing processes and files on the host system that are not
> -needed by QEMU.
> +- SELinux and AppArmor make it possible to confine processes beyond the
> +  traditional UNIX process and file permissions model.  They restrict the
> QEMU
> +  process from accessing processes and files on the host system that are
> not
> +  needed by QEMU.
>
> -@item Resource limits and cgroup controllers provide throughput and
> utilization
> -limits on key resources such as CPU time, memory, and I/O bandwidth.
> +- Resource limits and cgroup controllers provide throughput and
> utilization
> +  limits on key resources such as CPU time, memory, and I/O bandwidth.
>
> -@item Linux namespaces can be used to make process, file system, and
> other system
> -resources unavailable to QEMU.  A namespaced QEMU process is restricted
> to only
> -those resources that were granted to it.
> +- Linux namespaces can be used to make process, file system, and other
> system
> +  resources unavailable to QEMU.  A namespaced QEMU process is restricted
> to only
> +  those resources that were granted to it.
>
> -@item Linux seccomp is available via the QEMU @option{--sandbox} option.
> It disables
> -system calls that are not needed by QEMU, thereby reducing the host kernel
> -attack surface.
> -@end itemize
> +- Linux seccomp is available via the QEMU ``--sandbox`` option.  It
> disables
> +  system calls that are not needed by QEMU, thereby reducing the host
> kernel
> +  attack surface.
>
> -@section Sensitive configurations
> +Sensitive configurations
> +------------------------
>
>  There are aspects of QEMU that can have security implications which users
> &
>  management applications must be aware of.
>
> -@subsection Monitor console (QMP and HMP)
> +Monitor console (QMP and HMP)
> +'''''''''''''''''''''''''''''
>
>  The monitor console (whether used with QMP or HMP) provides an interface
>  to dynamically control many aspects of QEMU's runtime operation. Many of
> the
>  commands exposed will instruct QEMU to access content on the host file
> system
>  and/or trigger spawning of external processes.
>
> -For example, the @code{migrate} command allows for the spawning of
> arbitrary
> +For example, the ``migrate`` command allows for the spawning of arbitrary
>  processes for the purpose of tunnelling the migration data stream. The
> -@code{blockdev-add} command instructs QEMU to open arbitrary files,
> exposing
> +``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
>  their content to the guest as a virtual disk.
>
>  Unless QEMU is otherwise confined using technologies such as SELinux,
> AppArmor,
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 33b9597b1dc..c11b1a5d5ad 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -40,7 +40,6 @@
>  * QEMU System emulator for non PC targets::
>  * QEMU User space emulator::
>  * System requirements::
> -* Security::
>  * Implementation notes::
>  * Deprecated features::
>  * Recently removed features::
> @@ -2836,8 +2835,6 @@ added with Linux 4.5 which is supported by the major
> distros. And even
>  if RHEL7 has kernel 3.10, KVM there has the required functionality there
>  to make it close to a 4.5 or newer kernel.
>
> -@include docs/security.texi
> -
>  @include qemu-tech.texi
>
>  @include qemu-deprecated.texi
> --
> 2.20.1
>
>
>

[-- Attachment #2: Type: text/html, Size: 12327 bytes --]

Re: [PATCH 3/4] docs: Convert 'managed start up options' docs to rST

[Aleksandar Markovic]

[-- Attachment #1: Type: text/plain, Size: 6446 bytes --]

On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@linaro.org>
wrote:

> The only remaining content in qemu-tech.texi is a few paragraphs
> about managed start up options; move them to a new rST document
> in the system manual.
>
> In the process we fix one typo and format more option and
> command names as literal text, but make no significant
> changes to the content.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---


FWIW:

Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com>


>  Makefile                        |  2 +-
>  docs/system/index.rst           |  1 +
>  docs/system/managed-startup.rst | 35 +++++++++++++++++++++++++++
>  qemu-doc.texi                   |  3 ---
>  qemu-tech.texi                  | 42 ---------------------------------
>  5 files changed, 37 insertions(+), 46 deletions(-)
>  create mode 100644 docs/system/managed-startup.rst
>  delete mode 100644 qemu-tech.texi
>
> diff --git a/Makefile b/Makefile
> index 5f0f803b471..28749d20401 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1114,7 +1114,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt
> docs/interop/qemu-ga-ref.txt
>
>  qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
>         qemu-options.texi \
> -       qemu-tech.texi qemu-option-trace.texi \
> +       qemu-option-trace.texi \
>         qemu-deprecated.texi qemu-monitor.texi \
>         qemu-monitor-info.texi \
>         docs/qemu-cpu-models.texi
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 794e5d8de03..887bef92f40 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -14,5 +14,6 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>
> +   managed-startup
>     qemu-block-drivers
>     security
> diff --git a/docs/system/managed-startup.rst
> b/docs/system/managed-startup.rst
> new file mode 100644
> index 00000000000..9bcf98ea790
> --- /dev/null
> +++ b/docs/system/managed-startup.rst
> @@ -0,0 +1,35 @@
> +Managed start up options
> +========================
> +
> +In system mode emulation, it's possible to create a VM in a paused
> +state using the ``-S`` command line option. In this state the machine
> +is completely initialized according to command line options and ready
> +to execute VM code but VCPU threads are not executing any code. The VM
> +state in this paused state depends on the way QEMU was started. It
> +could be in:
> +
> +- initial state (after reset/power on state)
> +- with direct kernel loading, the initial state could be amended to
> execute
> +  code loaded by QEMU in the VM's RAM and with incoming migration
> +- with incoming migration, initial state will be amended with the migrated
> +  machine state after migration completes
> +
> +This paused state is typically used by users to query machine state and/or
> +additionally configure the machine (by hotplugging devices) in runtime
> before
> +allowing VM code to run.
> +
> +However, at the ``-S`` pause point, it's impossible to configure options
> +that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or
> +cold plug devices. The experimental ``--preconfig`` command line option
> +allows pausing QEMU before the initial VM creation, in a "preconfig"
> state,
> +where additional queries and configuration can be performed via QMP
> +before moving on to the resulting configuration startup. In the
> +preconfig state, QEMU only allows a limited set of commands over the
> +QMP monitor, where the commands do not depend on an initialized
> +machine, including but not limited to:
> +
> +- ``qmp_capabilities``
> +- ``query-qmp-schema``
> +- ``query-commands``
> +- ``query-status``
> +- ``x-exit-preconfig``
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index c11b1a5d5ad..7798e072a1c 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -40,7 +40,6 @@
>  * QEMU System emulator for non PC targets::
>  * QEMU User space emulator::
>  * System requirements::
> -* Implementation notes::
>  * Deprecated features::
>  * Recently removed features::
>  * Supported build platforms::
> @@ -2835,8 +2834,6 @@ added with Linux 4.5 which is supported by the major
> distros. And even
>  if RHEL7 has kernel 3.10, KVM there has the required functionality there
>  to make it close to a 4.5 or newer kernel.
>
> -@include qemu-tech.texi
> -
>  @include qemu-deprecated.texi
>
>  @node Supported build platforms
> diff --git a/qemu-tech.texi b/qemu-tech.texi
> deleted file mode 100644
> index 35da6a40af1..00000000000
> --- a/qemu-tech.texi
> +++ /dev/null
> @@ -1,42 +0,0 @@
> -@node Implementation notes
> -@appendix Implementation notes
> -
> -@menu
> -* Managed start up options::
> -@end menu
> -
> -@node Managed start up options
> -@section Managed start up options
> -
> -In system mode emulation, it's possible to create a VM in a paused state
> using
> -the -S command line option. In this state the machine is completely
> initialized
> -according to command line options and ready to execute VM code but VCPU
> threads
> -are not executing any code. The VM state in this paused state depends on
> the way
> -QEMU was started. It could be in:
> -@table @asis
> -@item initial state (after reset/power on state)
> -@item with direct kernel loading, the initial state could be amended to
> execute
> -code loaded by QEMU in the VM's RAM and with incoming migration
> -@item with incoming migration, initial state will by amended with the
> migrated
> -machine state after migration completes.
> -@end table
> -
> -This paused state is typically used by users to query machine state and/or
> -additionally configure the machine (by hotplugging devices) in runtime
> before
> -allowing VM code to run.
> -
> -However, at the -S pause point, it's impossible to configure options that
> affect
> -initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The
> -experimental --preconfig command line option  allows pausing QEMU
> -before the initial VM creation, in a ``preconfig'' state, where additional
> -queries and configuration can be performed via QMP before moving on to
> -the resulting configuration startup. In the preconfig state, QEMU only
> allows
> -a limited set of commands over the QMP monitor, where the commands do not
> -depend on an initialized machine, including but not limited to:
> -@table @asis
> -@item qmp_capabilities
> -@item query-qmp-schema
> -@item query-commands
> -@item query-status
> -@item x-exit-preconfig
> -@end table
> --
> 2.20.1
>
>
>

[-- Attachment #2: Type: text/html, Size: 7567 bytes --]