Statistics
| Branch: | Revision:

root / qemu-options.hx @ df97b920

History | View | Annotate | Download (52.9 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          set the number of CPUs to 'n' [default=1]\n")
43
STEXI
44
@item -smp @var{n}
45
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
46
CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
47
to 4.
48
ETEXI
49

    
50
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
51
    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n")
52
STEXI
53
@item -numa @var{opts}
54
Simulate a multi node NUMA system. If mem and cpus are omitted, resources
55
are split equally.
56
ETEXI
57

    
58
DEF("fda", HAS_ARG, QEMU_OPTION_fda,
59
    "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n")
60
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "")
61
STEXI
62
@item -fda @var{file}
63
@item -fdb @var{file}
64
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
65
use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
66
ETEXI
67

    
68
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
69
    "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n")
70
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "")
71
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
72
    "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n")
73
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "")
74
STEXI
75
@item -hda @var{file}
76
@item -hdb @var{file}
77
@item -hdc @var{file}
78
@item -hdd @var{file}
79
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
80
ETEXI
81

    
82
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
83
    "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n")
84
STEXI
85
@item -cdrom @var{file}
86
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
87
@option{-cdrom} at the same time). You can use the host CD-ROM by
88
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
89
ETEXI
90

    
91
DEF("drive", HAS_ARG, QEMU_OPTION_drive,
92
    "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
93
    "       [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
94
    "       [,cache=writethrough|writeback|none][,format=f][,serial=s]\n"
95
    "                use 'file' as a drive image\n")
96
STEXI
97
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
98

    
99
Define a new drive. Valid options are:
100

    
101
@table @code
102
@item file=@var{file}
103
This option defines which disk image (@pxref{disk_images}) to use with
104
this drive. If the filename contains comma, you must double it
105
(for instance, "file=my,,file" to use file "my,file").
106
@item if=@var{interface}
107
This option defines on which type on interface the drive is connected.
108
Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
109
@item bus=@var{bus},unit=@var{unit}
110
These options define where is connected the drive by defining the bus number and
111
the unit id.
112
@item index=@var{index}
113
This option defines where is connected the drive by using an index in the list
114
of available connectors of a given interface type.
115
@item media=@var{media}
116
This option defines the type of the media: disk or cdrom.
117
@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
118
These options have the same definition as they have in @option{-hdachs}.
119
@item snapshot=@var{snapshot}
120
@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
121
@item cache=@var{cache}
122
@var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.
123
@item format=@var{format}
124
Specify which disk @var{format} will be used rather than detecting
125
the format.  Can be used to specifiy format=raw to avoid interpreting
126
an untrusted format header.
127
@item serial=@var{serial}
128
This option specifies the serial number to assign to the device.
129
@end table
130

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

    
136
Writeback caching will report data writes as completed as soon as the data is
137
present in the host page cache.  This is safe as long as you trust your host.
138
If your host crashes or loses power, then the guest may experience data
139
corruption.  When using the @option{-snapshot} option, writeback caching is
140
used by default.
141

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

    
146
Some block drivers perform badly with @option{cache=writethrough}, most notably,
147
qcow2.  If performance is more important than correctness,
148
@option{cache=writeback} should be used with qcow2.  By default, if no explicit
149
caching is specified for a qcow2 disk image, @option{cache=writeback} will be
150
used.  For all other disk types, @option{cache=writethrough} is the default.
151

    
152
Instead of @option{-cdrom} you can use:
153
@example
154
qemu -drive file=file,index=2,media=cdrom
155
@end example
156

    
157
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
158
use:
159
@example
160
qemu -drive file=file,index=0,media=disk
161
qemu -drive file=file,index=1,media=disk
162
qemu -drive file=file,index=2,media=disk
163
qemu -drive file=file,index=3,media=disk
164
@end example
165

    
166
You can connect a CDROM to the slave of ide0:
167
@example
168
qemu -drive file=file,if=ide,index=1,media=cdrom
169
@end example
170

    
171
If you don't specify the "file=" argument, you define an empty drive:
172
@example
173
qemu -drive if=ide,index=1,media=cdrom
174
@end example
175

    
176
You can connect a SCSI disk with unit ID 6 on the bus #0:
177
@example
178
qemu -drive file=file,if=scsi,bus=0,unit=6
179
@end example
180

    
181
Instead of @option{-fda}, @option{-fdb}, you can use:
182
@example
183
qemu -drive file=file,index=0,if=floppy
184
qemu -drive file=file,index=1,if=floppy
185
@end example
186

    
187
By default, @var{interface} is "ide" and @var{index} is automatically
188
incremented:
189
@example
190
qemu -drive file=a -drive file=b"
191
@end example
192
is interpreted like:
193
@example
194
qemu -hda a -hdb b
195
@end example
196
ETEXI
197

    
198
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
199
    "-mtdblock file  use 'file' as on-board Flash memory image\n")
200
STEXI
201

    
202
@item -mtdblock file
203
Use 'file' as on-board Flash memory image.
204
ETEXI
205

    
206
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
207
    "-sd file        use 'file' as SecureDigital card image\n")
208
STEXI
209
@item -sd file
210
Use 'file' as SecureDigital card image.
211
ETEXI
212

    
213
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
214
    "-pflash file    use 'file' as a parallel flash image\n")
215
STEXI
216
@item -pflash file
217
Use 'file' as a parallel flash image.
218
ETEXI
219

    
220
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
221
    "-boot [a|c|d|n] boot on floppy (a), hard disk (c), CD-ROM (d), or network (n)\n")
222
STEXI
223
@item -boot [a|c|d|n]
224
Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
225
is the default.
226
ETEXI
227

    
228
DEF("snapshot", 0, QEMU_OPTION_snapshot,
229
    "-snapshot       write to temporary files instead of disk image files\n")
230
STEXI
231
@item -snapshot
232
Write to temporary files instead of disk image files. In this case,
233
the raw disk image you use is not written back. You can however force
234
the write back by pressing @key{C-a s} (@pxref{disk_images}).
235
ETEXI
236

    
237
DEF("m", HAS_ARG, QEMU_OPTION_m,
238
    "-m megs         set virtual RAM size to megs MB [default=%d]\n")
239
STEXI
240
@item -m @var{megs}
241
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
242
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
243
gigabytes respectively.
244
ETEXI
245

    
246
DEF("k", HAS_ARG, QEMU_OPTION_k,
247
    "-k language     use keyboard layout (for example 'fr' for French)\n")
248
STEXI
249
@item -k @var{language}
250

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

    
257
The available layouts are:
258
@example
259
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
260
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
261
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
262
@end example
263

    
264
The default is @code{en-us}.
265
ETEXI
266

    
267

    
268
#ifdef HAS_AUDIO
269
DEF("audio-help", 0, QEMU_OPTION_audio_help,
270
    "-audio-help     print list of audio drivers and their options\n")
271
#endif
272
STEXI
273
@item -audio-help
274

    
275
Will show the audio subsystem help: list of drivers, tunable
276
parameters.
277
ETEXI
278

    
279
#ifdef HAS_AUDIO
280
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
281
    "-soundhw c1,... enable audio support\n"
282
    "                and only specified sound cards (comma separated list)\n"
283
    "                use -soundhw ? to get the list of supported cards\n"
284
    "                use -soundhw all to enable all of them\n")
285
#endif
286
STEXI
287
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
288

    
289
Enable audio and selected sound hardware. Use ? to print all
290
available sound hardware.
291

    
292
@example
293
qemu -soundhw sb16,adlib disk.img
294
qemu -soundhw es1370 disk.img
295
qemu -soundhw ac97 disk.img
296
qemu -soundhw all disk.img
297
qemu -soundhw ?
298
@end example
299

    
300
Note that Linux's i810_audio OSS kernel (for AC97) module might
301
require manually specifying clocking.
302

    
303
@example
304
modprobe i810_audio clocking=48000
305
@end example
306
ETEXI
307

    
308
STEXI
309
@end table
310
ETEXI
311

    
312
DEF("usb", 0, QEMU_OPTION_usb,
313
    "-usb            enable the USB driver (will be the default soon)\n")
314
STEXI
315
USB options:
316
@table @option
317

    
318
@item -usb
319
Enable the USB driver (will be the default soon)
320
ETEXI
321

    
322
DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
323
    "-usbdevice name add the host or guest USB device 'name'\n")
324
STEXI
325

    
326
@item -usbdevice @var{devname}
327
Add the USB device @var{devname}. @xref{usb_devices}.
328

    
329
@table @code
330

    
331
@item mouse
332
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
333

    
334
@item tablet
335
Pointer device that uses absolute coordinates (like a touchscreen). This
336
means qemu is able to report the mouse position without having to grab the
337
mouse. Also overrides the PS/2 mouse emulation when activated.
338

    
339
@item disk:[format=@var{format}]:file
340
Mass storage device based on file. The optional @var{format} argument
341
will be used rather than detecting the format. Can be used to specifiy
342
format=raw to avoid interpreting an untrusted format header.
343

    
344
@item host:bus.addr
345
Pass through the host device identified by bus.addr (Linux only).
346

    
347
@item host:vendor_id:product_id
348
Pass through the host device identified by vendor_id:product_id (Linux only).
349

    
350
@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
351
Serial converter to host character device @var{dev}, see @code{-serial} for the
352
available devices.
353

    
354
@item braille
355
Braille device.  This will use BrlAPI to display the braille output on a real
356
or fake device.
357

    
358
@item net:options
359
Network adapter that supports CDC ethernet and RNDIS protocols.
360

    
361
@end table
362
ETEXI
363

    
364
DEF("name", HAS_ARG, QEMU_OPTION_name,
365
    "-name string    set the name of the guest\n")
366
STEXI
367
@item -name @var{name}
368
Sets the @var{name} of the guest.
369
This name will be displayed in the SDL window caption.
370
The @var{name} will also be used for the VNC server.
371
ETEXI
372

    
373
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
374
    "-uuid %%08x-%%04x-%%04x-%%04x-%%012x\n"
375
    "                specify machine UUID\n")
376
STEXI
377
@item -uuid @var{uuid}
378
Set system UUID.
379
ETEXI
380

    
381
STEXI
382
@end table
383
ETEXI
384

    
385
DEFHEADING()
386

    
387
DEFHEADING(Display options:)
388

    
389
STEXI
390
@table @option
391
ETEXI
392

    
393
DEF("nographic", 0, QEMU_OPTION_nographic,
394
    "-nographic      disable graphical output and redirect serial I/Os to console\n")
395
STEXI
396
@item -nographic
397

    
398
Normally, QEMU uses SDL to display the VGA output. With this option,
399
you can totally disable graphical output so that QEMU is a simple
400
command line application. The emulated serial port is redirected on
401
the console. Therefore, you can still use QEMU to debug a Linux kernel
402
with a serial console.
403
ETEXI
404

    
405
#ifdef CONFIG_CURSES
406
DEF("curses", 0, QEMU_OPTION_curses,
407
    "-curses         use a curses/ncurses interface instead of SDL\n")
408
#endif
409
STEXI
410
@item -curses
411

    
412
Normally, QEMU uses SDL to display the VGA output.  With this option,
413
QEMU can display the VGA output when in text mode using a
414
curses/ncurses interface.  Nothing is displayed in graphical mode.
415
ETEXI
416

    
417
#ifdef CONFIG_SDL
418
DEF("no-frame", 0, QEMU_OPTION_no_frame,
419
    "-no-frame       open SDL window without a frame and window decorations\n")
420
#endif
421
STEXI
422
@item -no-frame
423

    
424
Do not use decorations for SDL windows and start them using the whole
425
available screen space. This makes the using QEMU in a dedicated desktop
426
workspace more convenient.
427
ETEXI
428

    
429
#ifdef CONFIG_SDL
430
DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
431
    "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n")
432
#endif
433
STEXI
434
@item -alt-grab
435

    
436
Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt).
437
ETEXI
438

    
439
#ifdef CONFIG_SDL
440
DEF("no-quit", 0, QEMU_OPTION_no_quit,
441
    "-no-quit        disable SDL window close capability\n")
442
#endif
443
STEXI
444
@item -no-quit
445

    
446
Disable SDL window close capability.
447
ETEXI
448

    
449
#ifdef CONFIG_SDL
450
DEF("sdl", 0, QEMU_OPTION_sdl,
451
    "-sdl            enable SDL\n")
452
#endif
453
STEXI
454
@item -sdl
455

    
456
Enable SDL.
457
ETEXI
458

    
459
DEF("portrait", 0, QEMU_OPTION_portrait,
460
    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n")
461
STEXI
462
@item -portrait
463

    
464
Rotate graphical output 90 deg left (only PXA LCD).
465
ETEXI
466

    
467
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
468
    "-vga [std|cirrus|vmware|xenfb|none]\n"
469
    "                select video card type\n")
470
STEXI
471
@item -vga @var{type}
472
Select type of VGA card to emulate. Valid values for @var{type} are
473
@table @code
474
@item cirrus
475
Cirrus Logic GD5446 Video card. All Windows versions starting from
476
Windows 95 should recognize and use this graphic card. For optimal
477
performances, use 16 bit color depth in the guest and the host OS.
478
(This one is the default)
479
@item std
480
Standard VGA card with Bochs VBE extensions.  If your guest OS
481
supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
482
to use high resolution modes (>= 1280x1024x16) then you should use
483
this option.
484
@item vmware
485
VMWare SVGA-II compatible adapter. Use it if you have sufficiently
486
recent XFree86/XOrg server or Windows guest with a driver for this
487
card.
488
@item none
489
Disable VGA card.
490
@end table
491
ETEXI
492

    
493
DEF("full-screen", 0, QEMU_OPTION_full_screen,
494
    "-full-screen    start in full screen\n")
495
STEXI
496
@item -full-screen
497
Start in full screen.
498
ETEXI
499

    
500
#if defined(TARGET_PPC) || defined(TARGET_SPARC)
501
DEF("g", 1, QEMU_OPTION_g ,
502
    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n")
503
#endif
504
STEXI
505
ETEXI
506

    
507
DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
508
    "-vnc display    start a VNC server on display\n")
509
STEXI
510
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
511

    
512
Normally, QEMU uses SDL to display the VGA output.  With this option,
513
you can have QEMU listen on VNC display @var{display} and redirect the VGA
514
display over the VNC session.  It is very useful to enable the usb
515
tablet device when using this option (option @option{-usbdevice
516
tablet}). When using the VNC display, you must use the @option{-k}
517
parameter to set the keyboard layout if you are not using en-us. Valid
518
syntax for the @var{display} is
519

    
520
@table @code
521

    
522
@item @var{host}:@var{d}
523

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

    
528
@item @code{unix}:@var{path}
529

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

    
533
@item none
534

    
535
VNC is initialized but not started. The monitor @code{change} command
536
can be used to later start the VNC server.
537

    
538
@end table
539

    
540
Following the @var{display} value there may be one or more @var{option} flags
541
separated by commas. Valid options are
542

    
543
@table @code
544

    
545
@item reverse
546

    
547
Connect to a listening VNC client via a ``reverse'' connection. The
548
client is specified by the @var{display}. For reverse network
549
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
550
is a TCP port number, not a display number.
551

    
552
@item password
553

    
554
Require that password based authentication is used for client connections.
555
The password must be set separately using the @code{change} command in the
556
@ref{pcsys_monitor}
557

    
558
@item tls
559

    
560
Require that client use TLS when communicating with the VNC server. This
561
uses anonymous TLS credentials so is susceptible to a man-in-the-middle
562
attack. It is recommended that this option be combined with either the
563
@var{x509} or @var{x509verify} options.
564

    
565
@item x509=@var{/path/to/certificate/dir}
566

    
567
Valid if @option{tls} is specified. Require that x509 credentials are used
568
for negotiating the TLS session. The server will send its x509 certificate
569
to the client. It is recommended that a password be set on the VNC server
570
to provide authentication of the client when this is used. The path following
571
this option specifies where the x509 certificates are to be loaded from.
572
See the @ref{vnc_security} section for details on generating certificates.
573

    
574
@item x509verify=@var{/path/to/certificate/dir}
575

    
576
Valid if @option{tls} is specified. Require that x509 credentials are used
577
for negotiating the TLS session. The server will send its x509 certificate
578
to the client, and request that the client send its own x509 certificate.
579
The server will validate the client's certificate against the CA certificate,
580
and reject clients when validation fails. If the certificate authority is
581
trusted, this is a sufficient authentication mechanism. You may still wish
582
to set a password on the VNC server as a second authentication layer. The
583
path following this option specifies where the x509 certificates are to
584
be loaded from. See the @ref{vnc_security} section for details on generating
585
certificates.
586

    
587
@item sasl
588

    
589
Require that the client use SASL to authenticate with the VNC server.
590
The exact choice of authentication method used is controlled from the
591
system / user's SASL configuration file for the 'qemu' service. This
592
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
593
unprivileged user, an environment variable SASL_CONF_PATH can be used
594
to make it search alternate locations for the service config.
595
While some SASL auth methods can also provide data encryption (eg GSSAPI),
596
it is recommended that SASL always be combined with the 'tls' and
597
'x509' settings to enable use of SSL and server certificates. This
598
ensures a data encryption preventing compromise of authentication
599
credentials. See the @ref{vnc_security} section for details on using
600
SASL authentication.
601

    
602
@item acl
603

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

    
615
@end table
616
ETEXI
617

    
618
STEXI
619
@end table
620
ETEXI
621

    
622
DEFHEADING()
623

    
624
#ifdef TARGET_I386
625
DEFHEADING(i386 target only:)
626
#endif
627
STEXI
628
@table @option
629
ETEXI
630

    
631
#ifdef TARGET_I386
632
DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
633
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n")
634
#endif
635
STEXI
636
@item -win2k-hack
637
Use it when installing Windows 2000 to avoid a disk full bug. After
638
Windows 2000 is installed, you no longer need this option (this option
639
slows down the IDE transfers).
640
ETEXI
641

    
642
#ifdef TARGET_I386
643
DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack,
644
    "-rtc-td-hack    use it to fix time drift in Windows ACPI HAL\n")
645
#endif
646
STEXI
647
@item -rtc-td-hack
648
Use it if you experience time drift problem in Windows with ACPI HAL.
649
This option will try to figure out how many timer interrupts were not
650
processed by the Windows guest and will re-inject them.
651
ETEXI
652

    
653
#ifdef TARGET_I386
654
DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
655
    "-no-fd-bootchk  disable boot signature checking for floppy disks\n")
656
#endif
657
STEXI
658
@item -no-fd-bootchk
659
Disable boot signature checking for floppy disks in Bochs BIOS. It may
660
be needed to boot from old floppy disks.
661
ETEXI
662

    
663
#ifdef TARGET_I386
664
DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
665
           "-no-acpi        disable ACPI\n")
666
#endif
667
STEXI
668
@item -no-acpi
669
Disable ACPI (Advanced Configuration and Power Interface) support. Use
670
it if your guest OS complains about ACPI problems (PC target machine
671
only).
672
ETEXI
673

    
674
#ifdef TARGET_I386
675
DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
676
    "-no-hpet        disable HPET\n")
677
#endif
678
STEXI
679
@item -no-hpet
680
Disable HPET support.
681
ETEXI
682

    
683
#ifdef TARGET_I386
684
DEF("no-virtio-balloon", 0, QEMU_OPTION_no_virtio_balloon,
685
    "-no-virtio-balloon disable virtio balloon device\n")
686
#endif
687
STEXI
688
@item -no-virtio-balloon
689
Disable virtio-balloon device.
690
ETEXI
691

    
692
#ifdef TARGET_I386
693
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
694
    "-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"
695
    "                ACPI table description\n")
696
#endif
697
STEXI
698
@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}]...]
699
Add ACPI table with specified header fields and context from specified files.
700
ETEXI
701

    
702
#ifdef TARGET_I386
703
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
704
    "-smbios file=binary\n"
705
    "                Load SMBIOS entry from binary file\n"
706
    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%%d.%%d]\n"
707
    "                Specify SMBIOS type 0 fields\n"
708
    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
709
    "              [,uuid=uuid][,sku=str][,family=str]\n"
710
    "                Specify SMBIOS type 1 fields\n")
711
#endif
712
STEXI
713
@item -smbios file=@var{binary}
714
Load SMBIOS entry from binary file.
715

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

    
719
@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}]
720
Specify SMBIOS type 1 fields
721
ETEXI
722

    
723
#ifdef TARGET_I386
724
DEFHEADING()
725
#endif
726
STEXI
727
@end table
728
ETEXI
729

    
730
DEFHEADING(Network options:)
731
STEXI
732
@table @option
733
ETEXI
734

    
735
DEF("net", HAS_ARG, QEMU_OPTION_net,
736
    "-net nic[,vlan=n][,macaddr=addr][,model=type][,name=str]\n"
737
    "                create a new Network Interface Card and connect it to VLAN 'n'\n"
738
#ifdef CONFIG_SLIRP
739
    "-net user[,vlan=n][,name=str][,hostname=host]\n"
740
    "                connect the user mode network stack to VLAN 'n' and send\n"
741
    "                hostname 'host' to DHCP clients\n"
742
#endif
743
#ifdef _WIN32
744
    "-net tap[,vlan=n][,name=str],ifname=name\n"
745
    "                connect the host TAP network interface to VLAN 'n'\n"
746
#else
747
    "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile]\n"
748
    "                connect the host TAP network interface to VLAN 'n' and use the\n"
749
    "                network scripts 'file' (default=%s)\n"
750
    "                and 'dfile' (default=%s);\n"
751
    "                use '[down]script=no' to disable script execution;\n"
752
    "                use 'fd=h' to connect to an already opened TAP interface\n"
753
#endif
754
    "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
755
    "                connect the vlan 'n' to another VLAN using a socket connection\n"
756
    "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port]\n"
757
    "                connect the vlan 'n' to multicast maddr and port\n"
758
#ifdef CONFIG_VDE
759
    "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
760
    "                connect the vlan 'n' to port 'n' of a vde switch running\n"
761
    "                on host and listening for incoming connections on 'socketpath'.\n"
762
    "                Use group 'groupname' and mode 'octalmode' to change default\n"
763
    "                ownership and permissions for communication port.\n"
764
#endif
765
    "-net dump[,vlan=n][,file=f][,len=n]\n"
766
    "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
767
    "-net none       use it alone to have zero network devices; if no -net option\n"
768
    "                is provided, the default is '-net nic -net user'\n")
769
STEXI
770
@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}][,name=@var{name}]
771
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
772
= 0 is the default). The NIC is an ne2k_pci by default on the PC
773
target. Optionally, the MAC address can be changed to @var{addr}
774
and a @var{name} can be assigned for use in monitor commands. If no
775
@option{-net} option is specified, a single NIC is created.
776
Qemu can emulate several different models of network card.
777
Valid values for @var{type} are
778
@code{i82551}, @code{i82557b}, @code{i82559er},
779
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
780
@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
781
Not all devices are supported on all targets.  Use -net nic,model=?
782
for a list of available devices for your target.
783

    
784
@item -net user[,vlan=@var{n}][,hostname=@var{name}][,name=@var{name}]
785
Use the user mode network stack which requires no administrator
786
privilege to run.  @option{hostname=name} can be used to specify the client
787
hostname reported by the builtin DHCP server.
788

    
789
@item -net channel,@var{port}:@var{dev}
790
Forward @option{user} TCP connection to port @var{port} to character device @var{dev}
791

    
792
@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
793
Connect the host TAP network interface @var{name} to VLAN @var{n}, use
794
the network script @var{file} to configure it and the network script
795
@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
796
automatically provides one. @option{fd}=@var{h} can be used to specify
797
the handle of an already opened host TAP interface. The default network
798
configure script is @file{/etc/qemu-ifup} and the default network
799
deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
800
or @option{downscript=no} to disable script execution. Example:
801

    
802
@example
803
qemu linux.img -net nic -net tap
804
@end example
805

    
806
More complicated example (two NICs, each one connected to a TAP device)
807
@example
808
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
809
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
810
@end example
811

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

    
814
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
815
machine using a TCP socket connection. If @option{listen} is
816
specified, QEMU waits for incoming connections on @var{port}
817
(@var{host} is optional). @option{connect} is used to connect to
818
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
819
specifies an already opened TCP socket.
820

    
821
Example:
822
@example
823
# launch a first QEMU instance
824
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
825
               -net socket,listen=:1234
826
# connect the VLAN 0 of this instance to the VLAN 0
827
# of the first instance
828
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
829
               -net socket,connect=127.0.0.1:1234
830
@end example
831

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

    
834
Create a VLAN @var{n} shared with another QEMU virtual
835
machines using a UDP multicast socket, effectively making a bus for
836
every QEMU with same multicast address @var{maddr} and @var{port}.
837
NOTES:
838
@enumerate
839
@item
840
Several QEMU can be running on different hosts and share same bus (assuming
841
correct multicast setup for these hosts).
842
@item
843
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
844
@url{http://user-mode-linux.sf.net}.
845
@item
846
Use @option{fd=h} to specify an already opened UDP multicast socket.
847
@end enumerate
848

    
849
Example:
850
@example
851
# launch one QEMU instance
852
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
853
               -net socket,mcast=230.0.0.1:1234
854
# launch another QEMU instance on same "bus"
855
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
856
               -net socket,mcast=230.0.0.1:1234
857
# launch yet another QEMU instance on same "bus"
858
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
859
               -net socket,mcast=230.0.0.1:1234
860
@end example
861

    
862
Example (User Mode Linux compat.):
863
@example
864
# launch QEMU instance (note mcast address selected
865
# is UML's default)
866
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
867
               -net socket,mcast=239.192.168.1:1102
868
# launch UML
869
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
870
@end example
871

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

    
879
Example:
880
@example
881
# launch vde switch
882
vde_switch -F -sock /tmp/myswitch
883
# launch QEMU instance
884
qemu linux.img -net nic -net vde,sock=/tmp/myswitch
885
@end example
886

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

    
892
@item -net none
893
Indicate that no network devices should be configured. It is used to
894
override the default configuration (@option{-net nic -net user}) which
895
is activated if no @option{-net} options are provided.
896
ETEXI
897

    
898
#ifdef CONFIG_SLIRP
899
DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, \
900
    "-tftp dir       allow tftp access to files in dir [-net user]\n")
901
#endif
902
STEXI
903
@item -tftp @var{dir}
904
When using the user mode network stack, activate a built-in TFTP
905
server. The files in @var{dir} will be exposed as the root of a TFTP server.
906
The TFTP client on the guest must be configured in binary mode (use the command
907
@code{bin} of the Unix TFTP client). The host IP address on the guest is as
908
usual 10.0.2.2.
909
ETEXI
910

    
911
#ifdef CONFIG_SLIRP
912
DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, \
913
    "-bootp file     advertise file in BOOTP replies\n")
914
#endif
915
STEXI
916
@item -bootp @var{file}
917
When using the user mode network stack, broadcast @var{file} as the BOOTP
918
filename.  In conjunction with @option{-tftp}, this can be used to network boot
919
a guest from a local directory.
920

    
921
Example (using pxelinux):
922
@example
923
qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
924
@end example
925
ETEXI
926

    
927
#ifndef _WIN32
928
DEF("smb", HAS_ARG, QEMU_OPTION_smb, \
929
           "-smb dir        allow SMB access to files in 'dir' [-net user]\n")
930
#endif
931
STEXI
932
@item -smb @var{dir}
933
When using the user mode network stack, activate a built-in SMB
934
server so that Windows OSes can access to the host files in @file{@var{dir}}
935
transparently.
936

    
937
In the guest Windows OS, the line:
938
@example
939
10.0.2.4 smbserver
940
@end example
941
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
942
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
943

    
944
Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
945

    
946
Note that a SAMBA server must be installed on the host OS in
947
@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
948
2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
949
ETEXI
950

    
951
#ifdef CONFIG_SLIRP
952
DEF("redir", HAS_ARG, QEMU_OPTION_redir, \
953
    "-redir [tcp|udp]:host-port:[guest-host]:guest-port\n" \
954
    "                redirect TCP or UDP connections from host to guest [-net user]\n")
955
#endif
956
STEXI
957
@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
958

    
959
When using the user mode network stack, redirect incoming TCP or UDP
960
connections to the host port @var{host-port} to the guest
961
@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
962
is not specified, its value is 10.0.2.15 (default address given by the
963
built-in DHCP server). If no connection type is specified, TCP is used.
964

    
965
For example, to redirect host X11 connection from screen 1 to guest
966
screen 0, use the following:
967

    
968
@example
969
# on the host
970
qemu -redir tcp:6001::6000 [...]
971
# this host xterm should open in the guest X11 server
972
xterm -display :1
973
@end example
974

    
975
To redirect telnet connections from host port 5555 to telnet port on
976
the guest, use the following:
977

    
978
@example
979
# on the host
980
qemu -redir tcp:5555::23 [...]
981
telnet localhost 5555
982
@end example
983

    
984
Then when you use on the host @code{telnet localhost 5555}, you
985
connect to the guest telnet server.
986

    
987
@end table
988
ETEXI
989

    
990
DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
991
    "\n" \
992
    "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
993
    "-bt hci,host[:id]\n" \
994
    "                use host's HCI with the given name\n" \
995
    "-bt hci[,vlan=n]\n" \
996
    "                emulate a standard HCI in virtual scatternet 'n'\n" \
997
    "-bt vhci[,vlan=n]\n" \
998
    "                add host computer to virtual scatternet 'n' using VHCI\n" \
999
    "-bt device:dev[,vlan=n]\n" \
1000
    "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
1001
STEXI
1002
Bluetooth(R) options:
1003
@table @option
1004

    
1005
@item -bt hci[...]
1006
Defines the function of the corresponding Bluetooth HCI.  -bt options
1007
are matched with the HCIs present in the chosen machine type.  For
1008
example when emulating a machine with only one HCI built into it, only
1009
the first @code{-bt hci[...]} option is valid and defines the HCI's
1010
logic.  The Transport Layer is decided by the machine type.  Currently
1011
the machines @code{n800} and @code{n810} have one HCI and all other
1012
machines have none.
1013

    
1014
@anchor{bt-hcis}
1015
The following three types are recognized:
1016

    
1017
@table @code
1018
@item -bt hci,null
1019
(default) The corresponding Bluetooth HCI assumes no internal logic
1020
and will not respond to any HCI commands or emit events.
1021

    
1022
@item -bt hci,host[:@var{id}]
1023
(@code{bluez} only) The corresponding HCI passes commands / events
1024
to / from the physical HCI identified by the name @var{id} (default:
1025
@code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1026
capable systems like Linux.
1027

    
1028
@item -bt hci[,vlan=@var{n}]
1029
Add a virtual, standard HCI that will participate in the Bluetooth
1030
scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1031
VLANs, devices inside a bluetooth network @var{n} can only communicate
1032
with other devices in the same network (scatternet).
1033
@end table
1034

    
1035
@item -bt vhci[,vlan=@var{n}]
1036
(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1037
to the host bluetooth stack instead of to the emulated target.  This
1038
allows the host and target machines to participate in a common scatternet
1039
and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1040
be used as following:
1041

    
1042
@example
1043
qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1044
@end example
1045

    
1046
@item -bt device:@var{dev}[,vlan=@var{n}]
1047
Emulate a bluetooth device @var{dev} and place it in network @var{n}
1048
(default @code{0}).  QEMU can only emulate one type of bluetooth devices
1049
currently:
1050

    
1051
@table @code
1052
@item keyboard
1053
Virtual wireless keyboard implementing the HIDP bluetooth profile.
1054
@end table
1055
@end table
1056
ETEXI
1057

    
1058
DEFHEADING()
1059

    
1060
DEFHEADING(Linux boot specific:)
1061
STEXI
1062
When using these options, you can use a given
1063
Linux kernel without installing it in the disk image. It can be useful
1064
for easier testing of various kernels.
1065

    
1066
@table @option
1067
ETEXI
1068

    
1069
DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1070
    "-kernel bzImage use 'bzImage' as kernel image\n")
1071
STEXI
1072
@item -kernel @var{bzImage}
1073
Use @var{bzImage} as kernel image.
1074
ETEXI
1075

    
1076
DEF("append", HAS_ARG, QEMU_OPTION_append, \
1077
    "-append cmdline use 'cmdline' as kernel command line\n")
1078
STEXI
1079
@item -append @var{cmdline}
1080
Use @var{cmdline} as kernel command line
1081
ETEXI
1082

    
1083
DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1084
           "-initrd file    use 'file' as initial ram disk\n")
1085
STEXI
1086
@item -initrd @var{file}
1087
Use @var{file} as initial ram disk.
1088
ETEXI
1089

    
1090
STEXI
1091
@end table
1092
ETEXI
1093

    
1094
DEFHEADING()
1095

    
1096
DEFHEADING(Debug/Expert options:)
1097

    
1098
STEXI
1099
@table @option
1100
ETEXI
1101

    
1102
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1103
    "-serial dev     redirect the serial port to char device 'dev'\n")
1104
STEXI
1105
@item -serial @var{dev}
1106
Redirect the virtual serial port to host character device
1107
@var{dev}. The default device is @code{vc} in graphical mode and
1108
@code{stdio} in non graphical mode.
1109

    
1110
This option can be used several times to simulate up to 4 serial
1111
ports.
1112

    
1113
Use @code{-serial none} to disable all serial ports.
1114

    
1115
Available character devices are:
1116
@table @code
1117
@item vc[:WxH]
1118
Virtual console. Optionally, a width and height can be given in pixel with
1119
@example
1120
vc:800x600
1121
@end example
1122
It is also possible to specify width or height in characters:
1123
@example
1124
vc:80Cx24C
1125
@end example
1126
@item pty
1127
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
1128
@item none
1129
No device is allocated.
1130
@item null
1131
void device
1132
@item /dev/XXX
1133
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
1134
parameters are set according to the emulated ones.
1135
@item /dev/parport@var{N}
1136
[Linux only, parallel port only] Use host parallel port
1137
@var{N}. Currently SPP and EPP parallel port features can be used.
1138
@item file:@var{filename}
1139
Write output to @var{filename}. No character can be read.
1140
@item stdio
1141
[Unix only] standard input/output
1142
@item pipe:@var{filename}
1143
name pipe @var{filename}
1144
@item COM@var{n}
1145
[Windows only] Use host serial port @var{n}
1146
@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
1147
This implements UDP Net Console.
1148
When @var{remote_host} or @var{src_ip} are not specified
1149
they default to @code{0.0.0.0}.
1150
When not using a specified @var{src_port} a random port is automatically chosen.
1151
@item msmouse
1152
Three button serial mouse. Configure the guest to use Microsoft protocol.
1153

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

    
1159
If you plan to send characters back via netconsole or you want to stop
1160
and start qemu a lot of times, you should have qemu use the same
1161
source port each time by using something like @code{-serial
1162
udp::4555@@:4556} to qemu. Another approach is to use a patched
1163
version of netcat which can listen to a TCP port and send and receive
1164
characters via udp.  If you have a patched version of netcat which
1165
activates telnet remote echo and single char transfer, then you can
1166
use the following options to step up a netcat redirector to allow
1167
telnet on port 5555 to access the qemu port.
1168
@table @code
1169
@item Qemu Options:
1170
-serial udp::4555@@:4556
1171
@item netcat options:
1172
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
1173
@item telnet options:
1174
localhost 5555
1175
@end table
1176

    
1177
@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
1178
The TCP Net Console has two modes of operation.  It can send the serial
1179
I/O to a location or wait for a connection from a location.  By default
1180
the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
1181
the @var{server} option QEMU will wait for a client socket application
1182
to connect to the port before continuing, unless the @code{nowait}
1183
option was specified.  The @code{nodelay} option disables the Nagle buffering
1184
algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
1185
one TCP connection at a time is accepted. You can use @code{telnet} to
1186
connect to the corresponding character device.
1187
@table @code
1188
@item Example to send tcp console to 192.168.0.2 port 4444
1189
-serial tcp:192.168.0.2:4444
1190
@item Example to listen and wait on port 4444 for connection
1191
-serial tcp::4444,server
1192
@item Example to not wait and listen on ip 192.168.0.100 port 4444
1193
-serial tcp:192.168.0.100:4444,server,nowait
1194
@end table
1195

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

    
1205
@item unix:@var{path}[,server][,nowait]
1206
A unix domain socket is used instead of a tcp socket.  The option works the
1207
same as if you had specified @code{-serial tcp} except the unix domain socket
1208
@var{path} is used for connections.
1209

    
1210
@item mon:@var{dev_string}
1211
This is a special option to allow the monitor to be multiplexed onto
1212
another serial port.  The monitor is accessed with key sequence of
1213
@key{Control-a} and then pressing @key{c}. See monitor access
1214
@ref{pcsys_keys} in the -nographic section for more keys.
1215
@var{dev_string} should be any one of the serial devices specified
1216
above.  An example to multiplex the monitor onto a telnet server
1217
listening on port 4444 would be:
1218
@table @code
1219
@item -serial mon:telnet::4444,server,nowait
1220
@end table
1221

    
1222
@item braille
1223
Braille device.  This will use BrlAPI to display the braille output on a real
1224
or fake device.
1225

    
1226
@end table
1227
ETEXI
1228

    
1229
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
1230
    "-parallel dev   redirect the parallel port to char device 'dev'\n")
1231
STEXI
1232
@item -parallel @var{dev}
1233
Redirect the virtual parallel port to host device @var{dev} (same
1234
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1235
be used to use hardware devices connected on the corresponding host
1236
parallel port.
1237

    
1238
This option can be used several times to simulate up to 3 parallel
1239
ports.
1240

    
1241
Use @code{-parallel none} to disable all parallel ports.
1242
ETEXI
1243

    
1244
DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
1245
    "-monitor dev    redirect the monitor to char device 'dev'\n")
1246
STEXI
1247
@item -monitor @var{dev}
1248
Redirect the monitor to host device @var{dev} (same devices as the
1249
serial port).
1250
The default device is @code{vc} in graphical mode and @code{stdio} in
1251
non graphical mode.
1252
ETEXI
1253

    
1254
DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
1255
    "-pidfile file   write PID to 'file'\n")
1256
STEXI
1257
@item -pidfile @var{file}
1258
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
1259
from a script.
1260
ETEXI
1261

    
1262
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
1263
    "-singlestep   always run in singlestep mode\n")
1264
STEXI
1265
@item -singlestep
1266
Run the emulation in single step mode.
1267
ETEXI
1268

    
1269
DEF("S", 0, QEMU_OPTION_S, \
1270
    "-S              freeze CPU at startup (use 'c' to start execution)\n")
1271
STEXI
1272
@item -S
1273
Do not start CPU at startup (you must type 'c' in the monitor).
1274
ETEXI
1275

    
1276
DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
1277
    "-gdb dev        wait for gdb connection on 'dev'\n")
1278
STEXI
1279
@item -gdb @var{dev}
1280
Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
1281
connections will likely be TCP-based, but also UDP, pseudo TTY, or even
1282
stdio are reasonable use case. The latter is allowing to start qemu from
1283
within gdb and establish the connection via a pipe:
1284
@example
1285
(gdb) target remote | exec qemu -gdb stdio ...
1286
@end example
1287
ETEXI
1288

    
1289
DEF("s", 0, QEMU_OPTION_s, \
1290
    "-s              shorthand for -gdb tcp::%s\n")
1291
STEXI
1292
@item -s
1293
Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
1294
(@pxref{gdb_usage}).
1295
ETEXI
1296

    
1297
DEF("d", HAS_ARG, QEMU_OPTION_d, \
1298
    "-d item1,...    output log to %s (use -d ? for a list of log items)\n")
1299
STEXI
1300
@item -d
1301
Output log in /tmp/qemu.log
1302
ETEXI
1303

    
1304
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
1305
    "-hdachs c,h,s[,t]\n" \
1306
    "                force hard disk 0 physical geometry and the optional BIOS\n" \
1307
    "                translation (t=none or lba) (usually qemu can guess them)\n")
1308
STEXI
1309
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
1310
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1311
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1312
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
1313
all those parameters. This option is useful for old MS-DOS disk
1314
images.
1315
ETEXI
1316

    
1317
DEF("L", HAS_ARG, QEMU_OPTION_L, \
1318
    "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n")
1319
STEXI
1320
@item -L  @var{path}
1321
Set the directory for the BIOS, VGA BIOS and keymaps.
1322
ETEXI
1323

    
1324
DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
1325
    "-bios file      set the filename for the BIOS\n")
1326
STEXI
1327
@item -bios @var{file}
1328
Set the filename for the BIOS.
1329
ETEXI
1330

    
1331
#ifdef CONFIG_KQEMU
1332
DEF("kernel-kqemu", 0, QEMU_OPTION_kernel_kqemu, \
1333
    "-kernel-kqemu   enable KQEMU full virtualization (default is user mode only)\n")
1334
#endif
1335
STEXI
1336
@item -kernel-kqemu
1337
Enable KQEMU full virtualization (default is user mode only).
1338
ETEXI
1339

    
1340
#ifdef CONFIG_KQEMU
1341
DEF("no-kqemu", 0, QEMU_OPTION_no_kqemu, \
1342
    "-no-kqemu       disable KQEMU kernel module usage\n")
1343
#endif
1344
STEXI
1345
@item -no-kqemu
1346
Disable KQEMU kernel module usage. KQEMU options are only available if
1347
KQEMU support is enabled when compiling.
1348
ETEXI
1349

    
1350
#ifdef CONFIG_KVM
1351
DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
1352
    "-enable-kvm     enable KVM full virtualization support\n")
1353
#endif
1354
STEXI
1355
@item -enable-kvm
1356
Enable KVM full virtualization support. This option is only available
1357
if KVM support is enabled when compiling.
1358
ETEXI
1359

    
1360
#ifdef CONFIG_XEN
1361
DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
1362
    "-xen-domid id   specify xen guest domain id\n")
1363
DEF("xen-create", 0, QEMU_OPTION_xen_create,
1364
    "-xen-create     create domain using xen hypercalls, bypassing xend\n"
1365
    "                warning: should not be used when xend is in use\n")
1366
DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
1367
    "-xen-attach     attach to existing xen domain\n"
1368
    "                xend will use this when starting qemu\n")
1369
#endif
1370

    
1371
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
1372
    "-no-reboot      exit instead of rebooting\n")
1373
STEXI
1374
@item -no-reboot
1375
Exit instead of rebooting.
1376
ETEXI
1377

    
1378
DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
1379
    "-no-shutdown    stop before shutdown\n")
1380
STEXI
1381
@item -no-shutdown
1382
Don't exit QEMU on guest shutdown, but instead only stop the emulation.
1383
This allows for instance switching to monitor to commit changes to the
1384
disk image.
1385
ETEXI
1386

    
1387
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
1388
    "-loadvm [tag|id]\n" \
1389
    "                start right away with a saved state (loadvm in monitor)\n")
1390
STEXI
1391
@item -loadvm @var{file}
1392
Start right away with a saved state (@code{loadvm} in monitor)
1393
ETEXI
1394

    
1395
#ifndef _WIN32
1396
DEF("daemonize", 0, QEMU_OPTION_daemonize, \
1397
    "-daemonize      daemonize QEMU after initializing\n")
1398
#endif
1399
STEXI
1400
@item -daemonize
1401
Daemonize the QEMU process after initialization.  QEMU will not detach from
1402
standard IO until it is ready to receive connections on any of its devices.
1403
This option is a useful way for external programs to launch QEMU without having
1404
to cope with initialization race conditions.
1405
ETEXI
1406

    
1407
DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
1408
    "-option-rom rom load a file, rom, into the option ROM space\n")
1409
STEXI
1410
@item -option-rom @var{file}
1411
Load the contents of @var{file} as an option ROM.
1412
This option is useful to load things like EtherBoot.
1413
ETEXI
1414

    
1415
DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
1416
    "-clock          force the use of the given methods for timer alarm.\n" \
1417
    "                To see what timers are available use -clock ?\n")
1418
STEXI
1419
@item -clock @var{method}
1420
Force the use of the given methods for timer alarm. To see what timers
1421
are available use -clock ?.
1422
ETEXI
1423

    
1424
DEF("localtime", 0, QEMU_OPTION_localtime, \
1425
    "-localtime      set the real time clock to local time [default=utc]\n")
1426
STEXI
1427
@item -localtime
1428
Set the real time clock to local time (the default is to UTC
1429
time). This option is needed to have correct date in MS-DOS or
1430
Windows.
1431
ETEXI
1432

    
1433
DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, \
1434
    "-startdate      select initial date of the clock\n")
1435
STEXI
1436

    
1437
@item -startdate @var{date}
1438
Set the initial date of the real time clock. Valid formats for
1439
@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
1440
@code{2006-06-17}. The default value is @code{now}.
1441
ETEXI
1442

    
1443
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
1444
    "-icount [N|auto]\n" \
1445
    "                enable virtual instruction counter with 2^N clock ticks per\n" \
1446
    "                instruction\n")
1447
STEXI
1448
@item -icount [N|auto]
1449
Enable virtual instruction counter.  The virtual cpu will execute one
1450
instruction every 2^N ns of virtual time.  If @code{auto} is specified
1451
then the virtual cpu speed will be automatically adjusted to keep virtual
1452
time within a few seconds of real time.
1453

    
1454
Note that while this option can give deterministic behavior, it does not
1455
provide cycle accurate emulation.  Modern CPUs contain superscalar out of
1456
order cores with complex cache hierarchies.  The number of instructions
1457
executed often has little or no correlation with actual performance.
1458
ETEXI
1459

    
1460
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
1461
    "-watchdog i6300esb|ib700\n" \
1462
    "                enable virtual hardware watchdog [default=none]\n")
1463
STEXI
1464
@item -watchdog @var{model}
1465
Create a virtual hardware watchdog device.  Once enabled (by a guest
1466
action), the watchdog must be periodically polled by an agent inside
1467
the guest or else the guest will be restarted.
1468

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

    
1475
Use @code{-watchdog ?} to list available hardware models.  Only one
1476
watchdog can be enabled for a guest.
1477
ETEXI
1478

    
1479
DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
1480
    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
1481
    "                action when watchdog fires [default=reset]\n")
1482
STEXI
1483
@item -watchdog-action @var{action}
1484

    
1485
The @var{action} controls what QEMU will do when the watchdog timer
1486
expires.
1487
The default is
1488
@code{reset} (forcefully reset the guest).
1489
Other possible actions are:
1490
@code{shutdown} (attempt to gracefully shutdown the guest),
1491
@code{poweroff} (forcefully poweroff the guest),
1492
@code{pause} (pause the guest),
1493
@code{debug} (print a debug message and continue), or
1494
@code{none} (do nothing).
1495

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

    
1501
Examples:
1502

    
1503
@table @code
1504
@item -watchdog i6300esb -watchdog-action pause
1505
@item -watchdog ib700
1506
@end table
1507
ETEXI
1508

    
1509
DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
1510
    "-echr chr       set terminal escape character instead of ctrl-a\n")
1511
STEXI
1512

    
1513
@item -echr numeric_ascii_value
1514
Change the escape character used for switching to the monitor when using
1515
monitor and serial sharing.  The default is @code{0x01} when using the
1516
@code{-nographic} option.  @code{0x01} is equal to pressing
1517
@code{Control-a}.  You can select a different character from the ascii
1518
control keys where 1 through 26 map to Control-a through Control-z.  For
1519
instance you could use the either of the following to change the escape
1520
character to Control-t.
1521
@table @code
1522
@item -echr 0x14
1523
@item -echr 20
1524
@end table
1525
ETEXI
1526

    
1527
DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
1528
    "-virtioconsole c\n" \
1529
    "                set virtio console\n")
1530
STEXI
1531
@item -virtioconsole @var{c}
1532
Set virtio console.
1533
ETEXI
1534

    
1535
DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
1536
    "-show-cursor    show cursor\n")
1537
STEXI
1538
ETEXI
1539

    
1540
DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
1541
    "-tb-size n      set TB size\n")
1542
STEXI
1543
ETEXI
1544

    
1545
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
1546
    "-incoming p     prepare for incoming migration, listen on port p\n")
1547
STEXI
1548
ETEXI
1549

    
1550
#ifndef _WIN32
1551
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
1552
    "-chroot dir     Chroot to dir just before starting the VM.\n")
1553
#endif
1554
STEXI
1555
@item -chroot dir
1556
Immediately before starting guest execution, chroot to the specified
1557
directory.  Especially useful in combination with -runas.
1558
ETEXI
1559

    
1560
#ifndef _WIN32
1561
DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
1562
    "-runas user     Change to user id user just before starting the VM.\n")
1563
#endif
1564
STEXI
1565
@item -runas user
1566
Immediately before starting guest execution, drop root privileges, switching
1567
to the specified user.
1568
ETEXI
1569

    
1570
STEXI
1571
@end table
1572
ETEXI
1573

    
1574
#if defined(TARGET_SPARC) || defined(TARGET_PPC)
1575
DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
1576
    "-prom-env variable=value\n"
1577
    "                set OpenBIOS nvram variables\n")
1578
#endif
1579
#if defined(TARGET_ARM) || defined(TARGET_M68K)
1580
DEF("semihosting", 0, QEMU_OPTION_semihosting,
1581
    "-semihosting    semihosting mode\n")
1582
#endif
1583
#if defined(TARGET_ARM)
1584
DEF("old-param", 0, QEMU_OPTION_old_param,
1585
    "-old-param      old param mode\n")
1586
#endif