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 -device floppy,unit=UNIT,drive=DRIVE-ID 108 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 111 "Default Devices". 112 113* if=virtio 114 115 -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD 116 117 This lets you control PCI device class and MSI-X vectors. 118 119 IOEVENTFD controls whether or not ioeventfd is used for virtqueue 120 notify. It can be set to on (default) or off. 121 122 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to 123 control the PCI device address. This replaces option addr available 124 with -drive if=virtio. 125 126* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device 127 128For USB devices, the old way was actually different: 129 130 -usbdevice disk:format=FMT:FILENAME 131 132"Was" because "disk:" is gone since v2.12.0. 133 134The old way provided much less control than -drive's OPTS... The new 135way fixes that: 136 137 -device usb-storage,drive=DRIVE-ID,removable=RMB 138 139The removable parameter gives control over the SCSI INQUIRY removable 140(RMB) bit. USB thumbdrives usually set removable=on, while USB hard 141disks set removable=off. 142 143Bug: usb-storage pretends to be a block device, but it's really a SCSI 144controller that can serve only a single device, which it creates 145automatically. The automatic creation guesses what kind of guest part 146to create from the host part, like -drive if=scsi. Host and guest 147part are not cleanly separated. 148 149=== Character Devices === 150 151A QEMU character device has a host and a guest part. 152 153The old ways to define character devices define host and guest part 154together. 155 156The new way keeps the parts separate: you create the host part with 157-chardev, and the guest device with -device. 158 159The various old ways to define a character device are all of the 160general form 161 162 -FOO FOO-OPTS...,LEGACY-CHARDEV 163 164where FOO-OPTS... is specific to -FOO, and the host part 165LEGACY-CHARDEV is the same everywhere. 166 167In the new way, this becomes 168 169 -chardev HOST-OPTS...,id=CHR-ID 170 -device DEVNAME,chardev=CHR-ID,DEV-OPTS... 171 172The appropriate DEVNAME depends on the machine type. For type "pc": 173 174* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX 175 176 This lets you control I/O ports and IRQs. 177 178* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX 179 180 This lets you control I/O ports and IRQs. 181 182* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always 183 uses "braille". With -device, this useful default is gone, so you 184 have to use something like 185 186 -device usb-braille,chardev=braille -chardev braille,id=braille 187 188* -usbdevice serial::chardev is gone since v2.12.0. It became 189 -device usb-serial,chardev=dev. 190 191LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: 192 193* null becomes -chardev null 194 195* pty, msmouse, wctablet, braille, stdio likewise 196 197* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT 198 199* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS> 200 201* con: becomes -chardev console 202 203* COM<NUM> becomes -chardev serial,path=COM<NUM> 204 205* file:FNAME becomes -chardev file,path=FNAME 206 207* pipe:FNAME becomes -chardev pipe,path=FNAME 208 209* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS... 210 211* telnet:HOST:PORT,OPTS... becomes 212 -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on 213 214* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes 215 -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT 216 217* unix:FNAME becomes -chardev socket,path=FNAME 218 219* /dev/parportN becomes -chardev parallel,file=/dev/parportN 220 221* /dev/ppiN likewise 222 223* Any other /dev/FNAME becomes -chardev serial,path=/dev/FNAME 224 225* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the 226 character device defined by LEGACY-CHARDEV. -chardev provides more 227 general multiplexing instead: you can connect up to four users to a 228 single host part. You need to pass mux=on to -chardev to enable 229 switching the input focus. 230 231QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but 232also in various other places such as -monitor or -net 233user,guestfwd=... You can use chardev:CHR-ID in place of 234LEGACY-CHARDEV to refer to a host part defined with -chardev. 235 236=== Network Devices === 237 238Host and guest part of network devices have always been separate. 239 240The old way to define the guest part looks like this: 241 242 -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V 243 244Except for USB it looked like this: 245 246 -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID 247 248"Looked" because "net:" is gone since v2.12.0. 249 250The new way is -device: 251 252 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... 253 254DEVNAME equals MODEL, except for virtio you have to name the virtio 255device appropriate for the bus (virtio-net-pci for PCI), and for USB 256you have to use usb-net. 257 258The old name=ID parameter becomes the usual id=ID with -device. 259 260For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 261device address, as usual. The old -net nic provides parameter addr 262for that, which is silently ignored when the NIC is not a PCI device. 263 264For virtio-net-pci, you can control whether or not ioeventfd is used for 265virtqueue notify by setting ioeventfd= to on or off (default). 266 267-net nic accepts vectors=V for all models, but it's silently ignored 268except for virtio-net-pci (model=virtio). With -device, only devices 269that support it accept it. 270 271Not all devices are available with -device at this time. All PCI 272devices and ne2k_isa are. 273 274Some PCI devices aren't available with -net nic, e.g. i82558a. 275 276=== Graphics Devices === 277 278Host and guest part of graphics devices have always been separate. 279 280The old way to define the guest graphics device is -vga VGA. Not all 281machines support all -vga options. 282 283The new way is -device. The mapping from -vga argument to -device 284depends on the machine type. For machine "pc", it's: 285 286 std -device VGA 287 cirrus -device cirrus-vga 288 vmware -device vmware-svga 289 qxl -device qxl-vga 290 none -nodefaults 291 disables more than just VGA, see "Default Devices" 292 293As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control 294the PCI device address. 295 296-device VGA supports properties bios-offset and bios-size, but they 297aren't used with machine type "pc". 298 299For machine "isapc", it's 300 301 std -device isa-vga 302 cirrus not yet available with -device 303 none -nodefaults 304 disables more than just VGA, see "Default Devices" 305 306Bug: the new way doesn't work for machine types "pc" and "isapc", 307because it violates obscure device initialization ordering 308constraints. 309 310=== Audio Devices === 311 312Host and guest part of audio devices have always been separate. 313 314The old way to define guest audio devices is -soundhw C1,... 315 316The new way is to define each guest audio device separately with 317-device. 318 319Map from -soundhw sound card name to -device: 320 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 329 330For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 331device address, as usual. 332 333=== USB Devices === 334 335The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... 336 337The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: 338 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} 345* braille See "Character Devices" 346 347Until v2.12.0, we additionally had 348 349* host:... See "Host Device Assignment" 350* disk:... See "Block Devices" 351* serial:... See "Character Devices" 352* net:... See "Network Devices" 353 354=== Watchdog Devices === 355 356Host and guest part of watchdog devices have always been separate. 357 358The old way to define a guest watchdog device is -watchdog DEVNAME. 359The new way is -device DEVNAME. For PCI devices, you can add 360bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. 361 362=== Host Device Assignment === 363 364QEMU supports assigning host PCI devices (qemu-kvm only at this time) 365and host USB devices. PCI devices can only be assigned with -device: 366 367 -device vfio-pci,host=ADDR,id=ID 368 369The old way to assign a USB host device 370 371 -usbdevice host:auto:BUS.ADDR:VID:PRID 372 373was removed in v2.12.0. Any of BUS, ADDR, VID, PRID could be the 374wildcard *. 375 376The new way is 377 378 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID 379 380Omitted options match anything. 381 382=== Default Devices === 383 384QEMU creates a number of devices by default, depending on the machine 385type. 386 387-device DEVNAME... and global DEVNAME... suppress default devices for 388some DEVNAMEs: 389 390 default device suppressing DEVNAMEs 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 398 399The default NIC is connected to a default part created along with it. 400It is *not* suppressed by configuring a NIC with -device (you may call 401that a bug). -net and -netdev suppress the default NIC. 402 403-nodefaults suppresses all the default devices mentioned above, plus a 404few other things such as default SD-Card drive and default monitor. 405