deprecated.rst (15747B)
1 .. _Deprecated features: 2 3 Deprecated features 4 =================== 5 6 In general features are intended to be supported indefinitely once 7 introduced into QEMU. In the event that a feature needs to be removed, 8 it will be listed in this section. The feature will remain functional for the 9 release in which it was deprecated and one further release. After these two 10 releases, the feature is liable to be removed. Deprecated features may also 11 generate warnings on the console when QEMU starts up, or if activated via a 12 monitor command, however, this is not a mandatory requirement. 13 14 Prior to the 2.10.0 release there was no official policy on how 15 long features would be deprecated prior to their removal, nor 16 any documented list of which features were deprecated. Thus 17 any features deprecated prior to 2.10.0 will be treated as if 18 they were first deprecated in the 2.10.0 release. 19 20 What follows is a list of all features currently marked as 21 deprecated. 22 23 System emulator command line arguments 24 -------------------------------------- 25 26 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) 27 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 28 29 The ``-audiodev`` argument is now the preferred way to specify audio 30 backend settings instead of environment variables. To ease migration to 31 the new format, the ``-audiodev-help`` option can be used to convert 32 the current values of the environment variables to ``-audiodev`` options. 33 34 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) 35 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 36 37 When not using the deprecated legacy audio config, each sound card 38 should specify an ``audiodev=`` property. Additionally, when using 39 vnc, you should specify an ``audiodev=`` property if you plan to 40 transmit audio through the VNC protocol. 41 42 ``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 43 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 44 45 ``tty`` and ``parport`` are aliases that will be removed. Instead, the 46 actual backend names ``serial`` and ``parallel`` should be used. 47 48 Short-form boolean options (since 6.0) 49 '''''''''''''''''''''''''''''''''''''' 50 51 Boolean options such as ``share=on``/``share=off`` could be written 52 in short form as ``share`` and ``noshare``. This is now deprecated 53 and will cause a warning. 54 55 ``delay`` option for socket character devices (since 6.0) 56 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 57 58 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 59 rather than ``delay=off``. 60 61 Userspace local APIC with KVM (x86, since 6.0) 62 '''''''''''''''''''''''''''''''''''''''''''''' 63 64 Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 65 APIC is deprecated. The ``split`` setting is supported, as is using 66 ``-M kernel-irqchip=off`` with the ISA PC machine type. 67 68 hexadecimal sizes with scaling multipliers (since 6.0) 69 '''''''''''''''''''''''''''''''''''''''''''''''''''''' 70 71 Input parameters that take a size value should only use a size suffix 72 (such as 'k' or 'M') when the base is written in decimal, and not when 73 the value is hexadecimal. That is, '0x20M' is deprecated, and should 74 be written either as '32M' or as '0x2000000'. 75 76 ``-spice password=string`` (since 6.0) 77 '''''''''''''''''''''''''''''''''''''' 78 79 This option is insecure because the SPICE password remains visible in 80 the process listing. This is replaced by the new ``password-secret`` 81 option which lets the password be securely provided on the command 82 line using a ``secret`` object instance. 83 84 ``-smp`` ("parameter=0" SMP configurations) (since 6.2) 85 ''''''''''''''''''''''''''''''''''''''''''''''''''''''' 86 87 Specified CPU topology parameters must be greater than zero. 88 89 In the SMP configuration, users should either provide a CPU topology 90 parameter with a reasonable value (greater than zero) or just omit it 91 and QEMU will compute the missing value. 92 93 However, historically it was implicitly allowed for users to provide 94 a parameter with zero value, which is meaningless and could also possibly 95 cause unexpected results in the -smp parsing. So support for this kind of 96 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 97 be removed in the near future, users have to ensure that all the topology 98 members described with -smp are greater than zero. 99 100 Plugin argument passing through ``arg=<string>`` (since 6.1) 101 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 102 103 Passing TCG plugins arguments through ``arg=`` is redundant is makes the 104 command-line less readable, especially when the argument itself consist of a 105 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 106 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 107 as short-form boolean values, and passed to plugins as ``arg_name=on``. 108 However, short-form booleans are deprecated and full explicit ``arg_name=on`` 109 form is preferred. 110 111 ``-drive if=none`` for the sifive_u OTP device (since 6.2) 112 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 113 114 Using ``-drive if=none`` to configure the OTP device of the sifive_u 115 RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 116 117 118 QEMU Machine Protocol (QMP) commands 119 ------------------------------------ 120 121 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 122 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 123 124 Use argument ``id`` instead. 125 126 ``eject`` argument ``device`` (since 2.8) 127 ''''''''''''''''''''''''''''''''''''''''' 128 129 Use argument ``id`` instead. 130 131 ``blockdev-change-medium`` argument ``device`` (since 2.8) 132 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 133 134 Use argument ``id`` instead. 135 136 ``block_set_io_throttle`` argument ``device`` (since 2.8) 137 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 138 139 Use argument ``id`` instead. 140 141 ``blockdev-add`` empty string argument ``backing`` (since 2.10) 142 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 143 144 Use argument value ``null`` instead. 145 146 ``block-commit`` arguments ``base`` and ``top`` (since 3.1) 147 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 148 149 Use arguments ``base-node`` and ``top-node`` instead. 150 151 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 152 '''''''''''''''''''''''''''''''''''''''''''''''''''''''' 153 154 Use the more generic commands ``block-export-add`` and ``block-export-del`` 155 instead. As part of this deprecation, where ``nbd-server-add`` used a 156 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 157 158 ``query-qmp-schema`` return value member ``values`` (since 6.2) 159 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 160 161 Member ``values`` in return value elements with meta-type ``enum`` is 162 deprecated. Use ``members`` instead. 163 164 ``drive-backup`` (since 6.2) 165 '''''''''''''''''''''''''''' 166 167 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 168 This change primarily separates the creation/opening process of the backup 169 target with explicit, separate steps. ``blockdev-backup`` uses mostly the 170 same arguments as ``drive-backup``, except the ``format`` and ``mode`` 171 options are removed in favor of using explicit ``blockdev-create`` and 172 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 173 details. 174 175 Incorrectly typed ``device_add`` arguments (since 6.2) 176 '''''''''''''''''''''''''''''''''''''''''''''''''''''' 177 178 Due to shortcomings in the internal implementation of ``device_add``, QEMU 179 incorrectly accepts certain invalid arguments: Any object or list arguments are 180 silently ignored. Other argument types are not checked, but an implicit 181 conversion happens, so that e.g. string values can be assigned to integer 182 device properties or vice versa. 183 184 This is a bug in QEMU that will be fixed in the future so that previously 185 accepted incorrect commands will return an error. Users should make sure that 186 all arguments passed to ``device_add`` are consistent with the documented 187 property types. 188 189 ``query-sgx`` return value member ``section-size`` (since 7.0) 190 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 191 192 Member ``section-size`` in return value elements with meta-type ``uint64`` is 193 deprecated. Use ``sections`` instead. 194 195 196 ``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 197 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 198 199 Member ``section-size`` in return value elements with meta-type ``uint64`` is 200 deprecated. Use ``sections`` instead. 201 202 System accelerators 203 ------------------- 204 205 MIPS ``Trap-and-Emul`` KVM support (since 6.0) 206 '''''''''''''''''''''''''''''''''''''''''''''' 207 208 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 209 from Linux upstream kernel, declare it deprecated. 210 211 Host Architectures 212 ------------------ 213 214 BE MIPS (since 7.2) 215 ''''''''''''''''''' 216 217 As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 218 MIPS moved out of support making it hard to maintain our 219 cross-compilation CI tests of the architecture. As we no longer have 220 CI coverage support may bitrot away before the deprecation process 221 completes. The little endian variants of MIPS (both 32 and 64 bit) are 222 still a supported host architecture. 223 224 QEMU API (QAPI) events 225 ---------------------- 226 227 ``MEM_UNPLUG_ERROR`` (since 6.2) 228 '''''''''''''''''''''''''''''''''''''''''''''''''''''''' 229 230 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 231 232 233 System emulator machines 234 ------------------------ 235 236 Arm ``virt`` machine ``dtb-kaslr-seed`` property 237 '''''''''''''''''''''''''''''''''''''''''''''''' 238 239 The ``dtb-kaslr-seed`` property on the ``virt`` board has been 240 deprecated; use the new name ``dtb-randomness`` instead. The new name 241 better reflects the way this property affects all random data within 242 the device tree blob, not just the ``kaslr-seed`` node. 243 244 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) 245 ''''''''''''''''''''''''''''''''''''''''''''''''''''' 246 247 These old machine types are quite neglected nowadays and thus might have 248 various pitfalls with regards to live migration. Use a newer machine type 249 instead. 250 251 252 Backend options 253 --------------- 254 255 Using non-persistent backing file with pmem=on (since 6.1) 256 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 257 258 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 259 device. However enabling ``memory-backend-file.pmem`` option, when backing file 260 is (a) not DAX capable or (b) not on a filesystem that support direct mapping 261 of persistent memory, is not safe and may lead to data loss or corruption in case 262 of host crash. 263 Options are: 264 265 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 266 (without persistence guaranties) with backing file on non DAX storage 267 - move backing file to NVDIMM storage and keep ``pmem=on`` 268 (to have NVDIMM with persistence guaranties). 269 270 Device options 271 -------------- 272 273 Emulated device options 274 ''''''''''''''''''''''' 275 276 ``-device virtio-blk,scsi=on|off`` (since 5.0) 277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 278 279 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 280 and later do not support it because the virtio-scsi device was introduced for 281 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 282 283 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 284 alias. 285 286 ``-device sga`` (since 6.2) 287 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 288 289 The ``sga`` device loads an option ROM for x86 targets which enables 290 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 291 contains native support for this feature and thus use of the option 292 ROM approach is obsolete. The native SeaBIOS support can be activated 293 by using ``-machine graphics=off``. 294 295 ``-device nvme-ns,eui64-default=on|off`` (since 7.1) 296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 297 298 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 299 identifier that is not globally unique. If an EUI-64 identifier is required, the 300 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 301 302 ``-device nvme,use-intel-id=on|off`` (since 7.1) 303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 304 305 The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 306 from Intel that was not properly allocated. Since version 5.2, the controller 307 has used a properly allocated identifier. Deprecate the ``use-intel-id`` 308 machine compatibility parameter. 309 310 311 Block device options 312 '''''''''''''''''''' 313 314 ``"backing": ""`` (since 2.12) 315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 316 317 In order to prevent QEMU from automatically opening an image's backing 318 chain, use ``"backing": null`` instead. 319 320 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 321 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 322 323 Options for ``rbd`` should be specified according to its runtime options, 324 like other block drivers. Legacy parsing of keyvalue pair encoded 325 filenames is useful to open images with the old format for backing files; 326 These image files should be updated to use the current format. 327 328 Example of legacy encoding:: 329 330 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 331 332 The above, converted to the current supported format:: 333 334 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 335 336 Backwards compatibility 337 ----------------------- 338 339 Runnability guarantee of CPU models (since 4.1) 340 ''''''''''''''''''''''''''''''''''''''''''''''' 341 342 Previous versions of QEMU never changed existing CPU models in 343 ways that introduced additional host software or hardware 344 requirements to the VM. This allowed management software to 345 safely change the machine type of an existing VM without 346 introducing new requirements ("runnability guarantee"). This 347 prevented CPU models from being updated to include CPU 348 vulnerability mitigations, leaving guests vulnerable in the 349 default configuration. 350 351 The CPU model runnability guarantee won't apply anymore to 352 existing CPU models. Management software that needs runnability 353 guarantees must resolve the CPU model aliases using the 354 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP 355 command. 356 357 While those guarantees are kept, the return value of 358 ``query-cpu-definitions`` will have existing CPU model aliases 359 point to a version that doesn't break runnability guarantees 360 (specifically, version 1 of those CPU models). In future QEMU 361 versions, aliases will point to newer CPU model versions 362 depending on the machine type, so management software must 363 resolve CPU model aliases before starting a virtual machine. 364 365 Tools 366 ----- 367 368 virtiofsd 369 ''''''''' 370 371 There is a new Rust implementation of ``virtiofsd`` at 372 ``https://gitlab.com/virtio-fs/virtiofsd``; 373 since this is now marked stable, new development should be done on that 374 rather than the existing C version in the QEMU tree. 375 The C version will still accept fixes and patches that 376 are already in development for the moment, but will eventually 377 be deleted from this tree. 378 New deployments should use the Rust version, and existing systems 379 should consider moving to it. The command line and feature set 380 is very close and moving should be simple. 381 382 383 QEMU guest agent 384 ---------------- 385 386 ``--blacklist`` command line option (since 7.2) 387 ''''''''''''''''''''''''''''''''''''''''''''''' 388 389 ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better 390 wording for what this option does). The short form ``-b`` still stays 391 the same and thus is the preferred way for scripts that should run with 392 both, older and future versions of QEMU. 393 394 ``blacklist`` config file option (since 7.2) 395 '''''''''''''''''''''''''''''''''''''''''''' 396 397 The ``blacklist`` config file option has been renamed to ``block-rpcs`` 398 (to be in sync with the renaming of the corresponding command line 399 option).