Statistics
| Branch: | Revision:

root / qemu-options.hx @ d4970b07

History | View | Annotate | Download (81.5 kB)

1
HXCOMM Use DEFHEADING() to define headings in both help text and texi
2
HXCOMM Text between STEXI and ETEXI are copied to texi version and
3
HXCOMM discarded from C version
4
HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5
HXCOMM construct option structures, enums and help message for specified
6
HXCOMM architectures.
7
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8

    
9
DEFHEADING(Standard options:)
10
STEXI
11
@table @option
12
ETEXI
13

    
14
DEF("help", 0, QEMU_OPTION_h,
15
    "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
16
STEXI
17
@item -h
18
@findex -h
19
Display help and exit
20
ETEXI
21

    
22
DEF("version", 0, QEMU_OPTION_version,
23
    "-version        display version information and exit\n", QEMU_ARCH_ALL)
24
STEXI
25
@item -version
26
@findex -version
27
Display version information and exit
28
ETEXI
29

    
30
DEF("M", HAS_ARG, QEMU_OPTION_M,
31
    "-M machine      select emulated machine (-M ? for list)\n", QEMU_ARCH_ALL)
32
STEXI
33
@item -M @var{machine}
34
@findex -M
35
Select the emulated @var{machine} (@code{-M ?} for list)
36
ETEXI
37

    
38
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
39
    "-cpu cpu        select CPU (-cpu ? for list)\n", QEMU_ARCH_ALL)
40
STEXI
41
@item -cpu @var{model}
42
@findex -cpu
43
Select CPU model (-cpu ? for list and additional feature selection)
44
ETEXI
45

    
46
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
47
    "-smp n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
48
    "                set the number of CPUs to 'n' [default=1]\n"
49
    "                maxcpus= maximum number of total cpus, including\n"
50
    "                offline CPUs for hotplug, etc\n"
51
    "                cores= number of CPU cores on one socket\n"
52
    "                threads= number of threads on one CPU core\n"
53
    "                sockets= number of discrete sockets in the system\n",
54
        QEMU_ARCH_ALL)
55
STEXI
56
@item -smp @var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
57
@findex -smp
58
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
59
CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
60
to 4.
61
For the PC target, the number of @var{cores} per socket, the number
62
of @var{threads} per cores and the total number of @var{sockets} can be
63
specified. Missing values will be computed. If any on the three values is
64
given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
65
specifies the maximum number of hotpluggable CPUs.
66
ETEXI
67

    
68
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
69
    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
70
STEXI
71
@item -numa @var{opts}
72
@findex -numa
73
Simulate a multi node NUMA system. If mem and cpus are omitted, resources
74
are split equally.
75
ETEXI
76

    
77
DEF("fda", HAS_ARG, QEMU_OPTION_fda,
78
    "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
79
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
80
STEXI
81
@item -fda @var{file}
82
@item -fdb @var{file}
83
@findex -fda
84
@findex -fdb
85
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
86
use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
87
ETEXI
88

    
89
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
90
    "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
91
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
92
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
93
    "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
94
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
95
STEXI
96
@item -hda @var{file}
97
@item -hdb @var{file}
98
@item -hdc @var{file}
99
@item -hdd @var{file}
100
@findex -hda
101
@findex -hdb
102
@findex -hdc
103
@findex -hdd
104
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
105
ETEXI
106

    
107
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
108
    "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
109
    QEMU_ARCH_ALL)
110
STEXI
111
@item -cdrom @var{file}
112
@findex -cdrom
113
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
114
@option{-cdrom} at the same time). You can use the host CD-ROM by
115
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
116
ETEXI
117

    
118
DEF("drive", HAS_ARG, QEMU_OPTION_drive,
119
    "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
120
    "       [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
121
    "       [,cache=writethrough|writeback|none|unsafe][,format=f]\n"
122
    "       [,serial=s][,addr=A][,id=name][,aio=threads|native]\n"
123
    "       [,readonly=on|off]\n"
124
    "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
125
STEXI
126
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
127
@findex -drive
128

    
129
Define a new drive. Valid options are:
130

    
131
@table @option
132
@item file=@var{file}
133
This option defines which disk image (@pxref{disk_images}) to use with
134
this drive. If the filename contains comma, you must double it
135
(for instance, "file=my,,file" to use file "my,file").
136
@item if=@var{interface}
137
This option defines on which type on interface the drive is connected.
138
Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
139
@item bus=@var{bus},unit=@var{unit}
140
These options define where is connected the drive by defining the bus number and
141
the unit id.
142
@item index=@var{index}
143
This option defines where is connected the drive by using an index in the list
144
of available connectors of a given interface type.
145
@item media=@var{media}
146
This option defines the type of the media: disk or cdrom.
147
@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
148
These options have the same definition as they have in @option{-hdachs}.
149
@item snapshot=@var{snapshot}
150
@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
151
@item cache=@var{cache}
152
@var{cache} is "none", "writeback", "unsafe", or "writethrough" and controls how the host cache is used to access block data.
153
@item aio=@var{aio}
154
@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
155
@item format=@var{format}
156
Specify which disk @var{format} will be used rather than detecting
157
the format.  Can be used to specifiy format=raw to avoid interpreting
158
an untrusted format header.
159
@item serial=@var{serial}
160
This option specifies the serial number to assign to the device.
161
@item addr=@var{addr}
162
Specify the controller's PCI address (if=virtio only).
163
@end table
164

    
165
By default, writethrough caching is used for all block device.  This means that
166
the host page cache will be used to read and write data but write notification
167
will be sent to the guest only when the data has been reported as written by
168
the storage subsystem.
169

    
170
Writeback caching will report data writes as completed as soon as the data is
171
present in the host page cache.  This is safe as long as you trust your host.
172
If your host crashes or loses power, then the guest may experience data
173
corruption.
174

    
175
The host page cache can be avoided entirely with @option{cache=none}.  This will
176
attempt to do disk IO directly to the guests memory.  QEMU may still perform
177
an internal copy of the data.
178

    
179
Some block drivers perform badly with @option{cache=writethrough}, most notably,
180
qcow2.  If performance is more important than correctness,
181
@option{cache=writeback} should be used with qcow2.
182

    
183
In case you don't care about data integrity over host failures, use
184
cache=unsafe. This option tells qemu that it never needs to write any data
185
to the disk but can instead keeps things in cache. If anything goes wrong,
186
like your host losing power, the disk storage getting disconnected accidently,
187
etc. you're image will most probably be rendered unusable.   When using
188
the @option{-snapshot} option, unsafe caching is always used.
189

    
190
Instead of @option{-cdrom} you can use:
191
@example
192
qemu -drive file=file,index=2,media=cdrom
193
@end example
194

    
195
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
196
use:
197
@example
198
qemu -drive file=file,index=0,media=disk
199
qemu -drive file=file,index=1,media=disk
200
qemu -drive file=file,index=2,media=disk
201
qemu -drive file=file,index=3,media=disk
202
@end example
203

    
204
You can connect a CDROM to the slave of ide0:
205
@example
206
qemu -drive file=file,if=ide,index=1,media=cdrom
207
@end example
208

    
209
If you don't specify the "file=" argument, you define an empty drive:
210
@example
211
qemu -drive if=ide,index=1,media=cdrom
212
@end example
213

    
214
You can connect a SCSI disk with unit ID 6 on the bus #0:
215
@example
216
qemu -drive file=file,if=scsi,bus=0,unit=6
217
@end example
218

    
219
Instead of @option{-fda}, @option{-fdb}, you can use:
220
@example
221
qemu -drive file=file,index=0,if=floppy
222
qemu -drive file=file,index=1,if=floppy
223
@end example
224

    
225
By default, @var{interface} is "ide" and @var{index} is automatically
226
incremented:
227
@example
228
qemu -drive file=a -drive file=b"
229
@end example
230
is interpreted like:
231
@example
232
qemu -hda a -hdb b
233
@end example
234
ETEXI
235

    
236
DEF("set", HAS_ARG, QEMU_OPTION_set,
237
    "-set group.id.arg=value\n"
238
    "                set <arg> parameter for item <id> of type <group>\n"
239
    "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
240
STEXI
241
@item -set
242
@findex -set
243
TODO
244
ETEXI
245

    
246
DEF("global", HAS_ARG, QEMU_OPTION_global,
247
    "-global driver.property=value\n"
248
    "                set a global default for a driver property\n",
249
    QEMU_ARCH_ALL)
250
STEXI
251
@item -global
252
@findex -global
253
TODO
254
ETEXI
255

    
256
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
257
    "-mtdblock file  use 'file' as on-board Flash memory image\n",
258
    QEMU_ARCH_ALL)
259
STEXI
260
@item -mtdblock @var{file}
261
@findex -mtdblock
262
Use @var{file} as on-board Flash memory image.
263
ETEXI
264

    
265
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
266
    "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
267
STEXI
268
@item -sd @var{file}
269
@findex -sd
270
Use @var{file} as SecureDigital card image.
271
ETEXI
272

    
273
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
274
    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
275
STEXI
276
@item -pflash @var{file}
277
@findex -pflash
278
Use @var{file} as a parallel flash image.
279
ETEXI
280

    
281
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
282
    "-boot [order=drives][,once=drives][,menu=on|off]\n"
283
    "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n",
284
    QEMU_ARCH_ALL)
285
STEXI
286
@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off]
287
@findex -boot
288
Specify boot order @var{drives} as a string of drive letters. Valid
289
drive letters depend on the target achitecture. The x86 PC uses: a, b
290
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
291
from network adapter 1-4), hard disk boot is the default. To apply a
292
particular boot order only on the first startup, specify it via
293
@option{once}.
294

    
295
Interactive boot menus/prompts can be enabled via @option{menu=on} as far
296
as firmware/BIOS supports them. The default is non-interactive boot.
297

    
298
@example
299
# try to boot from network first, then from hard disk
300
qemu -boot order=nc
301
# boot from CD-ROM first, switch back to default order after reboot
302
qemu -boot once=d
303
@end example
304

    
305
Note: The legacy format '-boot @var{drives}' is still supported but its
306
use is discouraged as it may be removed from future versions.
307
ETEXI
308

    
309
DEF("snapshot", 0, QEMU_OPTION_snapshot,
310
    "-snapshot       write to temporary files instead of disk image files\n",
311
    QEMU_ARCH_ALL)
312
STEXI
313
@item -snapshot
314
@findex -snapshot
315
Write to temporary files instead of disk image files. In this case,
316
the raw disk image you use is not written back. You can however force
317
the write back by pressing @key{C-a s} (@pxref{disk_images}).
318
ETEXI
319

    
320
DEF("m", HAS_ARG, QEMU_OPTION_m,
321
    "-m megs         set virtual RAM size to megs MB [default="
322
    stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL)
323
STEXI
324
@item -m @var{megs}
325
@findex -m
326
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
327
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
328
gigabytes respectively.
329
ETEXI
330

    
331
DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
332
    "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
333
STEXI
334
@item -mem-path @var{path}
335
Allocate guest RAM from a temporarily created file in @var{path}.
336
ETEXI
337

    
338
#ifdef MAP_POPULATE
339
DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
340
    "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
341
    QEMU_ARCH_ALL)
342
STEXI
343
@item -mem-prealloc
344
Preallocate memory when using -mem-path.
345
ETEXI
346
#endif
347

    
348
DEF("k", HAS_ARG, QEMU_OPTION_k,
349
    "-k language     use keyboard layout (for example 'fr' for French)\n",
350
    QEMU_ARCH_ALL)
351
STEXI
352
@item -k @var{language}
353
@findex -k
354
Use keyboard layout @var{language} (for example @code{fr} for
355
French). This option is only needed where it is not easy to get raw PC
356
keycodes (e.g. on Macs, with some X11 servers or with a VNC
357
display). You don't normally need to use it on PC/Linux or PC/Windows
358
hosts.
359

    
360
The available layouts are:
361
@example
362
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
363
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
364
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
365
@end example
366

    
367
The default is @code{en-us}.
368
ETEXI
369

    
370

    
371
DEF("audio-help", 0, QEMU_OPTION_audio_help,
372
    "-audio-help     print list of audio drivers and their options\n",
373
    QEMU_ARCH_ALL)
374
STEXI
375
@item -audio-help
376
@findex -audio-help
377
Will show the audio subsystem help: list of drivers, tunable
378
parameters.
379
ETEXI
380

    
381
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
382
    "-soundhw c1,... enable audio support\n"
383
    "                and only specified sound cards (comma separated list)\n"
384
    "                use -soundhw ? to get the list of supported cards\n"
385
    "                use -soundhw all to enable all of them\n", QEMU_ARCH_ALL)
386
STEXI
387
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
388
@findex -soundhw
389
Enable audio and selected sound hardware. Use ? to print all
390
available sound hardware.
391

    
392
@example
393
qemu -soundhw sb16,adlib disk.img
394
qemu -soundhw es1370 disk.img
395
qemu -soundhw ac97 disk.img
396
qemu -soundhw hda disk.img
397
qemu -soundhw all disk.img
398
qemu -soundhw ?
399
@end example
400

    
401
Note that Linux's i810_audio OSS kernel (for AC97) module might
402
require manually specifying clocking.
403

    
404
@example
405
modprobe i810_audio clocking=48000
406
@end example
407
ETEXI
408

    
409
STEXI
410
@end table
411
ETEXI
412

    
413
DEF("usb", 0, QEMU_OPTION_usb,
414
    "-usb            enable the USB driver (will be the default soon)\n",
415
    QEMU_ARCH_ALL)
416
STEXI
417
USB options:
418
@table @option
419

    
420
@item -usb
421
@findex -usb
422
Enable the USB driver (will be the default soon)
423
ETEXI
424

    
425
DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
426
    "-usbdevice name add the host or guest USB device 'name'\n",
427
    QEMU_ARCH_ALL)
428
STEXI
429

    
430
@item -usbdevice @var{devname}
431
@findex -usbdevice
432
Add the USB device @var{devname}. @xref{usb_devices}.
433

    
434
@table @option
435

    
436
@item mouse
437
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
438

    
439
@item tablet
440
Pointer device that uses absolute coordinates (like a touchscreen). This
441
means qemu is able to report the mouse position without having to grab the
442
mouse. Also overrides the PS/2 mouse emulation when activated.
443

    
444
@item disk:[format=@var{format}]:@var{file}
445
Mass storage device based on file. The optional @var{format} argument
446
will be used rather than detecting the format. Can be used to specifiy
447
@code{format=raw} to avoid interpreting an untrusted format header.
448

    
449
@item host:@var{bus}.@var{addr}
450
Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
451

    
452
@item host:@var{vendor_id}:@var{product_id}
453
Pass through the host device identified by @var{vendor_id}:@var{product_id}
454
(Linux only).
455

    
456
@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
457
Serial converter to host character device @var{dev}, see @code{-serial} for the
458
available devices.
459

    
460
@item braille
461
Braille device.  This will use BrlAPI to display the braille output on a real
462
or fake device.
463

    
464
@item net:@var{options}
465
Network adapter that supports CDC ethernet and RNDIS protocols.
466

    
467
@end table
468
ETEXI
469

    
470
DEF("device", HAS_ARG, QEMU_OPTION_device,
471
    "-device driver[,prop[=value][,...]]\n"
472
    "                add device (based on driver)\n"
473
    "                prop=value,... sets driver properties\n"
474
    "                use -device ? to print all possible drivers\n"
475
    "                use -device driver,? to print all possible properties\n",
476
    QEMU_ARCH_ALL)
477
STEXI
478
@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
479
@findex -device
480
Add device @var{driver}.  @var{prop}=@var{value} sets driver
481
properties.  Valid properties depend on the driver.  To get help on
482
possible drivers and properties, use @code{-device ?} and
483
@code{-device @var{driver},?}.
484
ETEXI
485

    
486
DEFHEADING(File system options:)
487

    
488
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
489
    "-fsdev local,id=id,path=path,security_model=[mapped|passthrough|none]\n",
490
    QEMU_ARCH_ALL)
491

    
492
STEXI
493

    
494
The general form of a File system device option is:
495
@table @option
496

    
497
@item -fsdev @var{fstype} ,id=@var{id} [,@var{options}]
498
@findex -fsdev
499
Fstype is one of:
500
@option{local},
501
The specific Fstype will determine the applicable options.
502

    
503
Options to each backend are described below.
504

    
505
@item -fsdev local ,id=@var{id} ,path=@var{path} ,security_model=@var{security_model}
506

    
507
Create a file-system-"device" for local-filesystem.
508

    
509
@option{local} is only available on Linux.
510

    
511
@option{path} specifies the path to be exported. @option{path} is required.
512

    
513
@option{security_model} specifies the security model to be followed.
514
@option{security_model} is required.
515

    
516
@end table
517
ETEXI
518

    
519
DEFHEADING(Virtual File system pass-through options:)
520

    
521
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
522
    "-virtfs local,path=path,mount_tag=tag,security_model=[mapped|passthrough|none]\n",
523
    QEMU_ARCH_ALL)
524

    
525
STEXI
526

    
527
The general form of a Virtual File system pass-through option is:
528
@table @option
529

    
530
@item -virtfs @var{fstype} [,@var{options}]
531
@findex -virtfs
532
Fstype is one of:
533
@option{local},
534
The specific Fstype will determine the applicable options.
535

    
536
Options to each backend are described below.
537

    
538
@item -virtfs local ,path=@var{path} ,mount_tag=@var{mount_tag} ,security_model=@var{security_model}
539

    
540
Create a Virtual file-system-pass through for local-filesystem.
541

    
542
@option{local} is only available on Linux.
543

    
544
@option{path} specifies the path to be exported. @option{path} is required.
545

    
546
@option{security_model} specifies the security model to be followed.
547
@option{security_model} is required.
548

    
549

    
550
@option{mount_tag} specifies the tag with which the exported file is mounted.
551
@option{mount_tag} is required.
552

    
553
@end table
554
ETEXI
555

    
556
DEFHEADING()
557

    
558
DEF("name", HAS_ARG, QEMU_OPTION_name,
559
    "-name string1[,process=string2]\n"
560
    "                set the name of the guest\n"
561
    "                string1 sets the window title and string2 the process name (on Linux)\n",
562
    QEMU_ARCH_ALL)
563
STEXI
564
@item -name @var{name}
565
@findex -name
566
Sets the @var{name} of the guest.
567
This name will be displayed in the SDL window caption.
568
The @var{name} will also be used for the VNC server.
569
Also optionally set the top visible process name in Linux.
570
ETEXI
571

    
572
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
573
    "-uuid %08x-%04x-%04x-%04x-%012x\n"
574
    "                specify machine UUID\n", QEMU_ARCH_ALL)
575
STEXI
576
@item -uuid @var{uuid}
577
@findex -uuid
578
Set system UUID.
579
ETEXI
580

    
581
STEXI
582
@end table
583
ETEXI
584

    
585
DEFHEADING()
586

    
587
DEFHEADING(Display options:)
588

    
589
STEXI
590
@table @option
591
ETEXI
592

    
593
DEF("display", HAS_ARG, QEMU_OPTION_display,
594
    "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
595
    "            [,window_close=on|off]|curses|none|\n"
596
    "            vnc=<display>[,<optargs>]\n"
597
    "                select display type\n", QEMU_ARCH_ALL)
598
STEXI
599
@item -display @var{type}
600
@findex -display
601
Select type of display to use. This option is a replacement for the
602
old style -sdl/-curses/... options. Valid values for @var{type} are
603
@table @option
604
@item sdl
605
Display video output via SDL (usually in a separate graphics
606
window; see the SDL documentation for other possibilities).
607
@item curses
608
Display video output via curses. For graphics device models which
609
support a text mode, QEMU can display this output using a
610
curses/ncurses interface. Nothing is displayed when the graphics
611
device is in graphical mode or if the graphics device does not support
612
a text mode. Generally only the VGA device models support text mode.
613
@item none
614
Do not display video output. The guest will still see an emulated
615
graphics card, but its output will not be displayed to the QEMU
616
user. This option differs from the -nographic option in that it
617
only affects what is done with video output; -nographic also changes
618
the destination of the serial and parallel port data.
619
@item vnc
620
Start a VNC server on display <arg>
621
@end table
622
ETEXI
623

    
624
DEF("nographic", 0, QEMU_OPTION_nographic,
625
    "-nographic      disable graphical output and redirect serial I/Os to console\n",
626
    QEMU_ARCH_ALL)
627
STEXI
628
@item -nographic
629
@findex -nographic
630
Normally, QEMU uses SDL to display the VGA output. With this option,
631
you can totally disable graphical output so that QEMU is a simple
632
command line application. The emulated serial port is redirected on
633
the console. Therefore, you can still use QEMU to debug a Linux kernel
634
with a serial console.
635
ETEXI
636

    
637
DEF("curses", 0, QEMU_OPTION_curses,
638
    "-curses         use a curses/ncurses interface instead of SDL\n",
639
    QEMU_ARCH_ALL)
640
STEXI
641
@item -curses
642
@findex curses
643
Normally, QEMU uses SDL to display the VGA output.  With this option,
644
QEMU can display the VGA output when in text mode using a
645
curses/ncurses interface.  Nothing is displayed in graphical mode.
646
ETEXI
647

    
648
DEF("no-frame", 0, QEMU_OPTION_no_frame,
649
    "-no-frame       open SDL window without a frame and window decorations\n",
650
    QEMU_ARCH_ALL)
651
STEXI
652
@item -no-frame
653
@findex -no-frame
654
Do not use decorations for SDL windows and start them using the whole
655
available screen space. This makes the using QEMU in a dedicated desktop
656
workspace more convenient.
657
ETEXI
658

    
659
DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
660
    "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
661
    QEMU_ARCH_ALL)
662
STEXI
663
@item -alt-grab
664
@findex -alt-grab
665
Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
666
affects the special keys (for fullscreen, monitor-mode switching, etc).
667
ETEXI
668

    
669
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
670
    "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
671
    QEMU_ARCH_ALL)
672
STEXI
673
@item -ctrl-grab
674
@findex -ctrl-grab
675
Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
676
affects the special keys (for fullscreen, monitor-mode switching, etc).
677
ETEXI
678

    
679
DEF("no-quit", 0, QEMU_OPTION_no_quit,
680
    "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
681
STEXI
682
@item -no-quit
683
@findex -no-quit
684
Disable SDL window close capability.
685
ETEXI
686

    
687
DEF("sdl", 0, QEMU_OPTION_sdl,
688
    "-sdl            enable SDL\n", QEMU_ARCH_ALL)
689
STEXI
690
@item -sdl
691
@findex -sdl
692
Enable SDL.
693
ETEXI
694

    
695
DEF("spice", HAS_ARG, QEMU_OPTION_spice,
696
    "-spice <args>   enable spice\n", QEMU_ARCH_ALL)
697
STEXI
698
@item -spice @var{option}[,@var{option}[,...]]
699
@findex -spice
700
Enable the spice remote desktop protocol. Valid options are
701

    
702
@table @option
703

    
704
@item port=<nr>
705
Set the TCP port spice is listening on for plaintext channels.
706

    
707
@item addr=<addr>
708
Set the IP address spice is listening on.  Default is any address.
709

    
710
@item ipv4
711
@item ipv6
712
Force using the specified IP version.
713

    
714
@item password=<secret>
715
Set the password you need to authenticate.
716

    
717
@item disable-ticketing
718
Allow client connects without authentication.
719

    
720
@item disable-copy-paste
721
Disable copy paste between the client and the guest.
722

    
723
@item tls-port=<nr>
724
Set the TCP port spice is listening on for encrypted channels.
725

    
726
@item x509-dir=<dir>
727
Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
728

    
729
@item x509-key-file=<file>
730
@item x509-key-password=<file>
731
@item x509-cert-file=<file>
732
@item x509-cacert-file=<file>
733
@item x509-dh-key-file=<file>
734
The x509 file names can also be configured individually.
735

    
736
@item tls-ciphers=<list>
737
Specify which ciphers to use.
738

    
739
@item tls-channel=[main|display|inputs|record|playback|tunnel]
740
@item plaintext-channel=[main|display|inputs|record|playback|tunnel]
741
Force specific channel to be used with or without TLS encryption.  The
742
options can be specified multiple times to configure multiple
743
channels.  The special name "default" can be used to set the default
744
mode.  For channels which are not explicitly forced into one mode the
745
spice client is allowed to pick tls/plaintext as he pleases.
746

    
747
@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
748
Configure image compression (lossless).
749
Default is auto_glz.
750

    
751
@item jpeg-wan-compression=[auto|never|always]
752
@item zlib-glz-wan-compression=[auto|never|always]
753
Configure wan image compression (lossy for slow links).
754
Default is auto.
755

    
756
@item streaming-video=[off|all|filter]
757
Configure video stream detection.  Default is filter.
758

    
759
@item agent-mouse=[on|off]
760
Enable/disable passing mouse events via vdagent.  Default is on.
761

    
762
@item playback-compression=[on|off]
763
Enable/disable audio stream compression (using celt 0.5.1).  Default is on.
764

    
765
@end table
766
ETEXI
767

    
768
DEF("portrait", 0, QEMU_OPTION_portrait,
769
    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
770
    QEMU_ARCH_ALL)
771
STEXI
772
@item -portrait
773
@findex -portrait
774
Rotate graphical output 90 deg left (only PXA LCD).
775
ETEXI
776

    
777
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
778
    "-vga [std|cirrus|vmware|qxl|xenfb|none]\n"
779
    "                select video card type\n", QEMU_ARCH_ALL)
780
STEXI
781
@item -vga @var{type}
782
@findex -vga
783
Select type of VGA card to emulate. Valid values for @var{type} are
784
@table @option
785
@item cirrus
786
Cirrus Logic GD5446 Video card. All Windows versions starting from
787
Windows 95 should recognize and use this graphic card. For optimal
788
performances, use 16 bit color depth in the guest and the host OS.
789
(This one is the default)
790
@item std
791
Standard VGA card with Bochs VBE extensions.  If your guest OS
792
supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
793
to use high resolution modes (>= 1280x1024x16) then you should use
794
this option.
795
@item vmware
796
VMWare SVGA-II compatible adapter. Use it if you have sufficiently
797
recent XFree86/XOrg server or Windows guest with a driver for this
798
card.
799
@item qxl
800
QXL paravirtual graphic card.  It is VGA compatible (including VESA
801
2.0 VBE support).  Works best with qxl guest drivers installed though.
802
Recommended choice when using the spice protocol.
803
@item none
804
Disable VGA card.
805
@end table
806
ETEXI
807

    
808
DEF("full-screen", 0, QEMU_OPTION_full_screen,
809
    "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
810
STEXI
811
@item -full-screen
812
@findex -full-screen
813
Start in full screen.
814
ETEXI
815

    
816
DEF("g", 1, QEMU_OPTION_g ,
817
    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
818
    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
819
STEXI
820
@item -g @var{width}x@var{height}[x@var{depth}]
821
@findex -g
822
Set the initial graphical resolution and depth (PPC, SPARC only).
823
ETEXI
824

    
825
DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
826
    "-vnc display    start a VNC server on display\n", QEMU_ARCH_ALL)
827
STEXI
828
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
829
@findex -vnc
830
Normally, QEMU uses SDL to display the VGA output.  With this option,
831
you can have QEMU listen on VNC display @var{display} and redirect the VGA
832
display over the VNC session.  It is very useful to enable the usb
833
tablet device when using this option (option @option{-usbdevice
834
tablet}). When using the VNC display, you must use the @option{-k}
835
parameter to set the keyboard layout if you are not using en-us. Valid
836
syntax for the @var{display} is
837

    
838
@table @option
839

    
840
@item @var{host}:@var{d}
841

    
842
TCP connections will only be allowed from @var{host} on display @var{d}.
843
By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
844
be omitted in which case the server will accept connections from any host.
845

    
846
@item unix:@var{path}
847

    
848
Connections will be allowed over UNIX domain sockets where @var{path} is the
849
location of a unix socket to listen for connections on.
850

    
851
@item none
852

    
853
VNC is initialized but not started. The monitor @code{change} command
854
can be used to later start the VNC server.
855

    
856
@end table
857

    
858
Following the @var{display} value there may be one or more @var{option} flags
859
separated by commas. Valid options are
860

    
861
@table @option
862

    
863
@item reverse
864

    
865
Connect to a listening VNC client via a ``reverse'' connection. The
866
client is specified by the @var{display}. For reverse network
867
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
868
is a TCP port number, not a display number.
869

    
870
@item password
871

    
872
Require that password based authentication is used for client connections.
873
The password must be set separately using the @code{change} command in the
874
@ref{pcsys_monitor}
875

    
876
@item tls
877

    
878
Require that client use TLS when communicating with the VNC server. This
879
uses anonymous TLS credentials so is susceptible to a man-in-the-middle
880
attack. It is recommended that this option be combined with either the
881
@option{x509} or @option{x509verify} options.
882

    
883
@item x509=@var{/path/to/certificate/dir}
884

    
885
Valid if @option{tls} is specified. Require that x509 credentials are used
886
for negotiating the TLS session. The server will send its x509 certificate
887
to the client. It is recommended that a password be set on the VNC server
888
to provide authentication of the client when this is used. The path following
889
this option specifies where the x509 certificates are to be loaded from.
890
See the @ref{vnc_security} section for details on generating certificates.
891

    
892
@item x509verify=@var{/path/to/certificate/dir}
893

    
894
Valid if @option{tls} is specified. Require that x509 credentials are used
895
for negotiating the TLS session. The server will send its x509 certificate
896
to the client, and request that the client send its own x509 certificate.
897
The server will validate the client's certificate against the CA certificate,
898
and reject clients when validation fails. If the certificate authority is
899
trusted, this is a sufficient authentication mechanism. You may still wish
900
to set a password on the VNC server as a second authentication layer. The
901
path following this option specifies where the x509 certificates are to
902
be loaded from. See the @ref{vnc_security} section for details on generating
903
certificates.
904

    
905
@item sasl
906

    
907
Require that the client use SASL to authenticate with the VNC server.
908
The exact choice of authentication method used is controlled from the
909
system / user's SASL configuration file for the 'qemu' service. This
910
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
911
unprivileged user, an environment variable SASL_CONF_PATH can be used
912
to make it search alternate locations for the service config.
913
While some SASL auth methods can also provide data encryption (eg GSSAPI),
914
it is recommended that SASL always be combined with the 'tls' and
915
'x509' settings to enable use of SSL and server certificates. This
916
ensures a data encryption preventing compromise of authentication
917
credentials. See the @ref{vnc_security} section for details on using
918
SASL authentication.
919

    
920
@item acl
921

    
922
Turn on access control lists for checking of the x509 client certificate
923
and SASL party. For x509 certs, the ACL check is made against the
924
certificate's distinguished name. This is something that looks like
925
@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
926
made against the username, which depending on the SASL plugin, may
927
include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
928
When the @option{acl} flag is set, the initial access list will be
929
empty, with a @code{deny} policy. Thus no one will be allowed to
930
use the VNC server until the ACLs have been loaded. This can be
931
achieved using the @code{acl} monitor command.
932

    
933
@item lossy
934

    
935
Enable lossy compression methods (gradient, JPEG, ...). If this
936
option is set, VNC client may receive lossy framebuffer updates
937
depending on its encoding settings. Enabling this option can save
938
a lot of bandwidth at the expense of quality.
939

    
940
@item non-adaptive
941

    
942
Disable adaptive encodings. Adaptive encodings are enabled by default.
943
An adaptive encoding will try to detect frequently updated screen regions,
944
and send updates in these regions using a lossy encoding (like JPEG).
945
This can be really helpful to save bandwidth when playing videos. Disabling
946
adaptive encodings allows to restore the original static behavior of encodings
947
like Tight.
948

    
949
@end table
950
ETEXI
951

    
952
STEXI
953
@end table
954
ETEXI
955

    
956
DEFHEADING()
957

    
958
DEFHEADING(i386 target only:)
959
STEXI
960
@table @option
961
ETEXI
962

    
963
DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
964
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
965
    QEMU_ARCH_I386)
966
STEXI
967
@item -win2k-hack
968
@findex -win2k-hack
969
Use it when installing Windows 2000 to avoid a disk full bug. After
970
Windows 2000 is installed, you no longer need this option (this option
971
slows down the IDE transfers).
972
ETEXI
973

    
974
HXCOMM Deprecated by -rtc
975
DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
976

    
977
DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
978
    "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
979
    QEMU_ARCH_I386)
980
STEXI
981
@item -no-fd-bootchk
982
@findex -no-fd-bootchk
983
Disable boot signature checking for floppy disks in Bochs BIOS. It may
984
be needed to boot from old floppy disks.
985
TODO: check reference to Bochs BIOS.
986
ETEXI
987

    
988
DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
989
           "-no-acpi        disable ACPI\n", QEMU_ARCH_I386)
990
STEXI
991
@item -no-acpi
992
@findex -no-acpi
993
Disable ACPI (Advanced Configuration and Power Interface) support. Use
994
it if your guest OS complains about ACPI problems (PC target machine
995
only).
996
ETEXI
997

    
998
DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
999
    "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1000
STEXI
1001
@item -no-hpet
1002
@findex -no-hpet
1003
Disable HPET support.
1004
ETEXI
1005

    
1006
DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
1007
    "-balloon none   disable balloon device\n"
1008
    "-balloon virtio[,addr=str]\n"
1009
    "                enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
1010
STEXI
1011
@item -balloon none
1012
@findex -balloon
1013
Disable balloon device.
1014
@item -balloon virtio[,addr=@var{addr}]
1015
Enable virtio balloon device (default), optionally with PCI address
1016
@var{addr}.
1017
ETEXI
1018

    
1019
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1020
    "-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]\n"
1021
    "                ACPI table description\n", QEMU_ARCH_I386)
1022
STEXI
1023
@item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
1024
@findex -acpitable
1025
Add ACPI table with specified header fields and context from specified files.
1026
ETEXI
1027

    
1028
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1029
    "-smbios file=binary\n"
1030
    "                load SMBIOS entry from binary file\n"
1031
    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1032
    "                specify SMBIOS type 0 fields\n"
1033
    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1034
    "              [,uuid=uuid][,sku=str][,family=str]\n"
1035
    "                specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
1036
STEXI
1037
@item -smbios file=@var{binary}
1038
@findex -smbios
1039
Load SMBIOS entry from binary file.
1040

    
1041
@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
1042
@findex -smbios
1043
Specify SMBIOS type 0 fields
1044

    
1045
@item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}] [,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}] [,family=@var{str}]
1046
Specify SMBIOS type 1 fields
1047
ETEXI
1048

    
1049
DEFHEADING()
1050
STEXI
1051
@end table
1052
ETEXI
1053

    
1054
DEFHEADING(Network options:)
1055
STEXI
1056
@table @option
1057
ETEXI
1058

    
1059
HXCOMM Legacy slirp options (now moved to -net user):
1060
#ifdef CONFIG_SLIRP
1061
DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1062
DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1063
DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1064
#ifndef _WIN32
1065
DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1066
#endif
1067
#endif
1068

    
1069
DEF("net", HAS_ARG, QEMU_OPTION_net,
1070
    "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1071
    "                create a new Network Interface Card and connect it to VLAN 'n'\n"
1072
#ifdef CONFIG_SLIRP
1073
    "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=y|n]\n"
1074
    "         [,hostname=host][,dhcpstart=addr][,dns=addr][,tftp=dir][,bootfile=f]\n"
1075
    "         [,hostfwd=rule][,guestfwd=rule]"
1076
#ifndef _WIN32
1077
                                             "[,smb=dir[,smbserver=addr]]\n"
1078
#endif
1079
    "                connect the user mode network stack to VLAN 'n', configure its\n"
1080
    "                DHCP server and enabled optional services\n"
1081
#endif
1082
#ifdef _WIN32
1083
    "-net tap[,vlan=n][,name=str],ifname=name\n"
1084
    "                connect the host TAP network interface to VLAN 'n'\n"
1085
#else
1086
    "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n"
1087
    "                connect the host TAP network interface to VLAN 'n' and use the\n"
1088
    "                network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1089
    "                and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1090
    "                use '[down]script=no' to disable script execution\n"
1091
    "                use 'fd=h' to connect to an already opened TAP interface\n"
1092
    "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1093
    "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1094
    "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1095
    "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1096
    "                use vhost=on to enable experimental in kernel accelerator\n"
1097
    "                    (only has effect for virtio guests which use MSIX)\n"
1098
    "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1099
    "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
1100
#endif
1101
    "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1102
    "                connect the vlan 'n' to another VLAN using a socket connection\n"
1103
    "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1104
    "                connect the vlan 'n' to multicast maddr and port\n"
1105
    "                use 'localaddr=addr' to specify the host address to send packets from\n"
1106
#ifdef CONFIG_VDE
1107
    "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1108
    "                connect the vlan 'n' to port 'n' of a vde switch running\n"
1109
    "                on host and listening for incoming connections on 'socketpath'.\n"
1110
    "                Use group 'groupname' and mode 'octalmode' to change default\n"
1111
    "                ownership and permissions for communication port.\n"
1112
#endif
1113
    "-net dump[,vlan=n][,file=f][,len=n]\n"
1114
    "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1115
    "-net none       use it alone to have zero network devices. If no -net option\n"
1116
    "                is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
1117
DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1118
    "-netdev ["
1119
#ifdef CONFIG_SLIRP
1120
    "user|"
1121
#endif
1122
    "tap|"
1123
#ifdef CONFIG_VDE
1124
    "vde|"
1125
#endif
1126
    "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
1127
STEXI
1128
@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1129
@findex -net
1130
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1131
= 0 is the default). The NIC is an e1000 by default on the PC
1132
target. Optionally, the MAC address can be changed to @var{mac}, the
1133
device address set to @var{addr} (PCI cards only),
1134
and a @var{name} can be assigned for use in monitor commands.
1135
Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1136
that the card should have; this option currently only affects virtio cards; set
1137
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1138
NIC is created.  Qemu can emulate several different models of network card.
1139
Valid values for @var{type} are
1140
@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1141
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1142
@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1143
Not all devices are supported on all targets.  Use -net nic,model=?
1144
for a list of available devices for your target.
1145

    
1146
@item -net user[,@var{option}][,@var{option}][,...]
1147
Use the user mode network stack which requires no administrator
1148
privilege to run. Valid options are:
1149

    
1150
@table @option
1151
@item vlan=@var{n}
1152
Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1153

    
1154
@item name=@var{name}
1155
Assign symbolic name for use in monitor commands.
1156

    
1157
@item net=@var{addr}[/@var{mask}]
1158
Set IP network address the guest will see. Optionally specify the netmask,
1159
either in the form a.b.c.d or as number of valid top-most bits. Default is
1160
10.0.2.0/24.
1161

    
1162
@item host=@var{addr}
1163
Specify the guest-visible address of the host. Default is the 2nd IP in the
1164
guest network, i.e. x.x.x.2.
1165

    
1166
@item restrict=y|yes|n|no
1167
If this options is enabled, the guest will be isolated, i.e. it will not be
1168
able to contact the host and no guest IP packets will be routed over the host
1169
to the outside. This option does not affect explicitly set forwarding rule.
1170

    
1171
@item hostname=@var{name}
1172
Specifies the client hostname reported by the builtin DHCP server.
1173

    
1174
@item dhcpstart=@var{addr}
1175
Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1176
is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1177

    
1178
@item dns=@var{addr}
1179
Specify the guest-visible address of the virtual nameserver. The address must
1180
be different from the host address. Default is the 3rd IP in the guest network,
1181
i.e. x.x.x.3.
1182

    
1183
@item tftp=@var{dir}
1184
When using the user mode network stack, activate a built-in TFTP
1185
server. The files in @var{dir} will be exposed as the root of a TFTP server.
1186
The TFTP client on the guest must be configured in binary mode (use the command
1187
@code{bin} of the Unix TFTP client).
1188

    
1189
@item bootfile=@var{file}
1190
When using the user mode network stack, broadcast @var{file} as the BOOTP
1191
filename. In conjunction with @option{tftp}, this can be used to network boot
1192
a guest from a local directory.
1193

    
1194
Example (using pxelinux):
1195
@example
1196
qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1197
@end example
1198

    
1199
@item smb=@var{dir}[,smbserver=@var{addr}]
1200
When using the user mode network stack, activate a built-in SMB
1201
server so that Windows OSes can access to the host files in @file{@var{dir}}
1202
transparently. The IP address of the SMB server can be set to @var{addr}. By
1203
default the 4th IP in the guest network is used, i.e. x.x.x.4.
1204

    
1205
In the guest Windows OS, the line:
1206
@example
1207
10.0.2.4 smbserver
1208
@end example
1209
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1210
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1211

    
1212
Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1213

    
1214
Note that a SAMBA server must be installed on the host OS in
1215
@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd versions from
1216
Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
1217

    
1218
@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1219
Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1220
the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1221
@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1222
given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1223
be bound to a specific host interface. If no connection type is set, TCP is
1224
used. This option can be given multiple times.
1225

    
1226
For example, to redirect host X11 connection from screen 1 to guest
1227
screen 0, use the following:
1228

    
1229
@example
1230
# on the host
1231
qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1232
# this host xterm should open in the guest X11 server
1233
xterm -display :1
1234
@end example
1235

    
1236
To redirect telnet connections from host port 5555 to telnet port on
1237
the guest, use the following:
1238

    
1239
@example
1240
# on the host
1241
qemu -net user,hostfwd=tcp::5555-:23 [...]
1242
telnet localhost 5555
1243
@end example
1244

    
1245
Then when you use on the host @code{telnet localhost 5555}, you
1246
connect to the guest telnet server.
1247

    
1248
@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1249
Forward guest TCP connections to the IP address @var{server} on port @var{port}
1250
to the character device @var{dev}. This option can be given multiple times.
1251

    
1252
@end table
1253

    
1254
Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1255
processed and applied to -net user. Mixing them with the new configuration
1256
syntax gives undefined results. Their use for new applications is discouraged
1257
as they will be removed from future versions.
1258

    
1259
@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}] [,script=@var{file}][,downscript=@var{dfile}]
1260
Connect the host TAP network interface @var{name} to VLAN @var{n}, use
1261
the network script @var{file} to configure it and the network script
1262
@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1263
automatically provides one. @option{fd}=@var{h} can be used to specify
1264
the handle of an already opened host TAP interface. The default network
1265
configure script is @file{/etc/qemu-ifup} and the default network
1266
deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
1267
or @option{downscript=no} to disable script execution. Example:
1268

    
1269
@example
1270
qemu linux.img -net nic -net tap
1271
@end example
1272

    
1273
More complicated example (two NICs, each one connected to a TAP device)
1274
@example
1275
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1276
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1277
@end example
1278

    
1279
@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1280

    
1281
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1282
machine using a TCP socket connection. If @option{listen} is
1283
specified, QEMU waits for incoming connections on @var{port}
1284
(@var{host} is optional). @option{connect} is used to connect to
1285
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1286
specifies an already opened TCP socket.
1287

    
1288
Example:
1289
@example
1290
# launch a first QEMU instance
1291
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1292
               -net socket,listen=:1234
1293
# connect the VLAN 0 of this instance to the VLAN 0
1294
# of the first instance
1295
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1296
               -net socket,connect=127.0.0.1:1234
1297
@end example
1298

    
1299
@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1300

    
1301
Create a VLAN @var{n} shared with another QEMU virtual
1302
machines using a UDP multicast socket, effectively making a bus for
1303
every QEMU with same multicast address @var{maddr} and @var{port}.
1304
NOTES:
1305
@enumerate
1306
@item
1307
Several QEMU can be running on different hosts and share same bus (assuming
1308
correct multicast setup for these hosts).
1309
@item
1310
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1311
@url{http://user-mode-linux.sf.net}.
1312
@item
1313
Use @option{fd=h} to specify an already opened UDP multicast socket.
1314
@end enumerate
1315

    
1316
Example:
1317
@example
1318
# launch one QEMU instance
1319
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1320
               -net socket,mcast=230.0.0.1:1234
1321
# launch another QEMU instance on same "bus"
1322
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1323
               -net socket,mcast=230.0.0.1:1234
1324
# launch yet another QEMU instance on same "bus"
1325
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1326
               -net socket,mcast=230.0.0.1:1234
1327
@end example
1328

    
1329
Example (User Mode Linux compat.):
1330
@example
1331
# launch QEMU instance (note mcast address selected
1332
# is UML's default)
1333
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1334
               -net socket,mcast=239.192.168.1:1102
1335
# launch UML
1336
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
1337
@end example
1338

    
1339
Example (send packets from host's 1.2.3.4):
1340
@example
1341
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1342
               -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1343
@end example
1344

    
1345
@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1346
Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1347
listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1348
and MODE @var{octalmode} to change default ownership and permissions for
1349
communication port. This option is available only if QEMU has been compiled
1350
with vde support enabled.
1351

    
1352
Example:
1353
@example
1354
# launch vde switch
1355
vde_switch -F -sock /tmp/myswitch
1356
# launch QEMU instance
1357
qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1358
@end example
1359

    
1360
@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1361
Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1362
At most @var{len} bytes (64k by default) per packet are stored. The file format is
1363
libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1364

    
1365
@item -net none
1366
Indicate that no network devices should be configured. It is used to
1367
override the default configuration (@option{-net nic -net user}) which
1368
is activated if no @option{-net} options are provided.
1369

    
1370
@end table
1371
ETEXI
1372

    
1373
DEFHEADING()
1374

    
1375
DEFHEADING(Character device options:)
1376

    
1377
DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1378
    "-chardev null,id=id[,mux=on|off]\n"
1379
    "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1380
    "         [,server][,nowait][,telnet][,mux=on|off] (tcp)\n"
1381
    "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n"
1382
    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1383
    "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1384
    "-chardev msmouse,id=id[,mux=on|off]\n"
1385
    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1386
    "         [,mux=on|off]\n"
1387
    "-chardev file,id=id,path=path[,mux=on|off]\n"
1388
    "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1389
#ifdef _WIN32
1390
    "-chardev console,id=id[,mux=on|off]\n"
1391
    "-chardev serial,id=id,path=path[,mux=on|off]\n"
1392
#else
1393
    "-chardev pty,id=id[,mux=on|off]\n"
1394
    "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
1395
#endif
1396
#ifdef CONFIG_BRLAPI
1397
    "-chardev braille,id=id[,mux=on|off]\n"
1398
#endif
1399
#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1400
        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1401
    "-chardev tty,id=id,path=path[,mux=on|off]\n"
1402
#endif
1403
#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1404
    "-chardev parport,id=id,path=path[,mux=on|off]\n"
1405
#endif
1406
#if defined(CONFIG_SPICE)
1407
    "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
1408
#endif
1409
    , QEMU_ARCH_ALL
1410
)
1411

    
1412
STEXI
1413

    
1414
The general form of a character device option is:
1415
@table @option
1416

    
1417
@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
1418
@findex -chardev
1419
Backend is one of:
1420
@option{null},
1421
@option{socket},
1422
@option{udp},
1423
@option{msmouse},
1424
@option{vc},
1425
@option{file},
1426
@option{pipe},
1427
@option{console},
1428
@option{serial},
1429
@option{pty},
1430
@option{stdio},
1431
@option{braille},
1432
@option{tty},
1433
@option{parport},
1434
@option{spicevmc}.
1435
The specific backend will determine the applicable options.
1436

    
1437
All devices must have an id, which can be any string up to 127 characters long.
1438
It is used to uniquely identify this device in other command line directives.
1439

    
1440
A character device may be used in multiplexing mode by multiple front-ends.
1441
The key sequence of @key{Control-a} and @key{c} will rotate the input focus
1442
between attached front-ends. Specify @option{mux=on} to enable this mode.
1443

    
1444
Options to each backend are described below.
1445

    
1446
@item -chardev null ,id=@var{id}
1447
A void device. This device will not emit any data, and will drop any data it
1448
receives. The null backend does not take any options.
1449

    
1450
@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
1451

    
1452
Create a two-way stream socket, which can be either a TCP or a unix socket. A
1453
unix socket will be created if @option{path} is specified. Behaviour is
1454
undefined if TCP options are specified for a unix socket.
1455

    
1456
@option{server} specifies that the socket shall be a listening socket.
1457

    
1458
@option{nowait} specifies that QEMU should not block waiting for a client to
1459
connect to a listening socket.
1460

    
1461
@option{telnet} specifies that traffic on the socket should interpret telnet
1462
escape sequences.
1463

    
1464
TCP and unix socket options are given below:
1465

    
1466
@table @option
1467

    
1468
@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
1469

    
1470
@option{host} for a listening socket specifies the local address to be bound.
1471
For a connecting socket species the remote host to connect to. @option{host} is
1472
optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
1473

    
1474
@option{port} for a listening socket specifies the local port to be bound. For a
1475
connecting socket specifies the port on the remote host to connect to.
1476
@option{port} can be given as either a port number or a service name.
1477
@option{port} is required.
1478

    
1479
@option{to} is only relevant to listening sockets. If it is specified, and
1480
@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1481
to and including @option{to} until it succeeds. @option{to} must be specified
1482
as a port number.
1483

    
1484
@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1485
If neither is specified the socket may use either protocol.
1486

    
1487
@option{nodelay} disables the Nagle algorithm.
1488

    
1489
@item unix options: path=@var{path}
1490

    
1491
@option{path} specifies the local path of the unix socket. @option{path} is
1492
required.
1493

    
1494
@end table
1495

    
1496
@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
1497

    
1498
Sends all traffic from the guest to a remote host over UDP.
1499

    
1500
@option{host} specifies the remote host to connect to. If not specified it
1501
defaults to @code{localhost}.
1502

    
1503
@option{port} specifies the port on the remote host to connect to. @option{port}
1504
is required.
1505

    
1506
@option{localaddr} specifies the local address to bind to. If not specified it
1507
defaults to @code{0.0.0.0}.
1508

    
1509
@option{localport} specifies the local port to bind to. If not specified any
1510
available local port will be used.
1511

    
1512
@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1513
If neither is specified the device may use either protocol.
1514

    
1515
@item -chardev msmouse ,id=@var{id}
1516

    
1517
Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1518
take any options.
1519

    
1520
@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
1521

    
1522
Connect to a QEMU text console. @option{vc} may optionally be given a specific
1523
size.
1524

    
1525
@option{width} and @option{height} specify the width and height respectively of
1526
the console, in pixels.
1527

    
1528
@option{cols} and @option{rows} specify that the console be sized to fit a text
1529
console with the given dimensions.
1530

    
1531
@item -chardev file ,id=@var{id} ,path=@var{path}
1532

    
1533
Log all traffic received from the guest to a file.
1534

    
1535
@option{path} specifies the path of the file to be opened. This file will be
1536
created if it does not already exist, and overwritten if it does. @option{path}
1537
is required.
1538

    
1539
@item -chardev pipe ,id=@var{id} ,path=@var{path}
1540

    
1541
Create a two-way connection to the guest. The behaviour differs slightly between
1542
Windows hosts and other hosts:
1543

    
1544
On Windows, a single duplex pipe will be created at
1545
@file{\\.pipe\@option{path}}.
1546

    
1547
On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1548
@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1549
received by the guest. Data written by the guest can be read from
1550
@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1551
be present.
1552

    
1553
@option{path} forms part of the pipe path as described above. @option{path} is
1554
required.
1555

    
1556
@item -chardev console ,id=@var{id}
1557

    
1558
Send traffic from the guest to QEMU's standard output. @option{console} does not
1559
take any options.
1560

    
1561
@option{console} is only available on Windows hosts.
1562

    
1563
@item -chardev serial ,id=@var{id} ,path=@option{path}
1564

    
1565
Send traffic from the guest to a serial device on the host.
1566

    
1567
@option{serial} is
1568
only available on Windows hosts.
1569

    
1570
@option{path} specifies the name of the serial device to open.
1571

    
1572
@item -chardev pty ,id=@var{id}
1573

    
1574
Create a new pseudo-terminal on the host and connect to it. @option{pty} does
1575
not take any options.
1576

    
1577
@option{pty} is not available on Windows hosts.
1578

    
1579
@item -chardev stdio ,id=@var{id} [,signal=on|off]
1580
Connect to standard input and standard output of the qemu process.
1581

    
1582
@option{signal} controls if signals are enabled on the terminal, that includes
1583
exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
1584
default, use @option{signal=off} to disable it.
1585

    
1586
@option{stdio} is not available on Windows hosts.
1587

    
1588
@item -chardev braille ,id=@var{id}
1589

    
1590
Connect to a local BrlAPI server. @option{braille} does not take any options.
1591

    
1592
@item -chardev tty ,id=@var{id} ,path=@var{path}
1593

    
1594
Connect to a local tty device.
1595

    
1596
@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1597
DragonFlyBSD hosts.
1598

    
1599
@option{path} specifies the path to the tty. @option{path} is required.
1600

    
1601
@item -chardev parport ,id=@var{id} ,path=@var{path}
1602

    
1603
@option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
1604

    
1605
Connect to a local parallel port.
1606

    
1607
@option{path} specifies the path to the parallel port device. @option{path} is
1608
required.
1609

    
1610
#if defined(CONFIG_SPICE)
1611
@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
1612

    
1613
@option{debug} debug level for spicevmc
1614

    
1615
@option{name} name of spice channel to connect to
1616

    
1617
Connect to a spice virtual machine channel, such as vdiport.
1618
#endif
1619

    
1620
@end table
1621
ETEXI
1622

    
1623
DEFHEADING()
1624

    
1625
DEFHEADING(Bluetooth(R) options:)
1626

    
1627
DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1628
    "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
1629
    "-bt hci,host[:id]\n" \
1630
    "                use host's HCI with the given name\n" \
1631
    "-bt hci[,vlan=n]\n" \
1632
    "                emulate a standard HCI in virtual scatternet 'n'\n" \
1633
    "-bt vhci[,vlan=n]\n" \
1634
    "                add host computer to virtual scatternet 'n' using VHCI\n" \
1635
    "-bt device:dev[,vlan=n]\n" \
1636
    "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
1637
    QEMU_ARCH_ALL)
1638
STEXI
1639
@table @option
1640

    
1641
@item -bt hci[...]
1642
@findex -bt
1643
Defines the function of the corresponding Bluetooth HCI.  -bt options
1644
are matched with the HCIs present in the chosen machine type.  For
1645
example when emulating a machine with only one HCI built into it, only
1646
the first @code{-bt hci[...]} option is valid and defines the HCI's
1647
logic.  The Transport Layer is decided by the machine type.  Currently
1648
the machines @code{n800} and @code{n810} have one HCI and all other
1649
machines have none.
1650

    
1651
@anchor{bt-hcis}
1652
The following three types are recognized:
1653

    
1654
@table @option
1655
@item -bt hci,null
1656
(default) The corresponding Bluetooth HCI assumes no internal logic
1657
and will not respond to any HCI commands or emit events.
1658

    
1659
@item -bt hci,host[:@var{id}]
1660
(@code{bluez} only) The corresponding HCI passes commands / events
1661
to / from the physical HCI identified by the name @var{id} (default:
1662
@code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1663
capable systems like Linux.
1664

    
1665
@item -bt hci[,vlan=@var{n}]
1666
Add a virtual, standard HCI that will participate in the Bluetooth
1667
scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1668
VLANs, devices inside a bluetooth network @var{n} can only communicate
1669
with other devices in the same network (scatternet).
1670
@end table
1671

    
1672
@item -bt vhci[,vlan=@var{n}]
1673
(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1674
to the host bluetooth stack instead of to the emulated target.  This
1675
allows the host and target machines to participate in a common scatternet
1676
and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1677
be used as following:
1678

    
1679
@example
1680
qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1681
@end example
1682

    
1683
@item -bt device:@var{dev}[,vlan=@var{n}]
1684
Emulate a bluetooth device @var{dev} and place it in network @var{n}
1685
(default @code{0}).  QEMU can only emulate one type of bluetooth devices
1686
currently:
1687

    
1688
@table @option
1689
@item keyboard
1690
Virtual wireless keyboard implementing the HIDP bluetooth profile.
1691
@end table
1692
@end table
1693
ETEXI
1694

    
1695
DEFHEADING()
1696

    
1697
DEFHEADING(Linux/Multiboot boot specific:)
1698
STEXI
1699

    
1700
When using these options, you can use a given Linux or Multiboot
1701
kernel without installing it in the disk image. It can be useful
1702
for easier testing of various kernels.
1703

    
1704
@table @option
1705
ETEXI
1706

    
1707
DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1708
    "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
1709
STEXI
1710
@item -kernel @var{bzImage}
1711
@findex -kernel
1712
Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1713
or in multiboot format.
1714
ETEXI
1715

    
1716
DEF("append", HAS_ARG, QEMU_OPTION_append, \
1717
    "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
1718
STEXI
1719
@item -append @var{cmdline}
1720
@findex -append
1721
Use @var{cmdline} as kernel command line
1722
ETEXI
1723

    
1724
DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1725
           "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
1726
STEXI
1727
@item -initrd @var{file}
1728
@findex -initrd
1729
Use @var{file} as initial ram disk.
1730

    
1731
@item -initrd "@var{file1} arg=foo,@var{file2}"
1732

    
1733
This syntax is only available with multiboot.
1734

    
1735
Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
1736
first module.
1737
ETEXI
1738

    
1739
STEXI
1740
@end table
1741
ETEXI
1742

    
1743
DEFHEADING()
1744

    
1745
DEFHEADING(Debug/Expert options:)
1746

    
1747
STEXI
1748
@table @option
1749
ETEXI
1750

    
1751
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1752
    "-serial dev     redirect the serial port to char device 'dev'\n",
1753
    QEMU_ARCH_ALL)
1754
STEXI
1755
@item -serial @var{dev}
1756
@findex -serial
1757
Redirect the virtual serial port to host character device
1758
@var{dev}. The default device is @code{vc} in graphical mode and
1759
@code{stdio} in non graphical mode.
1760

    
1761
This option can be used several times to simulate up to 4 serial
1762
ports.
1763

    
1764
Use @code{-serial none} to disable all serial ports.
1765

    
1766
Available character devices are:
1767
@table @option
1768
@item vc[:@var{W}x@var{H}]
1769
Virtual console. Optionally, a width and height can be given in pixel with
1770
@example
1771
vc:800x600
1772
@end example
1773
It is also possible to specify width or height in characters:
1774
@example
1775
vc:80Cx24C
1776
@end example
1777
@item pty
1778
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
1779
@item none
1780
No device is allocated.
1781
@item null
1782
void device
1783
@item /dev/XXX
1784
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
1785
parameters are set according to the emulated ones.
1786
@item /dev/parport@var{N}
1787
[Linux only, parallel port only] Use host parallel port
1788
@var{N}. Currently SPP and EPP parallel port features can be used.
1789
@item file:@var{filename}
1790
Write output to @var{filename}. No character can be read.
1791
@item stdio
1792
[Unix only] standard input/output
1793
@item pipe:@var{filename}
1794
name pipe @var{filename}
1795
@item COM@var{n}
1796
[Windows only] Use host serial port @var{n}
1797
@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
1798
This implements UDP Net Console.
1799
When @var{remote_host} or @var{src_ip} are not specified
1800
they default to @code{0.0.0.0}.
1801
When not using a specified @var{src_port} a random port is automatically chosen.
1802

    
1803
If you just want a simple readonly console you can use @code{netcat} or
1804
@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
1805
@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
1806
will appear in the netconsole session.
1807

    
1808
If you plan to send characters back via netconsole or you want to stop
1809
and start qemu a lot of times, you should have qemu use the same
1810
source port each time by using something like @code{-serial
1811
udp::4555@@:4556} to qemu. Another approach is to use a patched
1812
version of netcat which can listen to a TCP port and send and receive
1813
characters via udp.  If you have a patched version of netcat which
1814
activates telnet remote echo and single char transfer, then you can
1815
use the following options to step up a netcat redirector to allow
1816
telnet on port 5555 to access the qemu port.
1817
@table @code
1818
@item Qemu Options:
1819
-serial udp::4555@@:4556
1820
@item netcat options:
1821
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
1822
@item telnet options:
1823
localhost 5555
1824
@end table
1825

    
1826
@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
1827
The TCP Net Console has two modes of operation.  It can send the serial
1828
I/O to a location or wait for a connection from a location.  By default
1829
the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
1830
the @var{server} option QEMU will wait for a client socket application
1831
to connect to the port before continuing, unless the @code{nowait}
1832
option was specified.  The @code{nodelay} option disables the Nagle buffering
1833
algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
1834
one TCP connection at a time is accepted. You can use @code{telnet} to
1835
connect to the corresponding character device.
1836
@table @code
1837
@item Example to send tcp console to 192.168.0.2 port 4444
1838
-serial tcp:192.168.0.2:4444
1839
@item Example to listen and wait on port 4444 for connection
1840
-serial tcp::4444,server
1841
@item Example to not wait and listen on ip 192.168.0.100 port 4444
1842
-serial tcp:192.168.0.100:4444,server,nowait
1843
@end table
1844

    
1845
@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
1846
The telnet protocol is used instead of raw tcp sockets.  The options
1847
work the same as if you had specified @code{-serial tcp}.  The
1848
difference is that the port acts like a telnet server or client using
1849
telnet option negotiation.  This will also allow you to send the
1850
MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
1851
sequence.  Typically in unix telnet you do it with Control-] and then
1852
type "send break" followed by pressing the enter key.
1853

    
1854
@item unix:@var{path}[,server][,nowait]
1855
A unix domain socket is used instead of a tcp socket.  The option works the
1856
same as if you had specified @code{-serial tcp} except the unix domain socket
1857
@var{path} is used for connections.
1858

    
1859
@item mon:@var{dev_string}
1860
This is a special option to allow the monitor to be multiplexed onto
1861
another serial port.  The monitor is accessed with key sequence of
1862
@key{Control-a} and then pressing @key{c}. See monitor access
1863
@ref{pcsys_keys} in the -nographic section for more keys.
1864
@var{dev_string} should be any one of the serial devices specified
1865
above.  An example to multiplex the monitor onto a telnet server
1866
listening on port 4444 would be:
1867
@table @code
1868
@item -serial mon:telnet::4444,server,nowait
1869
@end table
1870

    
1871
@item braille
1872
Braille device.  This will use BrlAPI to display the braille output on a real
1873
or fake device.
1874

    
1875
@item msmouse
1876
Three button serial mouse. Configure the guest to use Microsoft protocol.
1877
@end table
1878
ETEXI
1879

    
1880
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
1881
    "-parallel dev   redirect the parallel port to char device 'dev'\n",
1882
    QEMU_ARCH_ALL)
1883
STEXI
1884
@item -parallel @var{dev}
1885
@findex -parallel
1886
Redirect the virtual parallel port to host device @var{dev} (same
1887
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1888
be used to use hardware devices connected on the corresponding host
1889
parallel port.
1890

    
1891
This option can be used several times to simulate up to 3 parallel
1892
ports.
1893

    
1894
Use @code{-parallel none} to disable all parallel ports.
1895
ETEXI
1896

    
1897
DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
1898
    "-monitor dev    redirect the monitor to char device 'dev'\n",
1899
    QEMU_ARCH_ALL)
1900
STEXI
1901
@item -monitor @var{dev}
1902
@findex -monitor
1903
Redirect the monitor to host device @var{dev} (same devices as the
1904
serial port).
1905
The default device is @code{vc} in graphical mode and @code{stdio} in
1906
non graphical mode.
1907
ETEXI
1908
DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
1909
    "-qmp dev        like -monitor but opens in 'control' mode\n",
1910
    QEMU_ARCH_ALL)
1911
STEXI
1912
@item -qmp @var{dev}
1913
@findex -qmp
1914
Like -monitor but opens in 'control' mode.
1915
ETEXI
1916

    
1917
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
1918
    "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
1919
STEXI
1920
@item -mon chardev=[name][,mode=readline|control][,default]
1921
@findex -mon
1922
Setup monitor on chardev @var{name}.
1923
ETEXI
1924

    
1925
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
1926
    "-debugcon dev   redirect the debug console to char device 'dev'\n",
1927
    QEMU_ARCH_ALL)
1928
STEXI
1929
@item -debugcon @var{dev}
1930
@findex -debugcon
1931
Redirect the debug console to host device @var{dev} (same devices as the
1932
serial port).  The debug console is an I/O port which is typically port
1933
0xe9; writing to that I/O port sends output to this device.
1934
The default device is @code{vc} in graphical mode and @code{stdio} in
1935
non graphical mode.
1936
ETEXI
1937

    
1938
DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
1939
    "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
1940
STEXI
1941
@item -pidfile @var{file}
1942
@findex -pidfile
1943
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
1944
from a script.
1945
ETEXI
1946

    
1947
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
1948
    "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
1949
STEXI
1950
@item -singlestep
1951
@findex -singlestep
1952
Run the emulation in single step mode.
1953
ETEXI
1954

    
1955
DEF("S", 0, QEMU_OPTION_S, \
1956
    "-S              freeze CPU at startup (use 'c' to start execution)\n",
1957
    QEMU_ARCH_ALL)
1958
STEXI
1959
@item -S
1960
@findex -S
1961
Do not start CPU at startup (you must type 'c' in the monitor).
1962
ETEXI
1963

    
1964
DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
1965
    "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
1966
STEXI
1967
@item -gdb @var{dev}
1968
@findex -gdb
1969
Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
1970
connections will likely be TCP-based, but also UDP, pseudo TTY, or even
1971
stdio are reasonable use case. The latter is allowing to start qemu from
1972
within gdb and establish the connection via a pipe:
1973
@example
1974
(gdb) target remote | exec qemu -gdb stdio ...
1975
@end example
1976
ETEXI
1977

    
1978
DEF("s", 0, QEMU_OPTION_s, \
1979
    "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
1980
    QEMU_ARCH_ALL)
1981
STEXI
1982
@item -s
1983
@findex -s
1984
Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
1985
(@pxref{gdb_usage}).
1986
ETEXI
1987

    
1988
DEF("d", HAS_ARG, QEMU_OPTION_d, \
1989
    "-d item1,...    output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
1990
    QEMU_ARCH_ALL)
1991
STEXI
1992
@item -d
1993
@findex -d
1994
Output log in /tmp/qemu.log
1995
ETEXI
1996

    
1997
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
1998
    "-hdachs c,h,s[,t]\n" \
1999
    "                force hard disk 0 physical geometry and the optional BIOS\n" \
2000
    "                translation (t=none or lba) (usually qemu can guess them)\n",
2001
    QEMU_ARCH_ALL)
2002
STEXI
2003
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
2004
@findex -hdachs
2005
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
2006
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
2007
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
2008
all those parameters. This option is useful for old MS-DOS disk
2009
images.
2010
ETEXI
2011

    
2012
DEF("L", HAS_ARG, QEMU_OPTION_L, \
2013
    "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
2014
    QEMU_ARCH_ALL)
2015
STEXI
2016
@item -L  @var{path}
2017
@findex -L
2018
Set the directory for the BIOS, VGA BIOS and keymaps.
2019
ETEXI
2020

    
2021
DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2022
    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
2023
STEXI
2024
@item -bios @var{file}
2025
@findex -bios
2026
Set the filename for the BIOS.
2027
ETEXI
2028

    
2029
DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2030
    "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2031
STEXI
2032
@item -enable-kvm
2033
@findex -enable-kvm
2034
Enable KVM full virtualization support. This option is only available
2035
if KVM support is enabled when compiling.
2036
ETEXI
2037

    
2038
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
2039
    "-machine accel=accel1[:accel2]    use an accelerator (kvm,xen,tcg), default is tcg\n", QEMU_ARCH_ALL)
2040
STEXI
2041
@item -machine accel=@var{accels}
2042
@findex -machine
2043
This is use to enable an accelerator, in kvm,xen,tcg.
2044
By default, it use only tcg. If there a more than one accelerator
2045
specified, the next one is used if the first don't work.
2046
ETEXI
2047

    
2048
DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2049
    "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
2050
DEF("xen-create", 0, QEMU_OPTION_xen_create,
2051
    "-xen-create     create domain using xen hypercalls, bypassing xend\n"
2052
    "                warning: should not be used when xend is in use\n",
2053
    QEMU_ARCH_ALL)
2054
DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2055
    "-xen-attach     attach to existing xen domain\n"
2056
    "                xend will use this when starting qemu\n",
2057
    QEMU_ARCH_ALL)
2058
STEXI
2059
@item -xen-domid @var{id}
2060
@findex -xen-domid
2061
Specify xen guest domain @var{id} (XEN only).
2062
@item -xen-create
2063
@findex -xen-create
2064
Create domain using xen hypercalls, bypassing xend.
2065
Warning: should not be used when xend is in use (XEN only).
2066
@item -xen-attach
2067
@findex -xen-attach
2068
Attach to existing xen domain.
2069
xend will use this when starting qemu (XEN only).
2070
ETEXI
2071

    
2072
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
2073
    "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
2074
STEXI
2075
@item -no-reboot
2076
@findex -no-reboot
2077
Exit instead of rebooting.
2078
ETEXI
2079

    
2080
DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
2081
    "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
2082
STEXI
2083
@item -no-shutdown
2084
@findex -no-shutdown
2085
Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2086
This allows for instance switching to monitor to commit changes to the
2087
disk image.
2088
ETEXI
2089

    
2090
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2091
    "-loadvm [tag|id]\n" \
2092
    "                start right away with a saved state (loadvm in monitor)\n",
2093
    QEMU_ARCH_ALL)
2094
STEXI
2095
@item -loadvm @var{file}
2096
@findex -loadvm
2097
Start right away with a saved state (@code{loadvm} in monitor)
2098
ETEXI
2099

    
2100
#ifndef _WIN32
2101
DEF("daemonize", 0, QEMU_OPTION_daemonize, \
2102
    "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
2103
#endif
2104
STEXI
2105
@item -daemonize
2106
@findex -daemonize
2107
Daemonize the QEMU process after initialization.  QEMU will not detach from
2108
standard IO until it is ready to receive connections on any of its devices.
2109
This option is a useful way for external programs to launch QEMU without having
2110
to cope with initialization race conditions.
2111
ETEXI
2112

    
2113
DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
2114
    "-option-rom rom load a file, rom, into the option ROM space\n",
2115
    QEMU_ARCH_ALL)
2116
STEXI
2117
@item -option-rom @var{file}
2118
@findex -option-rom
2119
Load the contents of @var{file} as an option ROM.
2120
This option is useful to load things like EtherBoot.
2121
ETEXI
2122

    
2123
DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
2124
    "-clock          force the use of the given methods for timer alarm.\n" \
2125
    "                To see what timers are available use -clock ?\n",
2126
    QEMU_ARCH_ALL)
2127
STEXI
2128
@item -clock @var{method}
2129
@findex -clock
2130
Force the use of the given methods for timer alarm. To see what timers
2131
are available use -clock ?.
2132
ETEXI
2133

    
2134
HXCOMM Options deprecated by -rtc
2135
DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
2136
DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
2137

    
2138
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
2139
    "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
2140
    "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
2141
    QEMU_ARCH_ALL)
2142

    
2143
STEXI
2144

    
2145
@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
2146
@findex -rtc
2147
Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
2148
UTC or local time, respectively. @code{localtime} is required for correct date in
2149
MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
2150
format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
2151

    
2152
By default the RTC is driven by the host system time. This allows to use the
2153
RTC as accurate reference clock inside the guest, specifically if the host
2154
time is smoothly following an accurate external reference clock, e.g. via NTP.
2155
If you want to isolate the guest time from the host, even prevent it from
2156
progressing during suspension, you can set @option{clock} to @code{vm} instead.
2157

    
2158
Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
2159
specifically with Windows' ACPI HAL. This option will try to figure out how
2160
many timer interrupts were not processed by the Windows guest and will
2161
re-inject them.
2162
ETEXI
2163

    
2164
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
2165
    "-icount [N|auto]\n" \
2166
    "                enable virtual instruction counter with 2^N clock ticks per\n" \
2167
    "                instruction\n", QEMU_ARCH_ALL)
2168
STEXI
2169
@item -icount [@var{N}|auto]
2170
@findex -icount
2171
Enable virtual instruction counter.  The virtual cpu will execute one
2172
instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
2173
then the virtual cpu speed will be automatically adjusted to keep virtual
2174
time within a few seconds of real time.
2175

    
2176
Note that while this option can give deterministic behavior, it does not
2177
provide cycle accurate emulation.  Modern CPUs contain superscalar out of
2178
order cores with complex cache hierarchies.  The number of instructions
2179
executed often has little or no correlation with actual performance.
2180
ETEXI
2181

    
2182
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
2183
    "-watchdog i6300esb|ib700\n" \
2184
    "                enable virtual hardware watchdog [default=none]\n",
2185
    QEMU_ARCH_ALL)
2186
STEXI
2187
@item -watchdog @var{model}
2188
@findex -watchdog
2189
Create a virtual hardware watchdog device.  Once enabled (by a guest
2190
action), the watchdog must be periodically polled by an agent inside
2191
the guest or else the guest will be restarted.
2192

    
2193
The @var{model} is the model of hardware watchdog to emulate.  Choices
2194
for model are: @code{ib700} (iBASE 700) which is a very simple ISA
2195
watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
2196
controller hub) which is a much more featureful PCI-based dual-timer
2197
watchdog.  Choose a model for which your guest has drivers.
2198

    
2199
Use @code{-watchdog ?} to list available hardware models.  Only one
2200
watchdog can be enabled for a guest.
2201
ETEXI
2202

    
2203
DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
2204
    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
2205
    "                action when watchdog fires [default=reset]\n",
2206
    QEMU_ARCH_ALL)
2207
STEXI
2208
@item -watchdog-action @var{action}
2209

    
2210
The @var{action} controls what QEMU will do when the watchdog timer
2211
expires.
2212
The default is
2213
@code{reset} (forcefully reset the guest).
2214
Other possible actions are:
2215
@code{shutdown} (attempt to gracefully shutdown the guest),
2216
@code{poweroff} (forcefully poweroff the guest),
2217
@code{pause} (pause the guest),
2218
@code{debug} (print a debug message and continue), or
2219
@code{none} (do nothing).
2220

    
2221
Note that the @code{shutdown} action requires that the guest responds
2222
to ACPI signals, which it may not be able to do in the sort of
2223
situations where the watchdog would have expired, and thus
2224
@code{-watchdog-action shutdown} is not recommended for production use.
2225

    
2226
Examples:
2227

    
2228
@table @code
2229
@item -watchdog i6300esb -watchdog-action pause
2230
@item -watchdog ib700
2231
@end table
2232
ETEXI
2233

    
2234
DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
2235
    "-echr chr       set terminal escape character instead of ctrl-a\n",
2236
    QEMU_ARCH_ALL)
2237
STEXI
2238

    
2239
@item -echr @var{numeric_ascii_value}
2240
@findex -echr
2241
Change the escape character used for switching to the monitor when using
2242
monitor and serial sharing.  The default is @code{0x01} when using the
2243
@code{-nographic} option.  @code{0x01} is equal to pressing
2244
@code{Control-a}.  You can select a different character from the ascii
2245
control keys where 1 through 26 map to Control-a through Control-z.  For
2246
instance you could use the either of the following to change the escape
2247
character to Control-t.
2248
@table @code
2249
@item -echr 0x14
2250
@item -echr 20
2251
@end table
2252
ETEXI
2253

    
2254
DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
2255
    "-virtioconsole c\n" \
2256
    "                set virtio console\n", QEMU_ARCH_ALL)
2257
STEXI
2258
@item -virtioconsole @var{c}
2259
@findex -virtioconsole
2260
Set virtio console.
2261

    
2262
This option is maintained for backward compatibility.
2263

    
2264
Please use @code{-device virtconsole} for the new way of invocation.
2265
ETEXI
2266

    
2267
DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
2268
    "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
2269
STEXI
2270
@item -show-cursor
2271
@findex -show-cursor
2272
Show cursor.
2273
ETEXI
2274

    
2275
DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
2276
    "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
2277
STEXI
2278
@item -tb-size @var{n}
2279
@findex -tb-size
2280
Set TB size.
2281
ETEXI
2282

    
2283
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
2284
    "-incoming p     prepare for incoming migration, listen on port p\n",
2285
    QEMU_ARCH_ALL)
2286
STEXI
2287
@item -incoming @var{port}
2288
@findex -incoming
2289
Prepare for incoming migration, listen on @var{port}.
2290
ETEXI
2291

    
2292
DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
2293
    "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
2294
STEXI
2295
@item -nodefaults
2296
@findex -nodefaults
2297
Don't create default devices.
2298
ETEXI
2299

    
2300
#ifndef _WIN32
2301
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
2302
    "-chroot dir     chroot to dir just before starting the VM\n",
2303
    QEMU_ARCH_ALL)
2304
#endif
2305
STEXI
2306
@item -chroot @var{dir}
2307
@findex -chroot
2308
Immediately before starting guest execution, chroot to the specified
2309
directory.  Especially useful in combination with -runas.
2310
ETEXI
2311

    
2312
#ifndef _WIN32
2313
DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2314
    "-runas user     change to user id user just before starting the VM\n",
2315
    QEMU_ARCH_ALL)
2316
#endif
2317
STEXI
2318
@item -runas @var{user}
2319
@findex -runas
2320
Immediately before starting guest execution, drop root privileges, switching
2321
to the specified user.
2322
ETEXI
2323

    
2324
DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
2325
    "-prom-env variable=value\n"
2326
    "                set OpenBIOS nvram variables\n",
2327
    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
2328
STEXI
2329
@item -prom-env @var{variable}=@var{value}
2330
@findex -prom-env
2331
Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
2332
ETEXI
2333
DEF("semihosting", 0, QEMU_OPTION_semihosting,
2334
    "-semihosting    semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K)
2335
STEXI
2336
@item -semihosting
2337
@findex -semihosting
2338
Semihosting mode (ARM, M68K only).
2339
ETEXI
2340
DEF("old-param", 0, QEMU_OPTION_old_param,
2341
    "-old-param      old param mode\n", QEMU_ARCH_ARM)
2342
STEXI
2343
@item -old-param
2344
@findex -old-param (ARM)
2345
Old param mode (ARM only).
2346
ETEXI
2347

    
2348
DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2349
    "-readconfig <file>\n", QEMU_ARCH_ALL)
2350
STEXI
2351
@item -readconfig @var{file}
2352
@findex -readconfig
2353
Read device configuration from @var{file}.
2354
ETEXI
2355
DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2356
    "-writeconfig <file>\n"
2357
    "                read/write config file\n", QEMU_ARCH_ALL)
2358
STEXI
2359
@item -writeconfig @var{file}
2360
@findex -writeconfig
2361
Write device configuration to @var{file}.
2362
ETEXI
2363
DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2364
    "-nodefconfig\n"
2365
    "                do not load default config files at startup\n",
2366
    QEMU_ARCH_ALL)
2367
STEXI
2368
@item -nodefconfig
2369
@findex -nodefconfig
2370
Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2371
@var{sysconfdir}/target-@var{ARCH}.conf on startup.  The @code{-nodefconfig}
2372
option will prevent QEMU from loading these configuration files at startup.
2373
ETEXI
2374
#ifdef CONFIG_SIMPLE_TRACE
2375
DEF("trace", HAS_ARG, QEMU_OPTION_trace,
2376
    "-trace\n"
2377
    "                Specify a trace file to log traces to\n",
2378
    QEMU_ARCH_ALL)
2379
STEXI
2380
@item -trace
2381
@findex -trace
2382
Specify a trace file to log output traces to.
2383
ETEXI
2384
#endif
2385

    
2386
HXCOMM This is the last statement. Insert new options before this line!
2387
STEXI
2388
@end table
2389
ETEXI