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. These are 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 18Example: device i440FX-pcihost is on the root bus, and provides a PCI 19bus named pci.0. To put a FOO device into its slot 4, use -device 20FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0 21also works as long as the bus name is unique. 22 23Note: the USB device address can't be controlled at this time. 24 25=== Block Devices === 26 27A QEMU block device (drive) has a host and a guest part. 28 29In the general case, the guest device is connected to a controller 30device. For instance, the IDE controller provides two IDE buses, each 31of which can have up to two ide-drive devices, and each ide-drive 32device is a guest part, and is connected to a host part. 33 34Except we sometimes lump controller, bus(es) and drive device(s) all 35together into a single device. For instance, the ISA floppy 36controller is connected to up to two host drives. 37 38The old ways to define block devices define host and guest part 39together. Sometimes, they can even define a controller device in 40addition to the block device. 41 42The new way keeps the parts separate: you create the host part with 43-drive, and guest device(s) with -device. 44 45The various old ways to define drives all boil down to the common form 46 47 -drive if=TYPE,index=IDX,bus=BUS,unit=UNIT,HOST-OPTS... 48 49TYPE, BUS and UNIT identify the controller device, which of its buses 50to use, and the drive's address on that bus. Details depend on TYPE. 51IDX is an alternative way to specify BUS and UNIT. 52 53In the new way, this becomes something like 54 55 -drive if=none,id=DRIVE-ID,HOST-OPTS... 56 -device DEVNAME,drive=DRIVE-ID,DEV-OPTS... 57 58The -device argument differs in detail for each kind of drive: 59 60* if=ide 61 62 -device ide-drive,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT 63 64 where IDE-BUS identifies an IDE bus, normally either ide.0 or ide.1, 65 and UNIT is either 0 or 1. 66 67 Bug: new way does not work for ide.1 unit 0 (in old terms: index=2) 68 unless you disable the default CD-ROM with -nodefaults. 69 70* if=scsi 71 72 The old way implicitly creates SCSI controllers as needed. The new 73 way makes that explicit: 74 75 -device lsi53c895a,id=ID 76 77 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to 78 control the PCI device address. 79 80 This SCSI controller a single SCSI bus, named ID.0. Put a disk on 81 it: 82 83 -device scsi-disk,drive=DRIVE-ID,bus=ID.0,scsi-id=SCSI-ID 84 85* if=floppy 86 87 -global isa-fdc,driveA=DRIVE-ID,driveB=DRIVE-ID 88 89 This is -global instead of -device, because the floppy controller is 90 created automatically, and we want to configure that one, not create 91 a second one (which isn't possible anyway). 92 93 Omitting a drive parameter makes that drive empty. 94 95 Bug: driveA works only if you disable the default floppy drive with 96 -nodefaults. 97 98* if=virtio 99 100 -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD 101 102 This lets you control PCI device class and MSI-X vectors. 103 104 IOEVENTFD controls whether or not ioeventfd is used for virtqueue notify. It 105 can be set to on (default) or off. 106 107 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to 108 control the PCI device address. 109 110* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device 111 112For USB devices, the old way is actually different: 113 114 -usbdevice disk:format=FMT:FILENAME 115 116Provides much less control than -drive's HOST-OPTS... The new way 117fixes that: 118 119 -device usb-storage,drive=DRIVE-ID 120 121=== Character Devices === 122 123A QEMU character device has a host and a guest part. 124 125The old ways to define character devices define host and guest part 126together. 127 128The new way keeps the parts separate: you create the host part with 129-chardev, and the guest device with -device. 130 131The various old ways to define a character device are all of the 132general form 133 134 -FOO FOO-OPTS...,LEGACY-CHARDEV 135 136where FOO-OPTS... is specific to -FOO, and the host part 137LEGACY-CHARDEV is the same everywhere. 138 139In the new way, this becomes 140 141 -chardev HOST-OPTS...,id=CHR-ID 142 -device DEVNAME,chardev=CHR-ID,DEV-OPTS... 143 144The appropriate DEVNAME depends on the machine type. For type "pc": 145 146* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX 147 148 This lets you control I/O ports and IRQs. 149 150* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX 151 152 This lets you control I/O ports and IRQs. 153 154* -usbdevice serial:vendorid=VID,productid=PRID becomes 155 -device usb-serial,vendorid=VID,productid=PRID 156 157* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always 158 uses "braille". With -device, this useful default is gone, so you 159 have to use something like 160 161 -device usb-braille,chardev=braille,vendorid=VID,productid=PRID 162 -chardev braille,id=braille 163 164* -virtioconsole is still being worked on 165 166LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: 167 168* null becomes -chardev null 169 170* pty, msmouse, braille, stdio likewise 171 172* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT 173 174* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS> 175 176* con: becomes -chardev console 177 178* COM<NUM> becomes -chardev serial,path=<NUM> 179 180* file:FNAME becomes -chardev file,path=FNAME 181 182* pipe:FNAME becomes -chardev pipe,path=FNAME 183 184* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS... 185 186* telnet:HOST:PORT,OPTS... becomes 187 -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on 188 189* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes 190 -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT 191 192* unix:FNAME becomes -chardev socket,path=FNAME 193 194* /dev/parportN becomes -chardev parport,file=/dev/parportN 195 196* /dev/ppiN likewise 197 198* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME 199 200* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the 201 character device defined by LEGACY-CHARDEV. -chardev provides more 202 general multiplexing instead: you can connect up to four users to a 203 single host part. You need to pass mux=on to -chardev to enable 204 switching the input focus. 205 206QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but 207also in various other places such as -monitor or -net 208user,guestfwd=... You can use chardev:CHR-ID in place of 209LEGACY-CHARDEV to refer to a host part defined with -chardev. 210 211=== Network Devices === 212 213A QEMU network device (NIC) has a host and a guest part. 214 215The old ways to define NICs define host and guest part together. It 216looks like this: 217 218 -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V 219 220Except for USB it looks like this: 221 222 -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V 223 224The new way keeps the parts separate: you create the host part with 225-netdev, and the guest device with -device, like this: 226 227 -netdev type=TYPE,id=NET-ID 228 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... 229 230Unlike the old way, this creates just a network device, not a VLAN. 231If you really want a VLAN, create it the usual way, then create the 232guest device like this: 233 234 -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS... 235 236DEVNAME equals MODEL, except for virtio you have to name the virtio 237device appropriate for the bus (virtio-net-pci for PCI), and for USB 238NIC you have to use usb-net. 239 240The old name=ID parameter becomes the usual id=ID with -device. 241 242For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 243device address, as usual. The old -net nic provides parameter addr 244for that, it is silently ignored when the NIC is not a PCI device. 245 246For virtio-net-pci, you can control whether or not ioeventfd is used for 247virtqueue notify by setting ioeventfd= to on or off (default). 248 249-net nic accepts vectors=V for all models, but it's silently ignored 250except for virtio-net-pci (model=virtio). With -device, only devices 251that support it accept it. 252 253Not all devices are available with -device at this time. All PCI 254devices and ne2k_isa are. 255 256Some PCI devices aren't available with -net nic, e.g. i82558a. 257 258Bug: usb-net does not work, yet. Patch posted. 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. 265 266The new way is -device. Map from -vga argument to -device: 267 268 std -device VGA 269 cirrus -device cirrus-vga 270 vmware -device vmware-svga 271 xenfb not yet available with -device 272 273As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control 274the PCI device address. 275 276-device VGA supports properties bios-offset and bios-size, but they 277aren't used with machine type "pc". 278 279Bug: -device cirrus-vga and -device vmware-svga require -nodefaults. 280 281Bug: the new way requires PCI; ISA VGA is not yet available with 282-device. 283 284Bug: the new way doesn't work for machine type "pc", because it 285violates obscure device initialization ordering constraints. 286 287=== Audio Devices === 288 289Host and guest part of audio devices have always been separate. 290 291The old way to define guest audio devices is -soundhw C1,... 292 293The new way is to define each guest audio device separately with 294-device. 295 296Map from -soundhw sound card name to -device: 297 298 ac97 -device AC97 299 cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA 300 es1370 -device ES1370 301 gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F 302 sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V 303 adlib not yet available with -device 304 pcspk not yet available with -device 305 306For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 307device address, as usual. 308 309=== USB Devices === 310 311The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... 312 313The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: 314 315* mouse -device usb-mouse 316* tablet -device usb-tablet 317* keyboard -device usb-kdb 318* wacom-tablet -device usb-wacom-tablet 319* host:... See "Host Device Assignment" 320* disk:... See "Block Devices" 321* serial:... See "Character Devices" 322* braille See "Character Devices" 323* net:... See "Network Devices" 324* bt:... not yet available with -device 325 326=== Watchdog Devices === 327 328Host and guest part of watchdog devices have always been separate. 329 330The old way to define a guest watchdog device is -watchdog DEVNAME. 331The new way is -device DEVNAME. For PCI devices, you can add 332bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. 333 334=== Host Device Assignment === 335 336QEMU supports assigning host PCI devices (qemu-kvm only at this time) 337and host USB devices. 338 339The old way to assign a host PCI device is 340 341 -pcidevice host=ADDR,dma=none,id=ID 342 343The new way is 344 345 -device pci-assign,host=ADDR,iommu=IOMMU,id=ID 346 347The old dma=none becomes iommu=0 with -device. 348 349The old way to assign a host USB device is 350 351 -usbdevice host:auto:BUS.ADDR:VID:PRID 352 353where any of BUS, ADDR, VID, PRID can be the wildcard *. 354 355The new way is 356 357 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID 358 359where left out or zero BUS, ADDR, VID, PRID serve as wildcard. 360