qdev-device-use.txt (13383B)
1 = How to convert to -device & friends = 2 3 === Specifying Bus and Address on Bus === 4 5 In qdev, each device has a parent bus. Some devices provide one or 6 more buses for children. You can specify a device's parent bus with 7 -device parameter bus. 8 9 A device typically has a device address on its parent bus. For buses 10 where this address can be configured, devices provide a bus-specific 11 property. 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 23 Example: device i440FX-pcihost is on the root bus, and provides a PCI 24 bus named pci.0. To put a FOO device into its slot 4, use -device 25 FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0 26 also works as long as the bus name is unique. 27 28 === Block Devices === 29 30 A QEMU block device (drive) has a host and a guest part. 31 32 In the general case, the guest device is connected to a controller 33 device. For instance, the IDE controller provides two IDE buses, each 34 of which can have up to two devices, and each device is a guest part, 35 and is connected to a host part. 36 37 Except we sometimes lump controller, bus(es) and drive device(s) all 38 together into a single device. For instance, the ISA floppy 39 controller is connected to up to two host drives. 40 41 The old ways to define block devices define host and guest part 42 together. Sometimes, they can even define a controller device in 43 addition to the block device. 44 45 The new way keeps the parts separate: you create the host part with 46 -drive, and guest device(s) with -device. 47 48 The various old ways to define drives all boil down to the common form 49 50 -drive if=TYPE,bus=BUS,unit=UNIT,OPTS... 51 52 TYPE, BUS and UNIT identify the controller device, which of its buses 53 to use, and the drive's address on that bus. Details depend on TYPE. 54 55 Instead of bus=BUS,unit=UNIT, you can also say index=IDX. 56 57 In 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 62 The 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 79 The -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 128 For 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 134 The old way provided much less control than -drive's OPTS... The new 135 way fixes that: 136 137 -device usb-storage,drive=DRIVE-ID,removable=RMB 138 139 The removable parameter gives control over the SCSI INQUIRY removable 140 (RMB) bit. USB thumbdrives usually set removable=on, while USB hard 141 disks set removable=off. 142 143 Bug: usb-storage pretends to be a block device, but it's really a SCSI 144 controller that can serve only a single device, which it creates 145 automatically. The automatic creation guesses what kind of guest part 146 to create from the host part, like -drive if=scsi. Host and guest 147 part are not cleanly separated. 148 149 === Character Devices === 150 151 A QEMU character device has a host and a guest part. 152 153 The old ways to define character devices define host and guest part 154 together. 155 156 The new way keeps the parts separate: you create the host part with 157 -chardev, and the guest device with -device. 158 159 The various old ways to define a character device are all of the 160 general form 161 162 -FOO FOO-OPTS...,LEGACY-CHARDEV 163 164 where FOO-OPTS... is specific to -FOO, and the host part 165 LEGACY-CHARDEV is the same everywhere. 166 167 In the new way, this becomes 168 169 -chardev HOST-OPTS...,id=CHR-ID 170 -device DEVNAME,chardev=CHR-ID,DEV-OPTS... 171 172 The 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 191 LEGACY-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 parport,file=/dev/parportN 220 221 * /dev/ppiN likewise 222 223 * Any other /dev/FNAME becomes -chardev tty,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 231 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but 232 also in various other places such as -monitor or -net 233 user,guestfwd=... You can use chardev:CHR-ID in place of 234 LEGACY-CHARDEV to refer to a host part defined with -chardev. 235 236 === Network Devices === 237 238 Host and guest part of network devices have always been separate. 239 240 The 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 244 Except 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 250 The new way is -device: 251 252 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... 253 254 DEVNAME equals MODEL, except for virtio you have to name the virtio 255 device appropriate for the bus (virtio-net-pci for PCI), and for USB 256 you have to use usb-net. 257 258 The old name=ID parameter becomes the usual id=ID with -device. 259 260 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 261 device address, as usual. The old -net nic provides parameter addr 262 for that, which is silently ignored when the NIC is not a PCI device. 263 264 For virtio-net-pci, you can control whether or not ioeventfd is used for 265 virtqueue notify by setting ioeventfd= to on or off (default). 266 267 -net nic accepts vectors=V for all models, but it's silently ignored 268 except for virtio-net-pci (model=virtio). With -device, only devices 269 that support it accept it. 270 271 Not all devices are available with -device at this time. All PCI 272 devices and ne2k_isa are. 273 274 Some PCI devices aren't available with -net nic, e.g. i82558a. 275 276 === Graphics Devices === 277 278 Host and guest part of graphics devices have always been separate. 279 280 The old way to define the guest graphics device is -vga VGA. Not all 281 machines support all -vga options. 282 283 The new way is -device. The mapping from -vga argument to -device 284 depends 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 293 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control 294 the PCI device address. 295 296 -device VGA supports properties bios-offset and bios-size, but they 297 aren't used with machine type "pc". 298 299 For 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 306 Bug: the new way doesn't work for machine types "pc" and "isapc", 307 because it violates obscure device initialization ordering 308 constraints. 309 310 === Audio Devices === 311 312 Host and guest part of audio devices have always been separate. 313 314 The old way to define guest audio devices is -soundhw C1,... 315 316 The new way is to define each guest audio device separately with 317 -device. 318 319 Map 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 330 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI 331 device address, as usual. 332 333 === USB Devices === 334 335 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... 336 337 The 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 347 Until 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 356 Host and guest part of watchdog devices have always been separate. 357 358 The old way to define a guest watchdog device is -watchdog DEVNAME. 359 The new way is -device DEVNAME. For PCI devices, you can add 360 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. 361 362 === Host Device Assignment === 363 364 QEMU supports assigning host PCI devices (qemu-kvm only at this time) 365 and host USB devices. PCI devices can only be assigned with -device: 366 367 -device vfio-pci,host=ADDR,id=ID 368 369 The old way to assign a USB host device 370 371 -usbdevice host:auto:BUS.ADDR:VID:PRID 372 373 was removed in v2.12.0. Any of BUS, ADDR, VID, PRID could be the 374 wildcard *. 375 376 The new way is 377 378 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID 379 380 Omitted options match anything. 381 382 === Default Devices === 383 384 QEMU creates a number of devices by default, depending on the machine 385 type. 386 387 -device DEVNAME... and global DEVNAME... suppress default devices for 388 some 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 399 The default NIC is connected to a default part created along with it. 400 It is *not* suppressed by configuring a NIC with -device (you may call 401 that a bug). -net and -netdev suppress the default NIC. 402 403 -nodefaults suppresses all the default devices mentioned above, plus a 404 few other things such as default SD-Card drive and default monitor.