docs/qdev-device-use.txt

   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 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
 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.