Statistics
| Branch: | Revision:

root / qemu-options.hx @ 9052ea6b

History | View | Annotate | Download (83.6 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
@item werror=@var{action},rerror=@var{action}
164
Specify which @var{action} to take on write and read errors. Valid actions are:
165
"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
166
"report" (report the error to the guest), "enospc" (pause QEMU only if the
167
host disk is full; report the error to the guest otherwise).
168
The default setting is @option{werror=enospc} and @option{rerror=report}.
169
@item readonly
170
Open drive @option{file} as read-only. Guest write attempts will fail.
171
@end table
172

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

    
178
Writeback caching will report data writes as completed as soon as the data is
179
present in the host page cache.  This is safe as long as you trust your host.
180
If your host crashes or loses power, then the guest may experience data
181
corruption.
182

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

    
187
Some block drivers perform badly with @option{cache=writethrough}, most notably,
188
qcow2.  If performance is more important than correctness,
189
@option{cache=writeback} should be used with qcow2.
190

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

    
198
Instead of @option{-cdrom} you can use:
199
@example
200
qemu -drive file=file,index=2,media=cdrom
201
@end example
202

    
203
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
204
use:
205
@example
206
qemu -drive file=file,index=0,media=disk
207
qemu -drive file=file,index=1,media=disk
208
qemu -drive file=file,index=2,media=disk
209
qemu -drive file=file,index=3,media=disk
210
@end example
211

    
212
You can connect a CDROM to the slave of ide0:
213
@example
214
qemu -drive file=file,if=ide,index=1,media=cdrom
215
@end example
216

    
217
If you don't specify the "file=" argument, you define an empty drive:
218
@example
219
qemu -drive if=ide,index=1,media=cdrom
220
@end example
221

    
222
You can connect a SCSI disk with unit ID 6 on the bus #0:
223
@example
224
qemu -drive file=file,if=scsi,bus=0,unit=6
225
@end example
226

    
227
Instead of @option{-fda}, @option{-fdb}, you can use:
228
@example
229
qemu -drive file=file,index=0,if=floppy
230
qemu -drive file=file,index=1,if=floppy
231
@end example
232

    
233
By default, @var{interface} is "ide" and @var{index} is automatically
234
incremented:
235
@example
236
qemu -drive file=a -drive file=b"
237
@end example
238
is interpreted like:
239
@example
240
qemu -hda a -hdb b
241
@end example
242
ETEXI
243

    
244
DEF("set", HAS_ARG, QEMU_OPTION_set,
245
    "-set group.id.arg=value\n"
246
    "                set <arg> parameter for item <id> of type <group>\n"
247
    "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
248
STEXI
249
@item -set
250
@findex -set
251
TODO
252
ETEXI
253

    
254
DEF("global", HAS_ARG, QEMU_OPTION_global,
255
    "-global driver.property=value\n"
256
    "                set a global default for a driver property\n",
257
    QEMU_ARCH_ALL)
258
STEXI
259
@item -global
260
@findex -global
261
TODO
262
ETEXI
263

    
264
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
265
    "-mtdblock file  use 'file' as on-board Flash memory image\n",
266
    QEMU_ARCH_ALL)
267
STEXI
268
@item -mtdblock @var{file}
269
@findex -mtdblock
270
Use @var{file} as on-board Flash memory image.
271
ETEXI
272

    
273
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
274
    "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
275
STEXI
276
@item -sd @var{file}
277
@findex -sd
278
Use @var{file} as SecureDigital card image.
279
ETEXI
280

    
281
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
282
    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
283
STEXI
284
@item -pflash @var{file}
285
@findex -pflash
286
Use @var{file} as a parallel flash image.
287
ETEXI
288

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

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

    
306
@example
307
# try to boot from network first, then from hard disk
308
qemu -boot order=nc
309
# boot from CD-ROM first, switch back to default order after reboot
310
qemu -boot once=d
311
@end example
312

    
313
Note: The legacy format '-boot @var{drives}' is still supported but its
314
use is discouraged as it may be removed from future versions.
315
ETEXI
316

    
317
DEF("snapshot", 0, QEMU_OPTION_snapshot,
318
    "-snapshot       write to temporary files instead of disk image files\n",
319
    QEMU_ARCH_ALL)
320
STEXI
321
@item -snapshot
322
@findex -snapshot
323
Write to temporary files instead of disk image files. In this case,
324
the raw disk image you use is not written back. You can however force
325
the write back by pressing @key{C-a s} (@pxref{disk_images}).
326
ETEXI
327

    
328
DEF("m", HAS_ARG, QEMU_OPTION_m,
329
    "-m megs         set virtual RAM size to megs MB [default="
330
    stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL)
331
STEXI
332
@item -m @var{megs}
333
@findex -m
334
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
335
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
336
gigabytes respectively.
337
ETEXI
338

    
339
DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
340
    "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
341
STEXI
342
@item -mem-path @var{path}
343
Allocate guest RAM from a temporarily created file in @var{path}.
344
ETEXI
345

    
346
#ifdef MAP_POPULATE
347
DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
348
    "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
349
    QEMU_ARCH_ALL)
350
STEXI
351
@item -mem-prealloc
352
Preallocate memory when using -mem-path.
353
ETEXI
354
#endif
355

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

    
368
The available layouts are:
369
@example
370
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
371
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
372
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
373
@end example
374

    
375
The default is @code{en-us}.
376
ETEXI
377

    
378

    
379
DEF("audio-help", 0, QEMU_OPTION_audio_help,
380
    "-audio-help     print list of audio drivers and their options\n",
381
    QEMU_ARCH_ALL)
382
STEXI
383
@item -audio-help
384
@findex -audio-help
385
Will show the audio subsystem help: list of drivers, tunable
386
parameters.
387
ETEXI
388

    
389
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
390
    "-soundhw c1,... enable audio support\n"
391
    "                and only specified sound cards (comma separated list)\n"
392
    "                use -soundhw ? to get the list of supported cards\n"
393
    "                use -soundhw all to enable all of them\n", QEMU_ARCH_ALL)
394
STEXI
395
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
396
@findex -soundhw
397
Enable audio and selected sound hardware. Use ? to print all
398
available sound hardware.
399

    
400
@example
401
qemu -soundhw sb16,adlib disk.img
402
qemu -soundhw es1370 disk.img
403
qemu -soundhw ac97 disk.img
404
qemu -soundhw hda disk.img
405
qemu -soundhw all disk.img
406
qemu -soundhw ?
407
@end example
408

    
409
Note that Linux's i810_audio OSS kernel (for AC97) module might
410
require manually specifying clocking.
411

    
412
@example
413
modprobe i810_audio clocking=48000
414
@end example
415
ETEXI
416

    
417
STEXI
418
@end table
419
ETEXI
420

    
421
DEF("usb", 0, QEMU_OPTION_usb,
422
    "-usb            enable the USB driver (will be the default soon)\n",
423
    QEMU_ARCH_ALL)
424
STEXI
425
USB options:
426
@table @option
427

    
428
@item -usb
429
@findex -usb
430
Enable the USB driver (will be the default soon)
431
ETEXI
432

    
433
DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
434
    "-usbdevice name add the host or guest USB device 'name'\n",
435
    QEMU_ARCH_ALL)
436
STEXI
437

    
438
@item -usbdevice @var{devname}
439
@findex -usbdevice
440
Add the USB device @var{devname}. @xref{usb_devices}.
441

    
442
@table @option
443

    
444
@item mouse
445
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
446

    
447
@item tablet
448
Pointer device that uses absolute coordinates (like a touchscreen). This
449
means qemu is able to report the mouse position without having to grab the
450
mouse. Also overrides the PS/2 mouse emulation when activated.
451

    
452
@item disk:[format=@var{format}]:@var{file}
453
Mass storage device based on file. The optional @var{format} argument
454
will be used rather than detecting the format. Can be used to specifiy
455
@code{format=raw} to avoid interpreting an untrusted format header.
456

    
457
@item host:@var{bus}.@var{addr}
458
Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
459

    
460
@item host:@var{vendor_id}:@var{product_id}
461
Pass through the host device identified by @var{vendor_id}:@var{product_id}
462
(Linux only).
463

    
464
@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
465
Serial converter to host character device @var{dev}, see @code{-serial} for the
466
available devices.
467

    
468
@item braille
469
Braille device.  This will use BrlAPI to display the braille output on a real
470
or fake device.
471

    
472
@item net:@var{options}
473
Network adapter that supports CDC ethernet and RNDIS protocols.
474

    
475
@end table
476
ETEXI
477

    
478
DEF("device", HAS_ARG, QEMU_OPTION_device,
479
    "-device driver[,prop[=value][,...]]\n"
480
    "                add device (based on driver)\n"
481
    "                prop=value,... sets driver properties\n"
482
    "                use -device ? to print all possible drivers\n"
483
    "                use -device driver,? to print all possible properties\n",
484
    QEMU_ARCH_ALL)
485
STEXI
486
@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
487
@findex -device
488
Add device @var{driver}.  @var{prop}=@var{value} sets driver
489
properties.  Valid properties depend on the driver.  To get help on
490
possible drivers and properties, use @code{-device ?} and
491
@code{-device @var{driver},?}.
492
ETEXI
493

    
494
DEFHEADING(File system options:)
495

    
496
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
497
    "-fsdev local,id=id,path=path,security_model=[mapped|passthrough|none]\n",
498
    QEMU_ARCH_ALL)
499

    
500
STEXI
501

    
502
The general form of a File system device option is:
503
@table @option
504

    
505
@item -fsdev @var{fstype} ,id=@var{id} [,@var{options}]
506
@findex -fsdev
507
Fstype is one of:
508
@option{local},
509
The specific Fstype will determine the applicable options.
510

    
511
Options to each backend are described below.
512

    
513
@item -fsdev local ,id=@var{id} ,path=@var{path} ,security_model=@var{security_model}
514

    
515
Create a file-system-"device" for local-filesystem.
516

    
517
@option{local} is only available on Linux.
518

    
519
@option{path} specifies the path to be exported. @option{path} is required.
520

    
521
@option{security_model} specifies the security model to be followed.
522
@option{security_model} is required.
523

    
524
@end table
525
ETEXI
526

    
527
DEFHEADING(Virtual File system pass-through options:)
528

    
529
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
530
    "-virtfs local,path=path,mount_tag=tag,security_model=[mapped|passthrough|none]\n",
531
    QEMU_ARCH_ALL)
532

    
533
STEXI
534

    
535
The general form of a Virtual File system pass-through option is:
536
@table @option
537

    
538
@item -virtfs @var{fstype} [,@var{options}]
539
@findex -virtfs
540
Fstype is one of:
541
@option{local},
542
The specific Fstype will determine the applicable options.
543

    
544
Options to each backend are described below.
545

    
546
@item -virtfs local ,path=@var{path} ,mount_tag=@var{mount_tag} ,security_model=@var{security_model}
547

    
548
Create a Virtual file-system-pass through for local-filesystem.
549

    
550
@option{local} is only available on Linux.
551

    
552
@option{path} specifies the path to be exported. @option{path} is required.
553

    
554
@option{security_model} specifies the security model to be followed.
555
@option{security_model} is required.
556

    
557

    
558
@option{mount_tag} specifies the tag with which the exported file is mounted.
559
@option{mount_tag} is required.
560

    
561
@end table
562
ETEXI
563

    
564
DEFHEADING()
565

    
566
DEF("name", HAS_ARG, QEMU_OPTION_name,
567
    "-name string1[,process=string2]\n"
568
    "                set the name of the guest\n"
569
    "                string1 sets the window title and string2 the process name (on Linux)\n",
570
    QEMU_ARCH_ALL)
571
STEXI
572
@item -name @var{name}
573
@findex -name
574
Sets the @var{name} of the guest.
575
This name will be displayed in the SDL window caption.
576
The @var{name} will also be used for the VNC server.
577
Also optionally set the top visible process name in Linux.
578
ETEXI
579

    
580
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
581
    "-uuid %08x-%04x-%04x-%04x-%012x\n"
582
    "                specify machine UUID\n", QEMU_ARCH_ALL)
583
STEXI
584
@item -uuid @var{uuid}
585
@findex -uuid
586
Set system UUID.
587
ETEXI
588

    
589
STEXI
590
@end table
591
ETEXI
592

    
593
DEFHEADING()
594

    
595
DEFHEADING(Display options:)
596

    
597
STEXI
598
@table @option
599
ETEXI
600

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

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

    
645
DEF("curses", 0, QEMU_OPTION_curses,
646
    "-curses         use a curses/ncurses interface instead of SDL\n",
647
    QEMU_ARCH_ALL)
648
STEXI
649
@item -curses
650
@findex curses
651
Normally, QEMU uses SDL to display the VGA output.  With this option,
652
QEMU can display the VGA output when in text mode using a
653
curses/ncurses interface.  Nothing is displayed in graphical mode.
654
ETEXI
655

    
656
DEF("no-frame", 0, QEMU_OPTION_no_frame,
657
    "-no-frame       open SDL window without a frame and window decorations\n",
658
    QEMU_ARCH_ALL)
659
STEXI
660
@item -no-frame
661
@findex -no-frame
662
Do not use decorations for SDL windows and start them using the whole
663
available screen space. This makes the using QEMU in a dedicated desktop
664
workspace more convenient.
665
ETEXI
666

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

    
677
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
678
    "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
679
    QEMU_ARCH_ALL)
680
STEXI
681
@item -ctrl-grab
682
@findex -ctrl-grab
683
Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
684
affects the special keys (for fullscreen, monitor-mode switching, etc).
685
ETEXI
686

    
687
DEF("no-quit", 0, QEMU_OPTION_no_quit,
688
    "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
689
STEXI
690
@item -no-quit
691
@findex -no-quit
692
Disable SDL window close capability.
693
ETEXI
694

    
695
DEF("sdl", 0, QEMU_OPTION_sdl,
696
    "-sdl            enable SDL\n", QEMU_ARCH_ALL)
697
STEXI
698
@item -sdl
699
@findex -sdl
700
Enable SDL.
701
ETEXI
702

    
703
DEF("spice", HAS_ARG, QEMU_OPTION_spice,
704
    "-spice <args>   enable spice\n", QEMU_ARCH_ALL)
705
STEXI
706
@item -spice @var{option}[,@var{option}[,...]]
707
@findex -spice
708
Enable the spice remote desktop protocol. Valid options are
709

    
710
@table @option
711

    
712
@item port=<nr>
713
Set the TCP port spice is listening on for plaintext channels.
714

    
715
@item addr=<addr>
716
Set the IP address spice is listening on.  Default is any address.
717

    
718
@item ipv4
719
@item ipv6
720
Force using the specified IP version.
721

    
722
@item password=<secret>
723
Set the password you need to authenticate.
724

    
725
@item sasl
726
Require that the client use SASL to authenticate with the spice.
727
The exact choice of authentication method used is controlled from the
728
system / user's SASL configuration file for the 'qemu' service. This
729
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
730
unprivileged user, an environment variable SASL_CONF_PATH can be used
731
to make it search alternate locations for the service config.
732
While some SASL auth methods can also provide data encryption (eg GSSAPI),
733
it is recommended that SASL always be combined with the 'tls' and
734
'x509' settings to enable use of SSL and server certificates. This
735
ensures a data encryption preventing compromise of authentication
736
credentials.
737

    
738
@item disable-ticketing
739
Allow client connects without authentication.
740

    
741
@item disable-copy-paste
742
Disable copy paste between the client and the guest.
743

    
744
@item tls-port=<nr>
745
Set the TCP port spice is listening on for encrypted channels.
746

    
747
@item x509-dir=<dir>
748
Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
749

    
750
@item x509-key-file=<file>
751
@item x509-key-password=<file>
752
@item x509-cert-file=<file>
753
@item x509-cacert-file=<file>
754
@item x509-dh-key-file=<file>
755
The x509 file names can also be configured individually.
756

    
757
@item tls-ciphers=<list>
758
Specify which ciphers to use.
759

    
760
@item tls-channel=[main|display|inputs|record|playback|tunnel]
761
@item plaintext-channel=[main|display|inputs|record|playback|tunnel]
762
Force specific channel to be used with or without TLS encryption.  The
763
options can be specified multiple times to configure multiple
764
channels.  The special name "default" can be used to set the default
765
mode.  For channels which are not explicitly forced into one mode the
766
spice client is allowed to pick tls/plaintext as he pleases.
767

    
768
@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
769
Configure image compression (lossless).
770
Default is auto_glz.
771

    
772
@item jpeg-wan-compression=[auto|never|always]
773
@item zlib-glz-wan-compression=[auto|never|always]
774
Configure wan image compression (lossy for slow links).
775
Default is auto.
776

    
777
@item streaming-video=[off|all|filter]
778
Configure video stream detection.  Default is filter.
779

    
780
@item agent-mouse=[on|off]
781
Enable/disable passing mouse events via vdagent.  Default is on.
782

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

    
786
@end table
787
ETEXI
788

    
789
DEF("portrait", 0, QEMU_OPTION_portrait,
790
    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
791
    QEMU_ARCH_ALL)
792
STEXI
793
@item -portrait
794
@findex -portrait
795
Rotate graphical output 90 deg left (only PXA LCD).
796
ETEXI
797

    
798
DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
799
    "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
800
    QEMU_ARCH_ALL)
801
STEXI
802
@item -rotate
803
@findex -rotate
804
Rotate graphical output some deg left (only PXA LCD).
805
ETEXI
806

    
807
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
808
    "-vga [std|cirrus|vmware|qxl|xenfb|none]\n"
809
    "                select video card type\n", QEMU_ARCH_ALL)
810
STEXI
811
@item -vga @var{type}
812
@findex -vga
813
Select type of VGA card to emulate. Valid values for @var{type} are
814
@table @option
815
@item cirrus
816
Cirrus Logic GD5446 Video card. All Windows versions starting from
817
Windows 95 should recognize and use this graphic card. For optimal
818
performances, use 16 bit color depth in the guest and the host OS.
819
(This one is the default)
820
@item std
821
Standard VGA card with Bochs VBE extensions.  If your guest OS
822
supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
823
to use high resolution modes (>= 1280x1024x16) then you should use
824
this option.
825
@item vmware
826
VMWare SVGA-II compatible adapter. Use it if you have sufficiently
827
recent XFree86/XOrg server or Windows guest with a driver for this
828
card.
829
@item qxl
830
QXL paravirtual graphic card.  It is VGA compatible (including VESA
831
2.0 VBE support).  Works best with qxl guest drivers installed though.
832
Recommended choice when using the spice protocol.
833
@item none
834
Disable VGA card.
835
@end table
836
ETEXI
837

    
838
DEF("full-screen", 0, QEMU_OPTION_full_screen,
839
    "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
840
STEXI
841
@item -full-screen
842
@findex -full-screen
843
Start in full screen.
844
ETEXI
845

    
846
DEF("g", 1, QEMU_OPTION_g ,
847
    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
848
    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
849
STEXI
850
@item -g @var{width}x@var{height}[x@var{depth}]
851
@findex -g
852
Set the initial graphical resolution and depth (PPC, SPARC only).
853
ETEXI
854

    
855
DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
856
    "-vnc display    start a VNC server on display\n", QEMU_ARCH_ALL)
857
STEXI
858
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
859
@findex -vnc
860
Normally, QEMU uses SDL to display the VGA output.  With this option,
861
you can have QEMU listen on VNC display @var{display} and redirect the VGA
862
display over the VNC session.  It is very useful to enable the usb
863
tablet device when using this option (option @option{-usbdevice
864
tablet}). When using the VNC display, you must use the @option{-k}
865
parameter to set the keyboard layout if you are not using en-us. Valid
866
syntax for the @var{display} is
867

    
868
@table @option
869

    
870
@item @var{host}:@var{d}
871

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

    
876
@item unix:@var{path}
877

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

    
881
@item none
882

    
883
VNC is initialized but not started. The monitor @code{change} command
884
can be used to later start the VNC server.
885

    
886
@end table
887

    
888
Following the @var{display} value there may be one or more @var{option} flags
889
separated by commas. Valid options are
890

    
891
@table @option
892

    
893
@item reverse
894

    
895
Connect to a listening VNC client via a ``reverse'' connection. The
896
client is specified by the @var{display}. For reverse network
897
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
898
is a TCP port number, not a display number.
899

    
900
@item password
901

    
902
Require that password based authentication is used for client connections.
903
The password must be set separately using the @code{change} command in the
904
@ref{pcsys_monitor}
905

    
906
@item tls
907

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

    
913
@item x509=@var{/path/to/certificate/dir}
914

    
915
Valid if @option{tls} is specified. Require that x509 credentials are used
916
for negotiating the TLS session. The server will send its x509 certificate
917
to the client. It is recommended that a password be set on the VNC server
918
to provide authentication of the client when this is used. The path following
919
this option specifies where the x509 certificates are to be loaded from.
920
See the @ref{vnc_security} section for details on generating certificates.
921

    
922
@item x509verify=@var{/path/to/certificate/dir}
923

    
924
Valid if @option{tls} is specified. Require that x509 credentials are used
925
for negotiating the TLS session. The server will send its x509 certificate
926
to the client, and request that the client send its own x509 certificate.
927
The server will validate the client's certificate against the CA certificate,
928
and reject clients when validation fails. If the certificate authority is
929
trusted, this is a sufficient authentication mechanism. You may still wish
930
to set a password on the VNC server as a second authentication layer. The
931
path following this option specifies where the x509 certificates are to
932
be loaded from. See the @ref{vnc_security} section for details on generating
933
certificates.
934

    
935
@item sasl
936

    
937
Require that the client use SASL to authenticate with the VNC server.
938
The exact choice of authentication method used is controlled from the
939
system / user's SASL configuration file for the 'qemu' service. This
940
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
941
unprivileged user, an environment variable SASL_CONF_PATH can be used
942
to make it search alternate locations for the service config.
943
While some SASL auth methods can also provide data encryption (eg GSSAPI),
944
it is recommended that SASL always be combined with the 'tls' and
945
'x509' settings to enable use of SSL and server certificates. This
946
ensures a data encryption preventing compromise of authentication
947
credentials. See the @ref{vnc_security} section for details on using
948
SASL authentication.
949

    
950
@item acl
951

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

    
963
@item lossy
964

    
965
Enable lossy compression methods (gradient, JPEG, ...). If this
966
option is set, VNC client may receive lossy framebuffer updates
967
depending on its encoding settings. Enabling this option can save
968
a lot of bandwidth at the expense of quality.
969

    
970
@item non-adaptive
971

    
972
Disable adaptive encodings. Adaptive encodings are enabled by default.
973
An adaptive encoding will try to detect frequently updated screen regions,
974
and send updates in these regions using a lossy encoding (like JPEG).
975
This can be really helpful to save bandwidth when playing videos. Disabling
976
adaptive encodings allows to restore the original static behavior of encodings
977
like Tight.
978

    
979
@end table
980
ETEXI
981

    
982
STEXI
983
@end table
984
ETEXI
985

    
986
DEFHEADING()
987

    
988
DEFHEADING(i386 target only:)
989
STEXI
990
@table @option
991
ETEXI
992

    
993
DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
994
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
995
    QEMU_ARCH_I386)
996
STEXI
997
@item -win2k-hack
998
@findex -win2k-hack
999
Use it when installing Windows 2000 to avoid a disk full bug. After
1000
Windows 2000 is installed, you no longer need this option (this option
1001
slows down the IDE transfers).
1002
ETEXI
1003

    
1004
HXCOMM Deprecated by -rtc
1005
DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1006

    
1007
DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1008
    "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
1009
    QEMU_ARCH_I386)
1010
STEXI
1011
@item -no-fd-bootchk
1012
@findex -no-fd-bootchk
1013
Disable boot signature checking for floppy disks in Bochs BIOS. It may
1014
be needed to boot from old floppy disks.
1015
TODO: check reference to Bochs BIOS.
1016
ETEXI
1017

    
1018
DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1019
           "-no-acpi        disable ACPI\n", QEMU_ARCH_I386)
1020
STEXI
1021
@item -no-acpi
1022
@findex -no-acpi
1023
Disable ACPI (Advanced Configuration and Power Interface) support. Use
1024
it if your guest OS complains about ACPI problems (PC target machine
1025
only).
1026
ETEXI
1027

    
1028
DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1029
    "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1030
STEXI
1031
@item -no-hpet
1032
@findex -no-hpet
1033
Disable HPET support.
1034
ETEXI
1035

    
1036
DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
1037
    "-balloon none   disable balloon device\n"
1038
    "-balloon virtio[,addr=str]\n"
1039
    "                enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
1040
STEXI
1041
@item -balloon none
1042
@findex -balloon
1043
Disable balloon device.
1044
@item -balloon virtio[,addr=@var{addr}]
1045
Enable virtio balloon device (default), optionally with PCI address
1046
@var{addr}.
1047
ETEXI
1048

    
1049
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1050
    "-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"
1051
    "                ACPI table description\n", QEMU_ARCH_I386)
1052
STEXI
1053
@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}]...]
1054
@findex -acpitable
1055
Add ACPI table with specified header fields and context from specified files.
1056
ETEXI
1057

    
1058
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1059
    "-smbios file=binary\n"
1060
    "                load SMBIOS entry from binary file\n"
1061
    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1062
    "                specify SMBIOS type 0 fields\n"
1063
    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1064
    "              [,uuid=uuid][,sku=str][,family=str]\n"
1065
    "                specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
1066
STEXI
1067
@item -smbios file=@var{binary}
1068
@findex -smbios
1069
Load SMBIOS entry from binary file.
1070

    
1071
@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
1072
@findex -smbios
1073
Specify SMBIOS type 0 fields
1074

    
1075
@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}]
1076
Specify SMBIOS type 1 fields
1077
ETEXI
1078

    
1079
DEFHEADING()
1080
STEXI
1081
@end table
1082
ETEXI
1083

    
1084
DEFHEADING(Network options:)
1085
STEXI
1086
@table @option
1087
ETEXI
1088

    
1089
HXCOMM Legacy slirp options (now moved to -net user):
1090
#ifdef CONFIG_SLIRP
1091
DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1092
DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1093
DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1094
#ifndef _WIN32
1095
DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1096
#endif
1097
#endif
1098

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

    
1176
@item -net user[,@var{option}][,@var{option}][,...]
1177
Use the user mode network stack which requires no administrator
1178
privilege to run. Valid options are:
1179

    
1180
@table @option
1181
@item vlan=@var{n}
1182
Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1183

    
1184
@item name=@var{name}
1185
Assign symbolic name for use in monitor commands.
1186

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

    
1192
@item host=@var{addr}
1193
Specify the guest-visible address of the host. Default is the 2nd IP in the
1194
guest network, i.e. x.x.x.2.
1195

    
1196
@item restrict=y|yes|n|no
1197
If this option is enabled, the guest will be isolated, i.e. it will not be
1198
able to contact the host and no guest IP packets will be routed over the host
1199
to the outside. This option does not affect any explicitly set forwarding rules.
1200

    
1201
@item hostname=@var{name}
1202
Specifies the client hostname reported by the builtin DHCP server.
1203

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

    
1208
@item dns=@var{addr}
1209
Specify the guest-visible address of the virtual nameserver. The address must
1210
be different from the host address. Default is the 3rd IP in the guest network,
1211
i.e. x.x.x.3.
1212

    
1213
@item tftp=@var{dir}
1214
When using the user mode network stack, activate a built-in TFTP
1215
server. The files in @var{dir} will be exposed as the root of a TFTP server.
1216
The TFTP client on the guest must be configured in binary mode (use the command
1217
@code{bin} of the Unix TFTP client).
1218

    
1219
@item bootfile=@var{file}
1220
When using the user mode network stack, broadcast @var{file} as the BOOTP
1221
filename. In conjunction with @option{tftp}, this can be used to network boot
1222
a guest from a local directory.
1223

    
1224
Example (using pxelinux):
1225
@example
1226
qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1227
@end example
1228

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

    
1235
In the guest Windows OS, the line:
1236
@example
1237
10.0.2.4 smbserver
1238
@end example
1239
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1240
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1241

    
1242
Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1243

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

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

    
1256
For example, to redirect host X11 connection from screen 1 to guest
1257
screen 0, use the following:
1258

    
1259
@example
1260
# on the host
1261
qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1262
# this host xterm should open in the guest X11 server
1263
xterm -display :1
1264
@end example
1265

    
1266
To redirect telnet connections from host port 5555 to telnet port on
1267
the guest, use the following:
1268

    
1269
@example
1270
# on the host
1271
qemu -net user,hostfwd=tcp::5555-:23 [...]
1272
telnet localhost 5555
1273
@end example
1274

    
1275
Then when you use on the host @code{telnet localhost 5555}, you
1276
connect to the guest telnet server.
1277

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

    
1282
@end table
1283

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

    
1289
@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}] [,script=@var{file}][,downscript=@var{dfile}]
1290
Connect the host TAP network interface @var{name} to VLAN @var{n}, use
1291
the network script @var{file} to configure it and the network script
1292
@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1293
automatically provides one. @option{fd}=@var{h} can be used to specify
1294
the handle of an already opened host TAP interface. The default network
1295
configure script is @file{/etc/qemu-ifup} and the default network
1296
deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
1297
or @option{downscript=no} to disable script execution. Example:
1298

    
1299
@example
1300
qemu linux.img -net nic -net tap
1301
@end example
1302

    
1303
More complicated example (two NICs, each one connected to a TAP device)
1304
@example
1305
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1306
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1307
@end example
1308

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

    
1311
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1312
machine using a TCP socket connection. If @option{listen} is
1313
specified, QEMU waits for incoming connections on @var{port}
1314
(@var{host} is optional). @option{connect} is used to connect to
1315
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1316
specifies an already opened TCP socket.
1317

    
1318
Example:
1319
@example
1320
# launch a first QEMU instance
1321
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1322
               -net socket,listen=:1234
1323
# connect the VLAN 0 of this instance to the VLAN 0
1324
# of the first instance
1325
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1326
               -net socket,connect=127.0.0.1:1234
1327
@end example
1328

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

    
1331
Create a VLAN @var{n} shared with another QEMU virtual
1332
machines using a UDP multicast socket, effectively making a bus for
1333
every QEMU with same multicast address @var{maddr} and @var{port}.
1334
NOTES:
1335
@enumerate
1336
@item
1337
Several QEMU can be running on different hosts and share same bus (assuming
1338
correct multicast setup for these hosts).
1339
@item
1340
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1341
@url{http://user-mode-linux.sf.net}.
1342
@item
1343
Use @option{fd=h} to specify an already opened UDP multicast socket.
1344
@end enumerate
1345

    
1346
Example:
1347
@example
1348
# launch one QEMU instance
1349
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1350
               -net socket,mcast=230.0.0.1:1234
1351
# launch another QEMU instance on same "bus"
1352
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1353
               -net socket,mcast=230.0.0.1:1234
1354
# launch yet another QEMU instance on same "bus"
1355
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1356
               -net socket,mcast=230.0.0.1:1234
1357
@end example
1358

    
1359
Example (User Mode Linux compat.):
1360
@example
1361
# launch QEMU instance (note mcast address selected
1362
# is UML's default)
1363
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1364
               -net socket,mcast=239.192.168.1:1102
1365
# launch UML
1366
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
1367
@end example
1368

    
1369
Example (send packets from host's 1.2.3.4):
1370
@example
1371
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1372
               -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1373
@end example
1374

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

    
1382
Example:
1383
@example
1384
# launch vde switch
1385
vde_switch -F -sock /tmp/myswitch
1386
# launch QEMU instance
1387
qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1388
@end example
1389

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

    
1395
@item -net none
1396
Indicate that no network devices should be configured. It is used to
1397
override the default configuration (@option{-net nic -net user}) which
1398
is activated if no @option{-net} options are provided.
1399

    
1400
@end table
1401
ETEXI
1402

    
1403
DEFHEADING()
1404

    
1405
DEFHEADING(Character device options:)
1406

    
1407
DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1408
    "-chardev null,id=id[,mux=on|off]\n"
1409
    "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1410
    "         [,server][,nowait][,telnet][,mux=on|off] (tcp)\n"
1411
    "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n"
1412
    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1413
    "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1414
    "-chardev msmouse,id=id[,mux=on|off]\n"
1415
    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1416
    "         [,mux=on|off]\n"
1417
    "-chardev file,id=id,path=path[,mux=on|off]\n"
1418
    "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1419
#ifdef _WIN32
1420
    "-chardev console,id=id[,mux=on|off]\n"
1421
    "-chardev serial,id=id,path=path[,mux=on|off]\n"
1422
#else
1423
    "-chardev pty,id=id[,mux=on|off]\n"
1424
    "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
1425
#endif
1426
#ifdef CONFIG_BRLAPI
1427
    "-chardev braille,id=id[,mux=on|off]\n"
1428
#endif
1429
#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1430
        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1431
    "-chardev tty,id=id,path=path[,mux=on|off]\n"
1432
#endif
1433
#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1434
    "-chardev parport,id=id,path=path[,mux=on|off]\n"
1435
#endif
1436
#if defined(CONFIG_SPICE)
1437
    "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
1438
#endif
1439
    , QEMU_ARCH_ALL
1440
)
1441

    
1442
STEXI
1443

    
1444
The general form of a character device option is:
1445
@table @option
1446

    
1447
@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
1448
@findex -chardev
1449
Backend is one of:
1450
@option{null},
1451
@option{socket},
1452
@option{udp},
1453
@option{msmouse},
1454
@option{vc},
1455
@option{file},
1456
@option{pipe},
1457
@option{console},
1458
@option{serial},
1459
@option{pty},
1460
@option{stdio},
1461
@option{braille},
1462
@option{tty},
1463
@option{parport},
1464
@option{spicevmc}.
1465
The specific backend will determine the applicable options.
1466

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

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

    
1474
Options to each backend are described below.
1475

    
1476
@item -chardev null ,id=@var{id}
1477
A void device. This device will not emit any data, and will drop any data it
1478
receives. The null backend does not take any options.
1479

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

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

    
1486
@option{server} specifies that the socket shall be a listening socket.
1487

    
1488
@option{nowait} specifies that QEMU should not block waiting for a client to
1489
connect to a listening socket.
1490

    
1491
@option{telnet} specifies that traffic on the socket should interpret telnet
1492
escape sequences.
1493

    
1494
TCP and unix socket options are given below:
1495

    
1496
@table @option
1497

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

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

    
1504
@option{port} for a listening socket specifies the local port to be bound. For a
1505
connecting socket specifies the port on the remote host to connect to.
1506
@option{port} can be given as either a port number or a service name.
1507
@option{port} is required.
1508

    
1509
@option{to} is only relevant to listening sockets. If it is specified, and
1510
@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1511
to and including @option{to} until it succeeds. @option{to} must be specified
1512
as a port number.
1513

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

    
1517
@option{nodelay} disables the Nagle algorithm.
1518

    
1519
@item unix options: path=@var{path}
1520

    
1521
@option{path} specifies the local path of the unix socket. @option{path} is
1522
required.
1523

    
1524
@end table
1525

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

    
1528
Sends all traffic from the guest to a remote host over UDP.
1529

    
1530
@option{host} specifies the remote host to connect to. If not specified it
1531
defaults to @code{localhost}.
1532

    
1533
@option{port} specifies the port on the remote host to connect to. @option{port}
1534
is required.
1535

    
1536
@option{localaddr} specifies the local address to bind to. If not specified it
1537
defaults to @code{0.0.0.0}.
1538

    
1539
@option{localport} specifies the local port to bind to. If not specified any
1540
available local port will be used.
1541

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

    
1545
@item -chardev msmouse ,id=@var{id}
1546

    
1547
Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1548
take any options.
1549

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

    
1552
Connect to a QEMU text console. @option{vc} may optionally be given a specific
1553
size.
1554

    
1555
@option{width} and @option{height} specify the width and height respectively of
1556
the console, in pixels.
1557

    
1558
@option{cols} and @option{rows} specify that the console be sized to fit a text
1559
console with the given dimensions.
1560

    
1561
@item -chardev file ,id=@var{id} ,path=@var{path}
1562

    
1563
Log all traffic received from the guest to a file.
1564

    
1565
@option{path} specifies the path of the file to be opened. This file will be
1566
created if it does not already exist, and overwritten if it does. @option{path}
1567
is required.
1568

    
1569
@item -chardev pipe ,id=@var{id} ,path=@var{path}
1570

    
1571
Create a two-way connection to the guest. The behaviour differs slightly between
1572
Windows hosts and other hosts:
1573

    
1574
On Windows, a single duplex pipe will be created at
1575
@file{\\.pipe\@option{path}}.
1576

    
1577
On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1578
@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1579
received by the guest. Data written by the guest can be read from
1580
@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1581
be present.
1582

    
1583
@option{path} forms part of the pipe path as described above. @option{path} is
1584
required.
1585

    
1586
@item -chardev console ,id=@var{id}
1587

    
1588
Send traffic from the guest to QEMU's standard output. @option{console} does not
1589
take any options.
1590

    
1591
@option{console} is only available on Windows hosts.
1592

    
1593
@item -chardev serial ,id=@var{id} ,path=@option{path}
1594

    
1595
Send traffic from the guest to a serial device on the host.
1596

    
1597
@option{serial} is
1598
only available on Windows hosts.
1599

    
1600
@option{path} specifies the name of the serial device to open.
1601

    
1602
@item -chardev pty ,id=@var{id}
1603

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

    
1607
@option{pty} is not available on Windows hosts.
1608

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

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

    
1616
@option{stdio} is not available on Windows hosts.
1617

    
1618
@item -chardev braille ,id=@var{id}
1619

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

    
1622
@item -chardev tty ,id=@var{id} ,path=@var{path}
1623

    
1624
Connect to a local tty device.
1625

    
1626
@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1627
DragonFlyBSD hosts.
1628

    
1629
@option{path} specifies the path to the tty. @option{path} is required.
1630

    
1631
@item -chardev parport ,id=@var{id} ,path=@var{path}
1632

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

    
1635
Connect to a local parallel port.
1636

    
1637
@option{path} specifies the path to the parallel port device. @option{path} is
1638
required.
1639

    
1640
#if defined(CONFIG_SPICE)
1641
@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
1642

    
1643
@option{debug} debug level for spicevmc
1644

    
1645
@option{name} name of spice channel to connect to
1646

    
1647
Connect to a spice virtual machine channel, such as vdiport.
1648
#endif
1649

    
1650
@end table
1651
ETEXI
1652

    
1653
DEFHEADING()
1654

    
1655
DEFHEADING(Bluetooth(R) options:)
1656

    
1657
DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1658
    "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
1659
    "-bt hci,host[:id]\n" \
1660
    "                use host's HCI with the given name\n" \
1661
    "-bt hci[,vlan=n]\n" \
1662
    "                emulate a standard HCI in virtual scatternet 'n'\n" \
1663
    "-bt vhci[,vlan=n]\n" \
1664
    "                add host computer to virtual scatternet 'n' using VHCI\n" \
1665
    "-bt device:dev[,vlan=n]\n" \
1666
    "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
1667
    QEMU_ARCH_ALL)
1668
STEXI
1669
@table @option
1670

    
1671
@item -bt hci[...]
1672
@findex -bt
1673
Defines the function of the corresponding Bluetooth HCI.  -bt options
1674
are matched with the HCIs present in the chosen machine type.  For
1675
example when emulating a machine with only one HCI built into it, only
1676
the first @code{-bt hci[...]} option is valid and defines the HCI's
1677
logic.  The Transport Layer is decided by the machine type.  Currently
1678
the machines @code{n800} and @code{n810} have one HCI and all other
1679
machines have none.
1680

    
1681
@anchor{bt-hcis}
1682
The following three types are recognized:
1683

    
1684
@table @option
1685
@item -bt hci,null
1686
(default) The corresponding Bluetooth HCI assumes no internal logic
1687
and will not respond to any HCI commands or emit events.
1688

    
1689
@item -bt hci,host[:@var{id}]
1690
(@code{bluez} only) The corresponding HCI passes commands / events
1691
to / from the physical HCI identified by the name @var{id} (default:
1692
@code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1693
capable systems like Linux.
1694

    
1695
@item -bt hci[,vlan=@var{n}]
1696
Add a virtual, standard HCI that will participate in the Bluetooth
1697
scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1698
VLANs, devices inside a bluetooth network @var{n} can only communicate
1699
with other devices in the same network (scatternet).
1700
@end table
1701

    
1702
@item -bt vhci[,vlan=@var{n}]
1703
(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1704
to the host bluetooth stack instead of to the emulated target.  This
1705
allows the host and target machines to participate in a common scatternet
1706
and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1707
be used as following:
1708

    
1709
@example
1710
qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1711
@end example
1712

    
1713
@item -bt device:@var{dev}[,vlan=@var{n}]
1714
Emulate a bluetooth device @var{dev} and place it in network @var{n}
1715
(default @code{0}).  QEMU can only emulate one type of bluetooth devices
1716
currently:
1717

    
1718
@table @option
1719
@item keyboard
1720
Virtual wireless keyboard implementing the HIDP bluetooth profile.
1721
@end table
1722
@end table
1723
ETEXI
1724

    
1725
DEFHEADING()
1726

    
1727
DEFHEADING(Linux/Multiboot boot specific:)
1728
STEXI
1729

    
1730
When using these options, you can use a given Linux or Multiboot
1731
kernel without installing it in the disk image. It can be useful
1732
for easier testing of various kernels.
1733

    
1734
@table @option
1735
ETEXI
1736

    
1737
DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1738
    "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
1739
STEXI
1740
@item -kernel @var{bzImage}
1741
@findex -kernel
1742
Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1743
or in multiboot format.
1744
ETEXI
1745

    
1746
DEF("append", HAS_ARG, QEMU_OPTION_append, \
1747
    "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
1748
STEXI
1749
@item -append @var{cmdline}
1750
@findex -append
1751
Use @var{cmdline} as kernel command line
1752
ETEXI
1753

    
1754
DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1755
           "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
1756
STEXI
1757
@item -initrd @var{file}
1758
@findex -initrd
1759
Use @var{file} as initial ram disk.
1760

    
1761
@item -initrd "@var{file1} arg=foo,@var{file2}"
1762

    
1763
This syntax is only available with multiboot.
1764

    
1765
Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
1766
first module.
1767
ETEXI
1768

    
1769
STEXI
1770
@end table
1771
ETEXI
1772

    
1773
DEFHEADING()
1774

    
1775
DEFHEADING(Debug/Expert options:)
1776

    
1777
STEXI
1778
@table @option
1779
ETEXI
1780

    
1781
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1782
    "-serial dev     redirect the serial port to char device 'dev'\n",
1783
    QEMU_ARCH_ALL)
1784
STEXI
1785
@item -serial @var{dev}
1786
@findex -serial
1787
Redirect the virtual serial port to host character device
1788
@var{dev}. The default device is @code{vc} in graphical mode and
1789
@code{stdio} in non graphical mode.
1790

    
1791
This option can be used several times to simulate up to 4 serial
1792
ports.
1793

    
1794
Use @code{-serial none} to disable all serial ports.
1795

    
1796
Available character devices are:
1797
@table @option
1798
@item vc[:@var{W}x@var{H}]
1799
Virtual console. Optionally, a width and height can be given in pixel with
1800
@example
1801
vc:800x600
1802
@end example
1803
It is also possible to specify width or height in characters:
1804
@example
1805
vc:80Cx24C
1806
@end example
1807
@item pty
1808
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
1809
@item none
1810
No device is allocated.
1811
@item null
1812
void device
1813
@item /dev/XXX
1814
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
1815
parameters are set according to the emulated ones.
1816
@item /dev/parport@var{N}
1817
[Linux only, parallel port only] Use host parallel port
1818
@var{N}. Currently SPP and EPP parallel port features can be used.
1819
@item file:@var{filename}
1820
Write output to @var{filename}. No character can be read.
1821
@item stdio
1822
[Unix only] standard input/output
1823
@item pipe:@var{filename}
1824
name pipe @var{filename}
1825
@item COM@var{n}
1826
[Windows only] Use host serial port @var{n}
1827
@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
1828
This implements UDP Net Console.
1829
When @var{remote_host} or @var{src_ip} are not specified
1830
they default to @code{0.0.0.0}.
1831
When not using a specified @var{src_port} a random port is automatically chosen.
1832

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

    
1838
If you plan to send characters back via netconsole or you want to stop
1839
and start qemu a lot of times, you should have qemu use the same
1840
source port each time by using something like @code{-serial
1841
udp::4555@@:4556} to qemu. Another approach is to use a patched
1842
version of netcat which can listen to a TCP port and send and receive
1843
characters via udp.  If you have a patched version of netcat which
1844
activates telnet remote echo and single char transfer, then you can
1845
use the following options to step up a netcat redirector to allow
1846
telnet on port 5555 to access the qemu port.
1847
@table @code
1848
@item Qemu Options:
1849
-serial udp::4555@@:4556
1850
@item netcat options:
1851
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
1852
@item telnet options:
1853
localhost 5555
1854
@end table
1855

    
1856
@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
1857
The TCP Net Console has two modes of operation.  It can send the serial
1858
I/O to a location or wait for a connection from a location.  By default
1859
the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
1860
the @var{server} option QEMU will wait for a client socket application
1861
to connect to the port before continuing, unless the @code{nowait}
1862
option was specified.  The @code{nodelay} option disables the Nagle buffering
1863
algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
1864
one TCP connection at a time is accepted. You can use @code{telnet} to
1865
connect to the corresponding character device.
1866
@table @code
1867
@item Example to send tcp console to 192.168.0.2 port 4444
1868
-serial tcp:192.168.0.2:4444
1869
@item Example to listen and wait on port 4444 for connection
1870
-serial tcp::4444,server
1871
@item Example to not wait and listen on ip 192.168.0.100 port 4444
1872
-serial tcp:192.168.0.100:4444,server,nowait
1873
@end table
1874

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

    
1884
@item unix:@var{path}[,server][,nowait]
1885
A unix domain socket is used instead of a tcp socket.  The option works the
1886
same as if you had specified @code{-serial tcp} except the unix domain socket
1887
@var{path} is used for connections.
1888

    
1889
@item mon:@var{dev_string}
1890
This is a special option to allow the monitor to be multiplexed onto
1891
another serial port.  The monitor is accessed with key sequence of
1892
@key{Control-a} and then pressing @key{c}. See monitor access
1893
@ref{pcsys_keys} in the -nographic section for more keys.
1894
@var{dev_string} should be any one of the serial devices specified
1895
above.  An example to multiplex the monitor onto a telnet server
1896
listening on port 4444 would be:
1897
@table @code
1898
@item -serial mon:telnet::4444,server,nowait
1899
@end table
1900

    
1901
@item braille
1902
Braille device.  This will use BrlAPI to display the braille output on a real
1903
or fake device.
1904

    
1905
@item msmouse
1906
Three button serial mouse. Configure the guest to use Microsoft protocol.
1907
@end table
1908
ETEXI
1909

    
1910
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
1911
    "-parallel dev   redirect the parallel port to char device 'dev'\n",
1912
    QEMU_ARCH_ALL)
1913
STEXI
1914
@item -parallel @var{dev}
1915
@findex -parallel
1916
Redirect the virtual parallel port to host device @var{dev} (same
1917
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1918
be used to use hardware devices connected on the corresponding host
1919
parallel port.
1920

    
1921
This option can be used several times to simulate up to 3 parallel
1922
ports.
1923

    
1924
Use @code{-parallel none} to disable all parallel ports.
1925
ETEXI
1926

    
1927
DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
1928
    "-monitor dev    redirect the monitor to char device 'dev'\n",
1929
    QEMU_ARCH_ALL)
1930
STEXI
1931
@item -monitor @var{dev}
1932
@findex -monitor
1933
Redirect the monitor to host device @var{dev} (same devices as the
1934
serial port).
1935
The default device is @code{vc} in graphical mode and @code{stdio} in
1936
non graphical mode.
1937
ETEXI
1938
DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
1939
    "-qmp dev        like -monitor but opens in 'control' mode\n",
1940
    QEMU_ARCH_ALL)
1941
STEXI
1942
@item -qmp @var{dev}
1943
@findex -qmp
1944
Like -monitor but opens in 'control' mode.
1945
ETEXI
1946

    
1947
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
1948
    "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
1949
STEXI
1950
@item -mon chardev=[name][,mode=readline|control][,default]
1951
@findex -mon
1952
Setup monitor on chardev @var{name}.
1953
ETEXI
1954

    
1955
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
1956
    "-debugcon dev   redirect the debug console to char device 'dev'\n",
1957
    QEMU_ARCH_ALL)
1958
STEXI
1959
@item -debugcon @var{dev}
1960
@findex -debugcon
1961
Redirect the debug console to host device @var{dev} (same devices as the
1962
serial port).  The debug console is an I/O port which is typically port
1963
0xe9; writing to that I/O port sends output to this device.
1964
The default device is @code{vc} in graphical mode and @code{stdio} in
1965
non graphical mode.
1966
ETEXI
1967

    
1968
DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
1969
    "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
1970
STEXI
1971
@item -pidfile @var{file}
1972
@findex -pidfile
1973
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
1974
from a script.
1975
ETEXI
1976

    
1977
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
1978
    "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
1979
STEXI
1980
@item -singlestep
1981
@findex -singlestep
1982
Run the emulation in single step mode.
1983
ETEXI
1984

    
1985
DEF("S", 0, QEMU_OPTION_S, \
1986
    "-S              freeze CPU at startup (use 'c' to start execution)\n",
1987
    QEMU_ARCH_ALL)
1988
STEXI
1989
@item -S
1990
@findex -S
1991
Do not start CPU at startup (you must type 'c' in the monitor).
1992
ETEXI
1993

    
1994
DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
1995
    "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
1996
STEXI
1997
@item -gdb @var{dev}
1998
@findex -gdb
1999
Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2000
connections will likely be TCP-based, but also UDP, pseudo TTY, or even
2001
stdio are reasonable use case. The latter is allowing to start qemu from
2002
within gdb and establish the connection via a pipe:
2003
@example
2004
(gdb) target remote | exec qemu -gdb stdio ...
2005
@end example
2006
ETEXI
2007

    
2008
DEF("s", 0, QEMU_OPTION_s, \
2009
    "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2010
    QEMU_ARCH_ALL)
2011
STEXI
2012
@item -s
2013
@findex -s
2014
Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2015
(@pxref{gdb_usage}).
2016
ETEXI
2017

    
2018
DEF("d", HAS_ARG, QEMU_OPTION_d, \
2019
    "-d item1,...    output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
2020
    QEMU_ARCH_ALL)
2021
STEXI
2022
@item -d
2023
@findex -d
2024
Output log in /tmp/qemu.log
2025
ETEXI
2026

    
2027
DEF("D", HAS_ARG, QEMU_OPTION_D, \
2028
    "-D logfile      output log to logfile (instead of the default /tmp/qemu.log)\n",
2029
    QEMU_ARCH_ALL)
2030
STEXI
2031
@item -D
2032
@findex -D
2033
Output log in logfile instead of /tmp/qemu.log
2034
ETEXI
2035

    
2036
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
2037
    "-hdachs c,h,s[,t]\n" \
2038
    "                force hard disk 0 physical geometry and the optional BIOS\n" \
2039
    "                translation (t=none or lba) (usually qemu can guess them)\n",
2040
    QEMU_ARCH_ALL)
2041
STEXI
2042
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
2043
@findex -hdachs
2044
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
2045
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
2046
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
2047
all those parameters. This option is useful for old MS-DOS disk
2048
images.
2049
ETEXI
2050

    
2051
DEF("L", HAS_ARG, QEMU_OPTION_L, \
2052
    "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
2053
    QEMU_ARCH_ALL)
2054
STEXI
2055
@item -L  @var{path}
2056
@findex -L
2057
Set the directory for the BIOS, VGA BIOS and keymaps.
2058
ETEXI
2059

    
2060
DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2061
    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
2062
STEXI
2063
@item -bios @var{file}
2064
@findex -bios
2065
Set the filename for the BIOS.
2066
ETEXI
2067

    
2068
DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2069
    "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2070
STEXI
2071
@item -enable-kvm
2072
@findex -enable-kvm
2073
Enable KVM full virtualization support. This option is only available
2074
if KVM support is enabled when compiling.
2075
ETEXI
2076

    
2077
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
2078
    "-machine [type=]name[,prop[=value][,...]]\n"
2079
    "                selects emulated machine (-machine ? for list)\n"
2080
    "                property accel=accel1[:accel2[:...]] selects accelerator\n"
2081
    "                supported accelerators are kvm, xen, tcg (default: tcg)\n",
2082
    QEMU_ARCH_ALL)
2083
STEXI
2084
@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
2085
@findex -machine
2086
Select the emulated machine by @var{name}. Use @code{-machine ?} to list
2087
available machines. Supported machine properties are:
2088
@table @option
2089
@item accel=@var{accels1}[:@var{accels2}[:...]]
2090
This is used to enable an accelerator. Depending on the target architecture,
2091
kvm, xen, or tcg can be available. By default, tcg is used. If there is more
2092
than one accelerator specified, the next one is used if the previous one fails
2093
to initialize.
2094
@end table
2095
ETEXI
2096

    
2097
DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2098
    "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
2099
DEF("xen-create", 0, QEMU_OPTION_xen_create,
2100
    "-xen-create     create domain using xen hypercalls, bypassing xend\n"
2101
    "                warning: should not be used when xend is in use\n",
2102
    QEMU_ARCH_ALL)
2103
DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2104
    "-xen-attach     attach to existing xen domain\n"
2105
    "                xend will use this when starting qemu\n",
2106
    QEMU_ARCH_ALL)
2107
STEXI
2108
@item -xen-domid @var{id}
2109
@findex -xen-domid
2110
Specify xen guest domain @var{id} (XEN only).
2111
@item -xen-create
2112
@findex -xen-create
2113
Create domain using xen hypercalls, bypassing xend.
2114
Warning: should not be used when xend is in use (XEN only).
2115
@item -xen-attach
2116
@findex -xen-attach
2117
Attach to existing xen domain.
2118
xend will use this when starting qemu (XEN only).
2119
ETEXI
2120

    
2121
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
2122
    "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
2123
STEXI
2124
@item -no-reboot
2125
@findex -no-reboot
2126
Exit instead of rebooting.
2127
ETEXI
2128

    
2129
DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
2130
    "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
2131
STEXI
2132
@item -no-shutdown
2133
@findex -no-shutdown
2134
Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2135
This allows for instance switching to monitor to commit changes to the
2136
disk image.
2137
ETEXI
2138

    
2139
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2140
    "-loadvm [tag|id]\n" \
2141
    "                start right away with a saved state (loadvm in monitor)\n",
2142
    QEMU_ARCH_ALL)
2143
STEXI
2144
@item -loadvm @var{file}
2145
@findex -loadvm
2146
Start right away with a saved state (@code{loadvm} in monitor)
2147
ETEXI
2148

    
2149
#ifndef _WIN32
2150
DEF("daemonize", 0, QEMU_OPTION_daemonize, \
2151
    "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
2152
#endif
2153
STEXI
2154
@item -daemonize
2155
@findex -daemonize
2156
Daemonize the QEMU process after initialization.  QEMU will not detach from
2157
standard IO until it is ready to receive connections on any of its devices.
2158
This option is a useful way for external programs to launch QEMU without having
2159
to cope with initialization race conditions.
2160
ETEXI
2161

    
2162
DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
2163
    "-option-rom rom load a file, rom, into the option ROM space\n",
2164
    QEMU_ARCH_ALL)
2165
STEXI
2166
@item -option-rom @var{file}
2167
@findex -option-rom
2168
Load the contents of @var{file} as an option ROM.
2169
This option is useful to load things like EtherBoot.
2170
ETEXI
2171

    
2172
DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
2173
    "-clock          force the use of the given methods for timer alarm.\n" \
2174
    "                To see what timers are available use -clock ?\n",
2175
    QEMU_ARCH_ALL)
2176
STEXI
2177
@item -clock @var{method}
2178
@findex -clock
2179
Force the use of the given methods for timer alarm. To see what timers
2180
are available use -clock ?.
2181
ETEXI
2182

    
2183
HXCOMM Options deprecated by -rtc
2184
DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
2185
DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
2186

    
2187
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
2188
    "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
2189
    "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
2190
    QEMU_ARCH_ALL)
2191

    
2192
STEXI
2193

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

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

    
2207
Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
2208
specifically with Windows' ACPI HAL. This option will try to figure out how
2209
many timer interrupts were not processed by the Windows guest and will
2210
re-inject them.
2211
ETEXI
2212

    
2213
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
2214
    "-icount [N|auto]\n" \
2215
    "                enable virtual instruction counter with 2^N clock ticks per\n" \
2216
    "                instruction\n", QEMU_ARCH_ALL)
2217
STEXI
2218
@item -icount [@var{N}|auto]
2219
@findex -icount
2220
Enable virtual instruction counter.  The virtual cpu will execute one
2221
instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
2222
then the virtual cpu speed will be automatically adjusted to keep virtual
2223
time within a few seconds of real time.
2224

    
2225
Note that while this option can give deterministic behavior, it does not
2226
provide cycle accurate emulation.  Modern CPUs contain superscalar out of
2227
order cores with complex cache hierarchies.  The number of instructions
2228
executed often has little or no correlation with actual performance.
2229
ETEXI
2230

    
2231
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
2232
    "-watchdog i6300esb|ib700\n" \
2233
    "                enable virtual hardware watchdog [default=none]\n",
2234
    QEMU_ARCH_ALL)
2235
STEXI
2236
@item -watchdog @var{model}
2237
@findex -watchdog
2238
Create a virtual hardware watchdog device.  Once enabled (by a guest
2239
action), the watchdog must be periodically polled by an agent inside
2240
the guest or else the guest will be restarted.
2241

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

    
2248
Use @code{-watchdog ?} to list available hardware models.  Only one
2249
watchdog can be enabled for a guest.
2250
ETEXI
2251

    
2252
DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
2253
    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
2254
    "                action when watchdog fires [default=reset]\n",
2255
    QEMU_ARCH_ALL)
2256
STEXI
2257
@item -watchdog-action @var{action}
2258

    
2259
The @var{action} controls what QEMU will do when the watchdog timer
2260
expires.
2261
The default is
2262
@code{reset} (forcefully reset the guest).
2263
Other possible actions are:
2264
@code{shutdown} (attempt to gracefully shutdown the guest),
2265
@code{poweroff} (forcefully poweroff the guest),
2266
@code{pause} (pause the guest),
2267
@code{debug} (print a debug message and continue), or
2268
@code{none} (do nothing).
2269

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

    
2275
Examples:
2276

    
2277
@table @code
2278
@item -watchdog i6300esb -watchdog-action pause
2279
@item -watchdog ib700
2280
@end table
2281
ETEXI
2282

    
2283
DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
2284
    "-echr chr       set terminal escape character instead of ctrl-a\n",
2285
    QEMU_ARCH_ALL)
2286
STEXI
2287

    
2288
@item -echr @var{numeric_ascii_value}
2289
@findex -echr
2290
Change the escape character used for switching to the monitor when using
2291
monitor and serial sharing.  The default is @code{0x01} when using the
2292
@code{-nographic} option.  @code{0x01} is equal to pressing
2293
@code{Control-a}.  You can select a different character from the ascii
2294
control keys where 1 through 26 map to Control-a through Control-z.  For
2295
instance you could use the either of the following to change the escape
2296
character to Control-t.
2297
@table @code
2298
@item -echr 0x14
2299
@item -echr 20
2300
@end table
2301
ETEXI
2302

    
2303
DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
2304
    "-virtioconsole c\n" \
2305
    "                set virtio console\n", QEMU_ARCH_ALL)
2306
STEXI
2307
@item -virtioconsole @var{c}
2308
@findex -virtioconsole
2309
Set virtio console.
2310

    
2311
This option is maintained for backward compatibility.
2312

    
2313
Please use @code{-device virtconsole} for the new way of invocation.
2314
ETEXI
2315

    
2316
DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
2317
    "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
2318
STEXI
2319
@item -show-cursor
2320
@findex -show-cursor
2321
Show cursor.
2322
ETEXI
2323

    
2324
DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
2325
    "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
2326
STEXI
2327
@item -tb-size @var{n}
2328
@findex -tb-size
2329
Set TB size.
2330
ETEXI
2331

    
2332
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
2333
    "-incoming p     prepare for incoming migration, listen on port p\n",
2334
    QEMU_ARCH_ALL)
2335
STEXI
2336
@item -incoming @var{port}
2337
@findex -incoming
2338
Prepare for incoming migration, listen on @var{port}.
2339
ETEXI
2340

    
2341
DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
2342
    "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
2343
STEXI
2344
@item -nodefaults
2345
@findex -nodefaults
2346
Don't create default devices.
2347
ETEXI
2348

    
2349
#ifndef _WIN32
2350
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
2351
    "-chroot dir     chroot to dir just before starting the VM\n",
2352
    QEMU_ARCH_ALL)
2353
#endif
2354
STEXI
2355
@item -chroot @var{dir}
2356
@findex -chroot
2357
Immediately before starting guest execution, chroot to the specified
2358
directory.  Especially useful in combination with -runas.
2359
ETEXI
2360

    
2361
#ifndef _WIN32
2362
DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2363
    "-runas user     change to user id user just before starting the VM\n",
2364
    QEMU_ARCH_ALL)
2365
#endif
2366
STEXI
2367
@item -runas @var{user}
2368
@findex -runas
2369
Immediately before starting guest execution, drop root privileges, switching
2370
to the specified user.
2371
ETEXI
2372

    
2373
DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
2374
    "-prom-env variable=value\n"
2375
    "                set OpenBIOS nvram variables\n",
2376
    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
2377
STEXI
2378
@item -prom-env @var{variable}=@var{value}
2379
@findex -prom-env
2380
Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
2381
ETEXI
2382
DEF("semihosting", 0, QEMU_OPTION_semihosting,
2383
    "-semihosting    semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K)
2384
STEXI
2385
@item -semihosting
2386
@findex -semihosting
2387
Semihosting mode (ARM, M68K only).
2388
ETEXI
2389
DEF("old-param", 0, QEMU_OPTION_old_param,
2390
    "-old-param      old param mode\n", QEMU_ARCH_ARM)
2391
STEXI
2392
@item -old-param
2393
@findex -old-param (ARM)
2394
Old param mode (ARM only).
2395
ETEXI
2396

    
2397
DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2398
    "-readconfig <file>\n", QEMU_ARCH_ALL)
2399
STEXI
2400
@item -readconfig @var{file}
2401
@findex -readconfig
2402
Read device configuration from @var{file}.
2403
ETEXI
2404
DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2405
    "-writeconfig <file>\n"
2406
    "                read/write config file\n", QEMU_ARCH_ALL)
2407
STEXI
2408
@item -writeconfig @var{file}
2409
@findex -writeconfig
2410
Write device configuration to @var{file}.
2411
ETEXI
2412
DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2413
    "-nodefconfig\n"
2414
    "                do not load default config files at startup\n",
2415
    QEMU_ARCH_ALL)
2416
STEXI
2417
@item -nodefconfig
2418
@findex -nodefconfig
2419
Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2420
@var{sysconfdir}/target-@var{ARCH}.conf on startup.  The @code{-nodefconfig}
2421
option will prevent QEMU from loading these configuration files at startup.
2422
ETEXI
2423
#ifdef CONFIG_SIMPLE_TRACE
2424
DEF("trace", HAS_ARG, QEMU_OPTION_trace,
2425
    "-trace\n"
2426
    "                Specify a trace file to log traces to\n",
2427
    QEMU_ARCH_ALL)
2428
STEXI
2429
@item -trace
2430
@findex -trace
2431
Specify a trace file to log output traces to.
2432
ETEXI
2433
#endif
2434

    
2435
HXCOMM This is the last statement. Insert new options before this line!
2436
STEXI
2437
@end table
2438
ETEXI