]>
Commit | Line | Data |
---|---|---|
41fba161 PM |
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, | |
ef1f5b0a SH |
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. | |
41fba161 PM |
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 | ||
41fba161 PM |
24 | ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) |
25 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
26 | ||
27 | The ``-audiodev`` argument is now the preferred way to specify audio | |
28 | backend settings instead of environment variables. To ease migration to | |
29 | the new format, the ``-audiodev-help`` option can be used to convert | |
30 | the current values of the environment variables to ``-audiodev`` options. | |
31 | ||
32 | Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) | |
33 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
34 | ||
35 | When not using the deprecated legacy audio config, each sound card | |
36 | should specify an ``audiodev=`` property. Additionally, when using | |
76ca4b58 | 37 | vnc, you should specify an ``audiodev=`` property if you plan to |
41fba161 PM |
38 | transmit audio through the VNC protocol. |
39 | ||
825ff029 GH |
40 | Creating sound card devices using ``-soundhw`` (since 5.1) |
41 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
42 | ||
43 | Sound card devices should be created using ``-device`` instead. The | |
44 | names are the same for most devices. The exceptions are ``hda`` which | |
45 | needs two devices (``-device intel-hda -device hda-duplex``) and | |
46 | ``pcspk`` which can be activated using ``-machine | |
47 | pcspk-audiodev=<name>``. | |
48 | ||
59652436 KW |
49 | ``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) |
50 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
51 | ||
52 | ``tty`` and ``parport`` are aliases that will be removed. Instead, the | |
53 | actual backend names ``serial`` and ``parallel`` should be used. | |
54 | ||
ccd3b3b8 PB |
55 | Short-form boolean options (since 6.0) |
56 | '''''''''''''''''''''''''''''''''''''' | |
57 | ||
58 | Boolean options such as ``share=on``/``share=off`` could be written | |
59 | in short form as ``share`` and ``noshare``. This is now deprecated | |
60 | and will cause a warning. | |
a1b40bda | 61 | |
fe636424 PB |
62 | ``delay`` option for socket character devices (since 6.0) |
63 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
64 | ||
65 | The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` | |
66 | rather than ``delay=off``. | |
67 | ||
16631029 DB |
68 | ``--enable-fips`` (since 6.0) |
69 | ''''''''''''''''''''''''''''' | |
70 | ||
71 | This option restricts usage of certain cryptographic algorithms when | |
72 | the host is operating in FIPS mode. | |
73 | ||
74 | If FIPS compliance is required, QEMU should be built with the ``libgcrypt`` | |
75 | library enabled as a cryptography provider. | |
76 | ||
77 | Neither the ``nettle`` library, or the built-in cryptography provider are | |
78 | supported on FIPS enabled hosts. | |
79 | ||
b979c931 PB |
80 | ``-writeconfig`` (since 6.0) |
81 | ''''''''''''''''''''''''''''' | |
82 | ||
83 | The ``-writeconfig`` option is not able to serialize the entire contents | |
84 | of the QEMU command line. It is thus considered a failed experiment | |
85 | and deprecated, with no current replacement. | |
86 | ||
2c933ac6 PB |
87 | Userspace local APIC with KVM (x86, since 6.0) |
88 | '''''''''''''''''''''''''''''''''''''''''''''' | |
89 | ||
90 | Using ``-M kernel-irqchip=off`` with x86 machine types that include a local | |
91 | APIC is deprecated. The ``split`` setting is supported, as is using | |
92 | ``-M kernel-irqchip=off`` with the ISA PC machine type. | |
93 | ||
f174cd33 EB |
94 | hexadecimal sizes with scaling multipliers (since 6.0) |
95 | '''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
96 | ||
97 | Input parameters that take a size value should only use a size suffix | |
98 | (such as 'k' or 'M') when the base is written in decimal, and not when | |
99 | the value is hexadecimal. That is, '0x20M' is deprecated, and should | |
100 | be written either as '32M' or as '0x2000000'. | |
101 | ||
c47c0bcb DB |
102 | ``-spice password=string`` (since 6.0) |
103 | '''''''''''''''''''''''''''''''''''''' | |
104 | ||
105 | This option is insecure because the SPICE password remains visible in | |
106 | the process listing. This is replaced by the new ``password-secret`` | |
107 | option which lets the password be securely provided on the command | |
108 | line using a ``secret`` object instance. | |
109 | ||
e2cc363b YW |
110 | ``opened`` property of ``rng-*`` objects (since 6.0) |
111 | '''''''''''''''''''''''''''''''''''''''''''''''''''' | |
6815bc1d KW |
112 | |
113 | The only effect of specifying ``opened=on`` in the command line or QMP | |
114 | ``object-add`` is that the device is opened immediately, possibly before all | |
115 | other options have been processed. This will either have no effect (if | |
116 | ``opened`` was the last option) or cause errors. The property is therefore | |
117 | useless and should not be specified. | |
118 | ||
e2cc363b YW |
119 | ``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0) |
120 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
39c4c27d KW |
121 | |
122 | The only effect of specifying ``loaded=on`` in the command line or QMP | |
123 | ``object-add`` is that the secret is loaded immediately, possibly before all | |
124 | other options have been processed. This will either have no effect (if | |
125 | ``loaded`` was the last option) or cause options to be effectively ignored as | |
126 | if they were not given. The property is therefore useless and should not be | |
127 | specified. | |
128 | ||
bb20b86d TH |
129 | ``-display sdl,window_close=...`` (since 6.1) |
130 | ''''''''''''''''''''''''''''''''''''''''''''' | |
131 | ||
132 | Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of | |
133 | an underscore between "window" and "close"). | |
134 | ||
b6ddc6a2 TH |
135 | ``-no-quit`` (since 6.1) |
136 | '''''''''''''''''''''''' | |
137 | ||
138 | The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which | |
139 | should be used instead. | |
140 | ||
39c4c27d | 141 | |
41fba161 PM |
142 | QEMU Machine Protocol (QMP) commands |
143 | ------------------------------------ | |
144 | ||
e2cc363b YW |
145 | ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) |
146 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
147 | |
148 | Use argument ``id`` instead. | |
149 | ||
e2cc363b YW |
150 | ``eject`` argument ``device`` (since 2.8) |
151 | ''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
152 | |
153 | Use argument ``id`` instead. | |
154 | ||
e2cc363b YW |
155 | ``blockdev-change-medium`` argument ``device`` (since 2.8) |
156 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
157 | |
158 | Use argument ``id`` instead. | |
159 | ||
e2cc363b YW |
160 | ``block_set_io_throttle`` argument ``device`` (since 2.8) |
161 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
162 | |
163 | Use argument ``id`` instead. | |
164 | ||
e2cc363b YW |
165 | ``blockdev-add`` empty string argument ``backing`` (since 2.10) |
166 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
167 | |
168 | Use argument value ``null`` instead. | |
169 | ||
e2cc363b YW |
170 | ``block-commit`` arguments ``base`` and ``top`` (since 3.1) |
171 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
172 | |
173 | Use arguments ``base-node`` and ``top-node`` instead. | |
174 | ||
443127e8 KW |
175 | ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) |
176 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
177 | ||
178 | Use the more generic commands ``block-export-add`` and ``block-export-del`` | |
cbad81ce EB |
179 | instead. As part of this deprecation, where ``nbd-server-add`` used a |
180 | single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. | |
443127e8 | 181 | |
f071dc1f JY |
182 | System accelerators |
183 | ------------------- | |
184 | ||
185 | MIPS ``Trap-and-Emul`` KVM support (since 6.0) | |
186 | '''''''''''''''''''''''''''''''''''''''''''''' | |
187 | ||
188 | The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed | |
189 | from Linux upstream kernel, declare it deprecated. | |
190 | ||
41fba161 PM |
191 | System emulator CPUS |
192 | -------------------- | |
193 | ||
e2cc363b YW |
194 | ``Icelake-Client`` CPU Model (since 5.2) |
195 | '''''''''''''''''''''''''''''''''''''''' | |
3e6a015c RH |
196 | |
197 | ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU | |
198 | Models instead. | |
199 | ||
a60442eb PMD |
200 | MIPS ``I7200`` CPU Model (since 5.2) |
201 | '''''''''''''''''''''''''''''''''''' | |
202 | ||
203 | The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated | |
204 | (the ISA has never been upstreamed to a compiler toolchain). Therefore | |
205 | this CPU is also deprecated. | |
206 | ||
41fba161 PM |
207 | System emulator machines |
208 | ------------------------ | |
209 | ||
63a9c7e0 CLG |
210 | Aspeed ``swift-bmc`` machine (since 6.1) |
211 | '''''''''''''''''''''''''''''''''''''''' | |
212 | ||
213 | This machine is deprecated because we have enough AST2500 based OpenPOWER | |
214 | machines. It can be easily replaced by the ``witherspoon-bmc`` or the | |
215 | ``romulus-bmc`` machines. | |
216 | ||
cdcf766d IM |
217 | Backend options |
218 | --------------- | |
219 | ||
220 | Using non-persistent backing file with pmem=on (since 6.1) | |
221 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
222 | ||
223 | This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM | |
224 | device. However enabling ``memory-backend-file.pmem`` option, when backing file | |
225 | is (a) not DAX capable or (b) not on a filesystem that support direct mapping | |
226 | of persistent memory, is not safe and may lead to data loss or corruption in case | |
227 | of host crash. | |
228 | Options are: | |
229 | ||
230 | - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM | |
231 | (without persistence guaranties) with backing file on non DAX storage | |
232 | - move backing file to NVDIMM storage and keep ``pmem=on`` | |
233 | (to have NVDIMM with persistence guaranties). | |
234 | ||
41fba161 PM |
235 | Device options |
236 | -------------- | |
237 | ||
238 | Emulated device options | |
239 | ''''''''''''''''''''''' | |
240 | ||
e2cc363b YW |
241 | ``-device virtio-blk,scsi=on|off`` (since 5.0) |
242 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
243 | |
244 | The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 | |
245 | and later do not support it because the virtio-scsi device was introduced for | |
246 | full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. | |
247 | ||
248 | Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an | |
249 | alias. | |
250 | ||
251 | Block device options | |
252 | '''''''''''''''''''' | |
253 | ||
e2cc363b YW |
254 | ``"backing": ""`` (since 2.12) |
255 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
256 | |
257 | In order to prevent QEMU from automatically opening an image's backing | |
258 | chain, use ``"backing": null`` instead. | |
259 | ||
e2cc363b YW |
260 | ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) |
261 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
262 | |
263 | Options for ``rbd`` should be specified according to its runtime options, | |
264 | like other block drivers. Legacy parsing of keyvalue pair encoded | |
265 | filenames is useful to open images with the old format for backing files; | |
266 | These image files should be updated to use the current format. | |
267 | ||
268 | Example of legacy encoding:: | |
269 | ||
270 | json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} | |
271 | ||
272 | The above, converted to the current supported format:: | |
273 | ||
274 | json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} | |
275 | ||
0f10bf84 PM |
276 | linux-user mode CPUs |
277 | -------------------- | |
278 | ||
e2cc363b YW |
279 | ``ppc64abi32`` CPUs (since 5.2) |
280 | ''''''''''''''''''''''''''''''' | |
c609274b AB |
281 | |
282 | The ``ppc64abi32`` architecture has a number of issues which regularly | |
283 | trip up our CI testing and is suspected to be quite broken. For that | |
284 | reason the maintainers strongly suspect no one actually uses it. | |
285 | ||
a60442eb PMD |
286 | MIPS ``I7200`` CPU (since 5.2) |
287 | '''''''''''''''''''''''''''''' | |
288 | ||
289 | The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated | |
290 | (the ISA has never been upstreamed to a compiler toolchain). Therefore | |
291 | this CPU is also deprecated. | |
292 | ||
41fba161 PM |
293 | Related binaries |
294 | ---------------- | |
295 | ||
41fba161 PM |
296 | Backwards compatibility |
297 | ----------------------- | |
298 | ||
e2cc363b YW |
299 | Runnability guarantee of CPU models (since 4.1) |
300 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
41fba161 PM |
301 | |
302 | Previous versions of QEMU never changed existing CPU models in | |
303 | ways that introduced additional host software or hardware | |
304 | requirements to the VM. This allowed management software to | |
305 | safely change the machine type of an existing VM without | |
306 | introducing new requirements ("runnability guarantee"). This | |
307 | prevented CPU models from being updated to include CPU | |
308 | vulnerability mitigations, leaving guests vulnerable in the | |
309 | default configuration. | |
310 | ||
311 | The CPU model runnability guarantee won't apply anymore to | |
312 | existing CPU models. Management software that needs runnability | |
ac9574bc | 313 | guarantees must resolve the CPU model aliases using the |
41fba161 PM |
314 | ``alias-of`` field returned by the ``query-cpu-definitions`` QMP |
315 | command. | |
316 | ||
317 | While those guarantees are kept, the return value of | |
318 | ``query-cpu-definitions`` will have existing CPU model aliases | |
319 | point to a version that doesn't break runnability guarantees | |
320 | (specifically, version 1 of those CPU models). In future QEMU | |
321 | versions, aliases will point to newer CPU model versions | |
322 | depending on the machine type, so management software must | |
323 | resolve CPU model aliases before starting a virtual machine. | |
324 | ||
a60442eb PMD |
325 | Guest Emulator ISAs |
326 | ------------------- | |
327 | ||
328 | nanoMIPS ISA | |
329 | '''''''''''' | |
330 | ||
331 | The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. | |
332 | As it is hard to generate binaries for it, declare it deprecated. |