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