linux-user: save auxv length
[qemu.git] / docs / qdev-device-use.txt
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.  Examples:
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     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...)
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
50     -drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
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.
54
55 Instead of bus=BUS,unit=UNIT, you can also say index=IDX.
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
62 The old OPTS get split into HOST-OPTS and DEV-OPTS as follows:
63
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.
72
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.
76
77 * addr is special, see if=virtio below.
78
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.
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
98   This SCSI controller provides a single SCSI bus, named ID.0.  Put a
99   disk on it:
100
101   -device DEVNAME,drive=DRIVE-ID,bus=ID.0,scsi-id=UNIT
102
103   where DEVNAME is either scsi-hd, scsi-cd or scsi-generic.
104
105 * if=floppy
106
107   -global isa-fdc.driveA=DRIVE-ID
108   -global isa-fdc.driveB=DRIVE-ID
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
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".
117
118 * if=virtio
119
120   -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V,ioeventfd=IOEVENTFD
121
122   This lets you control PCI device class and MSI-X vectors.
123
124   IOEVENTFD controls whether or not ioeventfd is used for virtqueue
125   notify.  It can be set to on (default) or off.
126
127   As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
128   control the PCI device address.  This replaces option addr available
129   with -drive if=virtio.
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
137 Provides much less control than -drive's OPTS...  The new way fixes
138 that:
139
140     -device usb-storage,drive=DRIVE-ID,removable=RMB
141
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.
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
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
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=COM<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
246 Host and guest part of network devices have always been separate.
247
248 The old way to define the guest part looks like this:
249
250     -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
251
252 Except for USB it looks like this:
253
254     -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
255
256 The new way is -device:
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
262 you have to use usb-net.
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
268 for that, which is silently ignored when the NIC is not a PCI device.
269
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
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
282 To connect to a VLAN instead of an ordinary host part, replace
283 netdev=NET-ID by vlan=VLAN.
284
285 === Graphics Devices ===
286
287 Host and guest part of graphics devices have always been separate.
288
289 The old way to define the guest graphics device is -vga VGA.  Not all
290 machines support all -vga options.
291
292 The new way is -device.  The mapping from -vga argument to -device
293 depends on the machine type.  For machine "pc", it's:
294
295     std         -device VGA
296     cirrus      -device cirrus-vga
297     vmware      -device vmware-svga
298     qxl         -device qxl-vga
299     none        -nodefaults
300                 disables more than just VGA, see "Default Devices"
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
308 For machine "isapc", it's
309
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.
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
334     hda         -device intel-hda,msi=MSI -device hda-duplex
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
348 * ccid            -device usb-ccid
349 * keyboard        -device usb-kbd
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
381 The old dma=none becomes iommu=off with -device.
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
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.