Revision 23bf93b2
| b/docs/qdev-device-use.txt | ||
|---|---|---|
| 8 | 8 |
|
| 9 | 9 |
A device typically has a device address on its parent bus. For buses |
| 10 | 10 |
where this address can be configured, devices provide a bus-specific |
| 11 |
property. These are |
|
| 12 |
|
|
| 13 |
bus property name value format |
|
| 14 |
PCI addr %x.%x (dev.fn, .fn optional) |
|
| 15 |
I2C address %u |
|
| 16 |
SCSI scsi-id %u |
|
| 11 |
property. Examples: |
|
| 12 |
|
|
| 13 |
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...) |
|
| 17 | 22 |
|
| 18 | 23 |
Example: device i440FX-pcihost is on the root bus, and provides a PCI |
| 19 | 24 |
bus named pci.0. To put a FOO device into its slot 4, use -device |
| 20 | 25 |
FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0 |
| 21 | 26 |
also works as long as the bus name is unique. |
| 22 | 27 |
|
| 23 |
Note: the USB device address can't be controlled at this time. |
|
| 24 |
|
|
| 25 | 28 |
=== Block Devices === |
| 26 | 29 |
|
| 27 | 30 |
A QEMU block device (drive) has a host and a guest part. |
| ... | ... | |
| 44 | 47 |
|
| 45 | 48 |
The various old ways to define drives all boil down to the common form |
| 46 | 49 |
|
| 47 |
-drive if=TYPE,index=IDX,bus=BUS,unit=UNIT,HOST-OPTS...
|
|
| 50 |
-drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
|
|
| 48 | 51 |
|
| 49 | 52 |
TYPE, BUS and UNIT identify the controller device, which of its buses |
| 50 | 53 |
to use, and the drive's address on that bus. Details depend on TYPE. |
| 51 |
IDX is an alternative way to specify BUS and UNIT. |
|
| 54 |
|
|
| 55 |
Instead of bus=BUS,unit=UNIT, you can also say index=IDX. |
|
| 52 | 56 |
|
| 53 | 57 |
In the new way, this becomes something like |
| 54 | 58 |
|
| 55 | 59 |
-drive if=none,id=DRIVE-ID,HOST-OPTS... |
| 56 | 60 |
-device DEVNAME,drive=DRIVE-ID,DEV-OPTS... |
| 57 | 61 |
|
| 58 |
The -device argument differs in detail for each kind of drive:
|
|
| 62 |
The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
|
|
| 59 | 63 |
|
| 60 |
* if=ide |
|
| 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. |
|
| 61 | 72 |
|
| 62 |
-device ide-drive,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT |
|
| 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. |
|
| 63 | 76 |
|
| 64 |
where IDE-BUS identifies an IDE bus, normally either ide.0 or ide.1, |
|
| 65 |
and UNIT is either 0 or 1. |
|
| 77 |
* addr is special, see if=virtio below. |
|
| 66 | 78 |
|
| 67 |
Bug: new way does not work for ide.1 unit 0 (in old terms: index=2) |
|
| 68 |
unless you disable the default CD-ROM with -nodefaults. |
|
| 79 |
The -device argument differs in detail for each type of drive: |
|
| 80 |
|
|
| 81 |
* if=ide |
|
| 82 |
|
|
| 83 |
-device DEVNAME,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT |
|
| 84 |
|
|
| 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. |
|
| 69 | 87 |
|
| 70 | 88 |
* if=scsi |
| 71 | 89 |
|
| ... | ... | |
| 77 | 95 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to |
| 78 | 96 |
control the PCI device address. |
| 79 | 97 |
|
| 80 |
This SCSI controller a single SCSI bus, named ID.0. Put a disk on
|
|
| 81 |
it: |
|
| 98 |
This SCSI controller provides a single SCSI bus, named ID.0. Put a
|
|
| 99 |
disk on it:
|
|
| 82 | 100 |
|
| 83 |
-device scsi-disk,drive=DRIVE-ID,bus=ID.0,scsi-id=SCSI-ID,removable=RMB
|
|
| 101 |
-device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
|
|
| 84 | 102 |
|
| 85 |
The (optional) removable parameter lets you override the SCSI INQUIRY |
|
| 86 |
removable (RMB) bit for non CD-ROM devices. It is ignored for CD-ROM devices |
|
| 87 |
which are always removable. RMB is "on" or "off". |
|
| 103 |
where DEVNAME is either scsi-hd, scsi-cd or scsi-generic. |
|
| 88 | 104 |
|
| 89 | 105 |
* if=floppy |
| 90 | 106 |
|
| 91 |
-global isa-fdc,driveA=DRIVE-ID,driveB=DRIVE-ID |
|
| 107 |
-global isa-fdc.driveA=DRIVE-ID |
|
| 108 |
-global isa-fdc.driveB=DRIVE-ID |
|
| 92 | 109 |
|
| 93 | 110 |
This is -global instead of -device, because the floppy controller is |
| 94 | 111 |
created automatically, and we want to configure that one, not create |
| 95 | 112 |
a second one (which isn't possible anyway). |
| 96 | 113 |
|
| 97 |
Omitting a drive parameter makes that drive empty. |
|
| 98 |
|
|
| 99 |
Bug: driveA works only if you disable the default floppy drive with |
|
| 100 |
-nodefaults. |
|
| 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 |
|
| 116 |
"Default Devices". |
|
| 101 | 117 |
|
| 102 | 118 |
* if=virtio |
| 103 | 119 |
|
| ... | ... | |
| 105 | 121 |
|
| 106 | 122 |
This lets you control PCI device class and MSI-X vectors. |
| 107 | 123 |
|
| 108 |
IOEVENTFD controls whether or not ioeventfd is used for virtqueue notify. It
|
|
| 109 |
can be set to on (default) or off. |
|
| 124 |
IOEVENTFD controls whether or not ioeventfd is used for virtqueue |
|
| 125 |
notify. It can be set to on (default) or off.
|
|
| 110 | 126 |
|
| 111 | 127 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to |
| 112 |
control the PCI device address. |
|
| 128 |
control the PCI device address. This replaces option addr available |
|
| 129 |
with -drive if=virtio. |
|
| 113 | 130 |
|
| 114 | 131 |
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device |
| 115 | 132 |
|
| ... | ... | |
| 117 | 134 |
|
| 118 | 135 |
-usbdevice disk:format=FMT:FILENAME |
| 119 | 136 |
|
| 120 |
Provides much less control than -drive's HOST-OPTS... The new way
|
|
| 121 |
fixes that:
|
|
| 137 |
Provides much less control than -drive's OPTS... The new way fixes
|
|
| 138 |
that: |
|
| 122 | 139 |
|
| 123 | 140 |
-device usb-storage,drive=DRIVE-ID,removable=RMB |
| 124 | 141 |
|
| 125 |
The removable parameter gives control over the SCSI INQUIRY removable (RMB) |
|
| 126 |
bit. USB thumbdrives usually set removable=on, while USB hard disks set |
|
| 127 |
removable=off. See the if=scsi description above for details on the removable |
|
| 128 |
parameter, which applies only to scsi-disk devices and not to scsi-generic. |
|
| 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. |
|
| 145 |
|
|
| 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. |
|
| 129 | 151 |
|
| 130 | 152 |
=== Character Devices === |
| 131 | 153 |
|
| ... | ... | |
| 170 | 192 |
-device usb-braille,chardev=braille,vendorid=VID,productid=PRID |
| 171 | 193 |
-chardev braille,id=braille |
| 172 | 194 |
|
| 173 |
* -virtioconsole is still being worked on |
|
| 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 |
|
| 174 | 198 |
|
| 175 | 199 |
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: |
| 176 | 200 |
|
| ... | ... | |
| 219 | 243 |
|
| 220 | 244 |
=== Network Devices === |
| 221 | 245 |
|
| 222 |
A QEMU network device (NIC) has a host and a guest part.
|
|
| 246 |
Host and guest part of network devices have always been separate.
|
|
| 223 | 247 |
|
| 224 |
The old ways to define NICs define host and guest part together. It |
|
| 225 |
looks like this: |
|
| 248 |
The old way to define the guest part looks like this: |
|
| 226 | 249 |
|
| 227 |
-net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
|
|
| 250 |
-net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
|
|
| 228 | 251 |
|
| 229 | 252 |
Except for USB it looks like this: |
| 230 | 253 |
|
| 231 |
-usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V
|
|
| 254 |
-usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
|
|
| 232 | 255 |
|
| 233 |
The new way keeps the parts separate: you create the host part with |
|
| 234 |
-netdev, and the guest device with -device, like this: |
|
| 256 |
The new way is -device: |
|
| 235 | 257 |
|
| 236 |
-netdev type=TYPE,id=NET-ID |
|
| 237 | 258 |
-device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... |
| 238 | 259 |
|
| 239 |
Unlike the old way, this creates just a network device, not a VLAN. |
|
| 240 |
If you really want a VLAN, create it the usual way, then create the |
|
| 241 |
guest device like this: |
|
| 242 |
|
|
| 243 |
-device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS... |
|
| 244 |
|
|
| 245 | 260 |
DEVNAME equals MODEL, except for virtio you have to name the virtio |
| 246 | 261 |
device appropriate for the bus (virtio-net-pci for PCI), and for USB |
| 247 |
NIC you have to use usb-net.
|
|
| 262 |
you have to use usb-net. |
|
| 248 | 263 |
|
| 249 | 264 |
The old name=ID parameter becomes the usual id=ID with -device. |
| 250 | 265 |
|
| 251 | 266 |
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI |
| 252 | 267 |
device address, as usual. The old -net nic provides parameter addr |
| 253 |
for that, it is silently ignored when the NIC is not a PCI device.
|
|
| 268 |
for that, which is silently ignored when the NIC is not a PCI device.
|
|
| 254 | 269 |
|
| 255 | 270 |
For virtio-net-pci, you can control whether or not ioeventfd is used for |
| 256 | 271 |
virtqueue notify by setting ioeventfd= to on or off (default). |
| ... | ... | |
| 264 | 279 |
|
| 265 | 280 |
Some PCI devices aren't available with -net nic, e.g. i82558a. |
| 266 | 281 |
|
| 267 |
Bug: usb-net does not work, yet. Patch posted. |
|
| 282 |
To connect to a VLAN instead of an ordinary host part, replace |
|
| 283 |
netdev=NET-ID by vlan=VLAN. |
|
| 268 | 284 |
|
| 269 | 285 |
=== Graphics Devices === |
| 270 | 286 |
|
| 271 | 287 |
Host and guest part of graphics devices have always been separate. |
| 272 | 288 |
|
| 273 |
The old way to define the guest graphics device is -vga VGA. |
|
| 289 |
The old way to define the guest graphics device is -vga VGA. Not all |
|
| 290 |
machines support all -vga options. |
|
| 274 | 291 |
|
| 275 |
The new way is -device. Map from -vga argument to -device: |
|
| 292 |
The new way is -device. The mapping from -vga argument to -device |
|
| 293 |
depends on the machine type. For machine "pc", it's: |
|
| 276 | 294 |
|
| 277 | 295 |
std -device VGA |
| 278 | 296 |
cirrus -device cirrus-vga |
| 279 | 297 |
vmware -device vmware-svga |
| 280 |
xenfb not yet available with -device |
|
| 298 |
qxl -device qxl-vga |
|
| 299 |
none -nodefaults |
|
| 300 |
disables more than just VGA, see "Default Devices" |
|
| 281 | 301 |
|
| 282 | 302 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control |
| 283 | 303 |
the PCI device address. |
| ... | ... | |
| 285 | 305 |
-device VGA supports properties bios-offset and bios-size, but they |
| 286 | 306 |
aren't used with machine type "pc". |
| 287 | 307 |
|
| 288 |
Bug: -device cirrus-vga and -device vmware-svga require -nodefaults.
|
|
| 308 |
For machine "isapc", it's
|
|
| 289 | 309 |
|
| 290 |
Bug: the new way requires PCI; ISA VGA is not yet available with |
|
| 291 |
-device. |
|
| 310 |
std -device isa-vga |
|
| 311 |
cirrus not yet available with -device |
|
| 312 |
none -nodefaults |
|
| 313 |
disables more than just VGA, see "Default Devices" |
|
| 292 | 314 |
|
| 293 |
Bug: the new way doesn't work for machine type "pc", because it |
|
| 294 |
violates obscure device initialization ordering constraints. |
|
| 315 |
Bug: the new way doesn't work for machine types "pc" and "isapc", |
|
| 316 |
because it violates obscure device initialization ordering |
|
| 317 |
constraints. |
|
| 295 | 318 |
|
| 296 | 319 |
=== Audio Devices === |
| 297 | 320 |
|
| ... | ... | |
| 308 | 331 |
cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA |
| 309 | 332 |
es1370 -device ES1370 |
| 310 | 333 |
gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F |
| 334 |
hda -device intel-hda,msi=MSI -device hda-duplex |
|
| 311 | 335 |
sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V |
| 312 | 336 |
adlib not yet available with -device |
| 313 | 337 |
pcspk not yet available with -device |
| ... | ... | |
| 321 | 345 |
|
| 322 | 346 |
The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: |
| 323 | 347 |
|
| 348 |
* ccid -device usb-ccid |
|
| 349 |
* keyboard -device usb-kbd |
|
| 324 | 350 |
* mouse -device usb-mouse |
| 325 | 351 |
* tablet -device usb-tablet |
| 326 |
* keyboard -device usb-kdb |
|
| 327 | 352 |
* wacom-tablet -device usb-wacom-tablet |
| 328 | 353 |
* host:... See "Host Device Assignment" |
| 329 | 354 |
* disk:... See "Block Devices" |
| ... | ... | |
| 353 | 378 |
|
| 354 | 379 |
-device pci-assign,host=ADDR,iommu=IOMMU,id=ID |
| 355 | 380 |
|
| 356 |
The old dma=none becomes iommu=0 with -device.
|
|
| 381 |
The old dma=none becomes iommu=off with -device.
|
|
| 357 | 382 |
|
| 358 | 383 |
The old way to assign a host USB device is |
| 359 | 384 |
|
| ... | ... | |
| 365 | 390 |
|
| 366 | 391 |
-device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID |
| 367 | 392 |
|
| 368 |
where left out or zero BUS, ADDR, VID, PRID serve as wildcard. |
|
| 393 |
Omitted options match anything, just like the old way's wildcard. |
|
| 394 |
|
|
| 395 |
=== Default Devices === |
|
| 396 |
|
|
| 397 |
QEMU creates a number of devices by default, depending on the machine |
|
| 398 |
type. |
|
| 399 |
|
|
| 400 |
-device DEVNAME... and global DEVNAME... suppress default devices for |
|
| 401 |
some 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 |
|
|
| 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. |
|
| 414 |
|
|
| 415 |
-nodefaults suppresses all the default devices mentioned above, plus a |
|
| 416 |
few other things such as default SD-Card drive and default monitor. |
|
Also available in: Unified diff