root / docs / qdev-device-use.txt @ 96560cb3
History | View | Annotate | Download (11 kB)
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. These are |
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 |
|
18 |
Example: device i440FX-pcihost is on the root bus, and provides a PCI |
19 |
bus named pci.0. To put a FOO device into its slot 4, use -device |
20 |
FOO,bus=/i440FX-pcihost/pci.0,addr=4. The abbreviated form bus=pci.0 |
21 |
also works as long as the bus name is unique. |
22 |
|
23 |
Note: the USB device address can't be controlled at this time. |
24 |
|
25 |
=== Block Devices === |
26 |
|
27 |
A QEMU block device (drive) has a host and a guest part. |
28 |
|
29 |
In the general case, the guest device is connected to a controller |
30 |
device. For instance, the IDE controller provides two IDE buses, each |
31 |
of which can have up to two ide-drive devices, and each ide-drive |
32 |
device is a guest part, and is connected to a host part. |
33 |
|
34 |
Except we sometimes lump controller, bus(es) and drive device(s) all |
35 |
together into a single device. For instance, the ISA floppy |
36 |
controller is connected to up to two host drives. |
37 |
|
38 |
The old ways to define block devices define host and guest part |
39 |
together. Sometimes, they can even define a controller device in |
40 |
addition to the block device. |
41 |
|
42 |
The new way keeps the parts separate: you create the host part with |
43 |
-drive, and guest device(s) with -device. |
44 |
|
45 |
The various old ways to define drives all boil down to the common form |
46 |
|
47 |
-drive if=TYPE,index=IDX,bus=BUS,unit=UNIT,HOST-OPTS... |
48 |
|
49 |
TYPE, BUS and UNIT identify the controller device, which of its buses |
50 |
to use, and the drive's address on that bus. Details depend on TYPE. |
51 |
IDX is an alternative way to specify BUS and UNIT. |
52 |
|
53 |
In the new way, this becomes something like |
54 |
|
55 |
-drive if=none,id=DRIVE-ID,HOST-OPTS... |
56 |
-device DEVNAME,drive=DRIVE-ID,DEV-OPTS... |
57 |
|
58 |
The -device argument differs in detail for each kind of drive: |
59 |
|
60 |
* if=ide |
61 |
|
62 |
-device ide-drive,drive=DRIVE-ID,bus=IDE-BUS,unit=UNIT |
63 |
|
64 |
where IDE-BUS identifies an IDE bus, normally either ide.0 or ide.1, |
65 |
and UNIT is either 0 or 1. |
66 |
|
67 |
Bug: new way does not work for ide.1 unit 0 (in old terms: index=2) |
68 |
unless you disable the default CD-ROM with -nodefaults. |
69 |
|
70 |
* if=scsi |
71 |
|
72 |
The old way implicitly creates SCSI controllers as needed. The new |
73 |
way makes that explicit: |
74 |
|
75 |
-device lsi53c895a,id=ID |
76 |
|
77 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to |
78 |
control the PCI device address. |
79 |
|
80 |
This SCSI controller a single SCSI bus, named ID.0. Put a disk on |
81 |
it: |
82 |
|
83 |
-device scsi-disk,drive=DRIVE-ID,bus=ID.0,scsi-id=SCSI-ID |
84 |
|
85 |
* if=floppy |
86 |
|
87 |
-global isa-fdc,driveA=DRIVE-ID,driveB=DRIVE-ID |
88 |
|
89 |
This is -global instead of -device, because the floppy controller is |
90 |
created automatically, and we want to configure that one, not create |
91 |
a second one (which isn't possible anyway). |
92 |
|
93 |
Omitting a drive parameter makes that drive empty. |
94 |
|
95 |
Bug: driveA works only if you disable the default floppy drive with |
96 |
-nodefaults. |
97 |
|
98 |
* if=virtio |
99 |
|
100 |
-device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V |
101 |
|
102 |
This lets you control PCI device class and MSI-X vectors. |
103 |
|
104 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to |
105 |
control the PCI device address. |
106 |
|
107 |
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device |
108 |
|
109 |
For USB devices, the old way is actually different: |
110 |
|
111 |
-usbdevice disk:format=FMT:FILENAME |
112 |
|
113 |
Provides much less control than -drive's HOST-OPTS... The new way |
114 |
fixes that: |
115 |
|
116 |
-device usb-storage,drive=DRIVE-ID |
117 |
|
118 |
=== Character Devices === |
119 |
|
120 |
A QEMU character device has a host and a guest part. |
121 |
|
122 |
The old ways to define character devices define host and guest part |
123 |
together. |
124 |
|
125 |
The new way keeps the parts separate: you create the host part with |
126 |
-chardev, and the guest device with -device. |
127 |
|
128 |
The various old ways to define a character device are all of the |
129 |
general form |
130 |
|
131 |
-FOO FOO-OPTS...,LEGACY-CHARDEV |
132 |
|
133 |
where FOO-OPTS... is specific to -FOO, and the host part |
134 |
LEGACY-CHARDEV is the same everywhere. |
135 |
|
136 |
In the new way, this becomes |
137 |
|
138 |
-chardev HOST-OPTS...,id=CHR-ID |
139 |
-device DEVNAME,chardev=CHR-ID,DEV-OPTS... |
140 |
|
141 |
The appropriate DEVNAME depends on the machine type. For type "pc": |
142 |
|
143 |
* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX |
144 |
|
145 |
This lets you control I/O ports and IRQs. |
146 |
|
147 |
* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX |
148 |
|
149 |
This lets you control I/O ports and IRQs. |
150 |
|
151 |
* -usbdevice serial:vendorid=VID,productid=PRID becomes |
152 |
-device usb-serial,vendorid=VID,productid=PRID |
153 |
|
154 |
* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always |
155 |
uses "braille". With -device, this useful default is gone, so you |
156 |
have to use something like |
157 |
|
158 |
-device usb-braille,chardev=braille,vendorid=VID,productid=PRID |
159 |
-chardev braille,id=braille |
160 |
|
161 |
* -virtioconsole is still being worked on |
162 |
|
163 |
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: |
164 |
|
165 |
* null becomes -chardev null |
166 |
|
167 |
* pty, msmouse, braille, stdio likewise |
168 |
|
169 |
* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT |
170 |
|
171 |
* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS> |
172 |
|
173 |
* con: becomes -chardev console |
174 |
|
175 |
* COM<NUM> becomes -chardev serial,path=<NUM> |
176 |
|
177 |
* file:FNAME becomes -chardev file,path=FNAME |
178 |
|
179 |
* pipe:FNAME becomes -chardev pipe,path=FNAME |
180 |
|
181 |
* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS... |
182 |
|
183 |
* telnet:HOST:PORT,OPTS... becomes |
184 |
-chardev socket,host=HOST,port=PORT,OPTS...,telnet=on |
185 |
|
186 |
* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes |
187 |
-chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT |
188 |
|
189 |
* unix:FNAME becomes -chardev socket,path=FNAME |
190 |
|
191 |
* /dev/parportN becomes -chardev parport,file=/dev/parportN |
192 |
|
193 |
* /dev/ppiN likewise |
194 |
|
195 |
* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME |
196 |
|
197 |
* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the |
198 |
character device defined by LEGACY-CHARDEV. -chardev provides more |
199 |
general multiplexing instead: you can connect up to four users to a |
200 |
single host part. You need to pass mux=on to -chardev to enable |
201 |
switching the input focus. |
202 |
|
203 |
QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but |
204 |
also in various other places such as -monitor or -net |
205 |
user,guestfwd=... You can use chardev:CHR-ID in place of |
206 |
LEGACY-CHARDEV to refer to a host part defined with -chardev. |
207 |
|
208 |
=== Network Devices === |
209 |
|
210 |
A QEMU network device (NIC) has a host and a guest part. |
211 |
|
212 |
The old ways to define NICs define host and guest part together. It |
213 |
looks like this: |
214 |
|
215 |
-net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V |
216 |
|
217 |
Except for USB it looks like this: |
218 |
|
219 |
-usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V |
220 |
|
221 |
The new way keeps the parts separate: you create the host part with |
222 |
-netdev, and the guest device with -device, like this: |
223 |
|
224 |
-netdev type=TYPE,id=NET-ID |
225 |
-device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... |
226 |
|
227 |
Unlike the old way, this creates just a network device, not a VLAN. |
228 |
If you really want a VLAN, create it the usual way, then create the |
229 |
guest device like this: |
230 |
|
231 |
-device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS... |
232 |
|
233 |
DEVNAME equals MODEL, except for virtio you have to name the virtio |
234 |
device appropriate for the bus (virtio-net-pci for PCI), and for USB |
235 |
NIC you have to use usb-net. |
236 |
|
237 |
The old name=ID parameter becomes the usual id=ID with -device. |
238 |
|
239 |
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI |
240 |
device address, as usual. The old -net nic provides parameter addr |
241 |
for that, it is silently ignored when the NIC is not a PCI device. |
242 |
|
243 |
-net nic accepts vectors=V for all models, but it's silently ignored |
244 |
except for virtio-net-pci (model=virtio). With -device, only devices |
245 |
that support it accept it. |
246 |
|
247 |
Not all devices are available with -device at this time. All PCI |
248 |
devices and ne2k_isa are. |
249 |
|
250 |
Some PCI devices aren't available with -net nic, e.g. i82558a. |
251 |
|
252 |
Bug: usb-net does not work, yet. Patch posted. |
253 |
|
254 |
=== Graphics Devices === |
255 |
|
256 |
Host and guest part of graphics devices have always been separate. |
257 |
|
258 |
The old way to define the guest graphics device is -vga VGA. |
259 |
|
260 |
The new way is -device. Map from -vga argument to -device: |
261 |
|
262 |
std -device VGA |
263 |
cirrus -device cirrus-vga |
264 |
vmware -device vmware-svga |
265 |
xenfb not yet available with -device |
266 |
|
267 |
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control |
268 |
the PCI device address. |
269 |
|
270 |
-device VGA supports properties bios-offset and bios-size, but they |
271 |
aren't used with machine type "pc". |
272 |
|
273 |
Bug: -device cirrus-vga and -device vmware-svga require -nodefaults. |
274 |
|
275 |
Bug: the new way requires PCI; ISA VGA is not yet available with |
276 |
-device. |
277 |
|
278 |
Bug: the new way doesn't work for machine type "pc", because it |
279 |
violates obscure device initialization ordering constraints. |
280 |
|
281 |
=== Audio Devices === |
282 |
|
283 |
Host and guest part of audio devices have always been separate. |
284 |
|
285 |
The old way to define guest audio devices is -soundhw C1,... |
286 |
|
287 |
The new way is to define each guest audio device separately with |
288 |
-device. |
289 |
|
290 |
Map from -soundhw sound card name to -device: |
291 |
|
292 |
ac97 -device AC97 |
293 |
cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA |
294 |
es1370 -device ES1370 |
295 |
gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F |
296 |
sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V |
297 |
adlib not yet available with -device |
298 |
pcspk not yet available with -device |
299 |
|
300 |
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI |
301 |
device address, as usual. |
302 |
|
303 |
=== USB Devices === |
304 |
|
305 |
The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... |
306 |
|
307 |
The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: |
308 |
|
309 |
* mouse -device usb-mouse |
310 |
* tablet -device usb-tablet |
311 |
* keyboard -device usb-kdb |
312 |
* wacom-tablet -device usb-wacom-tablet |
313 |
* host:... See "Host Device Assignment" |
314 |
* disk:... See "Block Devices" |
315 |
* serial:... See "Character Devices" |
316 |
* braille See "Character Devices" |
317 |
* net:... See "Network Devices" |
318 |
* bt:... not yet available with -device |
319 |
|
320 |
=== Watchdog Devices === |
321 |
|
322 |
Host and guest part of watchdog devices have always been separate. |
323 |
|
324 |
The old way to define a guest watchdog device is -watchdog DEVNAME. |
325 |
The new way is -device DEVNAME. For PCI devices, you can add |
326 |
bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. |
327 |
|
328 |
=== Host Device Assignment === |
329 |
|
330 |
QEMU supports assigning host PCI devices (qemu-kvm only at this time) |
331 |
and host USB devices. |
332 |
|
333 |
The old way to assign a host PCI device is |
334 |
|
335 |
-pcidevice host=ADDR,dma=none,id=ID |
336 |
|
337 |
The new way is |
338 |
|
339 |
-device pci-assign,host=ADDR,iommu=IOMMU,id=ID |
340 |
|
341 |
The old dma=none becomes iommu=0 with -device. |
342 |
|
343 |
The old way to assign a host USB device is |
344 |
|
345 |
-usbdevice host:auto:BUS.ADDR:VID:PRID |
346 |
|
347 |
where any of BUS, ADDR, VID, PRID can be the wildcard *. |
348 |
|
349 |
The new way is |
350 |
|
351 |
-device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID |
352 |
|
353 |
where left out or zero BUS, ADDR, VID, PRID serve as wildcard. |