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 devices, and each device is a guest part, 35and 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::chardev becomes -device usb-serial,chardev=dev. 186 187* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always 188 uses "braille". With -device, this useful default is gone, so you 189 have to use something like 190 191 -device usb-braille,chardev=braille -chardev braille,id=braille 192 193* -virtioconsole becomes 194 -device virtio-serial-pci,class=C,vectors=V,ioeventfd=IOEVENTFD,max_ports=N 195 -device virtconsole,is_console=NUM,nr=NR,name=NAME 196 197LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: 198 199* null becomes -chardev null 200 201* pty, msmouse, wctablet, braille, stdio likewise 202 203* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT 204 205* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS> 206 207* con: becomes -chardev console 208 209* COM<NUM> becomes -chardev serial,path=COM<NUM> 210 211* file:FNAME becomes -chardev file,path=FNAME 212 213* pipe:FNAME becomes -chardev pipe,path=FNAME 214 215* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS... 216 217* telnet:HOST:PORT,OPTS... becomes 218 -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on 219 220* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes 221 -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT 222 223* unix:FNAME becomes -chardev socket,path=FNAME 224 225* /dev/parportN becomes -chardev parport,file=/dev/parportN 226 227* /dev/ppiN likewise 228 229* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME 230 231* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the 232 character device defined by LEGACY-CHARDEV. -chardev provides more 233 general multiplexing instead: you can connect up to four users to a 234 single host part. You need to pass mux=on to -chardev to enable 235 switching the input focus. 236 237QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but 238also in various other places such as -monitor or -net 239user,guestfwd=... You can use chardev:CHR-ID in place of 240LEGACY-CHARDEV to refer to a host part defined with -chardev. 241 242=== Network Devices === 243 244Host and guest part of network devices have always been separate. 245 246The old way to define the guest part looks like this: 247 248 -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V 249 250Except for USB it looks like this: 251 252 -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID 253 254The new way is -device: 255 256 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... 257 258DEVNAME equals MODEL, except for virtio you have to name the virtio 259device appropriate for the bus (virtio-net-pci for PCI), and for USB 260you have to use usb-net. 261 262The old name=ID parameter becomes the usual id=ID with -device. 263 264For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 265device address, as usual. The old -net nic provides parameter addr 266for that, which is silently ignored when the NIC is not a PCI device. 267 268For virtio-net-pci, you can control whether or not ioeventfd is used for 269virtqueue notify by setting ioeventfd= to on or off (default). 270 271-net nic accepts vectors=V for all models, but it's silently ignored 272except for virtio-net-pci (model=virtio). With -device, only devices 273that support it accept it. 274 275Not all devices are available with -device at this time. All PCI 276devices and ne2k_isa are. 277 278Some PCI devices aren't available with -net nic, e.g. i82558a. 279 280To connect to a VLAN instead of an ordinary host part, replace 281netdev=NET-ID by vlan=VLAN. 282 283=== Graphics Devices === 284 285Host and guest part of graphics devices have always been separate. 286 287The old way to define the guest graphics device is -vga VGA. Not all 288machines support all -vga options. 289 290The new way is -device. The mapping from -vga argument to -device 291depends on the machine type. For machine "pc", it's: 292 293 std -device VGA 294 cirrus -device cirrus-vga 295 vmware -device vmware-svga 296 qxl -device qxl-vga 297 none -nodefaults 298 disables more than just VGA, see "Default Devices" 299 300As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control 301the PCI device address. 302 303-device VGA supports properties bios-offset and bios-size, but they 304aren't used with machine type "pc". 305 306For machine "isapc", it's 307 308 std -device isa-vga 309 cirrus not yet available with -device 310 none -nodefaults 311 disables more than just VGA, see "Default Devices" 312 313Bug: the new way doesn't work for machine types "pc" and "isapc", 314because it violates obscure device initialization ordering 315constraints. 316 317=== Audio Devices === 318 319Host and guest part of audio devices have always been separate. 320 321The old way to define guest audio devices is -soundhw C1,... 322 323The new way is to define each guest audio device separately with 324-device. 325 326Map from -soundhw sound card name to -device: 327 328 ac97 -device AC97 329 cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA 330 es1370 -device ES1370 331 gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F 332 hda -device intel-hda,msi=MSI -device hda-duplex 333 sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V 334 adlib not yet available with -device 335 pcspk not yet available with -device 336 337For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 338device address, as usual. 339 340=== USB Devices === 341 342The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... 343 344The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: 345 346* ccid -device usb-ccid 347* keyboard -device usb-kbd 348* mouse -device usb-mouse 349* tablet -device usb-tablet 350* wacom-tablet -device usb-wacom-tablet 351* host:... See "Host Device Assignment" 352* disk:... See "Block Devices" 353* serial:... See "Character Devices" 354* braille See "Character Devices" 355* net:... See "Network Devices" 356* bt:... not yet available with -device 357 358=== Watchdog Devices === 359 360Host and guest part of watchdog devices have always been separate. 361 362The old way to define a guest watchdog device is -watchdog DEVNAME. 363The new way is -device DEVNAME. For PCI devices, you can add 364bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. 365 366=== Host Device Assignment === 367 368QEMU supports assigning host PCI devices (qemu-kvm only at this time) 369and host USB devices. 370 371The old way to assign a host PCI device is 372 373 -pcidevice host=ADDR,dma=none,id=ID 374 375The new way is 376 377 -device pci-assign,host=ADDR,iommu=IOMMU,id=ID 378 379The old dma=none becomes iommu=off with -device. 380 381The old way to assign a host USB device is 382 383 -usbdevice host:auto:BUS.ADDR:VID:PRID 384 385where any of BUS, ADDR, VID, PRID can be the wildcard *. 386 387The new way is 388 389 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID 390 391Omitted options match anything, just like the old way's wildcard. 392 393=== Default Devices === 394 395QEMU creates a number of devices by default, depending on the machine 396type. 397 398-device DEVNAME... and global DEVNAME... suppress default devices for 399some DEVNAMEs: 400 401 default device suppressing DEVNAMEs 402 CD-ROM ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd 403 isa-fdc's driveA floppy, isa-fdc 404 parallel isa-parallel 405 serial isa-serial 406 VGA VGA, cirrus-vga, isa-vga, isa-cirrus-vga, 407 vmware-svga, qxl-vga, virtio-vga 408 virtioconsole virtio-serial-pci, virtio-serial 409 410The default NIC is connected to a default part created along with it. 411It is *not* suppressed by configuring a NIC with -device (you may call 412that a bug). -net and -netdev suppress the default NIC. 413 414-nodefaults suppresses all the default devices mentioned above, plus a 415few other things such as default SD-Card drive and default monitor. 416