qemu/docs/qdev-device-use.txt

1 = How to convert to -device & friends =
7 -device parameter bus.
10 where this address can be configured, devices provide a bus-specific
16     SCSI        scsi-id             %u
19     virtio-serial-bus  nr           %u
20     ccid-bus    slot                %u
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
45 The new way keeps the parts separate: you create the host part with
46 -drive, and guest device(s) with -device.
50     -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
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:
65   HOST-OPTS.
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.
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.
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
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
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   -device floppy,unit=UNIT,drive=DRIVE-ID
109   Without any -device floppy,... you get an empty unit 0 and no unit
110   1.  You can use -nodefaults to suppress the default unit 0, see
115   -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
117   This lets you control PCI device class and MSI-X vectors.
122   As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
124   with -drive if=virtio.
126 * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
128 For USB devices, the old way was actually different:
130     -usbdevice disk:format=FMT:FILENAME
134 The old way provided much less control than -drive's OPTS...  The new
135 way fixes that:
137     -device usb-storage,drive=DRIVE-ID,removable=RMB
143 Bug: usb-storage pretends to be a block device, but it's really a SCSI
146 to create from the host part, like -drive if=scsi.  Host and guest
156 The new way keeps the parts separate: you create the host part with
157 -chardev, and the guest device with -device.
162     -FOO FOO-OPTS...,LEGACY-CHARDEV
164 where FOO-OPTS... is specific to -FOO, and the host part
165 LEGACY-CHARDEV is the same everywhere.
167 In the new way, this becomes
169     -chardev HOST-OPTS...,id=CHR-ID
170     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
174 * -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
178 * -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
182 * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
183   uses "braille".  With -device, this useful default is gone, so you
186   -device usb-braille,chardev=braille -chardev braille,id=braille
188 * -usbdevice serial::chardev is gone since v2.12.0.  It became
189   -device usb-serial,chardev=dev.
191 LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
193 * null becomes -chardev null
197 * vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
199 * vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
201 * con: becomes -chardev console
203 * COM<NUM> becomes -chardev serial,path=COM<NUM>
205 * file:FNAME becomes -chardev file,path=FNAME
207 * pipe:FNAME becomes -chardev pipe,path=FNAME
209 * tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
212   -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
215   -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
217 * unix:FNAME becomes -chardev socket,path=FNAME
219 * /dev/parportN becomes -chardev parallel,file=/dev/parportN
223 * Any other /dev/FNAME becomes -chardev serial,path=/dev/FNAME
225 * mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
226   character device defined by LEGACY-CHARDEV.  -chardev provides more
228   single host part.  You need to pass mux=on to -chardev to enable
231 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
232 also in various other places such as -monitor or -net
233 user,guestfwd=...  You can use chardev:CHR-ID in place of
234 LEGACY-CHARDEV to refer to a host part defined with -chardev.
240 The old way to define the guest part looks like this:
242     -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
246     -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
250 The new way is -device:
252     -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
255 device appropriate for the bus (virtio-net-pci for PCI), and for USB
256 you have to use usb-net.
258 The old name=ID parameter becomes the usual id=ID with -device.
260 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
261 device address, as usual.  The old -net nic provides parameter addr
264 For virtio-net-pci, you can control whether or not ioeventfd is used for
267 -net nic accepts vectors=V for all models, but it's silently ignored
268 except for virtio-net-pci (model=virtio).  With -device, only devices
271 Not all devices are available with -device at this time.  All PCI
274 Some PCI devices aren't available with -net nic, e.g. i82558a.
280 The old way to define the guest graphics device is -vga VGA.  Not all
281 machines support all -vga options.
283 The new way is -device.  The mapping from -vga argument to -device
286     std         -device VGA
287     cirrus      -device cirrus-vga
288     vmware      -device vmware-svga
289     qxl         -device qxl-vga
290     none        -nodefaults
293 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
296 -device VGA supports properties bios-offset and bios-size, but they
301     std         -device isa-vga
302     cirrus      not yet available with -device
303     none        -nodefaults
306 Bug: the new way doesn't work for machine types "pc" and "isapc",
314 The old way to define guest audio devices is -soundhw C1,...
316 The new way is to define each guest audio device separately with
317 -device.
319 Map from -soundhw sound card name to -device:
321     ac97        -device AC97
322     cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
323     es1370      -device ES1370
324     gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
325     hda         -device intel-hda,msi=MSI -device hda-duplex
326     sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
327     adlib       not yet available with -device
328     pcspk       not yet available with -device
330 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
335 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
337 The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
339 * ccid            -device usb-ccid
340 * keyboard        -device usb-kbd
341 * mouse           -device usb-mouse
342 * tablet          -device usb-tablet
343 * wacom-tablet    -device usb-wacom-tablet
344 * u2f             -device u2f-{emulated,passthru}
358 The old way to define a guest watchdog device is -watchdog DEVNAME.
359 The new way is -device DEVNAME.  For PCI devices, you can add
360 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
364 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
365 and host USB devices.  PCI devices can only be assigned with -device:
367     -device vfio-pci,host=ADDR,id=ID
369 The old way to assign a USB host device
371     -usbdevice host:auto:BUS.ADDR:VID:PRID
376 The new way is
378     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
387 -device DEVNAME... and global DEVNAME... suppress default devices for
391     CD-ROM              ide-cd, ide-hd, scsi-cd, scsi-hd
392     floppy              floppy, isa-fdc
393     parallel            isa-parallel
394     serial              isa-serial
395     VGA                 VGA, cirrus-vga, isa-vga, isa-cirrus-vga,
396                         vmware-svga, qxl-vga, virtio-vga, ati-vga,
397                         vhost-user-vga
400 It is *not* suppressed by configuring a NIC with -device (you may call
401 that a bug).  -net and -netdev suppress the default NIC.
403 -nodefaults suppresses all the default devices mentioned above, plus a
404 few other things such as default SD-Card drive and default monitor.