X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/68df0c30edf0b9766a2364cbf12328db3d7284e8..f7e81a945737631c19405a39d510d2284257c3ff:/qemu-deprecated.texi diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi index 674cc3fdf8..f7680c08e1 100644 --- a/qemu-deprecated.texi +++ b/qemu-deprecated.texi @@ -37,21 +37,6 @@ 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 -virtioconsole (since 3.0.0) - -Option @option{-virtioconsole} has been replaced by -@option{-device virtconsole}. - -@subsection -clock (since 3.0.0) - -The @code{-clock} option is ignored since QEMU version 1.7.0. There is no -replacement since it is not needed anymore. - -@subsection -enable-hax (since 3.0.0) - -The @option{-enable-hax} option has been replaced by @option{-accel hax}. -Both options have been introduced in QEMU version 2.9.0. - @subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0) The 'file' driver for drives is no longer appropriate for character or host @@ -75,6 +60,87 @@ 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 -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 -virtfs_synth (since 4.1) + +The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth'' +and ``-device virtio-9p-...'' instead. + +@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 `` - Tells QEMU to load the specified file as the firmwrae. + @section QEMU Machine Protocol (QMP) commands @subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0) @@ -82,6 +148,12 @@ topologies described with -smp include all possible cpus, i.e. "autoload" parameter is now ignored. All bitmaps are automatically loaded from qcow2 images. +@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-cpus (since 2.12.0) The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. @@ -97,6 +169,16 @@ 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) @@ -109,6 +191,35 @@ The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and 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 bluetooth (since 3.1) @@ -131,6 +242,12 @@ This machine type uses an unmaintained firmware, broken in lots of ways, and unable to start post-2004 operating systems. 40p 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 Block device options @@ -187,3 +304,37 @@ Note that if you are exposing the export via /dev/nbd0, it is easier to just export the entire image and then mount only /dev/nbd0p1 than it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a subset of the image. + +@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 Build system + +@subsection Python 2 support (since 4.1.0) + +In the future, QEMU will require Python 3 to be available at +build time. Support for Python 2 in scripts shipped with QEMU +is deprecated. + +@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.