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