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