1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
|
= How to convert to -device & friends =
=== Specifying Bus and Address on Bus ===
In qdev, each device has a parent bus. Some devices provide one or
more buses for children. You can specify a device's parent bus with
-device parameter bus.
A device typically has a device address on its parent bus. For buses
where this address can be configured, devices provide a bus-specific
property. Examples:
bus property name value format
PCI addr %x.%x (dev.fn, .fn optional)
I2C address %u
SCSI scsi-id %u
IDE unit %u
HDA cad %u
virtio-serial-bus nr %u
ccid-bus slot %u
USB port %d(.%d)* (port.port...)
Example: device i440FX-pcihost is on the root bus, and provides a PCI
bus named pci.0. To put a FOO device into its slot 4, use -device
FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0
also works as long as the bus name is unique.
=== Block Devices ===
A QEMU block device (drive) has a host and a guest part.
In the general case, the guest device is connected to a controller
device. For instance, the IDE controller provides two IDE buses, each
of which can have up to two devices, and each device is a guest part,
and is connected to a host part.
Except we sometimes lump controller, bus(es) and drive device(s) all
together into a single device. For instance, the ISA floppy
controller is connected to up to two host drives.
The old ways to define block devices define host and guest part
together. Sometimes, they can even define a controller device in
addition to the block device.
The new way keeps the parts separate: you create the host part with
-drive, and guest device(s) with -device.
The various old ways to define drives all boil down to the common form
-drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
TYPE, BUS and UNIT identify the controller device, which of its buses
to use, and the drive's address on that bus. Details depend on TYPE.
Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
In the new way, this becomes something like
-drive if=none,id=DRIVE-ID,HOST-OPTS...
-device DEVNAME,drive=DRIVE-ID,DEV-OPTS...
The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
* file, format, snapshot, cache, aio, readonly, rerror, werror go into
HOST-OPTS.
* cyls, head, secs and trans go into HOST-OPTS. Future work: they
should go into DEV-OPTS instead.
* serial goes into DEV-OPTS, for devices supporting serial numbers.
For other devices, it goes nowhere.
* media is special. In the old way, it selects disk vs. CD-ROM with
if=ide, if=scsi and if=xen. The new way uses DEVNAME for that.
Additionally, readonly=on goes into HOST-OPTS.
* addr is special, see if=virtio below.
The -device argument differs in detail for each type of drive:
* if=ide
-device DEVNAME,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT
where DEVNAME is either ide-hd or ide-cd, IDE-BUS identifies an IDE
bus, normally either ide.0 or ide.1, and UNIT is either 0 or 1.
* if=scsi
The old way implicitly creates SCSI controllers as needed. The new
way makes that explicit:
-device lsi53c895a,id=ID
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
control the PCI device address.
This SCSI controller provides a single SCSI bus, named ID.0. Put a
disk on it:
-device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
* if=floppy
-device floppy,unit=UNIT,drive=DRIVE-ID
Without any -device floppy,... you get an empty unit 0 and no unit
1. You can use -nodefaults to suppress the default unit 0, see
"Default Devices".
* if=virtio
-device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
This lets you control PCI device class and MSI-X vectors.
IOEVENTFD controls whether or not ioeventfd is used for virtqueue
notify. It can be set to on (default) or off.
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
control the PCI device address. This replaces option addr available
with -drive if=virtio.
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
For USB storage devices, you can use something like:
-device usb-storage,drive=DRIVE-ID,removable=RMB
The removable parameter gives control over the SCSI INQUIRY removable
(RMB) bit. USB thumbdrives usually set removable=on, while USB hard
disks set removable=off.
Bug: usb-storage pretends to be a block device, but it's really a SCSI
controller that can serve only a single device, which it creates
automatically. The automatic creation guesses what kind of guest part
to create from the host part, like -drive if=scsi. Host and guest
part are not cleanly separated.
=== Character Devices ===
A QEMU character device has a host and a guest part.
The old ways to define character devices define host and guest part
together.
The new way keeps the parts separate: you create the host part with
-chardev, and the guest device with -device.
The various old ways to define a character device are all of the
general form
-FOO FOO-OPTS...,LEGACY-CHARDEV
where FOO-OPTS... is specific to -FOO, and the host part
LEGACY-CHARDEV is the same everywhere.
In the new way, this becomes
-chardev HOST-OPTS...,id=CHR-ID
-device DEVNAME,chardev=CHR-ID,DEV-OPTS...
The appropriate DEVNAME depends on the machine type. For type "pc":
* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
This lets you control I/O ports and IRQs.
* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
This lets you control I/O ports and IRQs.
* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always
uses "braille". With -device, this useful default is gone, so you
have to use something like
-device usb-braille,chardev=braille -chardev braille,id=braille
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
* null becomes -chardev null
* pty, msmouse, wctablet, braille, stdio likewise
* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
* con: becomes -chardev console
* COM<NUM> becomes -chardev serial,path=COM<NUM>
* file:FNAME becomes -chardev file,path=FNAME
* pipe:FNAME becomes -chardev pipe,path=FNAME
* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
* telnet:HOST:PORT,OPTS... becomes
-chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
-chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
* unix:FNAME becomes -chardev socket,path=FNAME
* /dev/parportN becomes -chardev parport,file=/dev/parportN
* /dev/ppiN likewise
* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
character device defined by LEGACY-CHARDEV. -chardev provides more
general multiplexing instead: you can connect up to four users to a
single host part. You need to pass mux=on to -chardev to enable
switching the input focus.
QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
also in various other places such as -monitor or -net
user,guestfwd=... You can use chardev:CHR-ID in place of
LEGACY-CHARDEV to refer to a host part defined with -chardev.
=== Network Devices ===
Host and guest part of network devices have always been separate.
The old way to define the guest part looks like this:
-net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
The new way is -device:
-device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
DEVNAME equals MODEL, except for virtio you have to name the virtio
device appropriate for the bus (virtio-net-pci for PCI), and for USB
you have to use usb-net.
The old name=ID parameter becomes the usual id=ID with -device.
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
device address, as usual. The old -net nic provides parameter addr
for that, which is silently ignored when the NIC is not a PCI device.
For virtio-net-pci, you can control whether or not ioeventfd is used for
virtqueue notify by setting ioeventfd= to on or off (default).
-net nic accepts vectors=V for all models, but it's silently ignored
except for virtio-net-pci (model=virtio). With -device, only devices
that support it accept it.
Not all devices are available with -device at this time. All PCI
devices and ne2k_isa are.
Some PCI devices aren't available with -net nic, e.g. i82558a.
=== Graphics Devices ===
Host and guest part of graphics devices have always been separate.
The old way to define the guest graphics device is -vga VGA. Not all
machines support all -vga options.
The new way is -device. The mapping from -vga argument to -device
depends on the machine type. For machine "pc", it's:
std -device VGA
cirrus -device cirrus-vga
vmware -device vmware-svga
qxl -device qxl-vga
none -nodefaults
disables more than just VGA, see "Default Devices"
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
the PCI device address.
-device VGA supports properties bios-offset and bios-size, but they
aren't used with machine type "pc".
For machine "isapc", it's
std -device isa-vga
cirrus not yet available with -device
none -nodefaults
disables more than just VGA, see "Default Devices"
Bug: the new way doesn't work for machine types "pc" and "isapc",
because it violates obscure device initialization ordering
constraints.
=== Audio Devices ===
Host and guest part of audio devices have always been separate.
The old way to define guest audio devices is -soundhw C1,...
The new way is to define each guest audio device separately with
-device.
Map from -soundhw sound card name to -device:
ac97 -device AC97
cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
es1370 -device ES1370
gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
hda -device intel-hda,msi=MSI -device hda-duplex
sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
adlib not yet available with -device
pcspk not yet available with -device
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
device address, as usual.
=== USB Devices ===
The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER:
* ccid -device usb-ccid
* keyboard -device usb-kbd
* mouse -device usb-mouse
* tablet -device usb-tablet
* wacom-tablet -device usb-wacom-tablet
* braille See "Character Devices"
=== Watchdog Devices ===
Host and guest part of watchdog devices have always been separate.
The old way to define a guest watchdog device is -watchdog DEVNAME.
The new way is -device DEVNAME. For PCI devices, you can add
bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
=== Host Device Assignment ===
QEMU supports assigning host PCI devices (qemu-kvm only at this time)
and host USB devices. PCI devices can only be assigned with -device:
-device vfio-pci,host=ADDR,id=ID
To assign a host USB device use:
-device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
Omitted options match anything.
=== Default Devices ===
QEMU creates a number of devices by default, depending on the machine
type.
-device DEVNAME... and global DEVNAME... suppress default devices for
some DEVNAMEs:
default device suppressing DEVNAMEs
CD-ROM ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd
floppy floppy, isa-fdc
parallel isa-parallel
serial isa-serial
VGA VGA, cirrus-vga, isa-vga, isa-cirrus-vga,
vmware-svga, qxl-vga, virtio-vga, ati-vga,
vhost-user-vga
The default NIC is connected to a default part created along with it.
It is *not* suppressed by configuring a NIC with -device (you may call
that a bug). -net and -netdev suppress the default NIC.
-nodefaults suppresses all the default devices mentioned above, plus a
few other things such as default SD-Card drive and default monitor.
|