numa: drop support for '-numa node' (without memory specified)
[qemu.git] / docs / system / deprecated.rst
1 Deprecated features
2 ===================
3
4 In general features are intended to be supported indefinitely once
5 introduced into QEMU. In the event that a feature needs to be removed,
6 it will be listed in this section. The feature will remain functional for the
7 release in which it was deprecated and one further release. After these two
8 releases, the feature is liable to be removed. Deprecated features may also
9 generate warnings on the console when QEMU starts up, or if activated via a
10 monitor command, however, this is not a mandatory requirement.
11
12 Prior to the 2.10.0 release there was no official policy on how
13 long features would be deprecated prior to their removal, nor
14 any documented list of which features were deprecated. Thus
15 any features deprecated prior to 2.10.0 will be treated as if
16 they were first deprecated in the 2.10.0 release.
17
18 What follows is a list of all features currently marked as
19 deprecated.
20
21 System emulator command line arguments
22 --------------------------------------
23
24 ``-machine enforce-config-section=on|off`` (since 3.1)
25 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
26
27 The ``enforce-config-section`` parameter is replaced by the
28 ``-global migration.send-configuration={on|off}`` option.
29
30 ``-no-kvm`` (since 1.3.0)
31 '''''''''''''''''''''''''
32
33 The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
34
35 ``-usbdevice`` (since 2.10.0)
36 '''''''''''''''''''''''''''''
37
38 The ``-usbdevice DEV`` argument is now a synonym for setting
39 the ``-device usb-DEV`` argument instead. The deprecated syntax
40 would automatically enable USB support on the machine type.
41 If using the new syntax, USB support must be explicitly
42 enabled via the ``-machine usb=on`` argument.
43
44 ``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
45 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
46
47 The 'file' driver for drives is no longer appropriate for character or host
48 devices and will only accept regular files (S_IFREG). The correct driver
49 for these file types is 'host_cdrom' or 'host_device' as appropriate.
50
51 ``-vnc acl`` (since 4.0.0)
52 ''''''''''''''''''''''''''
53
54 The ``acl`` option to the ``-vnc`` argument has been replaced
55 by the ``tls-authz`` and ``sasl-authz`` options.
56
57 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
58 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
59
60 The ``-audiodev`` argument is now the preferred way to specify audio
61 backend settings instead of environment variables.  To ease migration to
62 the new format, the ``-audiodev-help`` option can be used to convert
63 the current values of the environment variables to ``-audiodev`` options.
64
65 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
66 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
67
68 When not using the deprecated legacy audio config, each sound card
69 should specify an ``audiodev=`` property.  Additionally, when using
70 vnc, you should specify an ``audiodev=`` property if you plan to
71 transmit audio through the VNC protocol.
72
73 Creating sound card devices using ``-soundhw`` (since 5.1)
74 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
75
76 Sound card devices should be created using ``-device`` instead.  The
77 names are the same for most devices.  The exceptions are ``hda`` which
78 needs two devices (``-device intel-hda -device hda-duplex``) and
79 ``pcspk`` which can be activated using ``-machine
80 pcspk-audiodev=<name>``.
81
82 ``-mon ...,control=readline,pretty=on|off`` (since 4.1)
83 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
84
85 The ``pretty=on|off`` switch has no effect for HMP monitors, but is
86 silently ignored. Using the switch with HMP monitors will become an
87 error in the future.
88
89 ``-realtime`` (since 4.1)
90 '''''''''''''''''''''''''
91
92 The ``-realtime mlock=on|off`` argument has been replaced by the
93 ``-overcommit mem-lock=on|off`` argument.
94
95 ``-mem-path`` fallback to RAM (since 4.1)
96 '''''''''''''''''''''''''''''''''''''''''
97
98 Currently if guest RAM allocation from file pointed by ``mem-path``
99 fails, QEMU falls back to allocating from RAM, which might result
100 in unpredictable behavior since the backing file specified by the user
101 is ignored. In the future, users will be responsible for making sure
102 the backing storage specified with ``-mem-path`` can actually provide
103 the guest RAM configured with ``-m`` and QEMU will fail to start up if
104 RAM allocation is unsuccessful.
105
106 RISC-V ``-bios`` (since 5.1)
107 ''''''''''''''''''''''''''''
108
109 QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
110 RISC-V virt machine and sifive_u machine. QEMU 4.1 had no changes to the
111 default behaviour to avoid breakages.
112
113 QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default``.
114
115 QEMU 5.1 has three options:
116  1. ``-bios default`` - This is the current default behavior if no -bios option
117       is included. This option will load the default OpenSBI firmware automatically.
118       The firmware is included with the QEMU release and no user interaction is
119       required. All a user needs to do is specify the kernel they want to boot
120       with the -kernel option
121  2. ``-bios none`` - QEMU will not automatically load any firmware. It is up
122       to the user to load all the images they need.
123  3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
124
125 ``-tb-size`` option (since 5.0)
126 '''''''''''''''''''''''''''''''
127
128 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
129 block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
130 previously available ``-tb-size`` option.
131
132 ``-show-cursor`` option (since 5.0)
133 '''''''''''''''''''''''''''''''''''
134
135 Use ``-display sdl,show-cursor=on`` or
136  ``-display gtk,show-cursor=on`` instead.
137
138 ``Configuring floppies with ``-global``
139 '''''''''''''''''''''''''''''''''''''''
140
141 Use ``-device floppy,...`` instead:
142 ::
143
144     -global isa-fdc.driveA=...
145     -global sysbus-fdc.driveA=...
146     -global SUNW,fdtwo.drive=...
147
148 become
149 ::
150
151     -device floppy,unit=0,drive=...
152
153 and
154 ::
155
156     -global isa-fdc.driveB=...
157     -global sysbus-fdc.driveB=...
158
159 become
160 ::
161
162     -device floppy,unit=1,drive=...
163
164 ``-drive`` with bogus interface type
165 ''''''''''''''''''''''''''''''''''''
166
167 Drives with interface types other than ``if=none`` are for onboard
168 devices.  It is possible to use drives the board doesn't pick up with
169 -device.  This usage is now deprecated.  Use ``if=none`` instead.
170
171
172 QEMU Machine Protocol (QMP) commands
173 ------------------------------------
174
175 ``change`` (since 2.5.0)
176 ''''''''''''''''''''''''
177
178 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
179
180 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0)
181 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
182
183 Use argument ``id`` instead.
184
185 ``eject`` argument ``device`` (since 2.8.0)
186 '''''''''''''''''''''''''''''''''''''''''''
187
188 Use argument ``id`` instead.
189
190 ``blockdev-change-medium`` argument ``device`` (since 2.8.0)
191 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
192
193 Use argument ``id`` instead.
194
195 ``block_set_io_throttle`` argument ``device`` (since 2.8.0)
196 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
197
198 Use argument ``id`` instead.
199
200 ``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
201 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
202
203 Use ``migrate-set-parameters`` instead.
204
205 ``query-named-block-nodes`` result ``encryption_key_missing`` (since 2.10.0)
206 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
207
208 Always false.
209
210 ``query-block`` result ``inserted.encryption_key_missing`` (since 2.10.0)
211 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
212
213 Always false.
214
215 ``blockdev-add`` empty string argument ``backing`` (since 2.10.0)
216 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
217
218 Use argument value ``null`` instead.
219
220 ``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
221 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
222
223 Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
224
225 ``block-commit`` arguments ``base`` and ``top`` (since 3.1.0)
226 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
227
228 Use arguments ``base-node`` and ``top-node`` instead.
229
230 ``object-add`` option ``props`` (since 5.0)
231 '''''''''''''''''''''''''''''''''''''''''''
232
233 Specify the properties for the object as top-level arguments instead.
234
235 ``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (since 4.0)
236 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
237
238 The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
239 these commands is deprecated. Two new boolean fields, ``recording`` and
240 ``busy`` effectively replace it.
241
242 ``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
243 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
244
245 The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
246 the query-block command is itself now deprecated. The ``dirty-bitmaps``
247 field of the ``BlockDeviceInfo`` struct should be used instead, which is the
248 type of the ``inserted`` field in query-block replies, as well as the
249 type of array items in query-named-block-nodes.
250
251 Since the ``dirty-bitmaps`` field is optionally present in both the old and
252 new locations, clients must use introspection to learn where to anticipate
253 the field if/when it does appear in command output.
254
255 ``query-cpus`` (since 2.12.0)
256 '''''''''''''''''''''''''''''
257
258 The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
259
260 ``query-cpus-fast`` ``arch`` output member (since 3.0.0)
261 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
262
263 The ``arch`` output member of the ``query-cpus-fast`` command is
264 replaced by the ``target`` output member.
265
266 ``query-events`` (since 4.0)
267 ''''''''''''''''''''''''''''
268
269 The ``query-events`` command has been superseded by the more powerful
270 and accurate ``query-qmp-schema`` command.
271
272 chardev client socket with ``wait`` option (since 4.0)
273 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
274
275 Character devices creating sockets in client mode should not specify
276 the 'wait' field, which is only applicable to sockets in server mode
277
278 Human Monitor Protocol (HMP) commands
279 -------------------------------------
280
281 ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
282 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
283
284 The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
285 ``acl_remove`` commands are deprecated with no replacement. Authorization
286 for VNC should be performed using the pluggable QAuthZ objects.
287
288 System emulator CPUS
289 --------------------
290
291 ``compat`` property of server class POWER CPUs (since 5.0)
292 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
293
294 The ``compat`` property used to set backwards compatibility modes for
295 the processor has been deprecated. The ``max-cpu-compat`` property of
296 the ``pseries`` machine type should be used instead.
297
298 ``lm32`` CPUs (since 5.2.0)
299 '''''''''''''''''''''''''''
300
301 The ``lm32`` guest CPU support is deprecated and will be removed in
302 a future version of QEMU. The only public user of this architecture
303 was the milkymist project, which has been dead for years; there was
304 never an upstream Linux port.
305
306 ``unicore32`` CPUs (since 5.2.0)
307 ''''''''''''''''''''''''''''''''
308
309 The ``unicore32`` guest CPU support is deprecated and will be removed in
310 a future version of QEMU. Support for this CPU was removed from the
311 upstream Linux kernel, and there is no available upstream toolchain
312 to build binaries for it.
313
314 System emulator devices
315 -----------------------
316
317 ``ide-drive`` (since 4.2)
318 '''''''''''''''''''''''''
319
320 The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
321 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
322
323 ``scsi-disk`` (since 4.2)
324 '''''''''''''''''''''''''
325
326 The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
327 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
328
329 System emulator machines
330 ------------------------
331
332 mips ``r4k`` platform (since 5.0)
333 '''''''''''''''''''''''''''''''''
334
335 This machine type is very old and unmaintained. Users should use the ``malta``
336 machine type instead.
337
338 mips ``fulong2e`` machine (since 5.1)
339 '''''''''''''''''''''''''''''''''''''
340
341 This machine has been renamed ``fuloong2e``.
342
343 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
344 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
345
346 These machine types are very old and likely can not be used for live migration
347 from old QEMU versions anymore. A newer machine type should be used instead.
348
349 Device options
350 --------------
351
352 Emulated device options
353 '''''''''''''''''''''''
354
355 ``-device virtio-blk,scsi=on|off`` (since 5.0.0)
356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
357
358 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
359 and later do not support it because the virtio-scsi device was introduced for
360 full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
361
362 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
363 alias.
364
365 Block device options
366 ''''''''''''''''''''
367
368 ``"backing": ""`` (since 2.12.0)
369 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370
371 In order to prevent QEMU from automatically opening an image's backing
372 chain, use ``"backing": null`` instead.
373
374 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
376
377 Options for ``rbd`` should be specified according to its runtime options,
378 like other block drivers.  Legacy parsing of keyvalue pair encoded
379 filenames is useful to open images with the old format for backing files;
380 These image files should be updated to use the current format.
381
382 Example of legacy encoding::
383
384   json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
385
386 The above, converted to the current supported format::
387
388   json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
389
390 linux-user mode CPUs
391 --------------------
392
393 ``tilegx`` CPUs (since 5.1.0)
394 '''''''''''''''''''''''''''''
395
396 The ``tilegx`` guest CPU support (which was only implemented in
397 linux-user mode) is deprecated and will be removed in a future version
398 of QEMU. Support for this CPU was removed from the upstream Linux
399 kernel in 2018, and has also been dropped from glibc.
400
401 ``ppc64abi32`` CPUs (since 5.2.0)
402 '''''''''''''''''''''''''''''''''
403
404 The ``ppc64abi32`` architecture has a number of issues which regularly
405 trip up our CI testing and is suspected to be quite broken. For that
406 reason the maintainers strongly suspect no one actually uses it.
407
408 Related binaries
409 ----------------
410
411 qemu-img amend to adjust backing file (since 5.1)
412 '''''''''''''''''''''''''''''''''''''''''''''''''
413
414 The use of ``qemu-img amend`` to modify the name or format of a qcow2
415 backing image is deprecated; this functionality was never fully
416 documented or tested, and interferes with other amend operations that
417 need access to the original backing image (such as deciding whether a
418 v3 zero cluster may be left unallocated when converting to a v2
419 image).  Rather, any changes to the backing chain should be performed
420 with ``qemu-img rebase -u`` either before or after the remaining
421 changes being performed by amend, as appropriate.
422
423 qemu-img backing file without format (since 5.1)
424 ''''''''''''''''''''''''''''''''''''''''''''''''
425
426 The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img
427 convert`` to create or modify an image that depends on a backing file
428 now recommends that an explicit backing format be provided.  This is
429 for safety: if QEMU probes a different format than what you thought,
430 the data presented to the guest will be corrupt; similarly, presenting
431 a raw image to a guest allows a potential security exploit if a future
432 probe sees a non-raw image based on guest writes.
433
434 To avoid the warning message, or even future refusal to create an
435 unsafe image, you must pass ``-o backing_fmt=`` (or the shorthand
436 ``-F`` during create) to specify the intended backing format.  You may
437 use ``qemu-img rebase -u`` to retroactively add a backing format to an
438 existing image.  However, be aware that there are already potential
439 security risks to blindly using ``qemu-img info`` to probe the format
440 of an untrusted backing image, when deciding what format to add into
441 an existing image.
442
443 Backwards compatibility
444 -----------------------
445
446 Runnability guarantee of CPU models (since 4.1.0)
447 '''''''''''''''''''''''''''''''''''''''''''''''''
448
449 Previous versions of QEMU never changed existing CPU models in
450 ways that introduced additional host software or hardware
451 requirements to the VM.  This allowed management software to
452 safely change the machine type of an existing VM without
453 introducing new requirements ("runnability guarantee").  This
454 prevented CPU models from being updated to include CPU
455 vulnerability mitigations, leaving guests vulnerable in the
456 default configuration.
457
458 The CPU model runnability guarantee won't apply anymore to
459 existing CPU models.  Management software that needs runnability
460 guarantees must resolve the CPU model aliases using te
461 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
462 command.
463
464 While those guarantees are kept, the return value of
465 ``query-cpu-definitions`` will have existing CPU model aliases
466 point to a version that doesn't break runnability guarantees
467 (specifically, version 1 of those CPU models).  In future QEMU
468 versions, aliases will point to newer CPU model versions
469 depending on the machine type, so management software must
470 resolve CPU model aliases before starting a virtual machine.
471
472
473 Recently removed features
474 =========================
475
476 What follows is a record of recently removed, formerly deprecated
477 features that serves as a record for users who have encountered
478 trouble after a recent upgrade.
479
480 System emulator command line arguments
481 --------------------------------------
482
483 ``-net ...,name=``\ *name* (removed in 5.1)
484 '''''''''''''''''''''''''''''''''''''''''''
485
486 The ``name`` parameter of the ``-net`` option was a synonym
487 for the ``id`` parameter, which should now be used instead.
488
489 QEMU Machine Protocol (QMP) commands
490 ------------------------------------
491
492 ``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
493 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
494
495 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
496 are automatically loaded from qcow2 images.
497
498 ``cpu-add`` (removed in 5.2)
499 ''''''''''''''''''''''''''''
500
501 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
502 documentation of ``query-hotpluggable-cpus`` for additional details.
503
504 Human Monitor Protocol (HMP) commands
505 -------------------------------------
506
507 The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
508 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
509
510 The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
511 'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
512
513 ``cpu-add`` (removed in 5.2)
514 ''''''''''''''''''''''''''''
515
516 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
517 documentation of ``query-hotpluggable-cpus`` for additional details.
518
519 Guest Emulator ISAs
520 -------------------
521
522 RISC-V ISA privilege specification version 1.09.1 (removed in 5.1)
523 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
524
525 The RISC-V ISA privilege specification version 1.09.1 has been removed.
526 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
527 should be used instead of the 1.09.1 version.
528
529 System emulator CPUS
530 --------------------
531
532 KVM guest support on 32-bit Arm hosts (removed in 5.2)
533 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
534
535 The Linux kernel has dropped support for allowing 32-bit Arm systems
536 to host KVM guests as of the 5.7 kernel. Accordingly, QEMU is deprecating
537 its support for this configuration and will remove it in a future version.
538 Running 32-bit guests on a 64-bit Arm host remains supported.
539
540 RISC-V ISA Specific CPUs (removed in 5.1)
541 '''''''''''''''''''''''''''''''''''''''''
542
543 The RISC-V cpus with the ISA version in the CPU name have been removed. The
544 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
545 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
546 option when using the ``rv32`` or ``rv64`` CPUs.
547
548 RISC-V no MMU CPUs (removed in 5.1)
549 '''''''''''''''''''''''''''''''''''
550
551 The RISC-V no MMU cpus have been removed. The two CPUs: ``rv32imacu-nommu`` and
552 ``rv64imacu-nommu`` can no longer be used. Instead the MMU status can be specified
553 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
554
555 System emulator machines
556 ------------------------
557
558 ``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
559 '''''''''''''''''''''''''''''''''''''''''''''''''''''
560
561 The version specific Spike machines have been removed in favour of the
562 generic ``spike`` machine. If you need to specify an older version of the RISC-V
563 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument.
564
565 Related binaries
566 ----------------
567
568 ``qemu-nbd --partition`` (removed in 5.0)
569 '''''''''''''''''''''''''''''''''''''''''
570
571 The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
572 could only handle MBR partitions, and never correctly handled logical
573 partitions beyond partition 5.  Exporting a partition can still be
574 done by utilizing the ``--image-opts`` option with a raw blockdev
575 using the ``offset`` and ``size`` parameters layered on top of
576 any other existing blockdev. For example, if partition 1 is 100MiB
577 long starting at 1MiB, the old command::
578
579   qemu-nbd -t -P 1 -f qcow2 file.qcow2
580
581 can be rewritten as::
582
583   qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
584
585 ``qemu-img convert -n -o`` (removed in 5.1)
586 '''''''''''''''''''''''''''''''''''''''''''
587
588 All options specified in ``-o`` are image creation options, so
589 they are now rejected when used with ``-n`` to skip image creation.
590
591
592 ``qemu-img create -b bad file $size`` (removed in 5.1)
593 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
594
595 When creating an image with a backing file that could not be opened,
596 ``qemu-img create`` used to issue a warning about the failure but
597 proceed with the image creation if an explicit size was provided.
598 However, as the ``-u`` option exists for this purpose, it is safer to
599 enforce that any failure to open the backing image (including if the
600 backing file is missing or an incorrect format was specified) is an
601 error when ``-u`` is not used.
602
603 Command line options
604 --------------------
605
606 ``-numa`` node (without memory specified) (removed 5.2)
607 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
608
609 Splitting RAM by default between NUMA nodes had the same issues as ``mem``
610 parameter with the difference that the role of the user plays QEMU using
611 implicit generic or board specific splitting rule.
612 Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
613 it's supported by used machine type) to define mapping explictly instead.
614 Users of existing VMs, wishing to preserve the same RAM distribution, should
615 configure it explicitly using ``-numa node,memdev`` options. Current RAM
616 distribution can be retrieved using HMP command ``info numa`` and if separate
617 memory devices (pc|nv-dimm) are present use ``info memory-device`` and subtract
618 device memory from output of ``info numa``.
619
620 ``-numa node,mem=``\ *size* (removed in 5.1)
621 ''''''''''''''''''''''''''''''''''''''''''''
622
623 The parameter ``mem`` of ``-numa node`` was used to assign a part of
624 guest RAM to a NUMA node. But when using it, it's impossible to manage a specified
625 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
626 so the guest ends up with the fake NUMA configuration with suboptiomal performance.
627 However since 2014 there is an alternative way to assign RAM to a NUMA node
628 using parameter ``memdev``, which does the same as ``mem`` and adds
629 means to actually manage node RAM on the host side. Use parameter ``memdev``
630 with *memory-backend-ram* backend as replacement for parameter ``mem``
631 to achieve the same fake NUMA effect or a properly configured
632 *memory-backend-file* backend to actually benefit from NUMA configuration.
633 New machine versions (since 5.1) will not accept the option but it will still
634 work with old machine types. User can check the QAPI schema to see if the legacy
635 option is supported by looking at MachineInfo::numa-mem-supported property.
636
637 ``-smp`` (invalid topologies) (removed 5.2)
638 '''''''''''''''''''''''''''''''''''''''''''
639
640 CPU topology properties should describe whole machine topology including
641 possible CPUs.
642
643 However, historically it was possible to start QEMU with an incorrect topology
644 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
645 which could lead to an incorrect topology enumeration by the guest.
646 Support for invalid topologies is removed, the user must ensure
647 topologies described with -smp include all possible cpus, i.e.
648 *sockets* * *cores* * *threads* = *maxcpus*.
649
650 Block devices
651 -------------
652
653 VXHS backend (removed in 5.1)
654 '''''''''''''''''''''''''''''
655
656 The VXHS code does not compile since v2.12.0. It was removed in 5.1.