blob: 136d2711203f4385a381b9dcb81ea6b61ef02dee [file] [log] [blame]
Markus Armbruster96560cb2009-12-17 17:19:17 +01001= How to convert to -device & friends =
2
3=== Specifying Bus and Address on Bus ===
4
5In qdev, each device has a parent bus. Some devices provide one or
6more buses for children. You can specify a device's parent bus with
7-device parameter bus.
8
9A device typically has a device address on its parent bus. For buses
10where this address can be configured, devices provide a bus-specific
Markus Armbruster23bf93b2011-06-07 10:34:31 +020011property. Examples:
Markus Armbruster96560cb2009-12-17 17:19:17 +010012
Markus Armbruster23bf93b2011-06-07 10:34:31 +020013 bus property name value format
14 PCI addr %x.%x (dev.fn, .fn optional)
15 I2C address %u
16 SCSI scsi-id %u
17 IDE unit %u
18 HDA cad %u
19 virtio-serial-bus nr %u
20 ccid-bus slot %u
21 USB port %d(.%d)* (port.port...)
Markus Armbruster96560cb2009-12-17 17:19:17 +010022
23Example: device i440FX-pcihost is on the root bus, and provides a PCI
24bus named pci.0. To put a FOO device into its slot 4, use -device
25FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0
26also works as long as the bus name is unique.
27
Markus Armbruster96560cb2009-12-17 17:19:17 +010028=== Block Devices ===
29
30A QEMU block device (drive) has a host and a guest part.
31
32In the general case, the guest device is connected to a controller
33device. For instance, the IDE controller provides two IDE buses, each
34of which can have up to two ide-drive devices, and each ide-drive
35device is a guest part, and is connected to a host part.
36
37Except we sometimes lump controller, bus(es) and drive device(s) all
38together into a single device. For instance, the ISA floppy
39controller is connected to up to two host drives.
40
41The old ways to define block devices define host and guest part
42together. Sometimes, they can even define a controller device in
43addition to the block device.
44
45The new way keeps the parts separate: you create the host part with
46-drive, and guest device(s) with -device.
47
48The various old ways to define drives all boil down to the common form
49
Markus Armbruster23bf93b2011-06-07 10:34:31 +020050 -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
Markus Armbruster96560cb2009-12-17 17:19:17 +010051
52TYPE, BUS and UNIT identify the controller device, which of its buses
53to use, and the drive's address on that bus. Details depend on TYPE.
Markus Armbruster23bf93b2011-06-07 10:34:31 +020054
55Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
Markus Armbruster96560cb2009-12-17 17:19:17 +010056
57In the new way, this becomes something like
58
59 -drive if=none,id=DRIVE-ID,HOST-OPTS...
60 -device DEVNAME,drive=DRIVE-ID,DEV-OPTS...
61
Markus Armbruster23bf93b2011-06-07 10:34:31 +020062The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
63
64* file, format, snapshot, cache, aio, readonly, rerror, werror go into
65 HOST-OPTS.
66
67* cyls, head, secs and trans go into HOST-OPTS. Future work: they
68 should go into DEV-OPTS instead.
69
70* serial goes into DEV-OPTS, for devices supporting serial numbers.
71 For other devices, it goes nowhere.
72
73* media is special. In the old way, it selects disk vs. CD-ROM with
74 if=ide, if=scsi and if=xen. The new way uses DEVNAME for that.
75 Additionally, readonly=on goes into HOST-OPTS.
76
77* addr is special, see if=virtio below.
78
79The -device argument differs in detail for each type of drive:
Markus Armbruster96560cb2009-12-17 17:19:17 +010080
81* if=ide
82
Markus Armbruster23bf93b2011-06-07 10:34:31 +020083 -device DEVNAME,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT
Markus Armbruster96560cb2009-12-17 17:19:17 +010084
Markus Armbruster23bf93b2011-06-07 10:34:31 +020085 where DEVNAME is either ide-hd or ide-cd, IDE-BUS identifies an IDE
86 bus, normally either ide.0 or ide.1, and UNIT is either 0 or 1.
Markus Armbruster96560cb2009-12-17 17:19:17 +010087
88* if=scsi
89
90 The old way implicitly creates SCSI controllers as needed. The new
91 way makes that explicit:
92
93 -device lsi53c895a,id=ID
94
95 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
96 control the PCI device address.
97
Markus Armbruster23bf93b2011-06-07 10:34:31 +020098 This SCSI controller provides a single SCSI bus, named ID.0. Put a
99 disk on it:
Markus Armbruster96560cb2009-12-17 17:19:17 +0100100
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200101 -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
Stefan Hajnoczia5c062e2011-01-24 15:35:01 +0000102
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200103 where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100104
105* if=floppy
106
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200107 -global isa-fdc.driveA=DRIVE-ID
108 -global isa-fdc.driveB=DRIVE-ID
Markus Armbruster96560cb2009-12-17 17:19:17 +0100109
110 This is -global instead of -device, because the floppy controller is
111 created automatically, and we want to configure that one, not create
112 a second one (which isn't possible anyway).
113
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200114 Without any -global isa-fdc,... you get an empty driveA and no
115 driveB. You can use -nodefaults to suppress the default driveA, see
116 "Default Devices".
Markus Armbruster96560cb2009-12-17 17:19:17 +0100117
118* if=virtio
119
Stefan Hajnoczi65d6dcb2010-12-17 12:01:52 +0000120 -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
Markus Armbruster96560cb2009-12-17 17:19:17 +0100121
122 This lets you control PCI device class and MSI-X vectors.
123
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200124 IOEVENTFD controls whether or not ioeventfd is used for virtqueue
125 notify. It can be set to on (default) or off.
Stefan Hajnoczi65d6dcb2010-12-17 12:01:52 +0000126
Markus Armbruster96560cb2009-12-17 17:19:17 +0100127 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200128 control the PCI device address. This replaces option addr available
129 with -drive if=virtio.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100130
131* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
132
133For USB devices, the old way is actually different:
134
135 -usbdevice disk:format=FMT:FILENAME
136
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200137Provides much less control than -drive's OPTS... The new way fixes
138that:
Markus Armbruster96560cb2009-12-17 17:19:17 +0100139
Stefan Hajnoczia5c062e2011-01-24 15:35:01 +0000140 -device usb-storage,drive=DRIVE-ID,removable=RMB
141
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200142The removable parameter gives control over the SCSI INQUIRY removable
143(RMB) bit. USB thumbdrives usually set removable=on, while USB hard
144disks set removable=off.
145
146Bug: usb-storage pretends to be a block device, but it's really a SCSI
147controller that can serve only a single device, which it creates
148automatically. The automatic creation guesses what kind of guest part
149to create from the host part, like -drive if=scsi. Host and guest
150part are not cleanly separated.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100151
152=== Character Devices ===
153
154A QEMU character device has a host and a guest part.
155
156The old ways to define character devices define host and guest part
157together.
158
159The new way keeps the parts separate: you create the host part with
160-chardev, and the guest device with -device.
161
162The various old ways to define a character device are all of the
163general form
164
165 -FOO FOO-OPTS...,LEGACY-CHARDEV
166
167where FOO-OPTS... is specific to -FOO, and the host part
168LEGACY-CHARDEV is the same everywhere.
169
170In the new way, this becomes
171
172 -chardev HOST-OPTS...,id=CHR-ID
173 -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
174
175The appropriate DEVNAME depends on the machine type. For type "pc":
176
177* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
178
179 This lets you control I/O ports and IRQs.
180
181* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
182
183 This lets you control I/O ports and IRQs.
184
185* -usbdevice serial:vendorid=VID,productid=PRID becomes
186 -device usb-serial,vendorid=VID,productid=PRID
187
188* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always
189 uses "braille". With -device, this useful default is gone, so you
190 have to use something like
191
192 -device usb-braille,chardev=braille,vendorid=VID,productid=PRID
193 -chardev braille,id=braille
194
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200195* -virtioconsole becomes
196 -device virtio-serial-pci,class=C,vectors=V,ioeventfd=IOEVENTFD,max_ports=N
197 -device virtconsole,is_console=NUM,nr=NR,name=NAME
Markus Armbruster96560cb2009-12-17 17:19:17 +0100198
199LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
200
201* null becomes -chardev null
202
203* pty, msmouse, braille, stdio likewise
204
205* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
206
207* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
208
209* con: becomes -chardev console
210
Markus Armbruster6e93a442011-09-06 10:01:36 +0200211* COM<NUM> becomes -chardev serial,path=COM<NUM>
Markus Armbruster96560cb2009-12-17 17:19:17 +0100212
213* file:FNAME becomes -chardev file,path=FNAME
214
215* pipe:FNAME becomes -chardev pipe,path=FNAME
216
217* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
218
219* telnet:HOST:PORT,OPTS... becomes
220 -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
221
222* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
223 -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
224
225* unix:FNAME becomes -chardev socket,path=FNAME
226
227* /dev/parportN becomes -chardev parport,file=/dev/parportN
228
229* /dev/ppiN likewise
230
231* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
232
233* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
234 character device defined by LEGACY-CHARDEV. -chardev provides more
235 general multiplexing instead: you can connect up to four users to a
236 single host part. You need to pass mux=on to -chardev to enable
237 switching the input focus.
238
239QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
240also in various other places such as -monitor or -net
241user,guestfwd=... You can use chardev:CHR-ID in place of
242LEGACY-CHARDEV to refer to a host part defined with -chardev.
243
244=== Network Devices ===
245
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200246Host and guest part of network devices have always been separate.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100247
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200248The old way to define the guest part looks like this:
Markus Armbruster96560cb2009-12-17 17:19:17 +0100249
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200250 -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
Markus Armbruster96560cb2009-12-17 17:19:17 +0100251
252Except for USB it looks like this:
253
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200254 -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
Markus Armbruster96560cb2009-12-17 17:19:17 +0100255
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200256The new way is -device:
Markus Armbruster96560cb2009-12-17 17:19:17 +0100257
Markus Armbruster96560cb2009-12-17 17:19:17 +0100258 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
259
Markus Armbruster96560cb2009-12-17 17:19:17 +0100260DEVNAME equals MODEL, except for virtio you have to name the virtio
261device appropriate for the bus (virtio-net-pci for PCI), and for USB
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200262you have to use usb-net.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100263
264The old name=ID parameter becomes the usual id=ID with -device.
265
266For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
267device address, as usual. The old -net nic provides parameter addr
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200268for that, which is silently ignored when the NIC is not a PCI device.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100269
Stefan Hajnoczi65d6dcb2010-12-17 12:01:52 +0000270For virtio-net-pci, you can control whether or not ioeventfd is used for
271virtqueue notify by setting ioeventfd= to on or off (default).
272
Markus Armbruster96560cb2009-12-17 17:19:17 +0100273-net nic accepts vectors=V for all models, but it's silently ignored
274except for virtio-net-pci (model=virtio). With -device, only devices
275that support it accept it.
276
277Not all devices are available with -device at this time. All PCI
278devices and ne2k_isa are.
279
280Some PCI devices aren't available with -net nic, e.g. i82558a.
281
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200282To connect to a VLAN instead of an ordinary host part, replace
283netdev=NET-ID by vlan=VLAN.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100284
285=== Graphics Devices ===
286
287Host and guest part of graphics devices have always been separate.
288
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200289The old way to define the guest graphics device is -vga VGA. Not all
290machines support all -vga options.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100291
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200292The new way is -device. The mapping from -vga argument to -device
293depends on the machine type. For machine "pc", it's:
Markus Armbruster96560cb2009-12-17 17:19:17 +0100294
295 std -device VGA
296 cirrus -device cirrus-vga
297 vmware -device vmware-svga
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200298 qxl -device qxl-vga
299 none -nodefaults
300 disables more than just VGA, see "Default Devices"
Markus Armbruster96560cb2009-12-17 17:19:17 +0100301
302As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
303the PCI device address.
304
305-device VGA supports properties bios-offset and bios-size, but they
306aren't used with machine type "pc".
307
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200308For machine "isapc", it's
Markus Armbruster96560cb2009-12-17 17:19:17 +0100309
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200310 std -device isa-vga
311 cirrus not yet available with -device
312 none -nodefaults
313 disables more than just VGA, see "Default Devices"
Markus Armbruster96560cb2009-12-17 17:19:17 +0100314
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200315Bug: the new way doesn't work for machine types "pc" and "isapc",
316because it violates obscure device initialization ordering
317constraints.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100318
319=== Audio Devices ===
320
321Host and guest part of audio devices have always been separate.
322
323The old way to define guest audio devices is -soundhw C1,...
324
325The new way is to define each guest audio device separately with
326-device.
327
328Map from -soundhw sound card name to -device:
329
330 ac97 -device AC97
331 cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
332 es1370 -device ES1370
333 gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200334 hda -device intel-hda,msi=MSI -device hda-duplex
Markus Armbruster96560cb2009-12-17 17:19:17 +0100335 sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
336 adlib not yet available with -device
337 pcspk not yet available with -device
338
339For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
340device address, as usual.
341
342=== USB Devices ===
343
344The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
345
346The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER:
347
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200348* ccid -device usb-ccid
349* keyboard -device usb-kbd
Markus Armbruster96560cb2009-12-17 17:19:17 +0100350* mouse -device usb-mouse
351* tablet -device usb-tablet
Markus Armbruster96560cb2009-12-17 17:19:17 +0100352* wacom-tablet -device usb-wacom-tablet
353* host:... See "Host Device Assignment"
354* disk:... See "Block Devices"
355* serial:... See "Character Devices"
356* braille See "Character Devices"
357* net:... See "Network Devices"
358* bt:... not yet available with -device
359
360=== Watchdog Devices ===
361
362Host and guest part of watchdog devices have always been separate.
363
364The old way to define a guest watchdog device is -watchdog DEVNAME.
365The new way is -device DEVNAME. For PCI devices, you can add
366bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
367
368=== Host Device Assignment ===
369
370QEMU supports assigning host PCI devices (qemu-kvm only at this time)
371and host USB devices.
372
373The old way to assign a host PCI device is
374
375 -pcidevice host=ADDR,dma=none,id=ID
376
377The new way is
378
379 -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
380
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200381The old dma=none becomes iommu=off with -device.
Markus Armbruster96560cb2009-12-17 17:19:17 +0100382
383The old way to assign a host USB device is
384
385 -usbdevice host:auto:BUS.ADDR:VID:PRID
386
387where any of BUS, ADDR, VID, PRID can be the wildcard *.
388
389The new way is
390
391 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
392
Markus Armbruster23bf93b2011-06-07 10:34:31 +0200393Omitted options match anything, just like the old way's wildcard.
394
395=== Default Devices ===
396
397QEMU creates a number of devices by default, depending on the machine
398type.
399
400-device DEVNAME... and global DEVNAME... suppress default devices for
401some DEVNAMEs:
402
403 default device suppressing DEVNAMEs
404 CD-ROM ide-cd, ide-drive, scsi-cd
405 isa-fdc's driveA isa-fdc
406 parallel isa-parallel
407 serial isa-serial
408 VGA VGA, cirrus-vga, vmware-svga
409 virtioconsole virtio-serial-pci, virtio-serial-s390, virtio-serial
410
411The default NIC is connected to a default part created along with it.
412It is *not* suppressed by configuring a NIC with -device (you may call
413that a bug). -net and -netdev suppress the default NIC.
414
415-nodefaults suppresses all the default devices mentioned above, plus a
416few other things such as default SD-Card drive and default monitor.