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 3967f14574SMahmoud MandourPlugin argument passing through ``arg=<string>`` (since 6.1) 4067f14574SMahmoud Mandour'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 4167f14574SMahmoud Mandour 4267f14574SMahmoud MandourPassing TCG plugins arguments through ``arg=`` is redundant is makes the 4367f14574SMahmoud Mandourcommand-line less readable, especially when the argument itself consist of a 4467f14574SMahmoud Mandourname and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 4567f14574SMahmoud MandourTherefore, the usage of ``arg`` is redundant. Single-word arguments are treated 4667f14574SMahmoud Mandouras short-form boolean values, and passed to plugins as ``arg_name=on``. 4767f14574SMahmoud MandourHowever, short-form booleans are deprecated and full explicit ``arg_name=on`` 4867f14574SMahmoud Mandourform is preferred. 4967f14574SMahmoud Mandour 5054c4ea8fSZhao Liu``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0) 5154c4ea8fSZhao Liu''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 5254c4ea8fSZhao Liu 5354c4ea8fSZhao LiuSpecified CPU topology parameters must be supported by the machine. 5454c4ea8fSZhao Liu 5554c4ea8fSZhao LiuIn the SMP configuration, users should provide the CPU topology parameters that 5654c4ea8fSZhao Liuare supported by the target machine. 5754c4ea8fSZhao Liu 5854c4ea8fSZhao LiuHowever, historically it was allowed for users to specify the unsupported 5954c4ea8fSZhao Liutopology parameter as "1", which is meaningless. So support for this kind of 6054c4ea8fSZhao Liuconfigurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is 6154c4ea8fSZhao Liumarked deprecated since 9.0, users have to ensure that all the topology members 6254c4ea8fSZhao Liudescribed with -smp are supported by the target machine. 6354c4ea8fSZhao Liu 6495e0fb0aSThomas Huth``-runas`` (since 9.1) 6595e0fb0aSThomas Huth---------------------- 6695e0fb0aSThomas Huth 6795e0fb0aSThomas HuthUse ``-run-with user=..`` instead. 6895e0fb0aSThomas Huth 6995e0fb0aSThomas Huth 70afc8b05cSZhao LiuUser-mode emulator command line arguments 71afc8b05cSZhao Liu----------------------------------------- 72afc8b05cSZhao Liu 73afc8b05cSZhao Liu``-p`` (since 9.0) 74afc8b05cSZhao Liu'''''''''''''''''' 75afc8b05cSZhao Liu 76afc8b05cSZhao LiuThe ``-p`` option pretends to control the host page size. However, 77afc8b05cSZhao Liuit is not possible to change the host page size, and using the 78afc8b05cSZhao Liuoption only causes failures. 79afc8b05cSZhao Liu 80f3478392SPeter MaydellQEMU Machine Protocol (QMP) commands 81f3478392SPeter Maydell------------------------------------ 82f3478392SPeter Maydell 83e2cc363bSYanan Wang``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 84e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 85f3478392SPeter Maydell 86f3478392SPeter MaydellUse argument ``id`` instead. 87f3478392SPeter Maydell 88e2cc363bSYanan Wang``eject`` argument ``device`` (since 2.8) 89e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''' 90f3478392SPeter Maydell 91f3478392SPeter MaydellUse argument ``id`` instead. 92f3478392SPeter Maydell 93e2cc363bSYanan Wang``blockdev-change-medium`` argument ``device`` (since 2.8) 94e2cc363bSYanan Wang'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 95f3478392SPeter Maydell 96f3478392SPeter MaydellUse argument ``id`` instead. 97f3478392SPeter Maydell 98e2cc363bSYanan Wang``block_set_io_throttle`` argument ``device`` (since 2.8) 99e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 100f3478392SPeter Maydell 101f3478392SPeter MaydellUse argument ``id`` instead. 102f3478392SPeter Maydell 103e2cc363bSYanan Wang``blockdev-add`` empty string argument ``backing`` (since 2.10) 104e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 105f3478392SPeter Maydell 106f3478392SPeter MaydellUse argument value ``null`` instead. 107f3478392SPeter Maydell 108e2cc363bSYanan Wang``block-commit`` arguments ``base`` and ``top`` (since 3.1) 109e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 110f3478392SPeter Maydell 111f3478392SPeter MaydellUse arguments ``base-node`` and ``top-node`` instead. 112f3478392SPeter Maydell 113f3478392SPeter Maydell``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 114f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 115f3478392SPeter Maydell 116f3478392SPeter MaydellUse the more generic commands ``block-export-add`` and ``block-export-del`` 117f3478392SPeter Maydellinstead. As part of this deprecation, where ``nbd-server-add`` used a 118f3478392SPeter Maydellsingle ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 119f3478392SPeter Maydell 12075ecee72SMarkus Armbruster``query-qmp-schema`` return value member ``values`` (since 6.2) 12175ecee72SMarkus Armbruster''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 12275ecee72SMarkus Armbruster 12375ecee72SMarkus ArmbrusterMember ``values`` in return value elements with meta-type ``enum`` is 12475ecee72SMarkus Armbrusterdeprecated. Use ``members`` instead. 12575ecee72SMarkus Armbruster 1261084159bSVladimir Sementsov-Ogievskiy``drive-backup`` (since 6.2) 1271084159bSVladimir Sementsov-Ogievskiy'''''''''''''''''''''''''''' 1281084159bSVladimir Sementsov-Ogievskiy 1291084159bSVladimir Sementsov-OgievskiyUse ``blockdev-backup`` in combination with ``blockdev-add`` instead. 1301084159bSVladimir Sementsov-OgievskiyThis change primarily separates the creation/opening process of the backup 1311084159bSVladimir Sementsov-Ogievskiytarget with explicit, separate steps. ``blockdev-backup`` uses mostly the 1321084159bSVladimir Sementsov-Ogievskiysame arguments as ``drive-backup``, except the ``format`` and ``mode`` 1331084159bSVladimir Sementsov-Ogievskiyoptions are removed in favor of using explicit ``blockdev-create`` and 1341084159bSVladimir Sementsov-Ogievskiy``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 1351084159bSVladimir Sementsov-Ogievskiydetails. 1361084159bSVladimir Sementsov-Ogievskiy 1374d8b0f0aSKevin WolfIncorrectly typed ``device_add`` arguments (since 6.2) 1384d8b0f0aSKevin Wolf'''''''''''''''''''''''''''''''''''''''''''''''''''''' 1394d8b0f0aSKevin Wolf 1404d8b0f0aSKevin WolfDue to shortcomings in the internal implementation of ``device_add``, QEMU 1414d8b0f0aSKevin Wolfincorrectly accepts certain invalid arguments: Any object or list arguments are 1424d8b0f0aSKevin Wolfsilently ignored. Other argument types are not checked, but an implicit 1434d8b0f0aSKevin Wolfconversion happens, so that e.g. string values can be assigned to integer 1444d8b0f0aSKevin Wolfdevice properties or vice versa. 1454d8b0f0aSKevin Wolf 1464d8b0f0aSKevin WolfThis is a bug in QEMU that will be fixed in the future so that previously 1474d8b0f0aSKevin Wolfaccepted incorrect commands will return an error. Users should make sure that 1484d8b0f0aSKevin Wolfall arguments passed to ``device_add`` are consistent with the documented 1494d8b0f0aSKevin Wolfproperty types. 1504d8b0f0aSKevin Wolf 15154ab3c3fSAlex BennéeHost Architectures 15254ab3c3fSAlex Bennée------------------ 15354ab3c3fSAlex Bennée 15454ab3c3fSAlex BennéeBE MIPS (since 7.2) 15554ab3c3fSAlex Bennée''''''''''''''''''' 15654ab3c3fSAlex Bennée 15754ab3c3fSAlex BennéeAs Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 15854ab3c3fSAlex BennéeMIPS moved out of support making it hard to maintain our 15954ab3c3fSAlex Bennéecross-compilation CI tests of the architecture. As we no longer have 16054ab3c3fSAlex BennéeCI coverage support may bitrot away before the deprecation process 16154ab3c3fSAlex Bennéecompletes. The little endian variants of MIPS (both 32 and 64 bit) are 16254ab3c3fSAlex Bennéestill a supported host architecture. 16354ab3c3fSAlex Bennée 1645c27baf9SThomas HuthSystem emulation on 32-bit x86 hosts (since 8.0) 1655c27baf9SThomas Huth'''''''''''''''''''''''''''''''''''''''''''''''' 1665c27baf9SThomas Huth 1675c27baf9SThomas HuthSupport for 32-bit x86 host deployments is increasingly uncommon in mainstream 1685c27baf9SThomas HuthOS distributions given the widespread availability of 64-bit x86 hardware. 1695c27baf9SThomas HuthThe QEMU project no longer considers 32-bit x86 support for system emulation to 1705c27baf9SThomas Huthbe an effective use of its limited resources, and thus intends to discontinue 1715c27baf9SThomas Huthit. Since all recent x86 hardware from the past >10 years is capable of the 1725c27baf9SThomas Huth64-bit x86 extensions, a corresponding 64-bit OS should be used instead. 1735c27baf9SThomas Huth 1745c27baf9SThomas Huth 1759997771bSPhilippe Mathieu-DaudéSystem emulator CPUs 1769997771bSPhilippe Mathieu-Daudé-------------------- 1779997771bSPhilippe Mathieu-Daudé 1786a41a621SThomas Huth``power5+`` and ``power7+`` CPU names (since 9.0) 1796a41a621SThomas Huth''''''''''''''''''''''''''''''''''''''''''''''''' 1806a41a621SThomas Huth 1816a41a621SThomas HuthThe character "+" in device (and thus also CPU) names is not allowed 1826a41a621SThomas Huthin the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 1836a41a621SThomas Huth``power7+`` and ``power7+_v2.1`` are currently still supported via 1846a41a621SThomas Huthan alias, but for consistency these will get removed in a future 1856a41a621SThomas Huthrelease, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 1866a41a621SThomas Huth 187029171b5SThomas Huth``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1) 188029171b5SThomas Huth''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 189029171b5SThomas Huth 190029171b5SThomas HuthThe character "+" in device (and thus also CPU) names is not allowed 191029171b5SThomas Huthin the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and 192029171b5SThomas Huth``Sun-UltraSparc-IV+`` are currently still supported via a workaround, 193029171b5SThomas Huthbut for consistency these will get removed in a future release, too. 194029171b5SThomas HuthUse ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead. 195029171b5SThomas Huth 196c7bbef40SAlex BennéeCRIS CPU architecture (since 9.0) 197c7bbef40SAlex Bennée''''''''''''''''''''''''''''''''' 198c7bbef40SAlex Bennée 199c7bbef40SAlex BennéeThe CRIS architecture was pulled from Linux in 4.17 and the compiler 200c7bbef40SAlex Bennéeis no longer packaged in any distro making it harder to run the 201c7bbef40SAlex Bennée``check-tcg`` tests. Unless we can improve the testing situation there 202c7bbef40SAlex Bennéeis a chance the code will bitrot without anyone noticing. 2039997771bSPhilippe Mathieu-Daudé 204f3478392SPeter MaydellSystem emulator machines 205f3478392SPeter Maydell------------------------ 206f3478392SPeter Maydell 207ac64ebbeSPeter MaydellArm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 208ac64ebbeSPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 2095242876fSJason A. Donenfeld 2105242876fSJason A. DonenfeldThe ``dtb-kaslr-seed`` property on the ``virt`` board has been 2115242876fSJason A. Donenfelddeprecated; use the new name ``dtb-randomness`` instead. The new name 2125242876fSJason A. Donenfeldbetter reflects the way this property affects all random data within 2135242876fSJason A. Donenfeldthe device tree blob, not just the ``kaslr-seed`` node. 2145242876fSJason A. Donenfeld 21546a2bd52SPhilippe Mathieu-Daudé``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) 21646a2bd52SPhilippe Mathieu-Daudé'''''''''''''''''''''''''''''''''''''''''''''''''''''' 217c7437f0dSThomas Huth 218c7437f0dSThomas HuthThese old machine types are quite neglected nowadays and thus might have 219c7437f0dSThomas Huthvarious pitfalls with regards to live migration. Use a newer machine type 220c7437f0dSThomas Huthinstead. 221c7437f0dSThomas Huth 222322b038cSSamuel Tardieu``shix`` (since 9.0) 223322b038cSSamuel Tardieu'''''''''''''''''''' 224322b038cSSamuel Tardieu 225322b038cSSamuel TardieuThe machine is no longer in existence and has been long unmaintained 226c8cdec74SSamuel Tardieuin QEMU. This also holds for the TC51828 16MiB flash that it uses. 227c7437f0dSThomas Huth 2280cac0f1bSPhilippe Mathieu-Daudé``pseries-2.1`` up to ``pseries-2.12`` (since 9.0) 2291392617dSCédric Le Goater'''''''''''''''''''''''''''''''''''''''''''''''''' 2301392617dSCédric Le Goater 2310cac0f1bSPhilippe Mathieu-DaudéOlder pseries machines before version 3.0 have undergone many changes 2321392617dSCédric Le Goaterto correct issues, mostly regarding migration compatibility. These are 2331392617dSCédric Le Goaterno longer maintained and removing them will make the code easier to 2340cac0f1bSPhilippe Mathieu-Daudéread and maintain. Use versions 3.0 and above as a replacement. 2351392617dSCédric Le Goater 236a2531bb8SPeter MaydellArm machines ``akita``, ``borzoi``, ``cheetah``, ``connex``, ``mainstone``, ``n800``, ``n810``, ``spitz``, ``terrier``, ``tosa``, ``verdex``, ``z2`` (since 9.0) 237a2531bb8SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 238a2531bb8SPeter Maydell 239a2531bb8SPeter MaydellQEMU includes models of some machine types where the QEMU code that 240a2531bb8SPeter Maydellemulates their SoCs is very old and unmaintained. This code is now 241a2531bb8SPeter Maydellblocking our ability to move forward with various changes across 242a2531bb8SPeter Maydellthe codebase, and over many years nobody has been interested in 243a2531bb8SPeter Maydelltrying to modernise it. We don't expect any of these machines to have 244a2531bb8SPeter Maydella large number of users, because they're all modelling hardware that 245a2531bb8SPeter Maydellhas now passed away into history. We are therefore dropping support 246a2531bb8SPeter Maydellfor all machine types using the PXA2xx and OMAP2 SoCs. We are also 247a2531bb8SPeter Maydelldropping the ``cheetah`` OMAP1 board, because we don't have any 248a2531bb8SPeter Maydelltest images for it and don't know of anybody who does; the ``sx1`` 249a2531bb8SPeter Maydelland ``sx1-v1`` OMAP1 machines remain supported for now. 250a2531bb8SPeter Maydell 251ed95bdd1SCédric Le GoaterPPC 405 ``ref405ep`` machine (since 9.1) 252ed95bdd1SCédric Le Goater'''''''''''''''''''''''''''''''''''''''' 253ed95bdd1SCédric Le Goater 254ed95bdd1SCédric Le GoaterThe ``ref405ep`` machine and PPC 405 CPU have no known users, firmware 255ed95bdd1SCédric Le Goaterimages are not available, OpenWRT dropped support in 2019, U-Boot in 256ed95bdd1SCédric Le Goater2017, Linux also is dropping support in 2024. It is time to let go of 257ed95bdd1SCédric Le Goaterthis ancient hardware and focus on newer CPUs and platforms. 258ed95bdd1SCédric Le Goater 259f3478392SPeter MaydellBackend options 260f3478392SPeter Maydell--------------- 261f3478392SPeter Maydell 262f3478392SPeter MaydellUsing non-persistent backing file with pmem=on (since 6.1) 263f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 264f3478392SPeter Maydell 265f3478392SPeter MaydellThis option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 266f3478392SPeter Maydelldevice. However enabling ``memory-backend-file.pmem`` option, when backing file 267f3478392SPeter Maydellis (a) not DAX capable or (b) not on a filesystem that support direct mapping 268f3478392SPeter Maydellof persistent memory, is not safe and may lead to data loss or corruption in case 269f3478392SPeter Maydellof host crash. 270f3478392SPeter MaydellOptions are: 271f3478392SPeter Maydell 272f3478392SPeter Maydell - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 273f3478392SPeter Maydell (without persistence guaranties) with backing file on non DAX storage 274f3478392SPeter Maydell - move backing file to NVDIMM storage and keep ``pmem=on`` 275f3478392SPeter Maydell (to have NVDIMM with persistence guaranties). 276f3478392SPeter Maydell 277f3478392SPeter MaydellDevice options 278f3478392SPeter Maydell-------------- 279f3478392SPeter Maydell 280f3478392SPeter MaydellEmulated device options 281f3478392SPeter Maydell''''''''''''''''''''''' 282f3478392SPeter Maydell 28336d83272SKlaus Jensen``-device nvme-ns,eui64-default=on|off`` (since 7.1) 28436d83272SKlaus Jensen^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 28536d83272SKlaus Jensen 28636d83272SKlaus JensenIn QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 287120f765eSStefan Weilidentifier that is not globally unique. If an EUI-64 identifier is required, the 28836d83272SKlaus Jensenuser must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 28936d83272SKlaus Jensen 2908b1e59a6SKlaus Jensen``-device nvme,use-intel-id=on|off`` (since 7.1) 2918b1e59a6SKlaus Jensen^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2928b1e59a6SKlaus Jensen 2938b1e59a6SKlaus JensenThe ``nvme`` device originally used a PCI Vendor/Device Identifier combination 2948b1e59a6SKlaus Jensenfrom Intel that was not properly allocated. Since version 5.2, the controller 2958b1e59a6SKlaus Jensenhas used a properly allocated identifier. Deprecate the ``use-intel-id`` 2968b1e59a6SKlaus Jensenmachine compatibility parameter. 2978b1e59a6SKlaus Jensen 298adacc814SGregory Price``-device cxl-type3,memdev=xxxx`` (since 8.0) 299adacc814SGregory Price^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 300adacc814SGregory Price 301adacc814SGregory PriceThe ``cxl-type3`` device initially only used a single memory backend. With 302adacc814SGregory Pricethe addition of volatile memory support, it is now necessary to distinguish 303adacc814SGregory Pricebetween persistent and volatile memory backends. As such, memdev is deprecated 304adacc814SGregory Pricein favor of persistent-memdev. 305adacc814SGregory Price 30671d72eceSChristian Schoenebeck``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 30771d72eceSChristian Schoenebeck^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 30871d72eceSChristian Schoenebeck 30971d72eceSChristian SchoenebeckThe 9p ``proxy`` filesystem backend driver has been deprecated and will be 31071d72eceSChristian Schoenebeckremoved (along with its proxy helper daemon) in a future version of QEMU. Please 31171d72eceSChristian Schoenebeckuse ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 31271d72eceSChristian Schoenebeckbackend, or alternatively consider deploying virtiofsd instead. 31371d72eceSChristian Schoenebeck 31471d72eceSChristian SchoenebeckThe 9p ``proxy`` backend was originally developed as an alternative to the 9p 31571d72eceSChristian Schoenebeck``local`` backend. The idea was to enhance security by dispatching actual low 31671d72eceSChristian Schoenebecklevel filesystem operations from 9p server (QEMU process) over to a separate 31771d72eceSChristian Schoenebeckprocess (the virtfs-proxy-helper binary). However this alternative never gained 31871d72eceSChristian Schoenebeckmomentum. The proxy backend is much slower than the local backend, hasn't seen 31971d72eceSChristian Schoenebeckany development in years, and showed to be less secure, especially due to the 32071d72eceSChristian Schoenebeckfact that its helper daemon must be run as root, whereas with the local backend 32171d72eceSChristian SchoenebeckQEMU is typically run as unprivileged user and allows to tighten behaviour by 32271d72eceSChristian Schoenebeckmapping permissions et al by using its 'mapped' security model option. 32371d72eceSChristian Schoenebeck 32471d72eceSChristian SchoenebeckNowadays it would make sense to reimplement the ``proxy`` backend by using 32571d72eceSChristian SchoenebeckQEMU's ``vhost`` feature, which would eliminate the high latency costs under 32671d72eceSChristian Schoenebeckwhich the 9p ``proxy`` backend currently suffers. However as of to date nobody 327313e1629SStefan Weilhas indicated plans for such kind of reimplementation unfortunately. 32871d72eceSChristian Schoenebeck 329f57d5f80SDaniel Henrique BarbozaRISC-V 'any' CPU type ``-cpu any`` (since 8.2) 330f57d5f80SDaniel Henrique Barboza^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 331f57d5f80SDaniel Henrique Barboza 332f57d5f80SDaniel Henrique BarbozaThe 'any' CPU type was introduced back in 2018 and has been around since the 333f57d5f80SDaniel Henrique Barbozainitial RISC-V QEMU port. Its usage has always been unclear: users don't know 334f57d5f80SDaniel Henrique Barbozawhat to expect from a CPU called 'any', and in fact the CPU does not do anything 335f57d5f80SDaniel Henrique Barbozaspecial that isn't already done by the default CPUs rv32/rv64. 336f57d5f80SDaniel Henrique Barboza 337f57d5f80SDaniel Henrique BarbozaAfter the introduction of the 'max' CPU type, RISC-V now has a good coverage 338f57d5f80SDaniel Henrique Barbozaof generic CPUs: rv32 and rv64 as default CPUs and 'max' as a feature complete 339f57d5f80SDaniel Henrique BarbozaCPU for both 32 and 64 bit builds. Users are then discouraged to use the 'any' 340f57d5f80SDaniel Henrique BarbozaCPU type starting in 8.2. 3417c8d295bSDaniel P. Berrangé 3428043effdSDaniel Henrique BarbozaRISC-V CPU properties which start with capital 'Z' (since 8.2) 3438043effdSDaniel Henrique Barboza^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3448043effdSDaniel Henrique Barboza 3458043effdSDaniel Henrique BarbozaAll RISC-V CPU properties which start with capital 'Z' are being deprecated 3468043effdSDaniel Henrique Barbozastarting in 8.2. The reason is that they were wrongly added with capital 'Z' 3478043effdSDaniel Henrique Barbozain the past. CPU properties were later added with lower-case names, which 3488043effdSDaniel Henrique Barbozais the format we want to use from now on. 3498043effdSDaniel Henrique Barboza 3508043effdSDaniel Henrique BarbozaUsers which try to use these deprecated properties will receive a warning 3518043effdSDaniel Henrique Barbozarecommending to switch to their stable counterparts: 3528043effdSDaniel Henrique Barboza 3538043effdSDaniel Henrique Barboza- "Zifencei" should be replaced with "zifencei" 3548043effdSDaniel Henrique Barboza- "Zicsr" should be replaced with "zicsr" 3558043effdSDaniel Henrique Barboza- "Zihintntl" should be replaced with "zihintntl" 3568043effdSDaniel Henrique Barboza- "Zihintpause" should be replaced with "zihintpause" 3578043effdSDaniel Henrique Barboza- "Zawrs" should be replaced with "zawrs" 3588043effdSDaniel Henrique Barboza- "Zfa" should be replaced with "zfa" 3598043effdSDaniel Henrique Barboza- "Zfh" should be replaced with "zfh" 3608043effdSDaniel Henrique Barboza- "Zfhmin" should be replaced with "zfhmin" 3618043effdSDaniel Henrique Barboza- "Zve32f" should be replaced with "zve32f" 3628043effdSDaniel Henrique Barboza- "Zve64f" should be replaced with "zve64f" 3638043effdSDaniel Henrique Barboza- "Zve64d" should be replaced with "zve64d" 3648043effdSDaniel Henrique Barboza 365*6a414c01SPhilippe Mathieu-Daudé``-device sd-card,spec_version=1`` (since 9.1) 366*6a414c01SPhilippe Mathieu-Daudé^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 367*6a414c01SPhilippe Mathieu-Daudé 368*6a414c01SPhilippe Mathieu-DaudéSD physical layer specification v2.00 supersedes the v1.10 one. 369*6a414c01SPhilippe Mathieu-Daudév2.00 is the default since QEMU 3.0.0. 370*6a414c01SPhilippe Mathieu-Daudé 371f3478392SPeter MaydellBlock device options 372f3478392SPeter Maydell'''''''''''''''''''' 373f3478392SPeter Maydell 374e2cc363bSYanan Wang``"backing": ""`` (since 2.12) 375e2cc363bSYanan Wang^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 376f3478392SPeter Maydell 377f3478392SPeter MaydellIn order to prevent QEMU from automatically opening an image's backing 378f3478392SPeter Maydellchain, use ``"backing": null`` instead. 379f3478392SPeter Maydell 380e2cc363bSYanan Wang``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 381e2cc363bSYanan Wang^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 382f3478392SPeter Maydell 383f3478392SPeter MaydellOptions for ``rbd`` should be specified according to its runtime options, 384f3478392SPeter Maydelllike other block drivers. Legacy parsing of keyvalue pair encoded 385f3478392SPeter Maydellfilenames is useful to open images with the old format for backing files; 386f3478392SPeter MaydellThese image files should be updated to use the current format. 387f3478392SPeter Maydell 388f3478392SPeter MaydellExample of legacy encoding:: 389f3478392SPeter Maydell 390f3478392SPeter Maydell json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 391f3478392SPeter Maydell 392f3478392SPeter MaydellThe above, converted to the current supported format:: 393f3478392SPeter Maydell 394f3478392SPeter Maydell json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 395f3478392SPeter Maydell 396610783cbSDaniel P. Berrangé``iscsi,password=xxx`` (since 8.0) 397610783cbSDaniel P. Berrangé^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 398610783cbSDaniel P. Berrangé 399610783cbSDaniel P. BerrangéSpecifying the iSCSI password in plain text on the command line using the 400610783cbSDaniel P. Berrangé``password`` option is insecure. The ``password-secret`` option should be 401610783cbSDaniel P. Berrangéused instead, to refer to a ``--object secret...`` instance that provides 402610783cbSDaniel P. Berrangéa password via a file, or encrypted. 403610783cbSDaniel P. Berrangé 404b04c1228SMarkus ArmbrusterCharacter device options 405b04c1228SMarkus Armbruster'''''''''''''''''''''''' 406b04c1228SMarkus Armbruster 407b04c1228SMarkus ArmbrusterBackend ``memory`` (since 9.0) 408b04c1228SMarkus Armbruster^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 409b04c1228SMarkus Armbruster 410b04c1228SMarkus Armbruster``memory`` is a deprecated synonym for ``ringbuf``. 411b04c1228SMarkus Armbruster 412bc5e8445SRob BradfordCPU device properties 413bc5e8445SRob Bradford''''''''''''''''''''' 414bc5e8445SRob Bradford 4159f07e47aSPaolo Bonzini``pcommit`` on x86 (since 9.1) 4169f07e47aSPaolo Bonzini^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4179f07e47aSPaolo Bonzini 4189f07e47aSPaolo BonziniThe PCOMMIT instruction was never included in any physical processor. 4199f07e47aSPaolo BonziniIt was implemented as a no-op instruction in TCG up to QEMU 9.0, but 4209f07e47aSPaolo Bonzinionly with ``-cpu max`` (which does not guarantee migration compatibility 4219f07e47aSPaolo Bonziniacross versions). 4229f07e47aSPaolo Bonzini 423bc5e8445SRob Bradford``pmu-num=n`` on RISC-V CPUs (since 8.2) 424bc5e8445SRob Bradford^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 425bc5e8445SRob Bradford 426bc5e8445SRob BradfordIn order to support more flexible counter configurations this has been replaced 427bc5e8445SRob Bradfordby a ``pmu-mask`` property. If set of counters is continuous then the mask can 428bc5e8445SRob Bradfordbe calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 429bc5e8445SRob Bradfordmust be left clear. 430bc5e8445SRob Bradford 431bc5e8445SRob Bradford 432f3478392SPeter MaydellBackwards compatibility 433f3478392SPeter Maydell----------------------- 434f3478392SPeter Maydell 435e2cc363bSYanan WangRunnability guarantee of CPU models (since 4.1) 436e2cc363bSYanan Wang''''''''''''''''''''''''''''''''''''''''''''''' 437f3478392SPeter Maydell 438f3478392SPeter MaydellPrevious versions of QEMU never changed existing CPU models in 439f3478392SPeter Maydellways that introduced additional host software or hardware 440f3478392SPeter Maydellrequirements to the VM. This allowed management software to 441f3478392SPeter Maydellsafely change the machine type of an existing VM without 442f3478392SPeter Maydellintroducing new requirements ("runnability guarantee"). This 443f3478392SPeter Maydellprevented CPU models from being updated to include CPU 444f3478392SPeter Maydellvulnerability mitigations, leaving guests vulnerable in the 445f3478392SPeter Maydelldefault configuration. 446f3478392SPeter Maydell 447f3478392SPeter MaydellThe CPU model runnability guarantee won't apply anymore to 448f3478392SPeter Maydellexisting CPU models. Management software that needs runnability 449f3478392SPeter Maydellguarantees must resolve the CPU model aliases using the 450f3478392SPeter Maydell``alias-of`` field returned by the ``query-cpu-definitions`` QMP 451f3478392SPeter Maydellcommand. 452f3478392SPeter Maydell 453f3478392SPeter MaydellWhile those guarantees are kept, the return value of 454f3478392SPeter Maydell``query-cpu-definitions`` will have existing CPU model aliases 455f3478392SPeter Maydellpoint to a version that doesn't break runnability guarantees 456f3478392SPeter Maydell(specifically, version 1 of those CPU models). In future QEMU 457f3478392SPeter Maydellversions, aliases will point to newer CPU model versions 458f3478392SPeter Maydelldepending on the machine type, so management software must 459f3478392SPeter Maydellresolve CPU model aliases before starting a virtual machine. 460f3478392SPeter Maydell 4617b24d326SJuan QuintelaMigration 4627b24d326SJuan Quintela--------- 4637b24d326SJuan Quintela 464c55deb86SFabiano Rosas``fd:`` URI when used for file migration (since 9.1) 465c55deb86SFabiano Rosas'''''''''''''''''''''''''''''''''''''''''''''''''''' 4667b24d326SJuan Quintela 467c55deb86SFabiano RosasThe ``fd:`` URI can currently provide a file descriptor that 468c55deb86SFabiano Rosasreferences either a socket or a plain file. These are two different 469c55deb86SFabiano Rosastypes of migration. In order to reduce ambiguity, the ``fd:`` URI 470c55deb86SFabiano Rosasusage of providing a file descriptor to a plain file has been 471c55deb86SFabiano Rosasdeprecated in favor of explicitly using the ``file:`` URI with the 472c55deb86SFabiano Rosasfile descriptor being passed as an ``fdset``. Refer to the ``add-fd`` 473c55deb86SFabiano Rosascommand documentation for details on the ``fdset`` usage. 474