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.  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
  18 Example: device i440FX-pcihost is on the root bus, and provides a PCI
  19 bus named pci.0.  To put a FOO device into its slot 4, use -device
  20 FOO,bus=/i440FX-pcihost/pci.0,addr=4.  The abbreviated form bus=pci.0
  21 also works as long as the bus name is unique.
  22
  23 Note: the USB device address can't be controlled at this time.
  24
  25 === Block Devices ===
  26
  27 A QEMU block device (drive) has a host and a guest part.
  28
  29 In the general case, the guest device is connected to a controller
  30 device.  For instance, the IDE controller provides two IDE buses, each
  31 of which can have up to two ide-drive devices, and each ide-drive
  32 device is a guest part, and is connected to a host part.
  33
  34 Except we sometimes lump controller, bus(es) and drive device(s) all
  35 together into a single device.  For instance, the ISA floppy
  36 controller is connected to up to two host drives.
  37
  38 The old ways to define block devices define host and guest part
  39 together.  Sometimes, they can even define a controller device in
  40 addition to the block device.
  41
  42 The new way keeps the parts separate: you create the host part with
  43 -drive, and guest device(s) with -device.
  44
  45 The 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
  49 TYPE, BUS and UNIT identify the controller device, which of its buses
  50 to use, and the drive's address on that bus.  Details depend on TYPE.
  51 IDX is an alternative way to specify BUS and UNIT.
  52
  53 In 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
  58 The -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
 112 For USB devices, the old way is actually different:
 113
 114     -usbdevice disk:format=FMT:FILENAME
 115
 116 Provides much less control than -drive's HOST-OPTS...  The new way
 117 fixes that:
 118
 119     -device usb-storage,drive=DRIVE-ID
 120
 121 === Character Devices ===
 122
 123 A QEMU character device has a host and a guest part.
 124
 125 The old ways to define character devices define host and guest part
 126 together.
 127
 128 The new way keeps the parts separate: you create the host part with
 129 -chardev, and the guest device with -device.
 130
 131 The various old ways to define a character device are all of the
 132 general form
 133
 134     -FOO FOO-OPTS...,LEGACY-CHARDEV
 135
 136 where FOO-OPTS... is specific to -FOO, and the host part
 137 LEGACY-CHARDEV is the same everywhere.
 138
 139 In the new way, this becomes
 140
 141     -chardev HOST-OPTS...,id=CHR-ID
 142     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
 143
 144 The 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
 166 LEGACY-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
 206 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
 207 also in various other places such as -monitor or -net
 208 user,guestfwd=...  You can use chardev:CHR-ID in place of
 209 LEGACY-CHARDEV to refer to a host part defined with -chardev.
 210
 211 === Network Devices ===
 212
 213 A QEMU network device (NIC) has a host and a guest part.
 214
 215 The old ways to define NICs define host and guest part together.  It
 216 looks like this:
 217
 218     -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
 219
 220 Except for USB it looks like this:
 221
 222     -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V
 223
 224 The 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
 230 Unlike the old way, this creates just a network device, not a VLAN.
 231 If you really want a VLAN, create it the usual way, then create the
 232 guest device like this:
 233
 234     -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS...
 235
 236 DEVNAME equals MODEL, except for virtio you have to name the virtio
 237 device appropriate for the bus (virtio-net-pci for PCI), and for USB
 238 NIC you have to use usb-net.
 239
 240 The old name=ID parameter becomes the usual id=ID with -device.
 241
 242 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 243 device address, as usual.  The old -net nic provides parameter addr
 244 for that, it is silently ignored when the NIC is not a PCI device.
 245
 246 For virtio-net-pci, you can control whether or not ioeventfd is used for
 247 virtqueue notify by setting ioeventfd= to on or off (default).
 248
 249 -net nic accepts vectors=V for all models, but it's silently ignored
 250 except for virtio-net-pci (model=virtio).  With -device, only devices
 251 that support it accept it.
 252
 253 Not all devices are available with -device at this time.  All PCI
 254 devices and ne2k_isa are.
 255
 256 Some PCI devices aren't available with -net nic, e.g. i82558a.
 257
 258 Bug: usb-net does not work, yet.  Patch posted.
 259
 260 === Graphics Devices ===
 261
 262 Host and guest part of graphics devices have always been separate.
 263
 264 The old way to define the guest graphics device is -vga VGA.
 265
 266 The 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
 273 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
 274 the PCI device address.
 275
 276 -device VGA supports properties bios-offset and bios-size, but they
 277 aren't used with machine type "pc".
 278
 279 Bug: -device cirrus-vga and -device vmware-svga require -nodefaults.
 280
 281 Bug: the new way requires PCI; ISA VGA is not yet available with
 282 -device.
 283
 284 Bug: the new way doesn't work for machine type "pc", because it
 285 violates obscure device initialization ordering constraints.
 286
 287 === Audio Devices ===
 288
 289 Host and guest part of audio devices have always been separate.
 290
 291 The old way to define guest audio devices is -soundhw C1,...
 292
 293 The new way is to define each guest audio device separately with
 294 -device.
 295
 296 Map 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
 306 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 307 device address, as usual.
 308
 309 === USB Devices ===
 310
 311 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
 312
 313 The 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
 328 Host and guest part of watchdog devices have always been separate.
 329
 330 The old way to define a guest watchdog device is -watchdog DEVNAME.
 331 The new way is -device DEVNAME.  For PCI devices, you can add
 332 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
 333
 334 === Host Device Assignment ===
 335
 336 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
 337 and host USB devices.
 338
 339 The old way to assign a host PCI device is
 340
 341     -pcidevice host=ADDR,dma=none,id=ID
 342
 343 The new way is
 344
 345     -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
 346
 347 The old dma=none becomes iommu=0 with -device.
 348
 349 The old way to assign a host USB device is
 350
 351     -usbdevice host:auto:BUS.ADDR:VID:PRID
 352
 353 where any of BUS, ADDR, VID, PRID can be the wildcard *.
 354
 355 The new way is
 356
 357     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
 358
 359 where left out or zero BUS, ADDR, VID, PRID serve as wildcard.