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,removable=RMB
  84
  85   The (optional) removable parameter lets you override the SCSI INQUIRY
  86   removable (RMB) bit for non CD-ROM devices.  It is ignored for CD-ROM devices
  87   which are always removable.  RMB is "on" or "off".
  88
  89 * if=floppy
  90
  91   -global isa-fdc,driveA=DRIVE-ID,driveB=DRIVE-ID
  92
  93   This is -global instead of -device, because the floppy controller is
  94   created automatically, and we want to configure that one, not create
  95   a second one (which isn't possible anyway).
  96
  97   Omitting a drive parameter makes that drive empty.
  98
  99   Bug: driveA works only if you disable the default floppy drive with
 100   -nodefaults.
 101
 102 * if=virtio
 103
 104   -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
 105
 106   This lets you control PCI device class and MSI-X vectors.
 107
 108   IOEVENTFD controls whether or not ioeventfd is used for virtqueue notify.  It
 109   can be set to on (default) or off.
 110
 111   As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
 112   control the PCI device address.
 113
 114 * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
 115
 116 For USB devices, the old way is actually different:
 117
 118     -usbdevice disk:format=FMT:FILENAME
 119
 120 Provides much less control than -drive's HOST-OPTS...  The new way
 121 fixes that:
 122
 123     -device usb-storage,drive=DRIVE-ID,removable=RMB
 124
 125 The removable parameter gives control over the SCSI INQUIRY removable (RMB)
 126 bit.  USB thumbdrives usually set removable=on, while USB hard disks set
 127 removable=off.  See the if=scsi description above for details on the removable
 128 parameter, which applies only to scsi-disk devices and not to scsi-generic.
 129
 130 === Character Devices ===
 131
 132 A QEMU character device has a host and a guest part.
 133
 134 The old ways to define character devices define host and guest part
 135 together.
 136
 137 The new way keeps the parts separate: you create the host part with
 138 -chardev, and the guest device with -device.
 139
 140 The various old ways to define a character device are all of the
 141 general form
 142
 143     -FOO FOO-OPTS...,LEGACY-CHARDEV
 144
 145 where FOO-OPTS... is specific to -FOO, and the host part
 146 LEGACY-CHARDEV is the same everywhere.
 147
 148 In the new way, this becomes
 149
 150     -chardev HOST-OPTS...,id=CHR-ID
 151     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
 152
 153 The appropriate DEVNAME depends on the machine type.  For type "pc":
 154
 155 * -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
 156
 157   This lets you control I/O ports and IRQs.
 158
 159 * -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
 160
 161   This lets you control I/O ports and IRQs.
 162
 163 * -usbdevice serial:vendorid=VID,productid=PRID becomes
 164   -device usb-serial,vendorid=VID,productid=PRID
 165
 166 * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
 167   uses "braille".  With -device, this useful default is gone, so you
 168   have to use something like
 169
 170   -device usb-braille,chardev=braille,vendorid=VID,productid=PRID
 171   -chardev braille,id=braille
 172
 173 * -virtioconsole is still being worked on
 174
 175 LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
 176
 177 * null becomes -chardev null
 178
 179 * pty, msmouse, braille, stdio likewise
 180
 181 * vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
 182
 183 * vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
 184
 185 * con: becomes -chardev console
 186
 187 * COM<NUM> becomes -chardev serial,path=<NUM>
 188
 189 * file:FNAME becomes -chardev file,path=FNAME
 190
 191 * pipe:FNAME becomes -chardev pipe,path=FNAME
 192
 193 * tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
 194
 195 * telnet:HOST:PORT,OPTS... becomes
 196   -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
 197
 198 * udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
 199   -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
 200
 201 * unix:FNAME becomes -chardev socket,path=FNAME
 202
 203 * /dev/parportN becomes -chardev parport,file=/dev/parportN
 204
 205 * /dev/ppiN likewise
 206
 207 * Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
 208
 209 * mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
 210   character device defined by LEGACY-CHARDEV.  -chardev provides more
 211   general multiplexing instead: you can connect up to four users to a
 212   single host part.  You need to pass mux=on to -chardev to enable
 213   switching the input focus.
 214
 215 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
 216 also in various other places such as -monitor or -net
 217 user,guestfwd=...  You can use chardev:CHR-ID in place of
 218 LEGACY-CHARDEV to refer to a host part defined with -chardev.
 219
 220 === Network Devices ===
 221
 222 A QEMU network device (NIC) has a host and a guest part.
 223
 224 The old ways to define NICs define host and guest part together.  It
 225 looks like this:
 226
 227     -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
 228
 229 Except for USB it looks like this:
 230
 231     -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V
 232
 233 The new way keeps the parts separate: you create the host part with
 234 -netdev, and the guest device with -device, like this:
 235
 236     -netdev type=TYPE,id=NET-ID
 237     -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
 238
 239 Unlike the old way, this creates just a network device, not a VLAN.
 240 If you really want a VLAN, create it the usual way, then create the
 241 guest device like this:
 242
 243     -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS...
 244
 245 DEVNAME equals MODEL, except for virtio you have to name the virtio
 246 device appropriate for the bus (virtio-net-pci for PCI), and for USB
 247 NIC you have to use usb-net.
 248
 249 The old name=ID parameter becomes the usual id=ID with -device.
 250
 251 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 252 device address, as usual.  The old -net nic provides parameter addr
 253 for that, it is silently ignored when the NIC is not a PCI device.
 254
 255 For virtio-net-pci, you can control whether or not ioeventfd is used for
 256 virtqueue notify by setting ioeventfd= to on or off (default).
 257
 258 -net nic accepts vectors=V for all models, but it's silently ignored
 259 except for virtio-net-pci (model=virtio).  With -device, only devices
 260 that support it accept it.
 261
 262 Not all devices are available with -device at this time.  All PCI
 263 devices and ne2k_isa are.
 264
 265 Some PCI devices aren't available with -net nic, e.g. i82558a.
 266
 267 Bug: usb-net does not work, yet.  Patch posted.
 268
 269 === Graphics Devices ===
 270
 271 Host and guest part of graphics devices have always been separate.
 272
 273 The old way to define the guest graphics device is -vga VGA.
 274
 275 The new way is -device.  Map from -vga argument to -device:
 276
 277     std         -device VGA
 278     cirrus      -device cirrus-vga
 279     vmware      -device vmware-svga
 280     xenfb       not yet available with -device
 281
 282 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
 283 the PCI device address.
 284
 285 -device VGA supports properties bios-offset and bios-size, but they
 286 aren't used with machine type "pc".
 287
 288 Bug: -device cirrus-vga and -device vmware-svga require -nodefaults.
 289
 290 Bug: the new way requires PCI; ISA VGA is not yet available with
 291 -device.
 292
 293 Bug: the new way doesn't work for machine type "pc", because it
 294 violates obscure device initialization ordering constraints.
 295
 296 === Audio Devices ===
 297
 298 Host and guest part of audio devices have always been separate.
 299
 300 The old way to define guest audio devices is -soundhw C1,...
 301
 302 The new way is to define each guest audio device separately with
 303 -device.
 304
 305 Map from -soundhw sound card name to -device:
 306
 307     ac97        -device AC97
 308     cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
 309     es1370      -device ES1370
 310     gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
 311     sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
 312     adlib       not yet available with -device
 313     pcspk       not yet available with -device
 314
 315 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 316 device address, as usual.
 317
 318 === USB Devices ===
 319
 320 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
 321
 322 The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
 323
 324 * mouse           -device usb-mouse
 325 * tablet          -device usb-tablet
 326 * keyboard        -device usb-kdb
 327 * wacom-tablet    -device usb-wacom-tablet
 328 * host:...        See "Host Device Assignment"
 329 * disk:...        See "Block Devices"
 330 * serial:...      See "Character Devices"
 331 * braille         See "Character Devices"
 332 * net:...         See "Network Devices"
 333 * bt:...          not yet available with -device
 334
 335 === Watchdog Devices ===
 336
 337 Host and guest part of watchdog devices have always been separate.
 338
 339 The old way to define a guest watchdog device is -watchdog DEVNAME.
 340 The new way is -device DEVNAME.  For PCI devices, you can add
 341 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
 342
 343 === Host Device Assignment ===
 344
 345 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
 346 and host USB devices.
 347
 348 The old way to assign a host PCI device is
 349
 350     -pcidevice host=ADDR,dma=none,id=ID
 351
 352 The new way is
 353
 354     -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
 355
 356 The old dma=none becomes iommu=0 with -device.
 357
 358 The old way to assign a host USB device is
 359
 360     -usbdevice host:auto:BUS.ADDR:VID:PRID
 361
 362 where any of BUS, ADDR, VID, PRID can be the wildcard *.
 363
 364 The new way is
 365
 366     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
 367
 368 where left out or zero BUS, ADDR, VID, PRID serve as wildcard.