![[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
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:
1.1.1.2 ! root 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".
1.1 root 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:
1.1.1.2 ! root 104: -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
1.1 root 105:
106: This lets you control PCI device class and MSI-X vectors.
107:
1.1.1.2 ! root 108: IOEVENTFD controls whether or not ioeventfd is used for virtqueue notify. It
! 109: can be set to on (default) or off.
! 110:
1.1 root 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:
1.1.1.2 ! root 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.
1.1 root 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:
1.1.1.2 ! root 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:
1.1 root 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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.