]>
Commit | Line | Data |
---|---|---|
96560cb3 MA |
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 | ||
65d6dcbd | 100 | -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD |
96560cb3 MA |
101 | |
102 | This lets you control PCI device class and MSI-X vectors. | |
103 | ||
65d6dcbd SH |
104 | IOEVENTFD controls whether or not ioeventfd is used for virtqueue notify. It |
105 | can be set to on (default) or off. | |
106 | ||
96560cb3 MA |
107 | As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to |
108 | control the PCI device address. | |
109 | ||
110 | * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device | |
111 | ||
112 | For USB devices, the old way is actually different: | |
113 | ||
114 | -usbdevice disk:format=FMT:FILENAME | |
115 | ||
116 | Provides much less control than -drive's HOST-OPTS... The new way | |
117 | fixes that: | |
118 | ||
119 | -device usb-storage,drive=DRIVE-ID | |
120 | ||
121 | === Character Devices === | |
122 | ||
123 | A QEMU character device has a host and a guest part. | |
124 | ||
125 | The old ways to define character devices define host and guest part | |
126 | together. | |
127 | ||
128 | The new way keeps the parts separate: you create the host part with | |
129 | -chardev, and the guest device with -device. | |
130 | ||
131 | The various old ways to define a character device are all of the | |
132 | general form | |
133 | ||
134 | -FOO FOO-OPTS...,LEGACY-CHARDEV | |
135 | ||
136 | where FOO-OPTS... is specific to -FOO, and the host part | |
137 | LEGACY-CHARDEV is the same everywhere. | |
138 | ||
139 | In the new way, this becomes | |
140 | ||
141 | -chardev HOST-OPTS...,id=CHR-ID | |
142 | -device DEVNAME,chardev=CHR-ID,DEV-OPTS... | |
143 | ||
144 | The appropriate DEVNAME depends on the machine type. For type "pc": | |
145 | ||
146 | * -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX | |
147 | ||
148 | This lets you control I/O ports and IRQs. | |
149 | ||
150 | * -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX | |
151 | ||
152 | This lets you control I/O ports and IRQs. | |
153 | ||
154 | * -usbdevice serial:vendorid=VID,productid=PRID becomes | |
155 | -device usb-serial,vendorid=VID,productid=PRID | |
156 | ||
157 | * -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always | |
158 | uses "braille". With -device, this useful default is gone, so you | |
159 | have to use something like | |
160 | ||
161 | -device usb-braille,chardev=braille,vendorid=VID,productid=PRID | |
162 | -chardev braille,id=braille | |
163 | ||
164 | * -virtioconsole is still being worked on | |
165 | ||
166 | LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: | |
167 | ||
168 | * null becomes -chardev null | |
169 | ||
170 | * pty, msmouse, braille, stdio likewise | |
171 | ||
172 | * vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT | |
173 | ||
174 | * vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS> | |
175 | ||
176 | * con: becomes -chardev console | |
177 | ||
178 | * COM<NUM> becomes -chardev serial,path=<NUM> | |
179 | ||
180 | * file:FNAME becomes -chardev file,path=FNAME | |
181 | ||
182 | * pipe:FNAME becomes -chardev pipe,path=FNAME | |
183 | ||
184 | * tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS... | |
185 | ||
186 | * telnet:HOST:PORT,OPTS... becomes | |
187 | -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on | |
188 | ||
189 | * udp:HOST:PORT@LOCALADDR:LOCALPORT becomes | |
190 | -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT | |
191 | ||
192 | * unix:FNAME becomes -chardev socket,path=FNAME | |
193 | ||
194 | * /dev/parportN becomes -chardev parport,file=/dev/parportN | |
195 | ||
196 | * /dev/ppiN likewise | |
197 | ||
198 | * Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME | |
199 | ||
200 | * mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the | |
201 | character device defined by LEGACY-CHARDEV. -chardev provides more | |
202 | general multiplexing instead: you can connect up to four users to a | |
203 | single host part. You need to pass mux=on to -chardev to enable | |
204 | switching the input focus. | |
205 | ||
206 | QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but | |
207 | also in various other places such as -monitor or -net | |
208 | user,guestfwd=... You can use chardev:CHR-ID in place of | |
209 | LEGACY-CHARDEV to refer to a host part defined with -chardev. | |
210 | ||
211 | === Network Devices === | |
212 | ||
213 | A QEMU network device (NIC) has a host and a guest part. | |
214 | ||
215 | The old ways to define NICs define host and guest part together. It | |
216 | looks like this: | |
217 | ||
218 | -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V | |
219 | ||
220 | Except for USB it looks like this: | |
221 | ||
222 | -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V | |
223 | ||
224 | The new way keeps the parts separate: you create the host part with | |
225 | -netdev, and the guest device with -device, like this: | |
226 | ||
227 | -netdev type=TYPE,id=NET-ID | |
228 | -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS... | |
229 | ||
230 | Unlike the old way, this creates just a network device, not a VLAN. | |
231 | If you really want a VLAN, create it the usual way, then create the | |
232 | guest device like this: | |
233 | ||
234 | -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS... | |
235 | ||
236 | DEVNAME equals MODEL, except for virtio you have to name the virtio | |
237 | device appropriate for the bus (virtio-net-pci for PCI), and for USB | |
238 | NIC you have to use usb-net. | |
239 | ||
240 | The old name=ID parameter becomes the usual id=ID with -device. | |
241 | ||
242 | For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI | |
243 | device address, as usual. The old -net nic provides parameter addr | |
244 | for that, it is silently ignored when the NIC is not a PCI device. | |
245 | ||
65d6dcbd SH |
246 | For virtio-net-pci, you can control whether or not ioeventfd is used for |
247 | virtqueue notify by setting ioeventfd= to on or off (default). | |
248 | ||
96560cb3 MA |
249 | -net nic accepts vectors=V for all models, but it's silently ignored |
250 | except for virtio-net-pci (model=virtio). With -device, only devices | |
251 | that support it accept it. | |
252 | ||
253 | Not all devices are available with -device at this time. All PCI | |
254 | devices and ne2k_isa are. | |
255 | ||
256 | Some PCI devices aren't available with -net nic, e.g. i82558a. | |
257 | ||
258 | Bug: usb-net does not work, yet. Patch posted. | |
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. | |
265 | ||
266 | The new way is -device. Map from -vga argument to -device: | |
267 | ||
268 | std -device VGA | |
269 | cirrus -device cirrus-vga | |
270 | vmware -device vmware-svga | |
271 | xenfb not yet available with -device | |
272 | ||
273 | As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control | |
274 | the PCI device address. | |
275 | ||
276 | -device VGA supports properties bios-offset and bios-size, but they | |
277 | aren't used with machine type "pc". | |
278 | ||
279 | Bug: -device cirrus-vga and -device vmware-svga require -nodefaults. | |
280 | ||
281 | Bug: the new way requires PCI; ISA VGA is not yet available with | |
282 | -device. | |
283 | ||
284 | Bug: the new way doesn't work for machine type "pc", because it | |
285 | violates obscure device initialization ordering constraints. | |
286 | ||
287 | === Audio Devices === | |
288 | ||
289 | Host and guest part of audio devices have always been separate. | |
290 | ||
291 | The old way to define guest audio devices is -soundhw C1,... | |
292 | ||
293 | The new way is to define each guest audio device separately with | |
294 | -device. | |
295 | ||
296 | Map from -soundhw sound card name to -device: | |
297 | ||
298 | ac97 -device AC97 | |
299 | cs4231a -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA | |
300 | es1370 -device ES1370 | |
301 | gus -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F | |
302 | sb16 -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V | |
303 | adlib not yet available with -device | |
304 | pcspk not yet available with -device | |
305 | ||
306 | For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI | |
307 | device address, as usual. | |
308 | ||
309 | === USB Devices === | |
310 | ||
311 | The old way to define a virtual USB device is -usbdevice DRIVER:OPTS... | |
312 | ||
313 | The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: | |
314 | ||
315 | * mouse -device usb-mouse | |
316 | * tablet -device usb-tablet | |
317 | * keyboard -device usb-kdb | |
318 | * wacom-tablet -device usb-wacom-tablet | |
319 | * host:... See "Host Device Assignment" | |
320 | * disk:... See "Block Devices" | |
321 | * serial:... See "Character Devices" | |
322 | * braille See "Character Devices" | |
323 | * net:... See "Network Devices" | |
324 | * bt:... not yet available with -device | |
325 | ||
326 | === Watchdog Devices === | |
327 | ||
328 | Host and guest part of watchdog devices have always been separate. | |
329 | ||
330 | The old way to define a guest watchdog device is -watchdog DEVNAME. | |
331 | The new way is -device DEVNAME. For PCI devices, you can add | |
332 | bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual. | |
333 | ||
334 | === Host Device Assignment === | |
335 | ||
336 | QEMU supports assigning host PCI devices (qemu-kvm only at this time) | |
337 | and host USB devices. | |
338 | ||
339 | The old way to assign a host PCI device is | |
340 | ||
341 | -pcidevice host=ADDR,dma=none,id=ID | |
342 | ||
343 | The new way is | |
344 | ||
345 | -device pci-assign,host=ADDR,iommu=IOMMU,id=ID | |
346 | ||
347 | The old dma=none becomes iommu=0 with -device. | |
348 | ||
349 | The old way to assign a host USB device is | |
350 | ||
351 | -usbdevice host:auto:BUS.ADDR:VID:PRID | |
352 | ||
353 | where any of BUS, ADDR, VID, PRID can be the wildcard *. | |
354 | ||
355 | The new way is | |
356 | ||
357 | -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID | |
358 | ||
359 | where left out or zero BUS, ADDR, VID, PRID serve as wildcard. |