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