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