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