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 is actually different:
 129
 130     -usbdevice disk:format=FMT:FILENAME
 131
 132 Provides much less control than -drive's OPTS...  The new way fixes
 133 that:
 134
 135     -device usb-storage,drive=DRIVE-ID,removable=RMB
 136
 137 The removable parameter gives control over the SCSI INQUIRY removable
 138 (RMB) bit.  USB thumbdrives usually set removable=on, while USB hard
 139 disks set removable=off.
 140
 141 Bug: usb-storage pretends to be a block device, but it's really a SCSI
 142 controller that can serve only a single device, which it creates
 143 automatically.  The automatic creation guesses what kind of guest part
 144 to create from the host part, like -drive if=scsi.  Host and guest
 145 part are not cleanly separated.
 146
 147 === Character Devices ===
 148
 149 A QEMU character device has a host and a guest part.
 150
 151 The old ways to define character devices define host and guest part
 152 together.
 153
 154 The new way keeps the parts separate: you create the host part with
 155 -chardev, and the guest device with -device.
 156
 157 The various old ways to define a character device are all of the
 158 general form
 159
 160     -FOO FOO-OPTS...,LEGACY-CHARDEV
 161
 162 where FOO-OPTS... is specific to -FOO, and the host part
 163 LEGACY-CHARDEV is the same everywhere.
 164
 165 In the new way, this becomes
 166
 167     -chardev HOST-OPTS...,id=CHR-ID
 168     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
 169
 170 The 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
 188 LEGACY-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
 228 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
 229 also in various other places such as -monitor or -net
 230 user,guestfwd=...  You can use chardev:CHR-ID in place of
 231 LEGACY-CHARDEV to refer to a host part defined with -chardev.
 232
 233 === Network Devices ===
 234
 235 Host and guest part of network devices have always been separate.
 236
 237 The 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
 241 Except for USB it looks like this:
 242
 243     -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
 244
 245 The new way is -device:
 246
 247     -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
 248
 249 DEVNAME equals MODEL, except for virtio you have to name the virtio
 250 device appropriate for the bus (virtio-net-pci for PCI), and for USB
 251 you have to use usb-net.
 252
 253 The old name=ID parameter becomes the usual id=ID with -device.
 254
 255 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 256 device address, as usual.  The old -net nic provides parameter addr
 257 for that, which is silently ignored when the NIC is not a PCI device.
 258
 259 For virtio-net-pci, you can control whether or not ioeventfd is used for
 260 virtqueue notify by setting ioeventfd= to on or off (default).
 261
 262 -net nic accepts vectors=V for all models, but it's silently ignored
 263 except for virtio-net-pci (model=virtio).  With -device, only devices
 264 that support it accept it.
 265
 266 Not all devices are available with -device at this time.  All PCI
 267 devices and ne2k_isa are.
 268
 269 Some PCI devices aren't available with -net nic, e.g. i82558a.
 270
 271 === Graphics Devices ===
 272
 273 Host and guest part of graphics devices have always been separate.
 274
 275 The old way to define the guest graphics device is -vga VGA.  Not all
 276 machines support all -vga options.
 277
 278 The new way is -device.  The mapping from -vga argument to -device
 279 depends 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
 288 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
 289 the PCI device address.
 290
 291 -device VGA supports properties bios-offset and bios-size, but they
 292 aren't used with machine type "pc".
 293
 294 For 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
 301 Bug: the new way doesn't work for machine types "pc" and "isapc",
 302 because it violates obscure device initialization ordering
 303 constraints.
 304
 305 === Audio Devices ===
 306
 307 Host and guest part of audio devices have always been separate.
 308
 309 The old way to define guest audio devices is -soundhw C1,...
 310
 311 The new way is to define each guest audio device separately with
 312 -device.
 313
 314 Map 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
 325 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 326 device address, as usual.
 327
 328 === USB Devices ===
 329
 330 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
 331
 332 The 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
 348 Host and guest part of watchdog devices have always been separate.
 349
 350 The old way to define a guest watchdog device is -watchdog DEVNAME.
 351 The new way is -device DEVNAME.  For PCI devices, you can add
 352 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
 353
 354 === Host Device Assignment ===
 355
 356 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
 357 and host USB devices.  PCI devices can only be assigned with -device:
 358
 359     -device vfio-pci,host=ADDR,id=ID
 360
 361 The old way to assign a host USB device is
 362
 363     -usbdevice host:auto:BUS.ADDR:VID:PRID
 364
 365 where any of BUS, ADDR, VID, PRID can be the wildcard *.
 366
 367 The new way is
 368
 369     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
 370
 371 Omitted options match anything, just like the old way's wildcard.
 372
 373 === Default Devices ===
 374
 375 QEMU creates a number of devices by default, depending on the machine
 376 type.
 377
 378 -device DEVNAME... and global DEVNAME... suppress default devices for
 379 some 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
 390 The default NIC is connected to a default part created along with it.
 391 It is *not* suppressed by configuring a NIC with -device (you may call
 392 that a bug).  -net and -netdev suppress the default NIC.
 393
 394 -nodefaults suppresses all the default devices mentioned above, plus a
 395 few other things such as default SD-Card drive and default monitor.