qemu/docs/qdev-device-use.txt
<<
>>
Prefs
   1= How to convert to -device & friends =
   2
   3=== Specifying Bus and Address on Bus ===
   4
   5In qdev, each device has a parent bus.  Some devices provide one or
   6more buses for children.  You can specify a device's parent bus with
   7-device parameter bus.
   8
   9A device typically has a device address on its parent bus.  For buses
  10where this address can be configured, devices provide a bus-specific
  11property.  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
  23Example: device i440FX-pcihost is on the root bus, and provides a PCI
  24bus named pci.0.  To put a FOO device into its slot 4, use -device
  25FOO,bus=/i440FX-pcihost/pci.0,addr=4.  The abbreviated form bus=pci.0
  26also works as long as the bus name is unique.
  27
  28=== Block Devices ===
  29
  30A QEMU block device (drive) has a host and a guest part.
  31
  32In the general case, the guest device is connected to a controller
  33device.  For instance, the IDE controller provides two IDE buses, each
  34of which can have up to two devices, and each device is a guest part,
  35and is connected to a host part.
  36
  37Except we sometimes lump controller, bus(es) and drive device(s) all
  38together into a single device.  For instance, the ISA floppy
  39controller is connected to up to two host drives.
  40
  41The old ways to define block devices define host and guest part
  42together.  Sometimes, they can even define a controller device in
  43addition to the block device.
  44
  45The new way keeps the parts separate: you create the host part with
  46-drive, and guest device(s) with -device.
  47
  48The various old ways to define drives all boil down to the common form
  49
  50    -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
  51
  52TYPE, BUS and UNIT identify the controller device, which of its buses
  53to use, and the drive's address on that bus.  Details depend on TYPE.
  54
  55Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
  56
  57In 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
  62The 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
  79The -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
 133For USB devices, the old way is actually different:
 134
 135    -usbdevice disk:format=FMT:FILENAME
 136
 137Provides much less control than -drive's OPTS...  The new way fixes
 138that:
 139
 140    -device usb-storage,drive=DRIVE-ID,removable=RMB
 141
 142The removable parameter gives control over the SCSI INQUIRY removable
 143(RMB) bit.  USB thumbdrives usually set removable=on, while USB hard
 144disks set removable=off.
 145
 146Bug: usb-storage pretends to be a block device, but it's really a SCSI
 147controller that can serve only a single device, which it creates
 148automatically.  The automatic creation guesses what kind of guest part
 149to create from the host part, like -drive if=scsi.  Host and guest
 150part are not cleanly separated.
 151
 152=== Character Devices ===
 153
 154A QEMU character device has a host and a guest part.
 155
 156The old ways to define character devices define host and guest part
 157together.
 158
 159The new way keeps the parts separate: you create the host part with
 160-chardev, and the guest device with -device.
 161
 162The various old ways to define a character device are all of the
 163general form
 164
 165    -FOO FOO-OPTS...,LEGACY-CHARDEV
 166
 167where FOO-OPTS... is specific to -FOO, and the host part
 168LEGACY-CHARDEV is the same everywhere.
 169
 170In the new way, this becomes
 171
 172    -chardev HOST-OPTS...,id=CHR-ID
 173    -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
 174
 175The 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::chardev becomes -device usb-serial,chardev=dev.
 186
 187* -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
 188  uses "braille".  With -device, this useful default is gone, so you
 189  have to use something like
 190
 191  -device usb-braille,chardev=braille -chardev braille,id=braille
 192
 193* -virtioconsole becomes
 194  -device virtio-serial-pci,class=C,vectors=V,ioeventfd=IOEVENTFD,max_ports=N
 195  -device virtconsole,is_console=NUM,nr=NR,name=NAME
 196
 197LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
 198
 199* null becomes -chardev null
 200
 201* pty, msmouse, wctablet, braille, stdio likewise
 202
 203* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
 204
 205* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
 206
 207* con: becomes -chardev console
 208
 209* COM<NUM> becomes -chardev serial,path=COM<NUM>
 210
 211* file:FNAME becomes -chardev file,path=FNAME
 212
 213* pipe:FNAME becomes -chardev pipe,path=FNAME
 214
 215* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
 216
 217* telnet:HOST:PORT,OPTS... becomes
 218  -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
 219
 220* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
 221  -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
 222
 223* unix:FNAME becomes -chardev socket,path=FNAME
 224
 225* /dev/parportN becomes -chardev parport,file=/dev/parportN
 226
 227* /dev/ppiN likewise
 228
 229* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
 230
 231* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
 232  character device defined by LEGACY-CHARDEV.  -chardev provides more
 233  general multiplexing instead: you can connect up to four users to a
 234  single host part.  You need to pass mux=on to -chardev to enable
 235  switching the input focus.
 236
 237QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
 238also in various other places such as -monitor or -net
 239user,guestfwd=...  You can use chardev:CHR-ID in place of
 240LEGACY-CHARDEV to refer to a host part defined with -chardev.
 241
 242=== Network Devices ===
 243
 244Host and guest part of network devices have always been separate.
 245
 246The old way to define the guest part looks like this:
 247
 248    -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
 249
 250Except for USB it looks like this:
 251
 252    -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
 253
 254The new way is -device:
 255
 256    -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
 257
 258DEVNAME equals MODEL, except for virtio you have to name the virtio
 259device appropriate for the bus (virtio-net-pci for PCI), and for USB
 260you have to use usb-net.
 261
 262The old name=ID parameter becomes the usual id=ID with -device.
 263
 264For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 265device address, as usual.  The old -net nic provides parameter addr
 266for that, which is silently ignored when the NIC is not a PCI device.
 267
 268For virtio-net-pci, you can control whether or not ioeventfd is used for
 269virtqueue notify by setting ioeventfd= to on or off (default).
 270
 271-net nic accepts vectors=V for all models, but it's silently ignored
 272except for virtio-net-pci (model=virtio).  With -device, only devices
 273that support it accept it.
 274
 275Not all devices are available with -device at this time.  All PCI
 276devices and ne2k_isa are.
 277
 278Some PCI devices aren't available with -net nic, e.g. i82558a.
 279
 280=== Graphics Devices ===
 281
 282Host and guest part of graphics devices have always been separate.
 283
 284The old way to define the guest graphics device is -vga VGA.  Not all
 285machines support all -vga options.
 286
 287The new way is -device.  The mapping from -vga argument to -device
 288depends on the machine type.  For machine "pc", it's:
 289
 290    std         -device VGA
 291    cirrus      -device cirrus-vga
 292    vmware      -device vmware-svga
 293    qxl         -device qxl-vga
 294    none        -nodefaults
 295                disables more than just VGA, see "Default Devices"
 296
 297As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
 298the PCI device address.
 299
 300-device VGA supports properties bios-offset and bios-size, but they
 301aren't used with machine type "pc".
 302
 303For machine "isapc", it's
 304
 305    std         -device isa-vga
 306    cirrus      not yet available with -device
 307    none        -nodefaults
 308                disables more than just VGA, see "Default Devices"
 309
 310Bug: the new way doesn't work for machine types "pc" and "isapc",
 311because it violates obscure device initialization ordering
 312constraints.
 313
 314=== Audio Devices ===
 315
 316Host and guest part of audio devices have always been separate.
 317
 318The old way to define guest audio devices is -soundhw C1,...
 319
 320The new way is to define each guest audio device separately with
 321-device.
 322
 323Map from -soundhw sound card name to -device:
 324
 325    ac97        -device AC97
 326    cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
 327    es1370      -device ES1370
 328    gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
 329    hda         -device intel-hda,msi=MSI -device hda-duplex
 330    sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
 331    adlib       not yet available with -device
 332    pcspk       not yet available with -device
 333
 334For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
 335device address, as usual.
 336
 337=== USB Devices ===
 338
 339The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
 340
 341The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
 342
 343* ccid            -device usb-ccid
 344* keyboard        -device usb-kbd
 345* mouse           -device usb-mouse
 346* tablet          -device usb-tablet
 347* wacom-tablet    -device usb-wacom-tablet
 348* host:...        See "Host Device Assignment"
 349* disk:...        See "Block Devices"
 350* serial:...      See "Character Devices"
 351* braille         See "Character Devices"
 352* net:...         See "Network Devices"
 353* bt:...          not yet available with -device
 354
 355=== Watchdog Devices ===
 356
 357Host and guest part of watchdog devices have always been separate.
 358
 359The old way to define a guest watchdog device is -watchdog DEVNAME.
 360The new way is -device DEVNAME.  For PCI devices, you can add
 361bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
 362
 363=== Host Device Assignment ===
 364
 365QEMU supports assigning host PCI devices (qemu-kvm only at this time)
 366and host USB devices.  PCI devices can only be assigned with -device:
 367
 368    -device vfio-pci,host=ADDR,id=ID
 369
 370The old way to assign a host USB device is
 371
 372    -usbdevice host:auto:BUS.ADDR:VID:PRID
 373
 374where any of BUS, ADDR, VID, PRID can be the wildcard *.
 375
 376The new way is
 377
 378    -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
 379
 380Omitted options match anything, just like the old way's wildcard.
 381
 382=== Default Devices ===
 383
 384QEMU creates a number of devices by default, depending on the machine
 385type.
 386
 387-device DEVNAME... and global DEVNAME... suppress default devices for
 388some DEVNAMEs:
 389
 390    default device      suppressing DEVNAMEs
 391    CD-ROM              ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd
 392    isa-fdc's driveA    floppy, isa-fdc
 393    parallel            isa-parallel
 394    serial              isa-serial
 395    VGA                 VGA, cirrus-vga, isa-vga, isa-cirrus-vga,
 396                        vmware-svga, qxl-vga, virtio-vga
 397    virtioconsole       virtio-serial-pci, virtio-serial
 398
 399The default NIC is connected to a default part created along with it.
 400It is *not* suppressed by configuring a NIC with -device (you may call
 401that a bug).  -net and -netdev suppress the default NIC.
 402
 403-nodefaults suppresses all the default devices mentioned above, plus a
 404few other things such as default SD-Card drive and default monitor.
 405