Merge remote-tracking branch 'remotes/vivier2/tags/trivial-branch-for-5.2-pull-reques...
[qemu.git] / 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.  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
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.
27
28 === Block Devices ===
29
30 A QEMU block device (drive) has a host and a guest part.
31
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.
36
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.
40
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.
44
45 The new way keeps the parts separate: you create the host part with
46 -drive, and guest device(s) with -device.
47
48 The various old ways to define drives all boil down to the common form
49
50     -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
51
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.
54
55 Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
56
57 In 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
62 The 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
79 The -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   -device floppy,unit=UNIT,drive=DRIVE-ID
108
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".
112
113 * if=virtio
114
115   -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
116
117   This lets you control PCI device class and MSI-X vectors.
118
119   IOEVENTFD controls whether or not ioeventfd is used for virtqueue
120   notify.  It can be set to on (default) or off.
121
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.
125
126 * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
127
128 For USB storage devices, you can use something like:
129
130     -device usb-storage,drive=DRIVE-ID,removable=RMB
131
132 The removable parameter gives control over the SCSI INQUIRY removable
133 (RMB) bit.  USB thumbdrives usually set removable=on, while USB hard
134 disks set removable=off.
135
136 Bug: usb-storage pretends to be a block device, but it's really a SCSI
137 controller that can serve only a single device, which it creates
138 automatically.  The automatic creation guesses what kind of guest part
139 to create from the host part, like -drive if=scsi.  Host and guest
140 part are not cleanly separated.
141
142 === Character Devices ===
143
144 A QEMU character device has a host and a guest part.
145
146 The old ways to define character devices define host and guest part
147 together.
148
149 The new way keeps the parts separate: you create the host part with
150 -chardev, and the guest device with -device.
151
152 The various old ways to define a character device are all of the
153 general form
154
155     -FOO FOO-OPTS...,LEGACY-CHARDEV
156
157 where FOO-OPTS... is specific to -FOO, and the host part
158 LEGACY-CHARDEV is the same everywhere.
159
160 In the new way, this becomes
161
162     -chardev HOST-OPTS...,id=CHR-ID
163     -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
164
165 The appropriate DEVNAME depends on the machine type.  For type "pc":
166
167 * -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
168
169   This lets you control I/O ports and IRQs.
170
171 * -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
172
173   This lets you control I/O ports and IRQs.
174
175 * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
176   uses "braille".  With -device, this useful default is gone, so you
177   have to use something like
178
179   -device usb-braille,chardev=braille -chardev braille,id=braille
180
181 LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
182
183 * null becomes -chardev null
184
185 * pty, msmouse, wctablet, braille, stdio likewise
186
187 * vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
188
189 * vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
190
191 * con: becomes -chardev console
192
193 * COM<NUM> becomes -chardev serial,path=COM<NUM>
194
195 * file:FNAME becomes -chardev file,path=FNAME
196
197 * pipe:FNAME becomes -chardev pipe,path=FNAME
198
199 * tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
200
201 * telnet:HOST:PORT,OPTS... becomes
202   -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
203
204 * udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
205   -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
206
207 * unix:FNAME becomes -chardev socket,path=FNAME
208
209 * /dev/parportN becomes -chardev parport,file=/dev/parportN
210
211 * /dev/ppiN likewise
212
213 * Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
214
215 * mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
216   character device defined by LEGACY-CHARDEV.  -chardev provides more
217   general multiplexing instead: you can connect up to four users to a
218   single host part.  You need to pass mux=on to -chardev to enable
219   switching the input focus.
220
221 QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
222 also in various other places such as -monitor or -net
223 user,guestfwd=...  You can use chardev:CHR-ID in place of
224 LEGACY-CHARDEV to refer to a host part defined with -chardev.
225
226 === Network Devices ===
227
228 Host and guest part of network devices have always been separate.
229
230 The old way to define the guest part looks like this:
231
232     -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
233
234 The new way is -device:
235
236     -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
237
238 DEVNAME equals MODEL, except for virtio you have to name the virtio
239 device appropriate for the bus (virtio-net-pci for PCI), and for USB
240 you have to use usb-net.
241
242 The old name=ID parameter becomes the usual id=ID with -device.
243
244 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
245 device address, as usual.  The old -net nic provides parameter addr
246 for that, which is silently ignored when the NIC is not a PCI device.
247
248 For virtio-net-pci, you can control whether or not ioeventfd is used for
249 virtqueue notify by setting ioeventfd= to on or off (default).
250
251 -net nic accepts vectors=V for all models, but it's silently ignored
252 except for virtio-net-pci (model=virtio).  With -device, only devices
253 that support it accept it.
254
255 Not all devices are available with -device at this time.  All PCI
256 devices and ne2k_isa are.
257
258 Some PCI devices aren't available with -net nic, e.g. i82558a.
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.  Not all
265 machines support all -vga options.
266
267 The new way is -device.  The mapping from -vga argument to -device
268 depends on the machine type.  For machine "pc", it's:
269
270     std         -device VGA
271     cirrus      -device cirrus-vga
272     vmware      -device vmware-svga
273     qxl         -device qxl-vga
274     none        -nodefaults
275                 disables more than just VGA, see "Default Devices"
276
277 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
278 the PCI device address.
279
280 -device VGA supports properties bios-offset and bios-size, but they
281 aren't used with machine type "pc".
282
283 For machine "isapc", it's
284
285     std         -device isa-vga
286     cirrus      not yet available with -device
287     none        -nodefaults
288                 disables more than just VGA, see "Default Devices"
289
290 Bug: the new way doesn't work for machine types "pc" and "isapc",
291 because it violates obscure device initialization ordering
292 constraints.
293
294 === Audio Devices ===
295
296 Host and guest part of audio devices have always been separate.
297
298 The old way to define guest audio devices is -soundhw C1,...
299
300 The new way is to define each guest audio device separately with
301 -device.
302
303 Map from -soundhw sound card name to -device:
304
305     ac97        -device AC97
306     cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
307     es1370      -device ES1370
308     gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
309     hda         -device intel-hda,msi=MSI -device hda-duplex
310     sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
311     adlib       not yet available with -device
312     pcspk       not yet available with -device
313
314 For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
315 device address, as usual.
316
317 === USB Devices ===
318
319 The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
320
321 The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
322
323 * ccid            -device usb-ccid
324 * keyboard        -device usb-kbd
325 * mouse           -device usb-mouse
326 * tablet          -device usb-tablet
327 * wacom-tablet    -device usb-wacom-tablet
328 * u2f             -device u2f-{emulated,passthru}
329 * braille         See "Character Devices"
330
331 === Watchdog Devices ===
332
333 Host and guest part of watchdog devices have always been separate.
334
335 The old way to define a guest watchdog device is -watchdog DEVNAME.
336 The new way is -device DEVNAME.  For PCI devices, you can add
337 bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
338
339 === Host Device Assignment ===
340
341 QEMU supports assigning host PCI devices (qemu-kvm only at this time)
342 and host USB devices.  PCI devices can only be assigned with -device:
343
344     -device vfio-pci,host=ADDR,id=ID
345
346 To assign a host USB device use:
347
348     -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
349
350 Omitted options match anything.
351
352 === Default Devices ===
353
354 QEMU creates a number of devices by default, depending on the machine
355 type.
356
357 -device DEVNAME... and global DEVNAME... suppress default devices for
358 some DEVNAMEs:
359
360     default device      suppressing DEVNAMEs
361     CD-ROM              ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd
362     floppy              floppy, isa-fdc
363     parallel            isa-parallel
364     serial              isa-serial
365     VGA                 VGA, cirrus-vga, isa-vga, isa-cirrus-vga,
366                         vmware-svga, qxl-vga, virtio-vga, ati-vga,
367                         vhost-user-vga
368
369 The default NIC is connected to a default part created along with it.
370 It is *not* suppressed by configuring a NIC with -device (you may call
371 that a bug).  -net and -netdev suppress the default NIC.
372
373 -nodefaults suppresses all the default devices mentioned above, plus a
374 few other things such as default SD-Card drive and default monitor.