blob: 1b9c007f1229044b612ea6f0a6c00b19cd28b908 [file] [log] [blame]
Markus Armbruster44c67842018-07-16 09:32:25 +02001@node Deprecated features
2@appendix Deprecated features
3
4In general features are intended to be supported indefinitely once
5introduced into QEMU. In the event that a feature needs to be removed,
6it will be listed in this appendix. The feature will remain functional
7for 2 releases prior to actual removal. Deprecated features may also
8generate warnings on the console when QEMU starts up, or if activated
9via a monitor command, however, this is not a mandatory requirement.
10
11Prior to the 2.10.0 release there was no official policy on how
12long features would be deprecated prior to their removal, nor
13any documented list of which features were deprecated. Thus
14any features deprecated prior to 2.10.0 will be treated as if
15they were first deprecated in the 2.10.0 release.
16
17What follows is a list of all features currently marked as
18deprecated.
19
20@section Build options
21
22@subsection GTK 2.x
23
24Previously QEMU has supported building against both GTK 2.x
25and 3.x series APIs. Support for the GTK 2.x builds will be
26discontinued, so maintainers should switch to using GTK 3.x,
27which is the default.
28
29@subsection SDL 1.2
30
31Previously QEMU has supported building against both SDL 1.2
32and 2.0 series APIs. Support for the SDL 1.2 builds will be
33discontinued, so maintainers should switch to using SDL 2.0,
34which is the default.
35
36@section System emulator command line arguments
37
38@subsection -no-kvm (since 1.3.0)
39
40The ``-no-kvm'' argument is now a synonym for setting
41``-machine accel=tcg''.
42
Markus Armbruster44c67842018-07-16 09:32:25 +020043@subsection -tftp (since 2.6.0)
44
45The ``-tftp /some/dir'' argument is replaced by either
46``-netdev user,id=x,tftp=/some/dir '' (for pluggable NICs, accompanied
47with ``-device ...,netdev=x''), or ``-nic user,tftp=/some/dir''
48(for embedded NICs). The new syntax allows different settings to be
49provided per NIC.
50
51@subsection -bootp (since 2.6.0)
52
53The ``-bootp /some/file'' argument is replaced by either
54``-netdev user,id=x,bootp=/some/file '' (for pluggable NICs, accompanied
55with ``-device ...,netdev=x''), or ``-nic user,bootp=/some/file''
56(for embedded NICs). The new syntax allows different settings to be
57provided per NIC.
58
59@subsection -redir (since 2.6.0)
60
61The ``-redir [tcp|udp]:hostport:[guestaddr]:guestport'' argument is
62replaced by either
63``-netdev user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport''
64(for pluggable NICs, accompanied with ``-device ...,netdev=x'') or
65``-nic user,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport''
66(for embedded NICs). The new syntax allows different settings to be
67provided per NIC.
68
69@subsection -smb (since 2.6.0)
70
71The ``-smb /some/dir'' argument is replaced by either
72``-netdev user,id=x,smb=/some/dir '' (for pluggable NICs, accompanied
73with ``-device ...,netdev=x''), or ``-nic user,smb=/some/dir''
74(for embedded NICs). The new syntax allows different settings to be
75provided per NIC.
76
Markus Armbruster44c67842018-07-16 09:32:25 +020077@subsection -usbdevice (since 2.10.0)
78
79The ``-usbdevice DEV'' argument is now a synonym for setting
80the ``-device usb-DEV'' argument instead. The deprecated syntax
81would automatically enable USB support on the machine type.
82If using the new syntax, USB support must be explicitly
83enabled via the ``-machine usb=on'' argument.
84
85@subsection -nodefconfig (since 2.11.0)
86
87The ``-nodefconfig`` argument is a synonym for ``-no-user-config``.
88
89@subsection -balloon (since 2.12.0)
90
91The @option{--balloon virtio} argument has been superseded by
92@option{--device virtio-balloon}.
93
Markus Armbruster44c67842018-07-16 09:32:25 +020094@subsection -fsdev handle (since 2.12.0)
95
96The ``handle'' fsdev backend does not support symlinks and causes the 9p
97filesystem in the guest to fail a fair amount of tests from the PJD POSIX
98filesystem test suite. Also it requires the CAP_DAC_READ_SEARCH capability,
99which is not the recommended way to run QEMU. This backend should not be
100used and it will be removed with no replacement.
101
102@subsection -no-frame (since 2.12.0)
103
104The @code{--no-frame} argument works with SDL 1.2 only. The other user
105interfaces never implemented this in the first place. So this will be
106removed together with SDL 1.2 support.
107
108@subsection -rtc-td-hack (since 2.12.0)
109
110The @code{-rtc-td-hack} option has been replaced by
111@code{-rtc driftfix=slew}.
112
113@subsection -localtime (since 2.12.0)
114
115The @code{-localtime} option has been replaced by @code{-rtc base=localtime}.
116
117@subsection -startdate (since 2.12.0)
118
119The @code{-startdate} option has been replaced by @code{-rtc base=@var{date}}.
120
121@subsection -virtioconsole (since 3.0.0)
122
123Option @option{-virtioconsole} has been replaced by
124@option{-device virtconsole}.
125
126@subsection -clock (since 3.0.0)
127
128The @code{-clock} option is ignored since QEMU version 1.7.0. There is no
129replacement since it is not needed anymore.
130
131@subsection -enable-hax (since 3.0.0)
132
133The @option{-enable-hax} option has been replaced by @option{-accel hax}.
134Both options have been introduced in QEMU version 2.9.0.
135
136@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
137
138The 'file' driver for drives is no longer appropriate for character or host
139devices and will only accept regular files (S_IFREG). The correct driver
140for these file types is 'host_cdrom' or 'host_device' as appropriate.
141
142@section QEMU Machine Protocol (QMP) commands
143
144@subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0)
145
146"autoload" parameter is now ignored. All bitmaps are automatically loaded
147from qcow2 images.
148
149@subsection query-cpus (since 2.12.0)
150
151The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
152
153@subsection query-cpus-fast "arch" output member (since 3.0.0)
154
155The ``arch'' output member of the ``query-cpus-fast'' command is
156replaced by the ``target'' output member.
157
158@section System emulator devices
159
160@subsection ivshmem (since 2.6.0)
161
162The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
163or ``ivshmem-doorbell`` device types.
164
165@subsection Page size support < 4k for embedded PowerPC CPUs (since 2.12.0)
166
167qemu-system-ppcemb will be removed. qemu-system-ppc (or qemu-system-ppc64)
168should be used instead. That means that embedded 4xx PowerPC CPUs will not
169support page sizes < 4096 any longer.
170
171@section System emulator machines
172
173@subsection pc-0.10 and pc-0.11 (since 3.0)
174
175These machine types are very old and likely can not be used for live migration
176from old QEMU versions anymore. A newer machine type should be used instead.
177
Hervé Poussineau93323282018-08-11 00:46:45 +0200178@subsection prep (PowerPC) (since 3.1)
179
180This machine type uses an unmaintained firmware, broken in lots of ways,
181and unable to start post-2004 operating systems. 40p machine type should be
182used instead.
183
Markus Armbruster44c67842018-07-16 09:32:25 +0200184@section Device options
185
186@subsection Block device options
187
188@subsubsection "backing": "" (since 2.12.0)
189
190In order to prevent QEMU from automatically opening an image's backing
191chain, use ``"backing": null'' instead.
192
193@subsection vio-spapr-device device options
194
195@subsubsection "irq": "" (since 3.0.0)
196
197The ``irq'' property is obsoleted.