Revision 96560cb3

b/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.  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

  
100
  -device virtio-blk-pci,drive=DRIVE-ID,class=C,vectors=V
101

  
102
  This lets you control PCI device class and MSI-X vectors.
103

  
104
  As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to
105
  control the PCI device address.
106

  
107
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
108

  
109
For USB devices, the old way is actually different:
110

  
111
    -usbdevice disk:format=FMT:FILENAME
112

  
113
Provides much less control than -drive's HOST-OPTS...  The new way
114
fixes that:
115

  
116
    -device usb-storage,drive=DRIVE-ID
117

  
118
=== Character Devices ===
119

  
120
A QEMU character device has a host and a guest part.
121

  
122
The old ways to define character devices define host and guest part
123
together.
124

  
125
The new way keeps the parts separate: you create the host part with
126
-chardev, and the guest device with -device.
127

  
128
The various old ways to define a character device are all of the
129
general form
130

  
131
    -FOO FOO-OPTS...,LEGACY-CHARDEV
132

  
133
where FOO-OPTS... is specific to -FOO, and the host part
134
LEGACY-CHARDEV is the same everywhere.
135

  
136
In the new way, this becomes
137

  
138
    -chardev HOST-OPTS...,id=CHR-ID
139
    -device DEVNAME,chardev=CHR-ID,DEV-OPTS...
140

  
141
The appropriate DEVNAME depends on the machine type.  For type "pc":
142

  
143
* -serial becomes -device isa-serial,iobase=IOADDR,irq=IRQ,index=IDX
144

  
145
  This lets you control I/O ports and IRQs.
146

  
147
* -parallel becomes -device isa-parallel,iobase=IOADDR,irq=IRQ,index=IDX
148

  
149
  This lets you control I/O ports and IRQs.
150

  
151
* -usbdevice serial:vendorid=VID,productid=PRID becomes
152
  -device usb-serial,vendorid=VID,productid=PRID
153

  
154
* -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
155
  uses "braille".  With -device, this useful default is gone, so you
156
  have to use something like
157

  
158
  -device usb-braille,chardev=braille,vendorid=VID,productid=PRID
159
  -chardev braille,id=braille
160

  
161
* -virtioconsole is still being worked on
162

  
163
LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows:
164

  
165
* null becomes -chardev null
166

  
167
* pty, msmouse, braille, stdio likewise
168

  
169
* vc:WIDTHxHEIGHT becomes -chardev vc,width=WIDTH,height=HEIGHT
170

  
171
* vc:<COLS>Cx<ROWS>C becomes -chardev vc,cols=<COLS>,rows=<ROWS>
172

  
173
* con: becomes -chardev console
174

  
175
* COM<NUM> becomes -chardev serial,path=<NUM>
176

  
177
* file:FNAME becomes -chardev file,path=FNAME
178

  
179
* pipe:FNAME becomes -chardev pipe,path=FNAME
180

  
181
* tcp:HOST:PORT,OPTS... becomes -chardev socket,host=HOST,port=PORT,OPTS...
182

  
183
* telnet:HOST:PORT,OPTS... becomes
184
  -chardev socket,host=HOST,port=PORT,OPTS...,telnet=on
185

  
186
* udp:HOST:PORT@LOCALADDR:LOCALPORT becomes
187
  -chardev udp,host=HOST,port=PORT,localaddr=LOCALADDR,localport=LOCALPORT
188

  
189
* unix:FNAME becomes -chardev socket,path=FNAME
190

  
191
* /dev/parportN becomes -chardev parport,file=/dev/parportN
192

  
193
* /dev/ppiN likewise
194

  
195
* Any other /dev/FNAME becomes -chardev tty,path=/dev/FNAME
196

  
197
* mon:LEGACY-CHARDEV is special: it multiplexes the monitor onto the
198
  character device defined by LEGACY-CHARDEV.  -chardev provides more
199
  general multiplexing instead: you can connect up to four users to a
200
  single host part.  You need to pass mux=on to -chardev to enable
201
  switching the input focus.
202

  
203
QEMU uses LEGACY-CHARDEV syntax not just to set up guest devices, but
204
also in various other places such as -monitor or -net
205
user,guestfwd=...  You can use chardev:CHR-ID in place of
206
LEGACY-CHARDEV to refer to a host part defined with -chardev.
207

  
208
=== Network Devices ===
209

  
210
A QEMU network device (NIC) has a host and a guest part.
211

  
212
The old ways to define NICs define host and guest part together.  It
213
looks like this:
214

  
215
    -net nic,vlan=VLAN,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V
216

  
217
Except for USB it looks like this:
218

  
219
    -usbdevice net:vlan=VLAN,macaddr=MACADDR,name=ID,addr=STR,vectors=V
220

  
221
The new way keeps the parts separate: you create the host part with
222
-netdev, and the guest device with -device, like this:
223

  
224
    -netdev type=TYPE,id=NET-ID
225
    -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
226

  
227
Unlike the old way, this creates just a network device, not a VLAN.
228
If you really want a VLAN, create it the usual way, then create the
229
guest device like this:
230

  
231
    -device DEVNAME,vlan=VLAN,mac=MACADDR,DEV-OPTS...
232

  
233
DEVNAME equals MODEL, except for virtio you have to name the virtio
234
device appropriate for the bus (virtio-net-pci for PCI), and for USB
235
NIC you have to use usb-net.
236

  
237
The old name=ID parameter becomes the usual id=ID with -device.
238

  
239
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
240
device address, as usual.  The old -net nic provides parameter addr
241
for that, it is silently ignored when the NIC is not a PCI device.
242

  
243
-net nic accepts vectors=V for all models, but it's silently ignored
244
except for virtio-net-pci (model=virtio).  With -device, only devices
245
that support it accept it.
246

  
247
Not all devices are available with -device at this time.  All PCI
248
devices and ne2k_isa are.
249

  
250
Some PCI devices aren't available with -net nic, e.g. i82558a.
251

  
252
Bug: usb-net does not work, yet.  Patch posted.
253

  
254
=== Graphics Devices ===
255

  
256
Host and guest part of graphics devices have always been separate.
257

  
258
The old way to define the guest graphics device is -vga VGA.
259

  
260
The new way is -device.  Map from -vga argument to -device:
261

  
262
    std         -device VGA
263
    cirrus      -device cirrus-vga
264
    vmware      -device vmware-svga
265
    xenfb       not yet available with -device
266

  
267
As for all PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control
268
the PCI device address.
269

  
270
-device VGA supports properties bios-offset and bios-size, but they
271
aren't used with machine type "pc".
272

  
273
Bug: -device cirrus-vga and -device vmware-svga require -nodefaults.
274

  
275
Bug: the new way requires PCI; ISA VGA is not yet available with
276
-device.
277

  
278
Bug: the new way doesn't work for machine type "pc", because it
279
violates obscure device initialization ordering constraints.
280

  
281
=== Audio Devices ===
282

  
283
Host and guest part of audio devices have always been separate.
284

  
285
The old way to define guest audio devices is -soundhw C1,...
286

  
287
The new way is to define each guest audio device separately with
288
-device.
289

  
290
Map from -soundhw sound card name to -device:
291

  
292
    ac97        -device AC97
293
    cs4231a     -device cs4231a,iobase=IOADDR,irq=IRQ,dma=DMA
294
    es1370      -device ES1370
295
    gus         -device gus,iobase=IOADDR,irq=IRQ,dma=DMA,freq=F
296
    sb16        -device sb16,iobase=IOADDR,irq=IRQ,dma=DMA,dma16=DMA16,version=V
297
    adlib       not yet available with -device
298
    pcspk       not yet available with -device
299

  
300
For PCI devices, you can add bus=PCI-BUS,addr=DEVFN to control the PCI
301
device address, as usual.
302

  
303
=== USB Devices ===
304

  
305
The old way to define a virtual USB device is -usbdevice DRIVER:OPTS...
306

  
307
The new way is -device DEVNAME,DEV-OPTS...  Details depend on DRIVER:
308

  
309
* mouse           -device usb-mouse
310
* tablet          -device usb-tablet
311
* keyboard        -device usb-kdb
312
* wacom-tablet    -device usb-wacom-tablet
313
* host:...        See "Host Device Assignment"
314
* disk:...        See "Block Devices"
315
* serial:...      See "Character Devices"
316
* braille         See "Character Devices"
317
* net:...         See "Network Devices"
318
* bt:...          not yet available with -device
319

  
320
=== Watchdog Devices ===
321

  
322
Host and guest part of watchdog devices have always been separate.
323

  
324
The old way to define a guest watchdog device is -watchdog DEVNAME.
325
The new way is -device DEVNAME.  For PCI devices, you can add
326
bus=PCI-BUS,addr=DEVFN to control the PCI device address, as usual.
327

  
328
=== Host Device Assignment ===
329

  
330
QEMU supports assigning host PCI devices (qemu-kvm only at this time)
331
and host USB devices.
332

  
333
The old way to assign a host PCI device is
334

  
335
    -pcidevice host=ADDR,dma=none,id=ID
336

  
337
The new way is
338

  
339
    -device pci-assign,host=ADDR,iommu=IOMMU,id=ID
340

  
341
The old dma=none becomes iommu=0 with -device.
342

  
343
The old way to assign a host USB device is
344

  
345
    -usbdevice host:auto:BUS.ADDR:VID:PRID
346

  
347
where any of BUS, ADDR, VID, PRID can be the wildcard *.
348

  
349
The new way is
350

  
351
    -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
352

  
353
where left out or zero BUS, ADDR, VID, PRID serve as wildcard.

Also available in: Unified diff