Statistics
| Branch: | Revision:

root / qemu-options.hx @ 95d5f08b

History | View | Annotate | Download (69.4 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) is used to construct
5
HXCOMM option structures, enums and help message.
6
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
7

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

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

    
20
DEF("version", 0, QEMU_OPTION_version,
21
    "-version        display version information and exit\n")
22
STEXI
23
@item -version
24
Display version information and exit
25
ETEXI
26

    
27
DEF("M", HAS_ARG, QEMU_OPTION_M,
28
    "-M machine      select emulated machine (-M ? for list)\n")
29
STEXI
30
@item -M @var{machine}
31
Select the emulated @var{machine} (@code{-M ?} for list)
32
ETEXI
33

    
34
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
35
    "-cpu cpu        select CPU (-cpu ? for list)\n")
36
STEXI
37
@item -cpu @var{model}
38
Select CPU model (-cpu ? for list and additional feature selection)
39
ETEXI
40

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

    
61
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
62
    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n")
63
STEXI
64
@item -numa @var{opts}
65
Simulate a multi node NUMA system. If mem and cpus are omitted, resources
66
are split equally.
67
ETEXI
68

    
69
DEF("fda", HAS_ARG, QEMU_OPTION_fda,
70
    "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n")
71
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "")
72
STEXI
73
@item -fda @var{file}
74
@item -fdb @var{file}
75
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
76
use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
77
ETEXI
78

    
79
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
80
    "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n")
81
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "")
82
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
83
    "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n")
84
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "")
85
STEXI
86
@item -hda @var{file}
87
@item -hdb @var{file}
88
@item -hdc @var{file}
89
@item -hdd @var{file}
90
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
91
ETEXI
92

    
93
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
94
    "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n")
95
STEXI
96
@item -cdrom @var{file}
97
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
98
@option{-cdrom} at the same time). You can use the host CD-ROM by
99
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
100
ETEXI
101

    
102
DEF("drive", HAS_ARG, QEMU_OPTION_drive,
103
    "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
104
    "       [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
105
    "       [,cache=writethrough|writeback|none][,format=f][,serial=s]\n"
106
    "       [,addr=A][,id=name][,aio=threads|native][,readonly=on|off]\n"
107
    "                use 'file' as a drive image\n")
108
DEF("set", HAS_ARG, QEMU_OPTION_set,
109
    "-set group.id.arg=value\n"
110
    "                set <arg> parameter for item <id> of type <group>\n"
111
    "                i.e. -set drive.$id.file=/path/to/image\n")
112
DEF("global", HAS_ARG, QEMU_OPTION_global,
113
    "-global driver.property=value\n"
114
    "                set a global default for a driver property\n")
115
STEXI
116
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
117

    
118
Define a new drive. Valid options are:
119

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

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

    
159
Writeback caching will report data writes as completed as soon as the data is
160
present in the host page cache.  This is safe as long as you trust your host.
161
If your host crashes or loses power, then the guest may experience data
162
corruption.  When using the @option{-snapshot} option, writeback caching is
163
used by default.
164

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

    
169
Some block drivers perform badly with @option{cache=writethrough}, most notably,
170
qcow2.  If performance is more important than correctness,
171
@option{cache=writeback} should be used with qcow2.
172

    
173
Instead of @option{-cdrom} you can use:
174
@example
175
qemu -drive file=file,index=2,media=cdrom
176
@end example
177

    
178
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
179
use:
180
@example
181
qemu -drive file=file,index=0,media=disk
182
qemu -drive file=file,index=1,media=disk
183
qemu -drive file=file,index=2,media=disk
184
qemu -drive file=file,index=3,media=disk
185
@end example
186

    
187
You can connect a CDROM to the slave of ide0:
188
@example
189
qemu -drive file=file,if=ide,index=1,media=cdrom
190
@end example
191

    
192
If you don't specify the "file=" argument, you define an empty drive:
193
@example
194
qemu -drive if=ide,index=1,media=cdrom
195
@end example
196

    
197
You can connect a SCSI disk with unit ID 6 on the bus #0:
198
@example
199
qemu -drive file=file,if=scsi,bus=0,unit=6
200
@end example
201

    
202
Instead of @option{-fda}, @option{-fdb}, you can use:
203
@example
204
qemu -drive file=file,index=0,if=floppy
205
qemu -drive file=file,index=1,if=floppy
206
@end example
207

    
208
By default, @var{interface} is "ide" and @var{index} is automatically
209
incremented:
210
@example
211
qemu -drive file=a -drive file=b"
212
@end example
213
is interpreted like:
214
@example
215
qemu -hda a -hdb b
216
@end example
217
ETEXI
218

    
219
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
220
    "-mtdblock file  use 'file' as on-board Flash memory image\n")
221
STEXI
222

    
223
@item -mtdblock @var{file}
224
Use @var{file} as on-board Flash memory image.
225
ETEXI
226

    
227
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
228
    "-sd file        use 'file' as SecureDigital card image\n")
229
STEXI
230
@item -sd @var{file}
231
Use @var{file} as SecureDigital card image.
232
ETEXI
233

    
234
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
235
    "-pflash file    use 'file' as a parallel flash image\n")
236
STEXI
237
@item -pflash @var{file}
238
Use @var{file} as a parallel flash image.
239
ETEXI
240

    
241
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
242
    "-boot [order=drives][,once=drives][,menu=on|off]\n"
243
    "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n")
244
STEXI
245
@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off]
246

    
247
Specify boot order @var{drives} as a string of drive letters. Valid
248
drive letters depend on the target achitecture. The x86 PC uses: a, b
249
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
250
from network adapter 1-4), hard disk boot is the default. To apply a
251
particular boot order only on the first startup, specify it via
252
@option{once}.
253

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

    
257
@example
258
# try to boot from network first, then from hard disk
259
qemu -boot order=nc
260
# boot from CD-ROM first, switch back to default order after reboot
261
qemu -boot once=d
262
@end example
263

    
264
Note: The legacy format '-boot @var{drives}' is still supported but its
265
use is discouraged as it may be removed from future versions.
266
ETEXI
267

    
268
DEF("snapshot", 0, QEMU_OPTION_snapshot,
269
    "-snapshot       write to temporary files instead of disk image files\n")
270
STEXI
271
@item -snapshot
272
Write to temporary files instead of disk image files. In this case,
273
the raw disk image you use is not written back. You can however force
274
the write back by pressing @key{C-a s} (@pxref{disk_images}).
275
ETEXI
276

    
277
DEF("m", HAS_ARG, QEMU_OPTION_m,
278
    "-m megs         set virtual RAM size to megs MB [default=%d]\n")
279
STEXI
280
@item -m @var{megs}
281
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
282
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
283
gigabytes respectively.
284
ETEXI
285

    
286
DEF("k", HAS_ARG, QEMU_OPTION_k,
287
    "-k language     use keyboard layout (for example 'fr' for French)\n")
288
STEXI
289
@item -k @var{language}
290

    
291
Use keyboard layout @var{language} (for example @code{fr} for
292
French). This option is only needed where it is not easy to get raw PC
293
keycodes (e.g. on Macs, with some X11 servers or with a VNC
294
display). You don't normally need to use it on PC/Linux or PC/Windows
295
hosts.
296

    
297
The available layouts are:
298
@example
299
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
300
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
301
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
302
@end example
303

    
304
The default is @code{en-us}.
305
ETEXI
306

    
307

    
308
#ifdef HAS_AUDIO
309
DEF("audio-help", 0, QEMU_OPTION_audio_help,
310
    "-audio-help     print list of audio drivers and their options\n")
311
#endif
312
STEXI
313
@item -audio-help
314

    
315
Will show the audio subsystem help: list of drivers, tunable
316
parameters.
317
ETEXI
318

    
319
#ifdef HAS_AUDIO
320
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
321
    "-soundhw c1,... enable audio support\n"
322
    "                and only specified sound cards (comma separated list)\n"
323
    "                use -soundhw ? to get the list of supported cards\n"
324
    "                use -soundhw all to enable all of them\n")
325
#endif
326
STEXI
327
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
328

    
329
Enable audio and selected sound hardware. Use ? to print all
330
available sound hardware.
331

    
332
@example
333
qemu -soundhw sb16,adlib disk.img
334
qemu -soundhw es1370 disk.img
335
qemu -soundhw ac97 disk.img
336
qemu -soundhw all disk.img
337
qemu -soundhw ?
338
@end example
339

    
340
Note that Linux's i810_audio OSS kernel (for AC97) module might
341
require manually specifying clocking.
342

    
343
@example
344
modprobe i810_audio clocking=48000
345
@end example
346
ETEXI
347

    
348
STEXI
349
@end table
350
ETEXI
351

    
352
DEF("usb", 0, QEMU_OPTION_usb,
353
    "-usb            enable the USB driver (will be the default soon)\n")
354
STEXI
355
USB options:
356
@table @option
357

    
358
@item -usb
359
Enable the USB driver (will be the default soon)
360
ETEXI
361

    
362
DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
363
    "-usbdevice name add the host or guest USB device 'name'\n")
364
STEXI
365

    
366
@item -usbdevice @var{devname}
367
Add the USB device @var{devname}. @xref{usb_devices}.
368

    
369
@table @option
370

    
371
@item mouse
372
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
373

    
374
@item tablet
375
Pointer device that uses absolute coordinates (like a touchscreen). This
376
means qemu is able to report the mouse position without having to grab the
377
mouse. Also overrides the PS/2 mouse emulation when activated.
378

    
379
@item disk:[format=@var{format}]:@var{file}
380
Mass storage device based on file. The optional @var{format} argument
381
will be used rather than detecting the format. Can be used to specifiy
382
@code{format=raw} to avoid interpreting an untrusted format header.
383

    
384
@item host:@var{bus}.@var{addr}
385
Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
386

    
387
@item host:@var{vendor_id}:@var{product_id}
388
Pass through the host device identified by @var{vendor_id}:@var{product_id}
389
(Linux only).
390

    
391
@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
392
Serial converter to host character device @var{dev}, see @code{-serial} for the
393
available devices.
394

    
395
@item braille
396
Braille device.  This will use BrlAPI to display the braille output on a real
397
or fake device.
398

    
399
@item net:@var{options}
400
Network adapter that supports CDC ethernet and RNDIS protocols.
401

    
402
@end table
403
ETEXI
404

    
405
DEF("device", HAS_ARG, QEMU_OPTION_device,
406
    "-device driver[,option[=value][,...]]\n"
407
    "                add device (based on driver) with default or\n"
408
    "                user defined options\n"
409
    "                use -device ? to print all possible drivers\n"
410
    "                use -device driver,? to print all possible options\n"
411
    "                use -device driver,option=? to print a help for value\n")
412
STEXI
413
@item -device @var{driver}[,@var{option}[=@var{value}][,...]]
414
Add device @var{driver}. Depending on the device type,
415
@var{option} (with default or given @var{value}) may be useful.
416
To get a help on possible @var{driver}s, @var{option}s or @var{value}s, use
417
@code{-device ?},
418
@code{-device @var{driver},?} or
419
@code{-device @var{driver},@var{option}=?}. 
420
ETEXI
421

    
422
DEF("name", HAS_ARG, QEMU_OPTION_name,
423
    "-name string1[,process=string2]\n"
424
    "                set the name of the guest\n"
425
    "                string1 sets the window title and string2 the process name (on Linux)\n")
426
STEXI
427
@item -name @var{name}
428
Sets the @var{name} of the guest.
429
This name will be displayed in the SDL window caption.
430
The @var{name} will also be used for the VNC server.
431
Also optionally set the top visible process name in Linux.
432
ETEXI
433

    
434
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
435
    "-uuid %%08x-%%04x-%%04x-%%04x-%%012x\n"
436
    "                specify machine UUID\n")
437
STEXI
438
@item -uuid @var{uuid}
439
Set system UUID.
440
ETEXI
441

    
442
STEXI
443
@end table
444
ETEXI
445

    
446
DEFHEADING()
447

    
448
DEFHEADING(Display options:)
449

    
450
STEXI
451
@table @option
452
ETEXI
453

    
454
DEF("nographic", 0, QEMU_OPTION_nographic,
455
    "-nographic      disable graphical output and redirect serial I/Os to console\n")
456
STEXI
457
@item -nographic
458

    
459
Normally, QEMU uses SDL to display the VGA output. With this option,
460
you can totally disable graphical output so that QEMU is a simple
461
command line application. The emulated serial port is redirected on
462
the console. Therefore, you can still use QEMU to debug a Linux kernel
463
with a serial console.
464
ETEXI
465

    
466
#ifdef CONFIG_CURSES
467
DEF("curses", 0, QEMU_OPTION_curses,
468
    "-curses         use a curses/ncurses interface instead of SDL\n")
469
#endif
470
STEXI
471
@item -curses
472

    
473
Normally, QEMU uses SDL to display the VGA output.  With this option,
474
QEMU can display the VGA output when in text mode using a
475
curses/ncurses interface.  Nothing is displayed in graphical mode.
476
ETEXI
477

    
478
#ifdef CONFIG_SDL
479
DEF("no-frame", 0, QEMU_OPTION_no_frame,
480
    "-no-frame       open SDL window without a frame and window decorations\n")
481
#endif
482
STEXI
483
@item -no-frame
484

    
485
Do not use decorations for SDL windows and start them using the whole
486
available screen space. This makes the using QEMU in a dedicated desktop
487
workspace more convenient.
488
ETEXI
489

    
490
#ifdef CONFIG_SDL
491
DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
492
    "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n")
493
#endif
494
STEXI
495
@item -alt-grab
496

    
497
Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt).
498
ETEXI
499

    
500
#ifdef CONFIG_SDL
501
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
502
    "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n")
503
#endif
504
STEXI
505
@item -ctrl-grab
506

    
507
Use Right-Ctrl to grab mouse (instead of Ctrl-Alt).
508
ETEXI
509

    
510
#ifdef CONFIG_SDL
511
DEF("no-quit", 0, QEMU_OPTION_no_quit,
512
    "-no-quit        disable SDL window close capability\n")
513
#endif
514
STEXI
515
@item -no-quit
516

    
517
Disable SDL window close capability.
518
ETEXI
519

    
520
#ifdef CONFIG_SDL
521
DEF("sdl", 0, QEMU_OPTION_sdl,
522
    "-sdl            enable SDL\n")
523
#endif
524
STEXI
525
@item -sdl
526

    
527
Enable SDL.
528
ETEXI
529

    
530
DEF("portrait", 0, QEMU_OPTION_portrait,
531
    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n")
532
STEXI
533
@item -portrait
534

    
535
Rotate graphical output 90 deg left (only PXA LCD).
536
ETEXI
537

    
538
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
539
    "-vga [std|cirrus|vmware|xenfb|none]\n"
540
    "                select video card type\n")
541
STEXI
542
@item -vga @var{type}
543
Select type of VGA card to emulate. Valid values for @var{type} are
544
@table @option
545
@item cirrus
546
Cirrus Logic GD5446 Video card. All Windows versions starting from
547
Windows 95 should recognize and use this graphic card. For optimal
548
performances, use 16 bit color depth in the guest and the host OS.
549
(This one is the default)
550
@item std
551
Standard VGA card with Bochs VBE extensions.  If your guest OS
552
supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
553
to use high resolution modes (>= 1280x1024x16) then you should use
554
this option.
555
@item vmware
556
VMWare SVGA-II compatible adapter. Use it if you have sufficiently
557
recent XFree86/XOrg server or Windows guest with a driver for this
558
card.
559
@item none
560
Disable VGA card.
561
@end table
562
ETEXI
563

    
564
DEF("full-screen", 0, QEMU_OPTION_full_screen,
565
    "-full-screen    start in full screen\n")
566
STEXI
567
@item -full-screen
568
Start in full screen.
569
ETEXI
570

    
571
#if defined(TARGET_PPC) || defined(TARGET_SPARC)
572
DEF("g", 1, QEMU_OPTION_g ,
573
    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n")
574
#endif
575
STEXI
576
@item -g @var{width}x@var{height}[x@var{depth}]
577
Set the initial graphical resolution and depth (PPC, SPARC only).
578
ETEXI
579

    
580
DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
581
    "-vnc display    start a VNC server on display\n")
582
STEXI
583
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
584

    
585
Normally, QEMU uses SDL to display the VGA output.  With this option,
586
you can have QEMU listen on VNC display @var{display} and redirect the VGA
587
display over the VNC session.  It is very useful to enable the usb
588
tablet device when using this option (option @option{-usbdevice
589
tablet}). When using the VNC display, you must use the @option{-k}
590
parameter to set the keyboard layout if you are not using en-us. Valid
591
syntax for the @var{display} is
592

    
593
@table @option
594

    
595
@item @var{host}:@var{d}
596

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

    
601
@item unix:@var{path}
602

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

    
606
@item none
607

    
608
VNC is initialized but not started. The monitor @code{change} command
609
can be used to later start the VNC server.
610

    
611
@end table
612

    
613
Following the @var{display} value there may be one or more @var{option} flags
614
separated by commas. Valid options are
615

    
616
@table @option
617

    
618
@item reverse
619

    
620
Connect to a listening VNC client via a ``reverse'' connection. The
621
client is specified by the @var{display}. For reverse network
622
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
623
is a TCP port number, not a display number.
624

    
625
@item password
626

    
627
Require that password based authentication is used for client connections.
628
The password must be set separately using the @code{change} command in the
629
@ref{pcsys_monitor}
630

    
631
@item tls
632

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

    
638
@item x509=@var{/path/to/certificate/dir}
639

    
640
Valid if @option{tls} is specified. Require that x509 credentials are used
641
for negotiating the TLS session. The server will send its x509 certificate
642
to the client. It is recommended that a password be set on the VNC server
643
to provide authentication of the client when this is used. The path following
644
this option specifies where the x509 certificates are to be loaded from.
645
See the @ref{vnc_security} section for details on generating certificates.
646

    
647
@item x509verify=@var{/path/to/certificate/dir}
648

    
649
Valid if @option{tls} is specified. Require that x509 credentials are used
650
for negotiating the TLS session. The server will send its x509 certificate
651
to the client, and request that the client send its own x509 certificate.
652
The server will validate the client's certificate against the CA certificate,
653
and reject clients when validation fails. If the certificate authority is
654
trusted, this is a sufficient authentication mechanism. You may still wish
655
to set a password on the VNC server as a second authentication layer. The
656
path following this option specifies where the x509 certificates are to
657
be loaded from. See the @ref{vnc_security} section for details on generating
658
certificates.
659

    
660
@item sasl
661

    
662
Require that the client use SASL to authenticate with the VNC server.
663
The exact choice of authentication method used is controlled from the
664
system / user's SASL configuration file for the 'qemu' service. This
665
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
666
unprivileged user, an environment variable SASL_CONF_PATH can be used
667
to make it search alternate locations for the service config.
668
While some SASL auth methods can also provide data encryption (eg GSSAPI),
669
it is recommended that SASL always be combined with the 'tls' and
670
'x509' settings to enable use of SSL and server certificates. This
671
ensures a data encryption preventing compromise of authentication
672
credentials. See the @ref{vnc_security} section for details on using
673
SASL authentication.
674

    
675
@item acl
676

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

    
688
@end table
689
ETEXI
690

    
691
STEXI
692
@end table
693
ETEXI
694

    
695
DEFHEADING()
696

    
697
#ifdef TARGET_I386
698
DEFHEADING(i386 target only:)
699
#endif
700
STEXI
701
@table @option
702
ETEXI
703

    
704
#ifdef TARGET_I386
705
DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
706
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n")
707
#endif
708
STEXI
709
@item -win2k-hack
710
Use it when installing Windows 2000 to avoid a disk full bug. After
711
Windows 2000 is installed, you no longer need this option (this option
712
slows down the IDE transfers).
713
ETEXI
714

    
715
#ifdef TARGET_I386
716
HXCOMM Deprecated by -rtc
717
DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "")
718
#endif
719

    
720
#ifdef TARGET_I386
721
DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
722
    "-no-fd-bootchk  disable boot signature checking for floppy disks\n")
723
#endif
724
STEXI
725
@item -no-fd-bootchk
726
Disable boot signature checking for floppy disks in Bochs BIOS. It may
727
be needed to boot from old floppy disks.
728
ETEXI
729

    
730
#ifdef TARGET_I386
731
DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
732
           "-no-acpi        disable ACPI\n")
733
#endif
734
STEXI
735
@item -no-acpi
736
Disable ACPI (Advanced Configuration and Power Interface) support. Use
737
it if your guest OS complains about ACPI problems (PC target machine
738
only).
739
ETEXI
740

    
741
#ifdef TARGET_I386
742
DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
743
    "-no-hpet        disable HPET\n")
744
#endif
745
STEXI
746
@item -no-hpet
747
Disable HPET support.
748
ETEXI
749

    
750
#ifdef TARGET_I386
751
DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
752
    "-balloon none   disable balloon device\n"
753
    "-balloon virtio[,addr=str]\n"
754
    "                enable virtio balloon device (default)\n")
755
#endif
756
STEXI
757
@item -balloon none
758
Disable balloon device.
759
@item -balloon virtio[,addr=@var{addr}]
760
Enable virtio balloon device (default), optionally with PCI address
761
@var{addr}.
762
ETEXI
763

    
764
#ifdef TARGET_I386
765
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
766
    "-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"
767
    "                ACPI table description\n")
768
#endif
769
STEXI
770
@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}]...]
771
Add ACPI table with specified header fields and context from specified files.
772
ETEXI
773

    
774
#ifdef TARGET_I386
775
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
776
    "-smbios file=binary\n"
777
    "                load SMBIOS entry from binary file\n"
778
    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%%d.%%d]\n"
779
    "                specify SMBIOS type 0 fields\n"
780
    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
781
    "              [,uuid=uuid][,sku=str][,family=str]\n"
782
    "                specify SMBIOS type 1 fields\n")
783
#endif
784
STEXI
785
@item -smbios file=@var{binary}
786
Load SMBIOS entry from binary file.
787

    
788
@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
789
Specify SMBIOS type 0 fields
790

    
791
@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}]
792
Specify SMBIOS type 1 fields
793
ETEXI
794

    
795
#ifdef TARGET_I386
796
DEFHEADING()
797
#endif
798
STEXI
799
@end table
800
ETEXI
801

    
802
DEFHEADING(Network options:)
803
STEXI
804
@table @option
805
ETEXI
806

    
807
HXCOMM Legacy slirp options (now moved to -net user):
808
#ifdef CONFIG_SLIRP
809
DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "")
810
DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "")
811
DEF("redir", HAS_ARG, QEMU_OPTION_redir, "")
812
#ifndef _WIN32
813
DEF("smb", HAS_ARG, QEMU_OPTION_smb, "")
814
#endif
815
#endif
816

    
817
DEF("net", HAS_ARG, QEMU_OPTION_net,
818
    "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
819
    "                create a new Network Interface Card and connect it to VLAN 'n'\n"
820
#ifdef CONFIG_SLIRP
821
    "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=y|n]\n"
822
    "         [,hostname=host][,dhcpstart=addr][,dns=addr][,tftp=dir][,bootfile=f]\n"
823
    "         [,hostfwd=rule][,guestfwd=rule]"
824
#ifndef _WIN32
825
                                             "[,smb=dir[,smbserver=addr]]\n"
826
#endif
827
    "                connect the user mode network stack to VLAN 'n', configure its\n"
828
    "                DHCP server and enabled optional services\n"
829
#endif
830
#ifdef _WIN32
831
    "-net tap[,vlan=n][,name=str],ifname=name\n"
832
    "                connect the host TAP network interface to VLAN 'n'\n"
833
#else
834
    "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,sndbuf=nbytes][,vnet_hdr=on|off]\n"
835
    "                connect the host TAP network interface to VLAN 'n' and use the\n"
836
    "                network scripts 'file' (default=%s)\n"
837
    "                and 'dfile' (default=%s)\n"
838
    "                use '[down]script=no' to disable script execution\n"
839
    "                use 'fd=h' to connect to an already opened TAP interface\n"
840
    "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
841
    "                default of 'sndbuf=1048576' can be disabled using 'sndbuf=0')\n"
842
    "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
843
    "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
844
#endif
845
    "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
846
    "                connect the vlan 'n' to another VLAN using a socket connection\n"
847
    "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port]\n"
848
    "                connect the vlan 'n' to multicast maddr and port\n"
849
#ifdef CONFIG_VDE
850
    "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
851
    "                connect the vlan 'n' to port 'n' of a vde switch running\n"
852
    "                on host and listening for incoming connections on 'socketpath'.\n"
853
    "                Use group 'groupname' and mode 'octalmode' to change default\n"
854
    "                ownership and permissions for communication port.\n"
855
#endif
856
    "-net dump[,vlan=n][,file=f][,len=n]\n"
857
    "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
858
    "-net none       use it alone to have zero network devices. If no -net option\n"
859
    "                is provided, the default is '-net nic -net user'\n")
860
DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
861
    "-netdev ["
862
#ifdef CONFIG_SLIRP
863
    "user|"
864
#endif
865
    "tap|"
866
#ifdef CONFIG_VDE
867
    "vde|"
868
#endif
869
    "socket],id=str[,option][,option][,...]\n")
870
STEXI
871
@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}][,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
872
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
873
= 0 is the default). The NIC is an e1000 by default on the PC
874
target. Optionally, the MAC address can be changed to @var{mac}, the
875
device address set to @var{addr} (PCI cards only),
876
and a @var{name} can be assigned for use in monitor commands.
877
Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
878
that the card should have; this option currently only affects virtio cards; set
879
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
880
NIC is created.  Qemu can emulate several different models of network card.
881
Valid values for @var{type} are
882
@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
883
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
884
@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
885
Not all devices are supported on all targets.  Use -net nic,model=?
886
for a list of available devices for your target.
887

    
888
@item -net user[,@var{option}][,@var{option}][,...]
889
Use the user mode network stack which requires no administrator
890
privilege to run. Valid options are:
891

    
892
@table @option
893
@item vlan=@var{n}
894
Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
895

    
896
@item name=@var{name}
897
Assign symbolic name for use in monitor commands.
898

    
899
@item net=@var{addr}[/@var{mask}]
900
Set IP network address the guest will see. Optionally specify the netmask,
901
either in the form a.b.c.d or as number of valid top-most bits. Default is
902
10.0.2.0/8.
903

    
904
@item host=@var{addr}
905
Specify the guest-visible address of the host. Default is the 2nd IP in the
906
guest network, i.e. x.x.x.2.
907

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

    
913
@item hostname=@var{name}
914
Specifies the client hostname reported by the builtin DHCP server.
915

    
916
@item dhcpstart=@var{addr}
917
Specify the first of the 16 IPs the built-in DHCP server can assign. Default
918
is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to x.x.x.31.
919

    
920
@item dns=@var{addr}
921
Specify the guest-visible address of the virtual nameserver. The address must
922
be different from the host address. Default is the 3rd IP in the guest network,
923
i.e. x.x.x.3.
924

    
925
@item tftp=@var{dir}
926
When using the user mode network stack, activate a built-in TFTP
927
server. The files in @var{dir} will be exposed as the root of a TFTP server.
928
The TFTP client on the guest must be configured in binary mode (use the command
929
@code{bin} of the Unix TFTP client).
930

    
931
@item bootfile=@var{file}
932
When using the user mode network stack, broadcast @var{file} as the BOOTP
933
filename. In conjunction with @option{tftp}, this can be used to network boot
934
a guest from a local directory.
935

    
936
Example (using pxelinux):
937
@example
938
qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
939
@end example
940

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

    
947
In the guest Windows OS, the line:
948
@example
949
10.0.2.4 smbserver
950
@end example
951
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
952
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
953

    
954
Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
955

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

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

    
968
For example, to redirect host X11 connection from screen 1 to guest
969
screen 0, use the following:
970

    
971
@example
972
# on the host
973
qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
974
# this host xterm should open in the guest X11 server
975
xterm -display :1
976
@end example
977

    
978
To redirect telnet connections from host port 5555 to telnet port on
979
the guest, use the following:
980

    
981
@example
982
# on the host
983
qemu -net user,hostfwd=tcp:5555::23 [...]
984
telnet localhost 5555
985
@end example
986

    
987
Then when you use on the host @code{telnet localhost 5555}, you
988
connect to the guest telnet server.
989

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

    
994
@end table
995

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

    
1001
@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
1002
Connect the host TAP network interface @var{name} to VLAN @var{n}, use
1003
the network script @var{file} to configure it and the network script
1004
@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1005
automatically provides one. @option{fd}=@var{h} can be used to specify
1006
the handle of an already opened host TAP interface. The default network
1007
configure script is @file{/etc/qemu-ifup} and the default network
1008
deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
1009
or @option{downscript=no} to disable script execution. Example:
1010

    
1011
@example
1012
qemu linux.img -net nic -net tap
1013
@end example
1014

    
1015
More complicated example (two NICs, each one connected to a TAP device)
1016
@example
1017
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1018
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1019
@end example
1020

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

    
1023
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1024
machine using a TCP socket connection. If @option{listen} is
1025
specified, QEMU waits for incoming connections on @var{port}
1026
(@var{host} is optional). @option{connect} is used to connect to
1027
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1028
specifies an already opened TCP socket.
1029

    
1030
Example:
1031
@example
1032
# launch a first QEMU instance
1033
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1034
               -net socket,listen=:1234
1035
# connect the VLAN 0 of this instance to the VLAN 0
1036
# of the first instance
1037
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1038
               -net socket,connect=127.0.0.1:1234
1039
@end example
1040

    
1041
@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
1042

    
1043
Create a VLAN @var{n} shared with another QEMU virtual
1044
machines using a UDP multicast socket, effectively making a bus for
1045
every QEMU with same multicast address @var{maddr} and @var{port}.
1046
NOTES:
1047
@enumerate
1048
@item
1049
Several QEMU can be running on different hosts and share same bus (assuming
1050
correct multicast setup for these hosts).
1051
@item
1052
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1053
@url{http://user-mode-linux.sf.net}.
1054
@item
1055
Use @option{fd=h} to specify an already opened UDP multicast socket.
1056
@end enumerate
1057

    
1058
Example:
1059
@example
1060
# launch one QEMU instance
1061
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1062
               -net socket,mcast=230.0.0.1:1234
1063
# launch another QEMU instance on same "bus"
1064
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1065
               -net socket,mcast=230.0.0.1:1234
1066
# launch yet another QEMU instance on same "bus"
1067
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1068
               -net socket,mcast=230.0.0.1:1234
1069
@end example
1070

    
1071
Example (User Mode Linux compat.):
1072
@example
1073
# launch QEMU instance (note mcast address selected
1074
# is UML's default)
1075
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1076
               -net socket,mcast=239.192.168.1:1102
1077
# launch UML
1078
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
1079
@end example
1080

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

    
1088
Example:
1089
@example
1090
# launch vde switch
1091
vde_switch -F -sock /tmp/myswitch
1092
# launch QEMU instance
1093
qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1094
@end example
1095

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

    
1101
@item -net none
1102
Indicate that no network devices should be configured. It is used to
1103
override the default configuration (@option{-net nic -net user}) which
1104
is activated if no @option{-net} options are provided.
1105

    
1106
@end table
1107
ETEXI
1108

    
1109
DEFHEADING()
1110

    
1111
DEFHEADING(Character device options:)
1112

    
1113
DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1114
    "-chardev null,id=id\n"
1115
    "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1116
    "         [,server][,nowait][,telnet] (tcp)\n"
1117
    "-chardev socket,id=id,path=path[,server][,nowait][,telnet] (unix)\n"
1118
    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1119
    "         [,localport=localport][,ipv4][,ipv6]\n"
1120
    "-chardev msmouse,id=id\n"
1121
    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1122
    "-chardev file,id=id,path=path\n"
1123
    "-chardev pipe,id=id,path=path\n"
1124
#ifdef _WIN32
1125
    "-chardev console,id=id\n"
1126
    "-chardev serial,id=id,path=path\n"
1127
#else
1128
    "-chardev pty,id=id\n"
1129
    "-chardev stdio,id=id\n"
1130
#endif
1131
#ifdef CONFIG_BRLAPI
1132
    "-chardev braille,id=id\n"
1133
#endif
1134
#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1135
        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1136
    "-chardev tty,id=id,path=path\n"
1137
#endif
1138
#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1139
    "-chardev parport,id=id,path=path\n"
1140
#endif
1141
)
1142

    
1143
STEXI
1144

    
1145
The general form of a character device option is:
1146
@table @option
1147

    
1148
@item -chardev @var{backend} ,id=@var{id} [,@var{options}]
1149

    
1150
Backend is one of:
1151
@option{null},
1152
@option{socket},
1153
@option{udp},
1154
@option{msmouse},
1155
@option{vc},
1156
@option{file},
1157
@option{pipe},
1158
@option{console},
1159
@option{serial},
1160
@option{pty},
1161
@option{stdio},
1162
@option{braille},
1163
@option{tty},
1164
@option{parport}.
1165
The specific backend will determine the applicable options.
1166

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

    
1170
Options to each backend are described below.
1171

    
1172
@item -chardev null ,id=@var{id}
1173
A void device. This device will not emit any data, and will drop any data it
1174
receives. The null backend does not take any options.
1175

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

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

    
1182
@option{server} specifies that the socket shall be a listening socket.
1183

    
1184
@option{nowait} specifies that QEMU should not block waiting for a client to
1185
connect to a listening socket.
1186

    
1187
@option{telnet} specifies that traffic on the socket should interpret telnet
1188
escape sequences.
1189

    
1190
TCP and unix socket options are given below:
1191

    
1192
@table @option
1193

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

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

    
1200
@option{port} for a listening socket specifies the local port to be bound. For a
1201
connecting socket specifies the port on the remote host to connect to.
1202
@option{port} can be given as either a port number or a service name.
1203
@option{port} is required.
1204

    
1205
@option{to} is only relevant to listening sockets. If it is specified, and
1206
@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1207
to and including @option{to} until it succeeds. @option{to} must be specified
1208
as a port number.
1209

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

    
1213
@option{nodelay} disables the Nagle algorithm.
1214

    
1215
@item unix options: path=@var{path}
1216

    
1217
@option{path} specifies the local path of the unix socket. @option{path} is
1218
required.
1219

    
1220
@end table
1221

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

    
1224
Sends all traffic from the guest to a remote host over UDP.
1225

    
1226
@option{host} specifies the remote host to connect to. If not specified it
1227
defaults to @code{localhost}.
1228

    
1229
@option{port} specifies the port on the remote host to connect to. @option{port}
1230
is required.
1231

    
1232
@option{localaddr} specifies the local address to bind to. If not specified it
1233
defaults to @code{0.0.0.0}.
1234

    
1235
@option{localport} specifies the local port to bind to. If not specified any
1236
available local port will be used.
1237

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

    
1241
@item -chardev msmouse ,id=@var{id}
1242

    
1243
Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1244
take any options.
1245

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

    
1248
Connect to a QEMU text console. @option{vc} may optionally be given a specific
1249
size.
1250

    
1251
@option{width} and @option{height} specify the width and height respectively of
1252
the console, in pixels.
1253

    
1254
@option{cols} and @option{rows} specify that the console be sized to fit a text
1255
console with the given dimensions.
1256

    
1257
@item -chardev file ,id=@var{id} ,path=@var{path}
1258

    
1259
Log all traffic received from the guest to a file.
1260

    
1261
@option{path} specifies the path of the file to be opened. This file will be
1262
created if it does not already exist, and overwritten if it does. @option{path}
1263
is required.
1264

    
1265
@item -chardev pipe ,id=@var{id} ,path=@var{path}
1266

    
1267
Create a two-way connection to the guest. The behaviour differs slightly between
1268
Windows hosts and other hosts:
1269

    
1270
On Windows, a single duplex pipe will be created at
1271
@file{\\.pipe\@option{path}}.
1272

    
1273
On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1274
@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1275
received by the guest. Data written by the guest can be read from
1276
@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1277
be present.
1278

    
1279
@option{path} forms part of the pipe path as described above. @option{path} is
1280
required.
1281

    
1282
@item -chardev console ,id=@var{id}
1283

    
1284
Send traffic from the guest to QEMU's standard output. @option{console} does not
1285
take any options.
1286

    
1287
@option{console} is only available on Windows hosts.
1288

    
1289
@item -chardev serial ,id=@var{id} ,path=@option{path}
1290

    
1291
Send traffic from the guest to a serial device on the host.
1292

    
1293
@option{serial} is
1294
only available on Windows hosts.
1295

    
1296
@option{path} specifies the name of the serial device to open.
1297

    
1298
@item -chardev pty ,id=@var{id}
1299

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

    
1303
@option{pty} is not available on Windows hosts.
1304

    
1305
@item -chardev stdio ,id=@var{id}
1306
Connect to standard input and standard output of the qemu process.
1307
@option{stdio} does not take any options. @option{stdio} is not available on
1308
Windows hosts.
1309

    
1310
@item -chardev braille ,id=@var{id}
1311

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

    
1314
@item -chardev tty ,id=@var{id} ,path=@var{path}
1315

    
1316
Connect to a local tty device.
1317

    
1318
@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1319
DragonFlyBSD hosts.
1320

    
1321
@option{path} specifies the path to the tty. @option{path} is required.
1322

    
1323
@item -chardev parport ,id=@var{id} ,path=@var{path}
1324

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

    
1327
Connect to a local parallel port.
1328

    
1329
@option{path} specifies the path to the parallel port device. @option{path} is
1330
required.
1331

    
1332
@end table
1333
ETEXI
1334

    
1335
DEFHEADING()
1336

    
1337
DEFHEADING(Bluetooth(R) options:)
1338

    
1339
DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1340
    "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
1341
    "-bt hci,host[:id]\n" \
1342
    "                use host's HCI with the given name\n" \
1343
    "-bt hci[,vlan=n]\n" \
1344
    "                emulate a standard HCI in virtual scatternet 'n'\n" \
1345
    "-bt vhci[,vlan=n]\n" \
1346
    "                add host computer to virtual scatternet 'n' using VHCI\n" \
1347
    "-bt device:dev[,vlan=n]\n" \
1348
    "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
1349
STEXI
1350
@table @option
1351

    
1352
@item -bt hci[...]
1353
Defines the function of the corresponding Bluetooth HCI.  -bt options
1354
are matched with the HCIs present in the chosen machine type.  For
1355
example when emulating a machine with only one HCI built into it, only
1356
the first @code{-bt hci[...]} option is valid and defines the HCI's
1357
logic.  The Transport Layer is decided by the machine type.  Currently
1358
the machines @code{n800} and @code{n810} have one HCI and all other
1359
machines have none.
1360

    
1361
@anchor{bt-hcis}
1362
The following three types are recognized:
1363

    
1364
@table @option
1365
@item -bt hci,null
1366
(default) The corresponding Bluetooth HCI assumes no internal logic
1367
and will not respond to any HCI commands or emit events.
1368

    
1369
@item -bt hci,host[:@var{id}]
1370
(@code{bluez} only) The corresponding HCI passes commands / events
1371
to / from the physical HCI identified by the name @var{id} (default:
1372
@code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1373
capable systems like Linux.
1374

    
1375
@item -bt hci[,vlan=@var{n}]
1376
Add a virtual, standard HCI that will participate in the Bluetooth
1377
scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1378
VLANs, devices inside a bluetooth network @var{n} can only communicate
1379
with other devices in the same network (scatternet).
1380
@end table
1381

    
1382
@item -bt vhci[,vlan=@var{n}]
1383
(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1384
to the host bluetooth stack instead of to the emulated target.  This
1385
allows the host and target machines to participate in a common scatternet
1386
and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1387
be used as following:
1388

    
1389
@example
1390
qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1391
@end example
1392

    
1393
@item -bt device:@var{dev}[,vlan=@var{n}]
1394
Emulate a bluetooth device @var{dev} and place it in network @var{n}
1395
(default @code{0}).  QEMU can only emulate one type of bluetooth devices
1396
currently:
1397

    
1398
@table @option
1399
@item keyboard
1400
Virtual wireless keyboard implementing the HIDP bluetooth profile.
1401
@end table
1402
@end table
1403
ETEXI
1404

    
1405
DEFHEADING()
1406

    
1407
DEFHEADING(Linux/Multiboot boot specific:)
1408
STEXI
1409

    
1410
When using these options, you can use a given Linux or Multiboot
1411
kernel without installing it in the disk image. It can be useful
1412
for easier testing of various kernels.
1413

    
1414
@table @option
1415
ETEXI
1416

    
1417
DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1418
    "-kernel bzImage use 'bzImage' as kernel image\n")
1419
STEXI
1420
@item -kernel @var{bzImage}
1421
Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1422
or in multiboot format.
1423
ETEXI
1424

    
1425
DEF("append", HAS_ARG, QEMU_OPTION_append, \
1426
    "-append cmdline use 'cmdline' as kernel command line\n")
1427
STEXI
1428
@item -append @var{cmdline}
1429
Use @var{cmdline} as kernel command line
1430
ETEXI
1431

    
1432
DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1433
           "-initrd file    use 'file' as initial ram disk\n")
1434
STEXI
1435
@item -initrd @var{file}
1436
Use @var{file} as initial ram disk.
1437

    
1438
@item -initrd "@var{file1} arg=foo,@var{file2}"
1439

    
1440
This syntax is only available with multiboot.
1441

    
1442
Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
1443
first module.
1444
ETEXI
1445

    
1446
STEXI
1447
@end table
1448
ETEXI
1449

    
1450
DEFHEADING()
1451

    
1452
DEFHEADING(Debug/Expert options:)
1453

    
1454
STEXI
1455
@table @option
1456
ETEXI
1457

    
1458
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1459
    "-serial dev     redirect the serial port to char device 'dev'\n")
1460
STEXI
1461
@item -serial @var{dev}
1462
Redirect the virtual serial port to host character device
1463
@var{dev}. The default device is @code{vc} in graphical mode and
1464
@code{stdio} in non graphical mode.
1465

    
1466
This option can be used several times to simulate up to 4 serial
1467
ports.
1468

    
1469
Use @code{-serial none} to disable all serial ports.
1470

    
1471
Available character devices are:
1472
@table @option
1473
@item vc[:@var{W}x@var{H}]
1474
Virtual console. Optionally, a width and height can be given in pixel with
1475
@example
1476
vc:800x600
1477
@end example
1478
It is also possible to specify width or height in characters:
1479
@example
1480
vc:80Cx24C
1481
@end example
1482
@item pty
1483
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
1484
@item none
1485
No device is allocated.
1486
@item null
1487
void device
1488
@item /dev/XXX
1489
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
1490
parameters are set according to the emulated ones.
1491
@item /dev/parport@var{N}
1492
[Linux only, parallel port only] Use host parallel port
1493
@var{N}. Currently SPP and EPP parallel port features can be used.
1494
@item file:@var{filename}
1495
Write output to @var{filename}. No character can be read.
1496
@item stdio
1497
[Unix only] standard input/output
1498
@item pipe:@var{filename}
1499
name pipe @var{filename}
1500
@item COM@var{n}
1501
[Windows only] Use host serial port @var{n}
1502
@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
1503
This implements UDP Net Console.
1504
When @var{remote_host} or @var{src_ip} are not specified
1505
they default to @code{0.0.0.0}.
1506
When not using a specified @var{src_port} a random port is automatically chosen.
1507

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

    
1513
If you plan to send characters back via netconsole or you want to stop
1514
and start qemu a lot of times, you should have qemu use the same
1515
source port each time by using something like @code{-serial
1516
udp::4555@@:4556} to qemu. Another approach is to use a patched
1517
version of netcat which can listen to a TCP port and send and receive
1518
characters via udp.  If you have a patched version of netcat which
1519
activates telnet remote echo and single char transfer, then you can
1520
use the following options to step up a netcat redirector to allow
1521
telnet on port 5555 to access the qemu port.
1522
@table @code
1523
@item Qemu Options:
1524
-serial udp::4555@@:4556
1525
@item netcat options:
1526
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
1527
@item telnet options:
1528
localhost 5555
1529
@end table
1530

    
1531
@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
1532
The TCP Net Console has two modes of operation.  It can send the serial
1533
I/O to a location or wait for a connection from a location.  By default
1534
the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
1535
the @var{server} option QEMU will wait for a client socket application
1536
to connect to the port before continuing, unless the @code{nowait}
1537
option was specified.  The @code{nodelay} option disables the Nagle buffering
1538
algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
1539
one TCP connection at a time is accepted. You can use @code{telnet} to
1540
connect to the corresponding character device.
1541
@table @code
1542
@item Example to send tcp console to 192.168.0.2 port 4444
1543
-serial tcp:192.168.0.2:4444
1544
@item Example to listen and wait on port 4444 for connection
1545
-serial tcp::4444,server
1546
@item Example to not wait and listen on ip 192.168.0.100 port 4444
1547
-serial tcp:192.168.0.100:4444,server,nowait
1548
@end table
1549

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

    
1559
@item unix:@var{path}[,server][,nowait]
1560
A unix domain socket is used instead of a tcp socket.  The option works the
1561
same as if you had specified @code{-serial tcp} except the unix domain socket
1562
@var{path} is used for connections.
1563

    
1564
@item mon:@var{dev_string}
1565
This is a special option to allow the monitor to be multiplexed onto
1566
another serial port.  The monitor is accessed with key sequence of
1567
@key{Control-a} and then pressing @key{c}. See monitor access
1568
@ref{pcsys_keys} in the -nographic section for more keys.
1569
@var{dev_string} should be any one of the serial devices specified
1570
above.  An example to multiplex the monitor onto a telnet server
1571
listening on port 4444 would be:
1572
@table @code
1573
@item -serial mon:telnet::4444,server,nowait
1574
@end table
1575

    
1576
@item braille
1577
Braille device.  This will use BrlAPI to display the braille output on a real
1578
or fake device.
1579

    
1580
@item msmouse
1581
Three button serial mouse. Configure the guest to use Microsoft protocol.
1582
@end table
1583
ETEXI
1584

    
1585
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
1586
    "-parallel dev   redirect the parallel port to char device 'dev'\n")
1587
STEXI
1588
@item -parallel @var{dev}
1589
Redirect the virtual parallel port to host device @var{dev} (same
1590
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1591
be used to use hardware devices connected on the corresponding host
1592
parallel port.
1593

    
1594
This option can be used several times to simulate up to 3 parallel
1595
ports.
1596

    
1597
Use @code{-parallel none} to disable all parallel ports.
1598
ETEXI
1599

    
1600
DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
1601
    "-monitor dev    redirect the monitor to char device 'dev'\n")
1602
STEXI
1603
@item -monitor @var{dev}
1604
Redirect the monitor to host device @var{dev} (same devices as the
1605
serial port).
1606
The default device is @code{vc} in graphical mode and @code{stdio} in
1607
non graphical mode.
1608
ETEXI
1609
DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
1610
    "-qmp dev        like -monitor but opens in 'control' mode\n")
1611
STEXI
1612
@item -qmp @var{dev}
1613
Like -monitor but opens in 'control' mode.
1614
ETEXI
1615

    
1616
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
1617
    "-mon chardev=[name][,mode=readline|control][,default]\n")
1618
STEXI
1619
@item -mon chardev=[name][,mode=readline|control][,default]
1620
Setup monitor on chardev @var{name}.
1621
ETEXI
1622

    
1623
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
1624
    "-debugcon dev   redirect the debug console to char device 'dev'\n")
1625
STEXI
1626
@item -debugcon @var{dev}
1627
Redirect the debug console to host device @var{dev} (same devices as the
1628
serial port).  The debug console is an I/O port which is typically port
1629
0xe9; writing to that I/O port sends output to this device.
1630
The default device is @code{vc} in graphical mode and @code{stdio} in
1631
non graphical mode.
1632
ETEXI
1633

    
1634
DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
1635
    "-pidfile file   write PID to 'file'\n")
1636
STEXI
1637
@item -pidfile @var{file}
1638
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
1639
from a script.
1640
ETEXI
1641

    
1642
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
1643
    "-singlestep     always run in singlestep mode\n")
1644
STEXI
1645
@item -singlestep
1646
Run the emulation in single step mode.
1647
ETEXI
1648

    
1649
DEF("S", 0, QEMU_OPTION_S, \
1650
    "-S              freeze CPU at startup (use 'c' to start execution)\n")
1651
STEXI
1652
@item -S
1653
Do not start CPU at startup (you must type 'c' in the monitor).
1654
ETEXI
1655

    
1656
DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
1657
    "-gdb dev        wait for gdb connection on 'dev'\n")
1658
STEXI
1659
@item -gdb @var{dev}
1660
Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
1661
connections will likely be TCP-based, but also UDP, pseudo TTY, or even
1662
stdio are reasonable use case. The latter is allowing to start qemu from
1663
within gdb and establish the connection via a pipe:
1664
@example
1665
(gdb) target remote | exec qemu -gdb stdio ...
1666
@end example
1667
ETEXI
1668

    
1669
DEF("s", 0, QEMU_OPTION_s, \
1670
    "-s              shorthand for -gdb tcp::%s\n")
1671
STEXI
1672
@item -s
1673
Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
1674
(@pxref{gdb_usage}).
1675
ETEXI
1676

    
1677
DEF("d", HAS_ARG, QEMU_OPTION_d, \
1678
    "-d item1,...    output log to %s (use -d ? for a list of log items)\n")
1679
STEXI
1680
@item -d
1681
Output log in /tmp/qemu.log
1682
ETEXI
1683

    
1684
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
1685
    "-hdachs c,h,s[,t]\n" \
1686
    "                force hard disk 0 physical geometry and the optional BIOS\n" \
1687
    "                translation (t=none or lba) (usually qemu can guess them)\n")
1688
STEXI
1689
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
1690
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1691
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1692
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
1693
all those parameters. This option is useful for old MS-DOS disk
1694
images.
1695
ETEXI
1696

    
1697
DEF("L", HAS_ARG, QEMU_OPTION_L, \
1698
    "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n")
1699
STEXI
1700
@item -L  @var{path}
1701
Set the directory for the BIOS, VGA BIOS and keymaps.
1702
ETEXI
1703

    
1704
DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
1705
    "-bios file      set the filename for the BIOS\n")
1706
STEXI
1707
@item -bios @var{file}
1708
Set the filename for the BIOS.
1709
ETEXI
1710

    
1711
#ifdef CONFIG_KVM
1712
DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
1713
    "-enable-kvm     enable KVM full virtualization support\n")
1714
#endif
1715
STEXI
1716
@item -enable-kvm
1717
Enable KVM full virtualization support. This option is only available
1718
if KVM support is enabled when compiling.
1719
ETEXI
1720

    
1721
#ifdef CONFIG_XEN
1722
DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
1723
    "-xen-domid id   specify xen guest domain id\n")
1724
DEF("xen-create", 0, QEMU_OPTION_xen_create,
1725
    "-xen-create     create domain using xen hypercalls, bypassing xend\n"
1726
    "                warning: should not be used when xend is in use\n")
1727
DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
1728
    "-xen-attach     attach to existing xen domain\n"
1729
    "                xend will use this when starting qemu\n")
1730
#endif
1731
STEXI
1732
@item -xen-domid @var{id}
1733
Specify xen guest domain @var{id} (XEN only).
1734
@item -xen-create
1735
Create domain using xen hypercalls, bypassing xend.
1736
Warning: should not be used when xend is in use (XEN only).
1737
@item -xen-attach
1738
Attach to existing xen domain.
1739
xend will use this when starting qemu (XEN only).
1740
ETEXI
1741

    
1742
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
1743
    "-no-reboot      exit instead of rebooting\n")
1744
STEXI
1745
@item -no-reboot
1746
Exit instead of rebooting.
1747
ETEXI
1748

    
1749
DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
1750
    "-no-shutdown    stop before shutdown\n")
1751
STEXI
1752
@item -no-shutdown
1753
Don't exit QEMU on guest shutdown, but instead only stop the emulation.
1754
This allows for instance switching to monitor to commit changes to the
1755
disk image.
1756
ETEXI
1757

    
1758
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
1759
    "-loadvm [tag|id]\n" \
1760
    "                start right away with a saved state (loadvm in monitor)\n")
1761
STEXI
1762
@item -loadvm @var{file}
1763
Start right away with a saved state (@code{loadvm} in monitor)
1764
ETEXI
1765

    
1766
#ifndef _WIN32
1767
DEF("daemonize", 0, QEMU_OPTION_daemonize, \
1768
    "-daemonize      daemonize QEMU after initializing\n")
1769
#endif
1770
STEXI
1771
@item -daemonize
1772
Daemonize the QEMU process after initialization.  QEMU will not detach from
1773
standard IO until it is ready to receive connections on any of its devices.
1774
This option is a useful way for external programs to launch QEMU without having
1775
to cope with initialization race conditions.
1776
ETEXI
1777

    
1778
DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
1779
    "-option-rom rom load a file, rom, into the option ROM space\n")
1780
STEXI
1781
@item -option-rom @var{file}
1782
Load the contents of @var{file} as an option ROM.
1783
This option is useful to load things like EtherBoot.
1784
ETEXI
1785

    
1786
DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
1787
    "-clock          force the use of the given methods for timer alarm.\n" \
1788
    "                To see what timers are available use -clock ?\n")
1789
STEXI
1790
@item -clock @var{method}
1791
Force the use of the given methods for timer alarm. To see what timers
1792
are available use -clock ?.
1793
ETEXI
1794

    
1795
HXCOMM Options deprecated by -rtc
1796
DEF("localtime", 0, QEMU_OPTION_localtime, "")
1797
DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "")
1798

    
1799
#ifdef TARGET_I386
1800
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
1801
    "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
1802
    "                set the RTC base and clock, enable drift fix for clock ticks\n")
1803
#else
1804
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
1805
    "-rtc [base=utc|localtime|date][,clock=host|vm]\n" \
1806
    "                set the RTC base and clock\n")
1807
#endif
1808

    
1809
STEXI
1810

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

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

    
1823
Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
1824
specifically with Windows' ACPI HAL. This option will try to figure out how
1825
many timer interrupts were not processed by the Windows guest and will
1826
re-inject them.
1827
ETEXI
1828

    
1829
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
1830
    "-icount [N|auto]\n" \
1831
    "                enable virtual instruction counter with 2^N clock ticks per\n" \
1832
    "                instruction\n")
1833
STEXI
1834
@item -icount [@var{N}|auto]
1835
Enable virtual instruction counter.  The virtual cpu will execute one
1836
instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
1837
then the virtual cpu speed will be automatically adjusted to keep virtual
1838
time within a few seconds of real time.
1839

    
1840
Note that while this option can give deterministic behavior, it does not
1841
provide cycle accurate emulation.  Modern CPUs contain superscalar out of
1842
order cores with complex cache hierarchies.  The number of instructions
1843
executed often has little or no correlation with actual performance.
1844
ETEXI
1845

    
1846
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
1847
    "-watchdog i6300esb|ib700\n" \
1848
    "                enable virtual hardware watchdog [default=none]\n")
1849
STEXI
1850
@item -watchdog @var{model}
1851
Create a virtual hardware watchdog device.  Once enabled (by a guest
1852
action), the watchdog must be periodically polled by an agent inside
1853
the guest or else the guest will be restarted.
1854

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

    
1861
Use @code{-watchdog ?} to list available hardware models.  Only one
1862
watchdog can be enabled for a guest.
1863
ETEXI
1864

    
1865
DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
1866
    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
1867
    "                action when watchdog fires [default=reset]\n")
1868
STEXI
1869
@item -watchdog-action @var{action}
1870

    
1871
The @var{action} controls what QEMU will do when the watchdog timer
1872
expires.
1873
The default is
1874
@code{reset} (forcefully reset the guest).
1875
Other possible actions are:
1876
@code{shutdown} (attempt to gracefully shutdown the guest),
1877
@code{poweroff} (forcefully poweroff the guest),
1878
@code{pause} (pause the guest),
1879
@code{debug} (print a debug message and continue), or
1880
@code{none} (do nothing).
1881

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

    
1887
Examples:
1888

    
1889
@table @code
1890
@item -watchdog i6300esb -watchdog-action pause
1891
@item -watchdog ib700
1892
@end table
1893
ETEXI
1894

    
1895
DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
1896
    "-echr chr       set terminal escape character instead of ctrl-a\n")
1897
STEXI
1898

    
1899
@item -echr @var{numeric_ascii_value}
1900
Change the escape character used for switching to the monitor when using
1901
monitor and serial sharing.  The default is @code{0x01} when using the
1902
@code{-nographic} option.  @code{0x01} is equal to pressing
1903
@code{Control-a}.  You can select a different character from the ascii
1904
control keys where 1 through 26 map to Control-a through Control-z.  For
1905
instance you could use the either of the following to change the escape
1906
character to Control-t.
1907
@table @code
1908
@item -echr 0x14
1909
@item -echr 20
1910
@end table
1911
ETEXI
1912

    
1913
DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
1914
    "-virtioconsole c\n" \
1915
    "                set virtio console\n")
1916
STEXI
1917
@item -virtioconsole @var{c}
1918
Set virtio console.
1919

    
1920
This option is maintained for backward compatibility.
1921

    
1922
Please use @code{-device virtconsole} for the new way of invocation.
1923
ETEXI
1924

    
1925
DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
1926
    "-show-cursor    show cursor\n")
1927
STEXI
1928
@item -show-cursor
1929
Show cursor.
1930
ETEXI
1931

    
1932
DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
1933
    "-tb-size n      set TB size\n")
1934
STEXI
1935
@item -tb-size @var{n}
1936
Set TB size.
1937
ETEXI
1938

    
1939
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
1940
    "-incoming p     prepare for incoming migration, listen on port p\n")
1941
STEXI
1942
@item -incoming @var{port}
1943
Prepare for incoming migration, listen on @var{port}.
1944
ETEXI
1945

    
1946
DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
1947
    "-nodefaults     don't create default devices\n")
1948
STEXI
1949
@item -nodefaults
1950
Don't create default devices.
1951
ETEXI
1952

    
1953
#ifndef _WIN32
1954
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
1955
    "-chroot dir     chroot to dir just before starting the VM\n")
1956
#endif
1957
STEXI
1958
@item -chroot @var{dir}
1959
Immediately before starting guest execution, chroot to the specified
1960
directory.  Especially useful in combination with -runas.
1961
ETEXI
1962

    
1963
#ifndef _WIN32
1964
DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
1965
    "-runas user     change to user id user just before starting the VM\n")
1966
#endif
1967
STEXI
1968
@item -runas @var{user}
1969
Immediately before starting guest execution, drop root privileges, switching
1970
to the specified user.
1971
ETEXI
1972

    
1973
#if defined(TARGET_SPARC) || defined(TARGET_PPC)
1974
DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
1975
    "-prom-env variable=value\n"
1976
    "                set OpenBIOS nvram variables\n")
1977
#endif
1978
STEXI
1979
@item -prom-env @var{variable}=@var{value}
1980
Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
1981
ETEXI
1982
#if defined(TARGET_ARM) || defined(TARGET_M68K)
1983
DEF("semihosting", 0, QEMU_OPTION_semihosting,
1984
    "-semihosting    semihosting mode\n")
1985
#endif
1986
STEXI
1987
@item -semihosting
1988
Semihosting mode (ARM, M68K only).
1989
ETEXI
1990
#if defined(TARGET_ARM)
1991
DEF("old-param", 0, QEMU_OPTION_old_param,
1992
    "-old-param      old param mode\n")
1993
#endif
1994
STEXI
1995
@item -old-param
1996
Old param mode (ARM only).
1997
ETEXI
1998

    
1999
DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2000
    "-readconfig <file>\n")
2001
STEXI
2002
@item -readconfig @var{file}
2003
Read device configuration from @var{file}.
2004
ETEXI
2005
DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2006
    "-writeconfig <file>\n"
2007
    "                read/write config file\n")
2008
STEXI
2009
@item -writeconfig @var{file}
2010
Write device configuration to @var{file}.
2011
ETEXI
2012
DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2013
    "-nodefconfig\n"
2014
    "                do not load default config files at startup\n")
2015
STEXI
2016
@item -nodefconfig
2017
Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2018
@var{sysconfdir}/target-@var{ARCH}.conf on startup.  The @code{-nodefconfig}
2019
option will prevent QEMU from loading these configuration files at startup.
2020
ETEXI
2021

    
2022
HXCOMM This is the last statement. Insert new options before this line!
2023
STEXI
2024
@end table
2025
ETEXI