1= 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 11property. 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...) 22 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 28=== 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 50 -drive if=TYPE,bus=BUS,unit=UNIT,OPTS... 51 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. 54 55Instead of bus=BUS,unit=UNIT, you can also say index=IDX. 56 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 62The 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: 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. 87 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 98 This SCSI controller provides a single SCSI bus, named ID.0. Put a 99 disk on it: 100 101 -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT 102 103 where DEVNAME is either scsi-hd, scsi-cd or scsi-generic. 104 105* if=floppy 106 107 -global isa-fdc.driveA=DRIVE-ID 108 -global isa-fdc.driveB=DRIVE-ID 109 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 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". 117 118* if=virtio 119 120 -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD 121 122 This lets you control PCI device class and MSI-X vectors. 123 124 IOEVENTFD controls whether or not ioeventfd is used for virtqueue 125 notify. It can be set to on (default) or off. 126 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. 130 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 137Provides much less control than -drive's OPTS... The new way fixes 138that: 139 140 -device usb-storage,drive=DRIVE-ID,removable=RMB 141 142The 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. 151 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 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 198 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 211* COM<NUM> becomes -chardev serial,path=COM<NUM> 212 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 246Host and guest part of network devices have always been separate. 247 248The old way to define the guest part looks like this: 249 250 -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V 251 252Except for USB it looks like this: 253 254 -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID 255 256The new way is -device: 257 258 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... 259 260DEVNAME equals MODEL, except for virtio you have to name the virtio 261device appropriate for the bus (virtio-net-pci for PCI), and for USB 262you have to use usb-net. 263 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 268for that, which is silently ignored when the NIC is not a PCI device. 269 270For virtio-net-pci, you can control whether or not ioeventfd is used for 271virtqueue notify by setting ioeventfd= to on or off (default). 272 273-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 282To connect to a VLAN instead of an ordinary host part, replace 283netdev=NET-ID by vlan=VLAN. 284 285=== Graphics Devices === 286 287Host and guest part of graphics devices have always been separate. 288 289The old way to define the guest graphics device is -vga VGA. Not all 290machines support all -vga options. 291 292The new way is -device. The mapping from -vga argument to -device 293depends on the machine type. For machine "pc", it's: 294 295 std -device VGA 296 cirrus -device cirrus-vga 297 vmware -device vmware-svga 298 qxl -device qxl-vga 299 none -nodefaults 300 disables more than just VGA, see "Default Devices" 301 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 308For machine "isapc", it's 309 310 std -device isa-vga 311 cirrus not yet available with -device 312 none -nodefaults 313 disables more than just VGA, see "Default Devices" 314 315Bug: the new way doesn't work for machine types "pc" and "isapc", 316because it violates obscure device initialization ordering 317constraints. 318 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 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 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 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 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 381The old dma=none becomes iommu=off with -device. 382 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 393Omitted 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. 417