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