17f800d34SMarc-André Lureau.. _Deprecated features: 27f800d34SMarc-André Lureau 3f3478392SPeter MaydellDeprecated features 4f3478392SPeter Maydell=================== 5f3478392SPeter Maydell 6f3478392SPeter MaydellIn general features are intended to be supported indefinitely once 7f3478392SPeter Maydellintroduced into QEMU. In the event that a feature needs to be removed, 8f3478392SPeter Maydellit will be listed in this section. The feature will remain functional for the 9f3478392SPeter Maydellrelease in which it was deprecated and one further release. After these two 10f3478392SPeter Maydellreleases, the feature is liable to be removed. Deprecated features may also 11f3478392SPeter Maydellgenerate warnings on the console when QEMU starts up, or if activated via a 12f3478392SPeter Maydellmonitor command, however, this is not a mandatory requirement. 13f3478392SPeter Maydell 14f3478392SPeter MaydellPrior to the 2.10.0 release there was no official policy on how 15f3478392SPeter Maydelllong features would be deprecated prior to their removal, nor 16f3478392SPeter Maydellany documented list of which features were deprecated. Thus 17f3478392SPeter Maydellany features deprecated prior to 2.10.0 will be treated as if 18f3478392SPeter Maydellthey were first deprecated in the 2.10.0 release. 19f3478392SPeter Maydell 20f3478392SPeter MaydellWhat follows is a list of all features currently marked as 21f3478392SPeter Maydelldeprecated. 22f3478392SPeter Maydell 23f3478392SPeter MaydellSystem emulator command line arguments 24f3478392SPeter Maydell-------------------------------------- 25f3478392SPeter Maydell 26f3478392SPeter MaydellShort-form boolean options (since 6.0) 27f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''' 28f3478392SPeter Maydell 29f3478392SPeter MaydellBoolean options such as ``share=on``/``share=off`` could be written 30f3478392SPeter Maydellin short form as ``share`` and ``noshare``. This is now deprecated 31f3478392SPeter Maydelland will cause a warning. 32f3478392SPeter Maydell 33f3478392SPeter Maydell``delay`` option for socket character devices (since 6.0) 34f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 35f3478392SPeter Maydell 36f3478392SPeter MaydellThe replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 37f3478392SPeter Maydellrather than ``delay=off``. 38f3478392SPeter Maydell 39c2511b16SYanan Wang``-smp`` ("parameter=0" SMP configurations) (since 6.2) 40c2511b16SYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''' 41c2511b16SYanan Wang 42c2511b16SYanan WangSpecified CPU topology parameters must be greater than zero. 43c2511b16SYanan Wang 44c2511b16SYanan WangIn the SMP configuration, users should either provide a CPU topology 45c2511b16SYanan Wangparameter with a reasonable value (greater than zero) or just omit it 46c2511b16SYanan Wangand QEMU will compute the missing value. 47c2511b16SYanan Wang 48c2511b16SYanan WangHowever, historically it was implicitly allowed for users to provide 49c2511b16SYanan Wanga parameter with zero value, which is meaningless and could also possibly 50c2511b16SYanan Wangcause unexpected results in the -smp parsing. So support for this kind of 51c2511b16SYanan Wangconfigurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 52c2511b16SYanan Wangbe removed in the near future, users have to ensure that all the topology 53c2511b16SYanan Wangmembers described with -smp are greater than zero. 54f3478392SPeter Maydell 5567f14574SMahmoud MandourPlugin argument passing through ``arg=<string>`` (since 6.1) 5667f14574SMahmoud Mandour'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 5767f14574SMahmoud Mandour 5867f14574SMahmoud MandourPassing TCG plugins arguments through ``arg=`` is redundant is makes the 5967f14574SMahmoud Mandourcommand-line less readable, especially when the argument itself consist of a 6067f14574SMahmoud Mandourname and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 6167f14574SMahmoud MandourTherefore, the usage of ``arg`` is redundant. Single-word arguments are treated 6267f14574SMahmoud Mandouras short-form boolean values, and passed to plugins as ``arg_name=on``. 6367f14574SMahmoud MandourHowever, short-form booleans are deprecated and full explicit ``arg_name=on`` 6467f14574SMahmoud Mandourform is preferred. 6567f14574SMahmoud Mandour 66f3478392SPeter MaydellQEMU Machine Protocol (QMP) commands 67f3478392SPeter Maydell------------------------------------ 68f3478392SPeter Maydell 69e2cc363bSYanan Wang``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 70e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 71f3478392SPeter Maydell 72f3478392SPeter MaydellUse argument ``id`` instead. 73f3478392SPeter Maydell 74e2cc363bSYanan Wang``eject`` argument ``device`` (since 2.8) 75e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''' 76f3478392SPeter Maydell 77f3478392SPeter MaydellUse argument ``id`` instead. 78f3478392SPeter Maydell 79e2cc363bSYanan Wang``blockdev-change-medium`` argument ``device`` (since 2.8) 80e2cc363bSYanan Wang'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 81f3478392SPeter Maydell 82f3478392SPeter MaydellUse argument ``id`` instead. 83f3478392SPeter Maydell 84e2cc363bSYanan Wang``block_set_io_throttle`` argument ``device`` (since 2.8) 85e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 86f3478392SPeter Maydell 87f3478392SPeter MaydellUse argument ``id`` instead. 88f3478392SPeter Maydell 89e2cc363bSYanan Wang``blockdev-add`` empty string argument ``backing`` (since 2.10) 90e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 91f3478392SPeter Maydell 92f3478392SPeter MaydellUse argument value ``null`` instead. 93f3478392SPeter Maydell 94e2cc363bSYanan Wang``block-commit`` arguments ``base`` and ``top`` (since 3.1) 95e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 96f3478392SPeter Maydell 97f3478392SPeter MaydellUse arguments ``base-node`` and ``top-node`` instead. 98f3478392SPeter Maydell 99f3478392SPeter Maydell``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 100f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 101f3478392SPeter Maydell 102f3478392SPeter MaydellUse the more generic commands ``block-export-add`` and ``block-export-del`` 103f3478392SPeter Maydellinstead. As part of this deprecation, where ``nbd-server-add`` used a 104f3478392SPeter Maydellsingle ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 105f3478392SPeter Maydell 10675ecee72SMarkus Armbruster``query-qmp-schema`` return value member ``values`` (since 6.2) 10775ecee72SMarkus Armbruster''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 10875ecee72SMarkus Armbruster 10975ecee72SMarkus ArmbrusterMember ``values`` in return value elements with meta-type ``enum`` is 11075ecee72SMarkus Armbrusterdeprecated. Use ``members`` instead. 11175ecee72SMarkus Armbruster 1121084159bSVladimir Sementsov-Ogievskiy``drive-backup`` (since 6.2) 1131084159bSVladimir Sementsov-Ogievskiy'''''''''''''''''''''''''''' 1141084159bSVladimir Sementsov-Ogievskiy 1151084159bSVladimir Sementsov-OgievskiyUse ``blockdev-backup`` in combination with ``blockdev-add`` instead. 1161084159bSVladimir Sementsov-OgievskiyThis change primarily separates the creation/opening process of the backup 1171084159bSVladimir Sementsov-Ogievskiytarget with explicit, separate steps. ``blockdev-backup`` uses mostly the 1181084159bSVladimir Sementsov-Ogievskiysame arguments as ``drive-backup``, except the ``format`` and ``mode`` 1191084159bSVladimir Sementsov-Ogievskiyoptions are removed in favor of using explicit ``blockdev-create`` and 1201084159bSVladimir Sementsov-Ogievskiy``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 1211084159bSVladimir Sementsov-Ogievskiydetails. 1221084159bSVladimir Sementsov-Ogievskiy 1234d8b0f0aSKevin WolfIncorrectly typed ``device_add`` arguments (since 6.2) 1244d8b0f0aSKevin Wolf'''''''''''''''''''''''''''''''''''''''''''''''''''''' 1254d8b0f0aSKevin Wolf 1264d8b0f0aSKevin WolfDue to shortcomings in the internal implementation of ``device_add``, QEMU 1274d8b0f0aSKevin Wolfincorrectly accepts certain invalid arguments: Any object or list arguments are 1284d8b0f0aSKevin Wolfsilently ignored. Other argument types are not checked, but an implicit 1294d8b0f0aSKevin Wolfconversion happens, so that e.g. string values can be assigned to integer 1304d8b0f0aSKevin Wolfdevice properties or vice versa. 1314d8b0f0aSKevin Wolf 1324d8b0f0aSKevin WolfThis is a bug in QEMU that will be fixed in the future so that previously 1334d8b0f0aSKevin Wolfaccepted incorrect commands will return an error. Users should make sure that 1344d8b0f0aSKevin Wolfall arguments passed to ``device_add`` are consistent with the documented 1354d8b0f0aSKevin Wolfproperty types. 1364d8b0f0aSKevin Wolf 1371a8fc850SAlex BennéeQEMU Machine Protocol (QMP) events 1381a8fc850SAlex Bennée---------------------------------- 1391a8fc850SAlex Bennée 1401a8fc850SAlex Bennée``MEM_UNPLUG_ERROR`` (since 6.2) 1411a8fc850SAlex Bennée'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 1421a8fc850SAlex Bennée 1431a8fc850SAlex BennéeUse the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 1441a8fc850SAlex Bennée 1455485e52aSAlex Bennée``vcpu`` trace events (since 8.1) 1465485e52aSAlex Bennée''''''''''''''''''''''''''''''''' 1475485e52aSAlex Bennée 1485485e52aSAlex BennéeThe ability to instrument QEMU helper functions with vCPU-aware trace 1495485e52aSAlex Bennéepoints was removed in 7.0. However QMP still exposed the vcpu 1505485e52aSAlex Bennéeparameter. This argument has now been deprecated and the remaining 1515485e52aSAlex Bennéeremaining trace points that used it are selected just by name. 1521a8fc850SAlex Bennée 15354ab3c3fSAlex BennéeHost Architectures 15454ab3c3fSAlex Bennée------------------ 15554ab3c3fSAlex Bennée 15654ab3c3fSAlex BennéeBE MIPS (since 7.2) 15754ab3c3fSAlex Bennée''''''''''''''''''' 15854ab3c3fSAlex Bennée 15954ab3c3fSAlex BennéeAs Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 16054ab3c3fSAlex BennéeMIPS moved out of support making it hard to maintain our 16154ab3c3fSAlex Bennéecross-compilation CI tests of the architecture. As we no longer have 16254ab3c3fSAlex BennéeCI coverage support may bitrot away before the deprecation process 16354ab3c3fSAlex Bennéecompletes. The little endian variants of MIPS (both 32 and 64 bit) are 16454ab3c3fSAlex Bennéestill a supported host architecture. 16554ab3c3fSAlex Bennée 1665c27baf9SThomas HuthSystem emulation on 32-bit x86 hosts (since 8.0) 1675c27baf9SThomas Huth'''''''''''''''''''''''''''''''''''''''''''''''' 1685c27baf9SThomas Huth 1695c27baf9SThomas HuthSupport for 32-bit x86 host deployments is increasingly uncommon in mainstream 1705c27baf9SThomas HuthOS distributions given the widespread availability of 64-bit x86 hardware. 1715c27baf9SThomas HuthThe QEMU project no longer considers 32-bit x86 support for system emulation to 1725c27baf9SThomas Huthbe an effective use of its limited resources, and thus intends to discontinue 1735c27baf9SThomas Huthit. Since all recent x86 hardware from the past >10 years is capable of the 1745c27baf9SThomas Huth64-bit x86 extensions, a corresponding 64-bit OS should be used instead. 1755c27baf9SThomas Huth 1765c27baf9SThomas Huth 1779997771bSPhilippe Mathieu-DaudéSystem emulator CPUs 1789997771bSPhilippe Mathieu-Daudé-------------------- 1799997771bSPhilippe Mathieu-Daudé 1809997771bSPhilippe Mathieu-DaudéNios II CPU (since 8.2) 1819997771bSPhilippe Mathieu-Daudé''''''''''''''''''''''' 1829997771bSPhilippe Mathieu-Daudé 1839997771bSPhilippe Mathieu-DaudéThe Nios II architecture is orphan. The ``nios2`` guest CPU support is 1849997771bSPhilippe Mathieu-Daudédeprecated and will be removed in a future version of QEMU. 1859997771bSPhilippe Mathieu-Daudé 1866a41a621SThomas Huth``power5+`` and ``power7+`` CPU names (since 9.0) 1876a41a621SThomas Huth''''''''''''''''''''''''''''''''''''''''''''''''' 1886a41a621SThomas Huth 1896a41a621SThomas HuthThe character "+" in device (and thus also CPU) names is not allowed 1906a41a621SThomas Huthin the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 1916a41a621SThomas Huth``power7+`` and ``power7+_v2.1`` are currently still supported via 1926a41a621SThomas Huthan alias, but for consistency these will get removed in a future 1936a41a621SThomas Huthrelease, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 1946a41a621SThomas Huth 195c7bbef40SAlex BennéeCRIS CPU architecture (since 9.0) 196c7bbef40SAlex Bennée''''''''''''''''''''''''''''''''' 197c7bbef40SAlex Bennée 198c7bbef40SAlex BennéeThe CRIS architecture was pulled from Linux in 4.17 and the compiler 199c7bbef40SAlex Bennéeis no longer packaged in any distro making it harder to run the 200c7bbef40SAlex Bennée``check-tcg`` tests. Unless we can improve the testing situation there 201c7bbef40SAlex Bennéeis a chance the code will bitrot without anyone noticing. 2029997771bSPhilippe Mathieu-Daudé 203f3478392SPeter MaydellSystem emulator machines 204f3478392SPeter Maydell------------------------ 205f3478392SPeter Maydell 206ac64ebbeSPeter MaydellArm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 207ac64ebbeSPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 2085242876fSJason A. Donenfeld 2095242876fSJason A. DonenfeldThe ``dtb-kaslr-seed`` property on the ``virt`` board has been 2105242876fSJason A. Donenfelddeprecated; use the new name ``dtb-randomness`` instead. The new name 2115242876fSJason A. Donenfeldbetter reflects the way this property affects all random data within 2125242876fSJason A. Donenfeldthe device tree blob, not just the ``kaslr-seed`` node. 2135242876fSJason A. Donenfeld 214c7437f0dSThomas Huth``pc-i440fx-2.0`` up to ``pc-i440fx-2.3`` (since 8.2) 215c7437f0dSThomas Huth''''''''''''''''''''''''''''''''''''''''''''''''''''' 216c7437f0dSThomas Huth 217c7437f0dSThomas HuthThese old machine types are quite neglected nowadays and thus might have 218c7437f0dSThomas Huthvarious pitfalls with regards to live migration. Use a newer machine type 219c7437f0dSThomas Huthinstead. 220c7437f0dSThomas Huth 2219997771bSPhilippe Mathieu-DaudéNios II ``10m50-ghrd`` and ``nios2-generic-nommu`` machines (since 8.2) 2229997771bSPhilippe Mathieu-Daudé''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 2239997771bSPhilippe Mathieu-Daudé 2249997771bSPhilippe Mathieu-DaudéThe Nios II architecture is orphan. 2259997771bSPhilippe Mathieu-Daudé 226322b038cSSamuel Tardieu``shix`` (since 9.0) 227322b038cSSamuel Tardieu'''''''''''''''''''' 228322b038cSSamuel Tardieu 229322b038cSSamuel TardieuThe machine is no longer in existence and has been long unmaintained 230c8cdec74SSamuel Tardieuin QEMU. This also holds for the TC51828 16MiB flash that it uses. 231c7437f0dSThomas Huth 232*1392617dSCédric Le Goater``pseries-2.1`` up to ``pseries-2.11`` (since 9.0) 233*1392617dSCédric Le Goater'''''''''''''''''''''''''''''''''''''''''''''''''' 234*1392617dSCédric Le Goater 235*1392617dSCédric Le GoaterOlder pseries machines before version 2.12 have undergone many changes 236*1392617dSCédric Le Goaterto correct issues, mostly regarding migration compatibility. These are 237*1392617dSCédric Le Goaterno longer maintained and removing them will make the code easier to 238*1392617dSCédric Le Goaterread and maintain. Use versions 2.12 and above as a replacement. 239*1392617dSCédric Le Goater 240f3478392SPeter MaydellBackend options 241f3478392SPeter Maydell--------------- 242f3478392SPeter Maydell 243f3478392SPeter MaydellUsing non-persistent backing file with pmem=on (since 6.1) 244f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 245f3478392SPeter Maydell 246f3478392SPeter MaydellThis option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 247f3478392SPeter Maydelldevice. However enabling ``memory-backend-file.pmem`` option, when backing file 248f3478392SPeter Maydellis (a) not DAX capable or (b) not on a filesystem that support direct mapping 249f3478392SPeter Maydellof persistent memory, is not safe and may lead to data loss or corruption in case 250f3478392SPeter Maydellof host crash. 251f3478392SPeter MaydellOptions are: 252f3478392SPeter Maydell 253f3478392SPeter Maydell - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 254f3478392SPeter Maydell (without persistence guaranties) with backing file on non DAX storage 255f3478392SPeter Maydell - move backing file to NVDIMM storage and keep ``pmem=on`` 256f3478392SPeter Maydell (to have NVDIMM with persistence guaranties). 257f3478392SPeter Maydell 258f3478392SPeter MaydellDevice options 259f3478392SPeter Maydell-------------- 260f3478392SPeter Maydell 261f3478392SPeter MaydellEmulated device options 262f3478392SPeter Maydell''''''''''''''''''''''' 263f3478392SPeter Maydell 264e2cc363bSYanan Wang``-device virtio-blk,scsi=on|off`` (since 5.0) 265e2cc363bSYanan Wang^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 266f3478392SPeter Maydell 267f3478392SPeter MaydellThe virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 268f3478392SPeter Maydelland later do not support it because the virtio-scsi device was introduced for 269f3478392SPeter Maydellfull SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 270f3478392SPeter Maydell 271f3478392SPeter MaydellNote this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 272f3478392SPeter Maydellalias. 273f3478392SPeter Maydell 27436d83272SKlaus Jensen``-device nvme-ns,eui64-default=on|off`` (since 7.1) 27536d83272SKlaus Jensen^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 27636d83272SKlaus Jensen 27736d83272SKlaus JensenIn QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 278120f765eSStefan Weilidentifier that is not globally unique. If an EUI-64 identifier is required, the 27936d83272SKlaus Jensenuser must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 28036d83272SKlaus Jensen 2818b1e59a6SKlaus Jensen``-device nvme,use-intel-id=on|off`` (since 7.1) 2828b1e59a6SKlaus Jensen^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2838b1e59a6SKlaus Jensen 2848b1e59a6SKlaus JensenThe ``nvme`` device originally used a PCI Vendor/Device Identifier combination 2858b1e59a6SKlaus Jensenfrom Intel that was not properly allocated. Since version 5.2, the controller 2868b1e59a6SKlaus Jensenhas used a properly allocated identifier. Deprecate the ``use-intel-id`` 2878b1e59a6SKlaus Jensenmachine compatibility parameter. 2888b1e59a6SKlaus Jensen 289adacc814SGregory Price``-device cxl-type3,memdev=xxxx`` (since 8.0) 290adacc814SGregory Price^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 291adacc814SGregory Price 292adacc814SGregory PriceThe ``cxl-type3`` device initially only used a single memory backend. With 293adacc814SGregory Pricethe addition of volatile memory support, it is now necessary to distinguish 294adacc814SGregory Pricebetween persistent and volatile memory backends. As such, memdev is deprecated 295adacc814SGregory Pricein favor of persistent-memdev. 296adacc814SGregory Price 29771d72eceSChristian Schoenebeck``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 29871d72eceSChristian Schoenebeck^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 29971d72eceSChristian Schoenebeck 30071d72eceSChristian SchoenebeckThe 9p ``proxy`` filesystem backend driver has been deprecated and will be 30171d72eceSChristian Schoenebeckremoved (along with its proxy helper daemon) in a future version of QEMU. Please 30271d72eceSChristian Schoenebeckuse ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 30371d72eceSChristian Schoenebeckbackend, or alternatively consider deploying virtiofsd instead. 30471d72eceSChristian Schoenebeck 30571d72eceSChristian SchoenebeckThe 9p ``proxy`` backend was originally developed as an alternative to the 9p 30671d72eceSChristian Schoenebeck``local`` backend. The idea was to enhance security by dispatching actual low 30771d72eceSChristian Schoenebecklevel filesystem operations from 9p server (QEMU process) over to a separate 30871d72eceSChristian Schoenebeckprocess (the virtfs-proxy-helper binary). However this alternative never gained 30971d72eceSChristian Schoenebeckmomentum. The proxy backend is much slower than the local backend, hasn't seen 31071d72eceSChristian Schoenebeckany development in years, and showed to be less secure, especially due to the 31171d72eceSChristian Schoenebeckfact that its helper daemon must be run as root, whereas with the local backend 31271d72eceSChristian SchoenebeckQEMU is typically run as unprivileged user and allows to tighten behaviour by 31371d72eceSChristian Schoenebeckmapping permissions et al by using its 'mapped' security model option. 31471d72eceSChristian Schoenebeck 31571d72eceSChristian SchoenebeckNowadays it would make sense to reimplement the ``proxy`` backend by using 31671d72eceSChristian SchoenebeckQEMU's ``vhost`` feature, which would eliminate the high latency costs under 31771d72eceSChristian Schoenebeckwhich the 9p ``proxy`` backend currently suffers. However as of to date nobody 318313e1629SStefan Weilhas indicated plans for such kind of reimplementation unfortunately. 31971d72eceSChristian Schoenebeck 320f57d5f80SDaniel Henrique BarbozaRISC-V 'any' CPU type ``-cpu any`` (since 8.2) 321f57d5f80SDaniel Henrique Barboza^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 322f57d5f80SDaniel Henrique Barboza 323f57d5f80SDaniel Henrique BarbozaThe 'any' CPU type was introduced back in 2018 and has been around since the 324f57d5f80SDaniel Henrique Barbozainitial RISC-V QEMU port. Its usage has always been unclear: users don't know 325f57d5f80SDaniel Henrique Barbozawhat to expect from a CPU called 'any', and in fact the CPU does not do anything 326f57d5f80SDaniel Henrique Barbozaspecial that isn't already done by the default CPUs rv32/rv64. 327f57d5f80SDaniel Henrique Barboza 328f57d5f80SDaniel Henrique BarbozaAfter the introduction of the 'max' CPU type, RISC-V now has a good coverage 329f57d5f80SDaniel Henrique Barbozaof generic CPUs: rv32 and rv64 as default CPUs and 'max' as a feature complete 330f57d5f80SDaniel Henrique BarbozaCPU for both 32 and 64 bit builds. Users are then discouraged to use the 'any' 331f57d5f80SDaniel Henrique BarbozaCPU type starting in 8.2. 3327c8d295bSDaniel P. Berrangé 3338043effdSDaniel Henrique BarbozaRISC-V CPU properties which start with capital 'Z' (since 8.2) 3348043effdSDaniel Henrique Barboza^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3358043effdSDaniel Henrique Barboza 3368043effdSDaniel Henrique BarbozaAll RISC-V CPU properties which start with capital 'Z' are being deprecated 3378043effdSDaniel Henrique Barbozastarting in 8.2. The reason is that they were wrongly added with capital 'Z' 3388043effdSDaniel Henrique Barbozain the past. CPU properties were later added with lower-case names, which 3398043effdSDaniel Henrique Barbozais the format we want to use from now on. 3408043effdSDaniel Henrique Barboza 3418043effdSDaniel Henrique BarbozaUsers which try to use these deprecated properties will receive a warning 3428043effdSDaniel Henrique Barbozarecommending to switch to their stable counterparts: 3438043effdSDaniel Henrique Barboza 3448043effdSDaniel Henrique Barboza- "Zifencei" should be replaced with "zifencei" 3458043effdSDaniel Henrique Barboza- "Zicsr" should be replaced with "zicsr" 3468043effdSDaniel Henrique Barboza- "Zihintntl" should be replaced with "zihintntl" 3478043effdSDaniel Henrique Barboza- "Zihintpause" should be replaced with "zihintpause" 3488043effdSDaniel Henrique Barboza- "Zawrs" should be replaced with "zawrs" 3498043effdSDaniel Henrique Barboza- "Zfa" should be replaced with "zfa" 3508043effdSDaniel Henrique Barboza- "Zfh" should be replaced with "zfh" 3518043effdSDaniel Henrique Barboza- "Zfhmin" should be replaced with "zfhmin" 3528043effdSDaniel Henrique Barboza- "Zve32f" should be replaced with "zve32f" 3538043effdSDaniel Henrique Barboza- "Zve64f" should be replaced with "zve64f" 3548043effdSDaniel Henrique Barboza- "Zve64d" should be replaced with "zve64d" 3558043effdSDaniel Henrique Barboza 356e9a54265SThomas Huth``-device pvrdma`` and the rdma subsystem (since 8.2) 357e9a54265SThomas Huth^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 358e9a54265SThomas Huth 359e9a54265SThomas HuthThe pvrdma device and the whole rdma subsystem are in a bad shape and 360e9a54265SThomas Huthwithout active maintenance. The QEMU project intends to remove this 361e9a54265SThomas Huthdevice and subsystem from the code base in a future release without 362e9a54265SThomas Huthreplacement unless somebody steps up and improves the situation. 363e9a54265SThomas Huth 364e2cc363bSYanan Wang 365e2cc363bSYanan WangBlock device options 366f3478392SPeter Maydell'''''''''''''''''''' 367f3478392SPeter Maydell 368f3478392SPeter Maydell``"backing": ""`` (since 2.12) 369f3478392SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 370f3478392SPeter Maydell 371f3478392SPeter MaydellIn order to prevent QEMU from automatically opening an image's backing 372f3478392SPeter Maydellchain, use ``"backing": null`` instead. 373f3478392SPeter Maydell 374f3478392SPeter Maydell``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 375f3478392SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 376f3478392SPeter Maydell 377f3478392SPeter MaydellOptions for ``rbd`` should be specified according to its runtime options, 378f3478392SPeter Maydelllike other block drivers. Legacy parsing of keyvalue pair encoded 379f3478392SPeter Maydellfilenames is useful to open images with the old format for backing files; 380f3478392SPeter MaydellThese image files should be updated to use the current format. 381f3478392SPeter Maydell 382f3478392SPeter MaydellExample of legacy encoding:: 383e2cc363bSYanan Wang 384e2cc363bSYanan Wang json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 385f3478392SPeter Maydell 386f3478392SPeter MaydellThe above, converted to the current supported format:: 387f3478392SPeter Maydell 388f3478392SPeter Maydell json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 389f3478392SPeter Maydell 390610783cbSDaniel P. Berrangé``iscsi,password=xxx`` (since 8.0) 391610783cbSDaniel P. Berrangé^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 392610783cbSDaniel P. Berrangé 393610783cbSDaniel P. BerrangéSpecifying the iSCSI password in plain text on the command line using the 394610783cbSDaniel P. Berrangé``password`` option is insecure. The ``password-secret`` option should be 395610783cbSDaniel P. Berrangéused instead, to refer to a ``--object secret...`` instance that provides 396610783cbSDaniel P. Berrangéa password via a file, or encrypted. 397610783cbSDaniel P. Berrangé 398b04c1228SMarkus ArmbrusterCharacter device options 399b04c1228SMarkus Armbruster'''''''''''''''''''''''' 400b04c1228SMarkus Armbruster 401b04c1228SMarkus ArmbrusterBackend ``memory`` (since 9.0) 402b04c1228SMarkus Armbruster^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 403b04c1228SMarkus Armbruster 404b04c1228SMarkus Armbruster``memory`` is a deprecated synonym for ``ringbuf``. 405b04c1228SMarkus Armbruster 406bc5e8445SRob BradfordCPU device properties 407bc5e8445SRob Bradford''''''''''''''''''''' 408bc5e8445SRob Bradford 409bc5e8445SRob Bradford``pmu-num=n`` on RISC-V CPUs (since 8.2) 410bc5e8445SRob Bradford^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 411bc5e8445SRob Bradford 412bc5e8445SRob BradfordIn order to support more flexible counter configurations this has been replaced 413bc5e8445SRob Bradfordby a ``pmu-mask`` property. If set of counters is continuous then the mask can 414bc5e8445SRob Bradfordbe calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 415bc5e8445SRob Bradfordmust be left clear. 416bc5e8445SRob Bradford 417bc5e8445SRob Bradford 418f3478392SPeter MaydellBackwards compatibility 419f3478392SPeter Maydell----------------------- 420f3478392SPeter Maydell 421e2cc363bSYanan WangRunnability guarantee of CPU models (since 4.1) 422e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''' 423f3478392SPeter Maydell 424f3478392SPeter MaydellPrevious versions of QEMU never changed existing CPU models in 425f3478392SPeter Maydellways that introduced additional host software or hardware 426f3478392SPeter Maydellrequirements to the VM. This allowed management software to 427f3478392SPeter Maydellsafely change the machine type of an existing VM without 428f3478392SPeter Maydellintroducing new requirements ("runnability guarantee"). This 429f3478392SPeter Maydellprevented CPU models from being updated to include CPU 430f3478392SPeter Maydellvulnerability mitigations, leaving guests vulnerable in the 431f3478392SPeter Maydelldefault configuration. 432f3478392SPeter Maydell 433f3478392SPeter MaydellThe CPU model runnability guarantee won't apply anymore to 434f3478392SPeter Maydellexisting CPU models. Management software that needs runnability 435f3478392SPeter Maydellguarantees must resolve the CPU model aliases using the 436f3478392SPeter Maydell``alias-of`` field returned by the ``query-cpu-definitions`` QMP 437f3478392SPeter Maydellcommand. 438f3478392SPeter Maydell 439f3478392SPeter MaydellWhile those guarantees are kept, the return value of 440f3478392SPeter Maydell``query-cpu-definitions`` will have existing CPU model aliases 441f3478392SPeter Maydellpoint to a version that doesn't break runnability guarantees 442f3478392SPeter Maydell(specifically, version 1 of those CPU models). In future QEMU 443f3478392SPeter Maydellversions, aliases will point to newer CPU model versions 444f3478392SPeter Maydelldepending on the machine type, so management software must 445f3478392SPeter Maydellresolve CPU model aliases before starting a virtual machine. 446f3478392SPeter Maydell 447582a098eSThomas HuthQEMU guest agent 448582a098eSThomas Huth---------------- 449582a098eSThomas Huth 450582a098eSThomas Huth``--blacklist`` command line option (since 7.2) 451582a098eSThomas Huth''''''''''''''''''''''''''''''''''''''''''''''' 452582a098eSThomas Huth 453582a098eSThomas Huth``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better 454582a098eSThomas Huthwording for what this option does). The short form ``-b`` still stays 455582a098eSThomas Huththe same and thus is the preferred way for scripts that should run with 456582a098eSThomas Huthboth, older and future versions of QEMU. 457582a098eSThomas Huth 458582a098eSThomas Huth``blacklist`` config file option (since 7.2) 459582a098eSThomas Huth'''''''''''''''''''''''''''''''''''''''''''' 460582a098eSThomas Huth 461582a098eSThomas HuthThe ``blacklist`` config file option has been renamed to ``block-rpcs`` 462582a098eSThomas Huth(to be in sync with the renaming of the corresponding command line 463582a098eSThomas Huthoption). 4647b24d326SJuan Quintela 4657b24d326SJuan QuintelaMigration 4667b24d326SJuan Quintela--------- 4677b24d326SJuan Quintela 4687b24d326SJuan Quintela``skipped`` MigrationStats field (since 8.1) 4697b24d326SJuan Quintela'''''''''''''''''''''''''''''''''''''''''''' 4707b24d326SJuan Quintela 4717b24d326SJuan Quintela``skipped`` field in Migration stats has been deprecated. It hasn't 4727b24d326SJuan Quintelabeen used for more than 10 years. 4737b24d326SJuan Quintela 47440101f32SJuan Quintela``inc`` migrate command option (since 8.2) 47540101f32SJuan Quintela'''''''''''''''''''''''''''''''''''''''''' 47640101f32SJuan Quintela 47740101f32SJuan QuintelaUse blockdev-mirror with NBD instead. 47840101f32SJuan Quintela 47940101f32SJuan QuintelaAs an intermediate step the ``inc`` functionality can be achieved by 48040101f32SJuan Quintelasetting the ``block-incremental`` migration parameter to ``true``. 48140101f32SJuan QuintelaBut this parameter is also deprecated. 4828846b5bfSJuan Quintela 4838846b5bfSJuan Quintela``blk`` migrate command option (since 8.2) 4848846b5bfSJuan Quintela'''''''''''''''''''''''''''''''''''''''''' 4858846b5bfSJuan Quintela 4868846b5bfSJuan QuintelaUse blockdev-mirror with NBD instead. 4878846b5bfSJuan Quintela 4888846b5bfSJuan QuintelaAs an intermediate step the ``blk`` functionality can be achieved by 4898846b5bfSJuan Quintelasetting the ``block`` migration capability to ``true``. But this 4908846b5bfSJuan Quintelacapability is also deprecated. 49166db46caSJuan Quintela 49266db46caSJuan Quintelablock migration (since 8.2) 49366db46caSJuan Quintela''''''''''''''''''''''''''' 49466db46caSJuan Quintela 49566db46caSJuan QuintelaBlock migration is too inflexible. It needs to migrate all block 49666db46caSJuan Quinteladevices or none. 49766db46caSJuan Quintela 49866db46caSJuan QuintelaPlease see "QMP invocation for live storage migration with 49966db46caSJuan Quintela``blockdev-mirror`` + NBD" in docs/interop/live-block-operations.rst 50066db46caSJuan Quintelafor a detailed explanation. 501864128dfSJuan Quintela 502864128dfSJuan Quintelaold compression method (since 8.2) 503864128dfSJuan Quintela'''''''''''''''''''''''''''''''''' 504864128dfSJuan Quintela 505864128dfSJuan QuintelaCompression method fails too much. Too many races. We are going to 506864128dfSJuan Quintelaremove it if nobody fixes it. For starters, migration-test 5076477366fSMichael Tokarevcompression tests are disabled because they fail randomly. If you need 508864128dfSJuan Quintelacompression, use multifd compression methods. 509