target/mips: Move MUL opcode check from decode_mxu() to decode_legacy()
[qemu/ar7.git] / docs / qdev-device-use.txt
1 = How to convert to -device & friends =
3 === Specifying Bus and Address on Bus ===
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.
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:
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...)
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.
28 === Block Devices ===
30 A QEMU block device (drive) has a host and a guest part.
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 devices, and each device is a guest part,
35 and is connected to a host part.
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.
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.
45 The new way keeps the parts separate: you create the host part with
46 -drive, and guest device(s) with -device.
48 The various old ways to define drives all boil down to the common form
50     -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
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.
55 Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
57 In the new way, this becomes something like
59    -drive if=none,id=DRIVE-ID,HOST-OPTS...
60    -device DEVNAME,drive=DRIVE-ID,DEV-OPTS...
62 The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
64 * file, format, snapshot, cache, aio, readonly, rerror, werror go into
67 * cyls, head, secs and trans go into HOST-OPTS.  Future work: they
68   should go into DEV-OPTS instead.
70 * serial goes into DEV-OPTS, for devices supporting serial numbers.
71   For other devices, it goes nowhere.
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.
77 * addr is special, see if=virtio below.
79 The -device argument differs in detail for each type of drive:
81 * if=ide
83   -device DEVNAME,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT
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.
88 * if=scsi
90   The old way implicitly creates SCSI controllers as needed.  The new
91   way makes that explicit:
93   -device lsi53c895a,id=ID
95   As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
96   control the PCI device address.
98   This SCSI controller provides a single SCSI bus, named ID.0.  Put a
99   disk on it:
101   -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
103   where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
105 * if=floppy
107   -device floppy,unit=UNIT,drive=DRIVE-ID
109   Without any -device floppy,... you get an empty unit 0 and no unit
110   1.  You can use -nodefaults to suppress the default unit 0, see
111   "Default Devices".
113 * if=virtio
115   -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
117   This lets you control PCI device class and MSI-X vectors.
119   IOEVENTFD controls whether or not ioeventfd is used for virtqueue
120   notify.  It can be set to on (default) or off.
122   As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
123   control the PCI device address.  This replaces option addr available
124   with -drive if=virtio.
126 * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
128 For USB devices, the old way was actually different:
130     -usbdevice disk:format=FMT:FILENAME
132 "Was" because "disk:" is gone since v2.12.0.
134 The old way provided much less control than -drive's OPTS...  The new
135 way fixes that:
137     -device usb-storage,drive=DRIVE-ID,removable=RMB
139 The removable parameter gives control over the SCSI INQUIRY removable
140 (RMB) bit.  USB thumbdrives usually set removable=on, while USB hard
141 disks set removable=off.
143 Bug: usb-storage pretends to be a block device, but it's really a SCSI
144 controller that can serve only a single device, which it creates
145 automatically.  The automatic creation guesses what kind of guest part
146 to create from the host part, like -drive if=scsi.  Host and guest
147 part are not cleanly separated.
149 === Character Devices ===
151 A QEMU character device has a host and a guest part.
153 The old ways to define character devices define host and guest part
154 together.
156 The new way keeps the parts separate: you create the host part with
157 -chardev, and the guest device with -device.
159 The various old ways to define a character device are all of the
160 general form
164 where FOO-OPTS... is specific to -FOO, and the host part
165 LEGACY-CHARDEV is the same everywhere.
167 In the new way, this becomes
169     -chardev HOST-OPTS...,id=CHR-ID
170     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
172 The appropriate DEVNAME depends on the machine type.  For type "pc":
174 * -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
176   This lets you control I/O ports and IRQs.
178 * -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
180   This lets you control I/O ports and IRQs.
182 * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
183   uses "braille".  With -device, this useful default is gone, so you
184   have to use something like
186   -device usb-braille,chardev=braille -chardev braille,id=braille
188 * -usbdevice serial::chardev is gone since v2.12.0.  It became
189   -device usb-serial,chardev=dev.
191 LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
193 * null becomes -chardev null
195 * pty, msmouse, wctablet, braille, stdio likewise
197 * vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
199 * vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
201 * con: becomes -chardev console
203 * COM<NUM> becomes -chardev serial,path=COM<NUM>
205 * file:FNAME becomes -chardev file,path=FNAME
207 * pipe:FNAME becomes -chardev pipe,path=FNAME
209 * tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
211 * telnet:HOST:PORT,OPTS... becomes
212   -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
215   -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
217 * unix:FNAME becomes -chardev socket,path=FNAME
219 * /dev/parportN becomes -chardev parport,file=/dev/parportN
221 * /dev/ppiN likewise
223 * Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
225 * mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
226   character device defined by LEGACY-CHARDEV.  -chardev provides more
227   general multiplexing instead: you can connect up to four users to a
228   single host part.  You need to pass mux=on to -chardev to enable
229   switching the input focus.
231 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
232 also in various other places such as -monitor or -net
233 user,guestfwd=...  You can use chardev:CHR-ID in place of
234 LEGACY-CHARDEV to refer to a host part defined with -chardev.
236 === Network Devices ===
238 Host and guest part of network devices have always been separate.
240 The old way to define the guest part looks like this:
242     -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
244 Except for USB it looked like this:
246     -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
248 "Looked" because "net:" is gone since v2.12.0.
250 The new way is -device:
252     -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
254 DEVNAME equals MODEL, except for virtio you have to name the virtio
255 device appropriate for the bus (virtio-net-pci for PCI), and for USB
256 you have to use usb-net.
258 The old name=ID parameter becomes the usual id=ID with -device.
260 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
261 device address, as usual.  The old -net nic provides parameter addr
262 for that, which is silently ignored when the NIC is not a PCI device.
264 For virtio-net-pci, you can control whether or not ioeventfd is used for
265 virtqueue notify by setting ioeventfd= to on or off (default).
267 -net nic accepts vectors=V for all models, but it's silently ignored
268 except for virtio-net-pci (model=virtio).  With -device, only devices
269 that support it accept it.
271 Not all devices are available with -device at this time.  All PCI
272 devices and ne2k_isa are.
274 Some PCI devices aren't available with -net nic, e.g. i82558a.
276 === Graphics Devices ===
278 Host and guest part of graphics devices have always been separate.
280 The old way to define the guest graphics device is -vga VGA.  Not all
281 machines support all -vga options.
283 The new way is -device.  The mapping from -vga argument to -device
284 depends on the machine type.  For machine "pc", it's:
286     std         -device VGA
287     cirrus      -device cirrus-vga
288     vmware      -device vmware-svga
289     qxl         -device qxl-vga
290     none        -nodefaults
291                 disables more than just VGA, see "Default Devices"
293 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
294 the PCI device address.
296 -device VGA supports properties bios-offset and bios-size, but they
297 aren't used with machine type "pc".
299 For machine "isapc", it's
301     std         -device isa-vga
302     cirrus      not yet available with -device
303     none        -nodefaults
304                 disables more than just VGA, see "Default Devices"
306 Bug: the new way doesn't work for machine types "pc" and "isapc",
307 because it violates obscure device initialization ordering
308 constraints.
310 === Audio Devices ===
312 Host and guest part of audio devices have always been separate.
314 The old way to define guest audio devices is -soundhw C1,...
316 The new way is to define each guest audio device separately with
317 -device.
319 Map from -soundhw sound card name to -device:
321     ac97        -device AC97
322     cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
323     es1370      -device ES1370
324     gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
325     hda         -device intel-hda,msi=MSI -device hda-duplex
326     sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
327     adlib       not yet available with -device
328     pcspk       not yet available with -device
330 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
331 device address, as usual.
333 === USB Devices ===
335 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
337 The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
339 * ccid            -device usb-ccid
340 * keyboard        -device usb-kbd
341 * mouse           -device usb-mouse
342 * tablet          -device usb-tablet
343 * wacom-tablet    -device usb-wacom-tablet
344 * u2f             -device u2f-{emulated,passthru}
345 * braille         See "Character Devices"
347 Until v2.12.0, we additionally had
349 * host:...        See "Host Device Assignment"
350 * disk:...        See "Block Devices"
351 * serial:...      See "Character Devices"
352 * net:...         See "Network Devices"
354 === Watchdog Devices ===
356 Host and guest part of watchdog devices have always been separate.
358 The old way to define a guest watchdog device is -watchdog DEVNAME.
359 The new way is -device DEVNAME.  For PCI devices, you can add
360 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
362 === Host Device Assignment ===
364 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
365 and host USB devices.  PCI devices can only be assigned with -device:
367     -device vfio-pci,host=ADDR,id=ID
369 The old way to assign a USB host device
371     -usbdevice host:auto:BUS.ADDR:VID:PRID
373 was removed in v2.12.0.  Any of BUS, ADDR, VID, PRID could be the
374 wildcard *.
376 The new way is
378     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
380 Omitted options match anything.
382 === Default Devices ===
384 QEMU creates a number of devices by default, depending on the machine
385 type.
387 -device DEVNAME... and global DEVNAME... suppress default devices for
388 some DEVNAMEs:
390     default device      suppressing DEVNAMEs
391     CD-ROM              ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd
392     floppy              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, ati-vga,
397                         vhost-user-vga
399 The default NIC is connected to a default part created along with it.
400 It is *not* suppressed by configuring a NIC with -device (you may call
401 that a bug).  -net and -netdev suppress the default NIC.
403 -nodefaults suppresses all the default devices mentioned above, plus a
404 few other things such as default SD-Card drive and default monitor.