]> git.proxmox.com Git - mirror_qemu.git/blame - docs/qdev-device-use.txt
kvm: use DIV_ROUND_UP
[mirror_qemu.git] / docs / qdev-device-use.txt
CommitLineData
96560cb3
MA
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
23bf93b2
MA
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...)
96560cb3
MA
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
96560cb3
MA
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
1c9f3b88
MA
34of which can have up to two devices, and each device is a guest part,
35and is connected to a host part.
96560cb3
MA
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
23bf93b2 50 -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
96560cb3
MA
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.
23bf93b2
MA
54
55Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
96560cb3
MA
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
23bf93b2 62The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
96560cb3 63
23bf93b2
MA
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.
96560cb3 72
23bf93b2
MA
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.
96560cb3 76
23bf93b2 77* addr is special, see if=virtio below.
96560cb3 78
23bf93b2
MA
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.
96560cb3
MA
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
23bf93b2
MA
98 This SCSI controller provides a single SCSI bus, named ID.0. Put a
99 disk on it:
96560cb3 100
23bf93b2 101 -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
a5c062ed 102
23bf93b2 103 where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
96560cb3
MA
104
105* if=floppy
106
23bf93b2
MA
107 -global isa-fdc.driveA=DRIVE-ID
108 -global isa-fdc.driveB=DRIVE-ID
96560cb3
MA
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
23bf93b2
MA
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".
96560cb3
MA
117
118* if=virtio
119
65d6dcbd 120 -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
96560cb3
MA
121
122 This lets you control PCI device class and MSI-X vectors.
123
23bf93b2
MA
124 IOEVENTFD controls whether or not ioeventfd is used for virtqueue
125 notify. It can be set to on (default) or off.
65d6dcbd 126
96560cb3 127 As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
23bf93b2
MA
128 control the PCI device address. This replaces option addr available
129 with -drive if=virtio.
96560cb3
MA
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
23bf93b2
MA
137Provides much less control than -drive's OPTS... The new way fixes
138that:
96560cb3 139
a5c062ed
SH
140 -device usb-storage,drive=DRIVE-ID,removable=RMB
141
23bf93b2
MA
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.
96560cb3
MA
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
a92ff8c1 185* -usbdevice serial::chardev becomes -device usb-serial,chardev=dev.
96560cb3
MA
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
a92ff8c1 191 -device usb-braille,chardev=braille -chardev braille,id=braille
96560cb3 192
23bf93b2
MA
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
96560cb3
MA
196
197LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
198
199* null becomes -chardev null
200
378af961 201* pty, msmouse, wctablet, braille, stdio likewise
96560cb3
MA
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
6e93a44b 209* COM<NUM> becomes -chardev serial,path=COM<NUM>
96560cb3
MA
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
23bf93b2 244Host and guest part of network devices have always been separate.
96560cb3 245
23bf93b2 246The old way to define the guest part looks like this:
96560cb3 247
23bf93b2 248 -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
96560cb3
MA
249
250Except for USB it looks like this:
251
23bf93b2 252 -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
96560cb3 253
23bf93b2 254The new way is -device:
96560cb3 255
96560cb3
MA
256 -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
257
96560cb3
MA
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
23bf93b2 260you have to use usb-net.
96560cb3
MA
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
23bf93b2 266for that, which is silently ignored when the NIC is not a PCI device.
96560cb3 267
65d6dcbd
SH
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
96560cb3
MA
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
23bf93b2
MA
280To connect to a VLAN instead of an ordinary host part, replace
281netdev=NET-ID by vlan=VLAN.
96560cb3
MA
282
283=== Graphics Devices ===
284
285Host and guest part of graphics devices have always been separate.
286
23bf93b2
MA
287The old way to define the guest graphics device is -vga VGA. Not all
288machines support all -vga options.
96560cb3 289
23bf93b2
MA
290The new way is -device. The mapping from -vga argument to -device
291depends on the machine type. For machine "pc", it's:
96560cb3
MA
292
293 std -device VGA
294 cirrus -device cirrus-vga
295 vmware -device vmware-svga
23bf93b2
MA
296 qxl -device qxl-vga
297 none -nodefaults
298 disables more than just VGA, see "Default Devices"
96560cb3
MA
299
300As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
301the PCI device address.
302
303-device VGA supports properties bios-offset and bios-size, but they
304aren't used with machine type "pc".
305
23bf93b2 306For machine "isapc", it's
96560cb3 307
23bf93b2
MA
308 std -device isa-vga
309 cirrus not yet available with -device
310 none -nodefaults
311 disables more than just VGA, see "Default Devices"
96560cb3 312
23bf93b2
MA
313Bug: the new way doesn't work for machine types "pc" and "isapc",
314because it violates obscure device initialization ordering
315constraints.
96560cb3
MA
316
317=== Audio Devices ===
318
319Host and guest part of audio devices have always been separate.
320
321The old way to define guest audio devices is -soundhw C1,...
322
323The new way is to define each guest audio device separately with
324-device.
325
326Map from -soundhw sound card name to -device:
327
328 ac97 -device AC97
329 cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
330 es1370 -device ES1370
331 gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
23bf93b2 332 hda -device intel-hda,msi=MSI -device hda-duplex
96560cb3
MA
333 sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
334 adlib not yet available with -device
335 pcspk not yet available with -device
336
337For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
338device address, as usual.
339
340=== USB Devices ===
341
342The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
343
344The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER:
345
23bf93b2
MA
346* ccid -device usb-ccid
347* keyboard -device usb-kbd
96560cb3
MA
348* mouse -device usb-mouse
349* tablet -device usb-tablet
96560cb3
MA
350* wacom-tablet -device usb-wacom-tablet
351* host:... See "Host Device Assignment"
352* disk:... See "Block Devices"
353* serial:... See "Character Devices"
354* braille See "Character Devices"
355* net:... See "Network Devices"
356* bt:... not yet available with -device
357
358=== Watchdog Devices ===
359
360Host and guest part of watchdog devices have always been separate.
361
362The old way to define a guest watchdog device is -watchdog DEVNAME.
363The new way is -device DEVNAME. For PCI devices, you can add
364bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
365
366=== Host Device Assignment ===
367
368QEMU supports assigning host PCI devices (qemu-kvm only at this time)
369and host USB devices.
370
371The old way to assign a host PCI device is
372
373 -pcidevice host=ADDR,dma=none,id=ID
374
375The new way is
376
377 -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
378
23bf93b2 379The old dma=none becomes iommu=off with -device.
96560cb3
MA
380
381The old way to assign a host USB device is
382
383 -usbdevice host:auto:BUS.ADDR:VID:PRID
384
385where any of BUS, ADDR, VID, PRID can be the wildcard *.
386
387The new way is
388
389 -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
390
23bf93b2
MA
391Omitted options match anything, just like the old way's wildcard.
392
393=== Default Devices ===
394
395QEMU creates a number of devices by default, depending on the machine
396type.
397
398-device DEVNAME... and global DEVNAME... suppress default devices for
399some DEVNAMEs:
400
401 default device suppressing DEVNAMEs
7a0bbd55
MA
402 CD-ROM ide-cd, ide-drive, ide-hd, scsi-cd, scsi-hd
403 isa-fdc's driveA floppy, isa-fdc
23bf93b2
MA
404 parallel isa-parallel
405 serial isa-serial
7a0bbd55
MA
406 VGA VGA, cirrus-vga, isa-vga, isa-cirrus-vga,
407 vmware-svga, qxl-vga, virtio-vga
408 virtioconsole virtio-serial-pci, virtio-serial
23bf93b2
MA
409
410The default NIC is connected to a default part created along with it.
411It is *not* suppressed by configuring a NIC with -device (you may call
412that a bug). -net and -netdev suppress the default NIC.
413
414-nodefaults suppresses all the default devices mentioned above, plus a
415few other things such as default SD-Card drive and default monitor.