1
= How to convert to -device & friends =
3
=== Specifying Bus and Address on Bus ===
5
In qdev, each device has a parent bus. Some devices provide one or
6
more buses for children. You can specify a device's parent bus with
9
A device typically has a device address on its parent bus. For buses
10
where this address can be configured, devices provide a bus-specific
13
bus property name value format
14
PCI addr %x.%x (dev.fn, .fn optional)
19
virtio-serial-bus nr %u
21
USB port %d(.%d)* (port.port...)
23
Example: device i440FX-pcihost is on the root bus, and provides a PCI
24
bus named pci.0. To put a FOO device into its slot 4, use -device
25
FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0
26
also works as long as the bus name is unique.
30
A QEMU block device (drive) has a host and a guest part.
32
In the general case, the guest device is connected to a controller
33
device. For instance, the IDE controller provides two IDE buses, each
34
of which can have up to two ide-drive devices, and each ide-drive
35
device is a guest part, and is connected to a host part.
37
Except we sometimes lump controller, bus(es) and drive device(s) all
38
together into a single device. For instance, the ISA floppy
39
controller is connected to up to two host drives.
41
The old ways to define block devices define host and guest part
42
together. Sometimes, they can even define a controller device in
43
addition to the block device.
45
The new way keeps the parts separate: you create the host part with
46
-drive, and guest device(s) with -device.
48
The various old ways to define drives all boil down to the common form
50
-drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
52
TYPE, BUS and UNIT identify the controller device, which of its buses
53
to use, and the drive's address on that bus. Details depend on TYPE.
55
Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
57
In the new way, this becomes something like
59
-drive if=none,id=DRIVE-ID,HOST-OPTS...
60
-device DEVNAME,drive=DRIVE-ID,DEV-OPTS...
62
The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
64
* file, format, snapshot, cache, aio, readonly, rerror, werror go into
67
* cyls, head, secs and trans go into HOST-OPTS. Future work: they
68
should go into DEV-OPTS instead.
70
* serial goes into DEV-OPTS, for devices supporting serial numbers.
71
For other devices, it goes nowhere.
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.
77
* addr is special, see if=virtio below.
79
The -device argument differs in detail for each type of drive:
83
-device DEVNAME,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT
85
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.
90
The old way implicitly creates SCSI controllers as needed. The new
91
way makes that explicit:
93
-device lsi53c895a,id=ID
95
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
96
control the PCI device address.
98
This SCSI controller provides a single SCSI bus, named ID.0. Put a
101
-device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
103
where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
107
-global isa-fdc.driveA=DRIVE-ID
108
-global isa-fdc.driveB=DRIVE-ID
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).
114
Without any -global isa-fdc,... you get an empty driveA and no
115
driveB. You can use -nodefaults to suppress the default driveA, see
120
-device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
122
This lets you control PCI device class and MSI-X vectors.
124
IOEVENTFD controls whether or not ioeventfd is used for virtqueue
125
notify. It can be set to on (default) or off.
127
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
128
control the PCI device address. This replaces option addr available
129
with -drive if=virtio.
131
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
133
For USB devices, the old way is actually different:
135
-usbdevice disk:format=FMT:FILENAME
137
Provides much less control than -drive's OPTS... The new way fixes
140
-device usb-storage,drive=DRIVE-ID,removable=RMB
142
The removable parameter gives control over the SCSI INQUIRY removable
143
(RMB) bit. USB thumbdrives usually set removable=on, while USB hard
144
disks set removable=off.
146
Bug: usb-storage pretends to be a block device, but it's really a SCSI
147
controller that can serve only a single device, which it creates
148
automatically. The automatic creation guesses what kind of guest part
149
to create from the host part, like -drive if=scsi. Host and guest
150
part are not cleanly separated.
152
=== Character Devices ===
154
A QEMU character device has a host and a guest part.
156
The old ways to define character devices define host and guest part
159
The new way keeps the parts separate: you create the host part with
160
-chardev, and the guest device with -device.
162
The various old ways to define a character device are all of the
165
-FOO FOO-OPTS...,LEGACY-CHARDEV
167
where FOO-OPTS... is specific to -FOO, and the host part
168
LEGACY-CHARDEV is the same everywhere.
170
In the new way, this becomes
172
-chardev HOST-OPTS...,id=CHR-ID
173
-device DEVNAME,chardev=CHR-ID,DEV-OPTS...
175
The appropriate DEVNAME depends on the machine type. For type "pc":
177
* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
179
This lets you control I/O ports and IRQs.
181
* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
183
This lets you control I/O ports and IRQs.
185
* -usbdevice serial:vendorid=VID,productid=PRID becomes
186
-device usb-serial,vendorid=VID,productid=PRID
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
192
-device usb-braille,chardev=braille,vendorid=VID,productid=PRID
193
-chardev braille,id=braille
195
* -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
199
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
201
* null becomes -chardev null
203
* pty, msmouse, braille, stdio likewise
205
* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
207
* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
209
* con: becomes -chardev console
211
* COM<NUM> becomes -chardev serial,path=COM<NUM>
213
* file:FNAME becomes -chardev file,path=FNAME
215
* pipe:FNAME becomes -chardev pipe,path=FNAME
217
* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
219
* telnet:HOST:PORT,OPTS... becomes
220
-chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
222
* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
223
-chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
225
* unix:FNAME becomes -chardev socket,path=FNAME
227
* /dev/parportN becomes -chardev parport,file=/dev/parportN
231
* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
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.
239
QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
240
also in various other places such as -monitor or -net
241
user,guestfwd=... You can use chardev:CHR-ID in place of
242
LEGACY-CHARDEV to refer to a host part defined with -chardev.
244
=== Network Devices ===
246
Host and guest part of network devices have always been separate.
248
The old way to define the guest part looks like this:
250
-net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
252
Except for USB it looks like this:
254
-usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
256
The new way is -device:
258
-device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
260
DEVNAME equals MODEL, except for virtio you have to name the virtio
261
device appropriate for the bus (virtio-net-pci for PCI), and for USB
262
you have to use usb-net.
264
The old name=ID parameter becomes the usual id=ID with -device.
266
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
267
device address, as usual. The old -net nic provides parameter addr
268
for that, which is silently ignored when the NIC is not a PCI device.
270
For virtio-net-pci, you can control whether or not ioeventfd is used for
271
virtqueue notify by setting ioeventfd= to on or off (default).
273
-net nic accepts vectors=V for all models, but it's silently ignored
274
except for virtio-net-pci (model=virtio). With -device, only devices
275
that support it accept it.
277
Not all devices are available with -device at this time. All PCI
278
devices and ne2k_isa are.
280
Some PCI devices aren't available with -net nic, e.g. i82558a.
282
To connect to a VLAN instead of an ordinary host part, replace
283
netdev=NET-ID by vlan=VLAN.
285
=== Graphics Devices ===
287
Host and guest part of graphics devices have always been separate.
289
The old way to define the guest graphics device is -vga VGA. Not all
290
machines support all -vga options.
292
The new way is -device. The mapping from -vga argument to -device
293
depends on the machine type. For machine "pc", it's:
296
cirrus -device cirrus-vga
297
vmware -device vmware-svga
300
disables more than just VGA, see "Default Devices"
302
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
303
the PCI device address.
305
-device VGA supports properties bios-offset and bios-size, but they
306
aren't used with machine type "pc".
308
For machine "isapc", it's
311
cirrus not yet available with -device
313
disables more than just VGA, see "Default Devices"
315
Bug: the new way doesn't work for machine types "pc" and "isapc",
316
because it violates obscure device initialization ordering
319
=== Audio Devices ===
321
Host and guest part of audio devices have always been separate.
323
The old way to define guest audio devices is -soundhw C1,...
325
The new way is to define each guest audio device separately with
328
Map from -soundhw sound card name to -device:
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
334
hda -device intel-hda,msi=MSI -device hda-duplex
335
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
339
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
340
device address, as usual.
344
The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
346
The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER:
348
* ccid -device usb-ccid
349
* keyboard -device usb-kbd
350
* mouse -device usb-mouse
351
* tablet -device usb-tablet
352
* 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
360
=== Watchdog Devices ===
362
Host and guest part of watchdog devices have always been separate.
364
The old way to define a guest watchdog device is -watchdog DEVNAME.
365
The new way is -device DEVNAME. For PCI devices, you can add
366
bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
368
=== Host Device Assignment ===
370
QEMU supports assigning host PCI devices (qemu-kvm only at this time)
371
and host USB devices.
373
The old way to assign a host PCI device is
375
-pcidevice host=ADDR,dma=none,id=ID
379
-device pci-assign,host=ADDR,iommu=IOMMU,id=ID
381
The old dma=none becomes iommu=off with -device.
383
The old way to assign a host USB device is
385
-usbdevice host:auto:BUS.ADDR:VID:PRID
387
where any of BUS, ADDR, VID, PRID can be the wildcard *.
391
-device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
393
Omitted options match anything, just like the old way's wildcard.
395
=== Default Devices ===
397
QEMU creates a number of devices by default, depending on the machine
400
-device DEVNAME... and global DEVNAME... suppress default devices for
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
408
VGA VGA, cirrus-vga, vmware-svga
409
virtioconsole virtio-serial-pci, virtio-serial-s390, virtio-serial
411
The default NIC is connected to a default part created along with it.
412
It is *not* suppressed by configuring a NIC with -device (you may call
413
that a bug). -net and -netdev suppress the default NIC.
415
-nodefaults suppresses all the default devices mentioned above, plus a
416
few other things such as default SD-Card drive and default monitor.
added
removed
docs/qdev-device-use.txt
