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. These are
-
- bus property name value format
- PCI addr %x.%x (dev.fn, .fn optional)
- I2C address %u
- SCSI scsi-id %u
+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.
-Note: the USB device address can't be controlled at this time.
-
=== 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 ide-drive devices, and each ide-drive
-device is a guest part, and is connected to a host part.
+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
The various old ways to define drives all boil down to the common form
- -drive if=TYPE,index=IDX,bus=BUS,unit=UNIT,HOST-OPTS...
+ -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.
-IDX is an alternative way to specify BUS and UNIT.
+
+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 -device argument differs in detail for each kind of drive:
+The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
-* if=ide
+* 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.
- -device ide-drive,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT
+* serial goes into DEV-OPTS, for devices supporting serial numbers.
+ For other devices, it goes nowhere.
- where IDE-BUS identifies an IDE bus, normally either ide.0 or ide.1,
- and UNIT is either 0 or 1.
+* 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
- Bug: new way does not work for ide.1 unit 0 (in old terms: index=2)
- unless you disable the default CD-ROM with -nodefaults.
+ -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
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
control the PCI device address.
- This SCSI controller a single SCSI bus, named ID.0. Put a disk on
- it:
+ This SCSI controller provides a single SCSI bus, named ID.0. Put a
+ disk on it:
- -device scsi-disk,drive=DRIVE-ID,bus=ID.0,scsi-id=SCSI-ID,removable=RMB
+ -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
- The (optional) removable parameter lets you override the SCSI INQUIRY
- removable (RMB) bit for non CD-ROM devices. It is ignored for CD-ROM devices
- which are always removable. RMB is "on" or "off".
+ where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
* if=floppy
- -global isa-fdc,driveA=DRIVE-ID,driveB=DRIVE-ID
-
- This is -global instead of -device, because the floppy controller is
- created automatically, and we want to configure that one, not create
- a second one (which isn't possible anyway).
+ -device floppy,unit=UNIT,drive=DRIVE-ID
- Omitting a drive parameter makes that drive empty.
-
- Bug: driveA works only if you disable the default floppy drive with
- -nodefaults.
+ 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
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.
+ 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.
+ 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 devices, the old way is actually different:
+For USB devices, the old way was actually different:
-usbdevice disk:format=FMT:FILENAME
-Provides much less control than -drive's HOST-OPTS... The new way
-fixes that:
+"Was" because "disk:" is gone since v2.12.0.
+
+The old way provided much less control than -drive's OPTS... The new
+way fixes that:
-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. See the if=scsi description above for details on the removable
-parameter, which applies only to scsi-disk devices and not to scsi-generic.
+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 ===
This lets you control I/O ports and IRQs.
-* -usbdevice serial:vendorid=VID,productid=PRID becomes
- -device usb-serial,vendorid=VID,productid=PRID
-
* -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,vendorid=VID,productid=PRID
- -chardev braille,id=braille
+ -device usb-braille,chardev=braille -chardev braille,id=braille
-* -virtioconsole is still being worked on
+* -usbdevice serial::chardev is gone since v2.12.0. It became
+ -device usb-serial,chardev=dev.
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
* null becomes -chardev null
-* pty, msmouse, braille, stdio likewise
+* pty, msmouse, wctablet, braille, stdio likewise
* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
* con: becomes -chardev console
-* COM<NUM> becomes -chardev serial,path=<NUM>
+* COM<NUM> becomes -chardev serial,path=COM<NUM>
* file:FNAME becomes -chardev file,path=FNAME
=== Network Devices ===
-A QEMU network device (NIC) has a host and a guest part.
+Host and guest part of network devices have always been separate.
-The old ways to define NICs define host and guest part together. It
-looks like this:
+The old way to define the guest part looks like this:
- -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
+ -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
-Except for USB it looks like this:
+Except for USB it looked like this:
- -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V
+ -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
-The new way keeps the parts separate: you create the host part with
--netdev, and the guest device with -device, like this:
+"Looked" because "net:" is gone since v2.12.0.
- -netdev type=TYPE,id=NET-ID
- -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
-
-Unlike the old way, this creates just a network device, not a VLAN.
-If you really want a VLAN, create it the usual way, then create the
-guest device like this:
+The new way is -device:
- -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS...
+ -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
-NIC you have to use usb-net.
+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, it is silently ignored when the NIC is not a PCI device.
+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).
Some PCI devices aren't available with -net nic, e.g. i82558a.
-Bug: usb-net does not work, yet. Patch posted.
-
=== 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.
+The old way to define the guest graphics device is -vga VGA. Not all
+machines support all -vga options.
-The new way is -device. Map from -vga argument to -device:
+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
- xenfb not yet available with -device
+ 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".
-Bug: -device cirrus-vga and -device vmware-svga require -nodefaults.
+For machine "isapc", it's
-Bug: the new way requires PCI; ISA VGA is not yet available with
--device.
+ 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 type "pc", because it
-violates obscure device initialization ordering constraints.
+Bug: the new way doesn't work for machine types "pc" and "isapc",
+because it violates obscure device initialization ordering
+constraints.
=== Audio Devices ===
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
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
-* keyboard -device usb-kdb
* wacom-tablet -device usb-wacom-tablet
+* u2f -device u2f-{emulated,passthru}
+* braille See "Character Devices"
+
+Until v2.12.0, we additionally had
+
* host:... See "Host Device Assignment"
* disk:... See "Block Devices"
* serial:... See "Character Devices"
-* braille See "Character Devices"
* net:... See "Network Devices"
-* bt:... not yet available with -device
=== Watchdog Devices ===
=== Host Device Assignment ===
QEMU supports assigning host PCI devices (qemu-kvm only at this time)
-and host USB devices.
+and host USB devices. PCI devices can only be assigned with -device:
+
+ -device vfio-pci,host=ADDR,id=ID
-The old way to assign a host PCI device is
+The old way to assign a USB host device
+
+ -usbdevice host:auto:BUS.ADDR:VID:PRID
- -pcidevice host=ADDR,dma=none,id=ID
+was removed in v2.12.0. Any of BUS, ADDR, VID, PRID could be the
+wildcard *.
The new way is
- -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
+ -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
-The old dma=none becomes iommu=0 with -device.
+Omitted options match anything.
-The old way to assign a host USB device is
+=== Default Devices ===
- -usbdevice host:auto:BUS.ADDR:VID:PRID
+QEMU creates a number of devices by default, depending on the machine
+type.
-where any of BUS, ADDR, VID, PRID can be the wildcard *.
+-device DEVNAME... and global DEVNAME... suppress default devices for
+some DEVNAMEs:
-The new way is
+ default device suppressing DEVNAMEs
+ CD-ROM ide-cd, 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
- -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
+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.
-where left out or zero BUS, ADDR, VID, PRID serve as wildcard.
+-nodefaults suppresses all the default devices mentioned above, plus a
+few other things such as default SD-Card drive and default monitor.