blob: 9519d9a072d78499b46b182bad73e0b6eb69d8ee [file] [log] [blame]
bellard386405f2003-03-23 21:28:45 +00001\input texinfo @c -*- texinfo -*-
bellarddebc7062006-04-30 21:58:41 +00002@c %**start of header
3@setfilename qemu-doc.info
bellard8f40c382006-09-20 20:28:05 +00004@settitle QEMU Emulator User Documentation
bellarddebc7062006-04-30 21:58:41 +00005@exampleindent 0
6@paragraphindent 0
7@c %**end of header
bellard386405f2003-03-23 21:28:45 +00008
bellard0806e3f2003-10-01 00:15:32 +00009@iftex
bellard386405f2003-03-23 21:28:45 +000010@titlepage
11@sp 7
bellard8f40c382006-09-20 20:28:05 +000012@center @titlefont{QEMU Emulator}
bellarddebc7062006-04-30 21:58:41 +000013@sp 1
14@center @titlefont{User Documentation}
bellard386405f2003-03-23 21:28:45 +000015@sp 3
16@end titlepage
bellard0806e3f2003-10-01 00:15:32 +000017@end iftex
bellard386405f2003-03-23 21:28:45 +000018
bellarddebc7062006-04-30 21:58:41 +000019@ifnottex
20@node Top
21@top
22
23@menu
24* Introduction::
25* Installation::
26* QEMU PC System emulator::
27* QEMU System emulator for non PC targets::
bellard83195232007-02-05 19:42:07 +000028* QEMU User space emulator::
bellarddebc7062006-04-30 21:58:41 +000029* compilation:: Compilation from the sources
30* Index::
31@end menu
32@end ifnottex
33
34@contents
35
36@node Introduction
bellard386405f2003-03-23 21:28:45 +000037@chapter Introduction
38
bellarddebc7062006-04-30 21:58:41 +000039@menu
40* intro_features:: Features
41@end menu
42
43@node intro_features
bellard322d0c62003-06-15 23:29:28 +000044@section Features
bellard386405f2003-03-23 21:28:45 +000045
bellard1f673132004-04-04 15:21:17 +000046QEMU is a FAST! processor emulator using dynamic translation to
47achieve good emulation speed.
bellard1eb20522003-06-25 16:21:49 +000048
49QEMU has two operating modes:
bellard0806e3f2003-10-01 00:15:32 +000050
51@itemize @minus
52
ths5fafdf22007-09-16 21:08:06 +000053@item
bellard1f673132004-04-04 15:21:17 +000054Full system emulation. In this mode, QEMU emulates a full system (for
bellard3f9f3aa2005-12-18 20:11:37 +000055example a PC), including one or several processors and various
56peripherals. It can be used to launch different Operating Systems
57without rebooting the PC or to debug system code.
bellard1eb20522003-06-25 16:21:49 +000058
ths5fafdf22007-09-16 21:08:06 +000059@item
bellard83195232007-02-05 19:42:07 +000060User mode emulation. In this mode, QEMU can launch
61processes compiled for one CPU on another CPU. It can be used to
bellard1f673132004-04-04 15:21:17 +000062launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63to ease cross-compilation and cross-debugging.
bellard1eb20522003-06-25 16:21:49 +000064
65@end itemize
66
bellard7c3fc842005-02-10 21:46:47 +000067QEMU can run without an host kernel driver and yet gives acceptable
ths5fafdf22007-09-16 21:08:06 +000068performance.
bellard322d0c62003-06-15 23:29:28 +000069
bellard52c00a52004-04-25 21:27:03 +000070For system emulation, the following hardware targets are supported:
71@itemize
bellard9d0a8e62005-07-03 17:34:05 +000072@item PC (x86 or x86_64 processor)
bellard3f9f3aa2005-12-18 20:11:37 +000073@item ISA PC (old style PC without PCI bus)
bellard52c00a52004-04-25 21:27:03 +000074@item PREP (PowerPC processor)
bellard9d0a8e62005-07-03 17:34:05 +000075@item G3 BW PowerMac (PowerPC processor)
76@item Mac99 PowerMac (PowerPC processor, in progress)
blueswir1ee76f822007-12-28 20:59:23 +000077@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
blueswir1c7ba2182008-07-22 07:07:34 +000078@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
thsd9aedc32007-12-17 03:47:55 +000079@item Malta board (32-bit and 64-bit MIPS processors)
aurel3288cb0a02008-04-08 05:57:37 +000080@item MIPS Magnum (64-bit MIPS processor)
pbrook9ee6e8b2007-11-11 00:04:49 +000081@item ARM Integrator/CP (ARM)
82@item ARM Versatile baseboard (ARM)
83@item ARM RealView Emulation baseboard (ARM)
balrogb00052e2007-04-30 02:22:06 +000084@item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
pbrook9ee6e8b2007-11-11 00:04:49 +000085@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
86@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
pbrook707e0112007-06-04 00:50:06 +000087@item Freescale MCF5208EVB (ColdFire V2).
pbrook209a4e62007-05-23 20:16:15 +000088@item Arnewsh MCF5206 evaluation board (ColdFire V2).
balrog02645922007-11-03 12:50:46 +000089@item Palm Tungsten|E PDA (OMAP310 processor)
balrogc30bb262008-05-18 13:01:40 +000090@item N800 and N810 tablets (OMAP2420 processor)
balrog57cd6e92008-05-07 12:23:32 +000091@item MusicPal (MV88W8618 ARM processor)
bellard52c00a52004-04-25 21:27:03 +000092@end itemize
bellard386405f2003-03-23 21:28:45 +000093
thsd9aedc32007-12-17 03:47:55 +000094For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +000095
bellarddebc7062006-04-30 21:58:41 +000096@node Installation
bellard5b9f4572003-10-28 00:49:54 +000097@chapter Installation
98
bellard15a34c62004-07-08 21:26:26 +000099If you want to compile QEMU yourself, see @ref{compilation}.
100
bellarddebc7062006-04-30 21:58:41 +0000101@menu
102* install_linux:: Linux
103* install_windows:: Windows
104* install_mac:: Macintosh
105@end menu
106
107@node install_linux
bellard1f673132004-04-04 15:21:17 +0000108@section Linux
109
bellard7c3fc842005-02-10 21:46:47 +0000110If a precompiled package is available for your distribution - you just
111have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000112
bellarddebc7062006-04-30 21:58:41 +0000113@node install_windows
bellard1f673132004-04-04 15:21:17 +0000114@section Windows
bellard8cd0ac22004-05-12 19:09:16 +0000115
bellard15a34c62004-07-08 21:26:26 +0000116Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000117@url{http://www.free.oszoo.org/@/download.html}.
bellardd691f662003-03-24 21:58:34 +0000118
bellarddebc7062006-04-30 21:58:41 +0000119@node install_mac
bellard1f673132004-04-04 15:21:17 +0000120@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000121
bellard15a34c62004-07-08 21:26:26 +0000122Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000123@url{http://www.free.oszoo.org/@/download.html}.
bellarddf0f11a2003-05-28 00:27:57 +0000124
bellarddebc7062006-04-30 21:58:41 +0000125@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000126@chapter QEMU PC System emulator
bellard1eb20522003-06-25 16:21:49 +0000127
bellarddebc7062006-04-30 21:58:41 +0000128@menu
129* pcsys_introduction:: Introduction
130* pcsys_quickstart:: Quick Start
131* sec_invocation:: Invocation
132* pcsys_keys:: Keys
133* pcsys_monitor:: QEMU Monitor
134* disk_images:: Disk Images
135* pcsys_network:: Network emulation
136* direct_linux_boot:: Direct Linux Boot
137* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000138* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000139* gdb_usage:: GDB usage
140* pcsys_os_specific:: Target OS specific information
141@end menu
142
143@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000144@section Introduction
145
146@c man begin DESCRIPTION
147
bellard3f9f3aa2005-12-18 20:11:37 +0000148The QEMU PC System emulator simulates the
149following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000150
151@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000152@item
bellard15a34c62004-07-08 21:26:26 +0000153i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000154@item
bellard15a34c62004-07-08 21:26:26 +0000155Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
156extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000157@item
158PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000159@item
bellard15a34c62004-07-08 21:26:26 +00001602 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000161@item
162Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000163@item
blueswir1c4a70602007-05-27 19:41:17 +0000164PCI/ISA PCI network adapters
bellard0806e3f2003-10-01 00:15:32 +0000165@item
bellard05d58182004-08-24 21:12:04 +0000166Serial ports
167@item
bellardc0fe3822005-11-05 18:55:28 +0000168Creative SoundBlaster 16 sound card
169@item
170ENSONIQ AudioPCI ES1370 sound card
171@item
balroge5c9a132008-01-14 04:27:55 +0000172Intel 82801AA AC97 Audio compatible sound card
173@item
bellardc0fe3822005-11-05 18:55:28 +0000174Adlib(OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000175@item
balrog26463db2008-01-17 21:47:25 +0000176Gravis Ultrasound GF1 sound card
177@item
malccc53d262008-06-13 10:48:22 +0000178CS4231A compatible sound card
179@item
bellardb389dbf2005-11-06 16:49:55 +0000180PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000181@end itemize
182
bellard3f9f3aa2005-12-18 20:11:37 +0000183SMP is supported with up to 255 CPUs.
184
malccc53d262008-06-13 10:48:22 +0000185Note that adlib, ac97, gus and cs4231a are only available when QEMU
malc0c58ac12008-06-25 21:04:05 +0000186was configured with --audio-card-list option containing the name(s) of
malce5178e82008-06-28 19:13:02 +0000187required card(s).
bellardc0fe3822005-11-05 18:55:28 +0000188
bellard15a34c62004-07-08 21:26:26 +0000189QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
190VGA BIOS.
191
bellardc0fe3822005-11-05 18:55:28 +0000192QEMU uses YM3812 emulation by Tatsuyuki Satoh.
193
balrog26463db2008-01-17 21:47:25 +0000194QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
195by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000196
malccc53d262008-06-13 10:48:22 +0000197CS4231A is the chip used in Windows Sound System and GUSMAX products
198
bellard0806e3f2003-10-01 00:15:32 +0000199@c man end
200
bellarddebc7062006-04-30 21:58:41 +0000201@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000202@section Quick Start
203
bellard285dc332003-10-27 23:58:04 +0000204Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000205
206@example
bellard285dc332003-10-27 23:58:04 +0000207qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000208@end example
209
210Linux should boot and give you a prompt.
211
bellard6cc721c2005-07-28 22:27:28 +0000212@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000213@section Invocation
214
215@example
216@c man begin SYNOPSIS
ths89dfe892007-11-21 22:38:37 +0000217usage: qemu [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000218@c man end
219@end example
220
221@c man begin OPTIONS
222@var{disk_image} is a raw hard disk image for IDE hard disk 0.
223
224General options:
225@table @option
ths89dfe892007-11-21 22:38:37 +0000226@item -M @var{machine}
227Select the emulated @var{machine} (@code{-M ?} for list)
bellard3dbbdc22005-11-06 18:20:37 +0000228
ths89dfe892007-11-21 22:38:37 +0000229@item -fda @var{file}
230@item -fdb @var{file}
bellarddebc7062006-04-30 21:58:41 +0000231Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
bellard19cb3732006-08-19 11:45:59 +0000232use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000233
ths89dfe892007-11-21 22:38:37 +0000234@item -hda @var{file}
235@item -hdb @var{file}
236@item -hdc @var{file}
237@item -hdd @var{file}
bellarddebc7062006-04-30 21:58:41 +0000238Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000239
ths89dfe892007-11-21 22:38:37 +0000240@item -cdrom @var{file}
241Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
bellardbe3edd92004-06-03 12:48:45 +0000242@option{-cdrom} at the same time). You can use the host CD-ROM by
bellard19cb3732006-08-19 11:45:59 +0000243using @file{/dev/cdrom} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000244
balroge0e7ada2007-12-11 21:56:43 +0000245@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
246
247Define a new drive. Valid options are:
248
249@table @code
250@item file=@var{file}
251This option defines which disk image (@pxref{disk_images}) to use with
balrog609497a2008-01-14 02:56:53 +0000252this drive. If the filename contains comma, you must double it
253(for instance, "file=my,,file" to use file "my,file").
balroge0e7ada2007-12-11 21:56:43 +0000254@item if=@var{interface}
255This option defines on which type on interface the drive is connected.
256Available types are: ide, scsi, sd, mtd, floppy, pflash.
257@item bus=@var{bus},unit=@var{unit}
258These options define where is connected the drive by defining the bus number and
259the unit id.
260@item index=@var{index}
261This option defines where is connected the drive by using an index in the list
262of available connectors of a given interface type.
263@item media=@var{media}
264This option defines the type of the media: disk or cdrom.
265@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
266These options have the same definition as they have in @option{-hdachs}.
267@item snapshot=@var{snapshot}
268@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
balrog33f00272007-12-24 14:33:24 +0000269@item cache=@var{cache}
270@var{cache} is "on" or "off" and allows to disable host cache to access data.
aurel321e72d3b2008-04-28 20:26:45 +0000271@item format=@var{format}
272Specify which disk @var{format} will be used rather than detecting
273the format. Can be used to specifiy format=raw to avoid interpreting
274an untrusted format header.
balroge0e7ada2007-12-11 21:56:43 +0000275@end table
276
277Instead of @option{-cdrom} you can use:
278@example
279qemu -drive file=file,index=2,media=cdrom
280@end example
281
282Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
283use:
284@example
285qemu -drive file=file,index=0,media=disk
286qemu -drive file=file,index=1,media=disk
287qemu -drive file=file,index=2,media=disk
288qemu -drive file=file,index=3,media=disk
289@end example
290
291You can connect a CDROM to the slave of ide0:
292@example
293qemu -drive file=file,if=ide,index=1,media=cdrom
294@end example
295
296If you don't specify the "file=" argument, you define an empty drive:
297@example
298qemu -drive if=ide,index=1,media=cdrom
299@end example
300
301You can connect a SCSI disk with unit ID 6 on the bus #0:
302@example
303qemu -drive file=file,if=scsi,bus=0,unit=6
304@end example
305
306Instead of @option{-fda}, @option{-fdb}, you can use:
307@example
308qemu -drive file=file,index=0,if=floppy
309qemu -drive file=file,index=1,if=floppy
310@end example
311
312By default, @var{interface} is "ide" and @var{index} is automatically
313incremented:
314@example
315qemu -drive file=a -drive file=b"
316@end example
317is interpreted like:
318@example
319qemu -hda a -hdb b
320@end example
321
thseec85c22007-01-05 17:41:07 +0000322@item -boot [a|c|d|n]
323Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
324is the default.
bellard1f673132004-04-04 15:21:17 +0000325
326@item -snapshot
327Write to temporary files instead of disk image files. In this case,
328the raw disk image you use is not written back. You can however force
ths42550fd2006-12-22 16:34:12 +0000329the write back by pressing @key{C-a s} (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000330
bellard52ca8d62006-06-14 16:03:05 +0000331@item -no-fd-bootchk
332Disable boot signature checking for floppy disks in Bochs BIOS. It may
333be needed to boot from old floppy disks.
334
ths89dfe892007-11-21 22:38:37 +0000335@item -m @var{megs}
aurel3200f82b82008-04-27 21:12:55 +0000336Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
337a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
338gigabytes respectively.
bellard1f673132004-04-04 15:21:17 +0000339
ths89dfe892007-11-21 22:38:37 +0000340@item -smp @var{n}
bellard3f9f3aa2005-12-18 20:11:37 +0000341Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
blueswir1a785e422007-10-20 08:09:05 +0000342CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
343to 4.
bellard3f9f3aa2005-12-18 20:11:37 +0000344
bellard1d14ffa2005-10-30 18:58:22 +0000345@item -audio-help
346
347Will show the audio subsystem help: list of drivers, tunable
348parameters.
349
ths89dfe892007-11-21 22:38:37 +0000350@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
bellard1d14ffa2005-10-30 18:58:22 +0000351
352Enable audio and selected sound hardware. Use ? to print all
353available sound hardware.
354
355@example
356qemu -soundhw sb16,adlib hda
357qemu -soundhw es1370 hda
balroge5c9a132008-01-14 04:27:55 +0000358qemu -soundhw ac97 hda
bellard6a36d842005-12-18 20:34:32 +0000359qemu -soundhw all hda
bellard1d14ffa2005-10-30 18:58:22 +0000360qemu -soundhw ?
361@end example
bellarda8c490c2004-04-26 20:59:17 +0000362
balroge5c9a132008-01-14 04:27:55 +0000363Note that Linux's i810_audio OSS kernel (for AC97) module might
364require manually specifying clocking.
365
366@example
367modprobe i810_audio clocking=48000
368@end example
369
bellard15a34c62004-07-08 21:26:26 +0000370@item -localtime
371Set the real time clock to local time (the default is to UTC
372time). This option is needed to have correct date in MS-DOS or
373Windows.
374
ths89dfe892007-11-21 22:38:37 +0000375@item -startdate @var{date}
bellard7e0af5d02007-11-07 16:24:33 +0000376Set the initial date of the real time clock. Valid format for
377@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
378@code{2006-06-17}. The default value is @code{now}.
379
ths89dfe892007-11-21 22:38:37 +0000380@item -pidfile @var{file}
bellardf7cce892004-12-08 22:21:25 +0000381Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
382from a script.
383
ths71e3ceb2006-12-22 02:11:31 +0000384@item -daemonize
385Daemonize the QEMU process after initialization. QEMU will not detach from
386standard IO until it is ready to receive connections on any of its devices.
387This option is a useful way for external programs to launch QEMU without having
388to cope with initialization race conditions.
389
bellard9d0a8e62005-07-03 17:34:05 +0000390@item -win2k-hack
391Use it when installing Windows 2000 to avoid a disk full bug. After
392Windows 2000 is installed, you no longer need this option (this option
393slows down the IDE transfers).
394
ths89dfe892007-11-21 22:38:37 +0000395@item -option-rom @var{file}
396Load the contents of @var{file} as an option ROM.
397This option is useful to load things like EtherBoot.
ths9ae02552007-01-05 17:39:04 +0000398
ths89dfe892007-11-21 22:38:37 +0000399@item -name @var{name}
400Sets the @var{name} of the guest.
401This name will be display in the SDL window caption.
402The @var{name} will also be used for the VNC server.
thsc35734b2007-03-19 15:17:08 +0000403
bellard1f673132004-04-04 15:21:17 +0000404@end table
405
thsf858dca2007-08-25 01:40:37 +0000406Display options:
407@table @option
408
409@item -nographic
410
411Normally, QEMU uses SDL to display the VGA output. With this option,
412you can totally disable graphical output so that QEMU is a simple
413command line application. The emulated serial port is redirected on
414the console. Therefore, you can still use QEMU to debug a Linux kernel
415with a serial console.
416
aurel32052caf72008-03-18 06:51:54 +0000417@item -curses
418
419Normally, QEMU uses SDL to display the VGA output. With this option,
420QEMU can display the VGA output when in text mode using a
421curses/ncurses interface. Nothing is displayed in graphical mode.
422
thsf858dca2007-08-25 01:40:37 +0000423@item -no-frame
424
425Do not use decorations for SDL windows and start them using the whole
426available screen space. This makes the using QEMU in a dedicated desktop
427workspace more convenient.
428
aurel3299aa9e42008-04-11 21:35:59 +0000429@item -no-quit
430
431Disable SDL window close capability.
432
thsf858dca2007-08-25 01:40:37 +0000433@item -full-screen
434Start in full screen.
435
ths89dfe892007-11-21 22:38:37 +0000436@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
thsf858dca2007-08-25 01:40:37 +0000437
438Normally, QEMU uses SDL to display the VGA output. With this option,
439you can have QEMU listen on VNC display @var{display} and redirect the VGA
440display over the VNC session. It is very useful to enable the usb
441tablet device when using this option (option @option{-usbdevice
442tablet}). When using the VNC display, you must use the @option{-k}
443parameter to set the keyboard layout if you are not using en-us. Valid
444syntax for the @var{display} is
445
446@table @code
447
balrog3aa3eea2008-02-03 02:54:04 +0000448@item @var{host}:@var{d}
thsf858dca2007-08-25 01:40:37 +0000449
balrog3aa3eea2008-02-03 02:54:04 +0000450TCP connections will only be allowed from @var{host} on display @var{d}.
451By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
452be omitted in which case the server will accept connections from any host.
thsf858dca2007-08-25 01:40:37 +0000453
balrog3aa3eea2008-02-03 02:54:04 +0000454@item @code{unix}:@var{path}
thsf858dca2007-08-25 01:40:37 +0000455
456Connections will be allowed over UNIX domain sockets where @var{path} is the
457location of a unix socket to listen for connections on.
458
ths89dfe892007-11-21 22:38:37 +0000459@item none
thsf858dca2007-08-25 01:40:37 +0000460
balrog3aa3eea2008-02-03 02:54:04 +0000461VNC is initialized but not started. The monitor @code{change} command
462can be used to later start the VNC server.
thsf858dca2007-08-25 01:40:37 +0000463
464@end table
465
466Following the @var{display} value there may be one or more @var{option} flags
467separated by commas. Valid options are
468
469@table @code
470
balrog3aa3eea2008-02-03 02:54:04 +0000471@item reverse
472
473Connect to a listening VNC client via a ``reverse'' connection. The
474client is specified by the @var{display}. For reverse network
475connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
476is a TCP port number, not a display number.
477
ths89dfe892007-11-21 22:38:37 +0000478@item password
thsf858dca2007-08-25 01:40:37 +0000479
480Require that password based authentication is used for client connections.
481The password must be set separately using the @code{change} command in the
482@ref{pcsys_monitor}
483
ths89dfe892007-11-21 22:38:37 +0000484@item tls
thsf858dca2007-08-25 01:40:37 +0000485
486Require that client use TLS when communicating with the VNC server. This
487uses anonymous TLS credentials so is susceptible to a man-in-the-middle
488attack. It is recommended that this option be combined with either the
489@var{x509} or @var{x509verify} options.
490
ths89dfe892007-11-21 22:38:37 +0000491@item x509=@var{/path/to/certificate/dir}
thsf858dca2007-08-25 01:40:37 +0000492
ths89dfe892007-11-21 22:38:37 +0000493Valid if @option{tls} is specified. Require that x509 credentials are used
thsf858dca2007-08-25 01:40:37 +0000494for negotiating the TLS session. The server will send its x509 certificate
495to the client. It is recommended that a password be set on the VNC server
496to provide authentication of the client when this is used. The path following
497this option specifies where the x509 certificates are to be loaded from.
498See the @ref{vnc_security} section for details on generating certificates.
499
ths89dfe892007-11-21 22:38:37 +0000500@item x509verify=@var{/path/to/certificate/dir}
thsf858dca2007-08-25 01:40:37 +0000501
ths89dfe892007-11-21 22:38:37 +0000502Valid if @option{tls} is specified. Require that x509 credentials are used
thsf858dca2007-08-25 01:40:37 +0000503for negotiating the TLS session. The server will send its x509 certificate
504to the client, and request that the client send its own x509 certificate.
505The server will validate the client's certificate against the CA certificate,
506and reject clients when validation fails. If the certificate authority is
507trusted, this is a sufficient authentication mechanism. You may still wish
508to set a password on the VNC server as a second authentication layer. The
509path following this option specifies where the x509 certificates are to
510be loaded from. See the @ref{vnc_security} section for details on generating
511certificates.
512
513@end table
514
ths89dfe892007-11-21 22:38:37 +0000515@item -k @var{language}
thsf858dca2007-08-25 01:40:37 +0000516
517Use keyboard layout @var{language} (for example @code{fr} for
518French). This option is only needed where it is not easy to get raw PC
519keycodes (e.g. on Macs, with some X11 servers or with a VNC
520display). You don't normally need to use it on PC/Linux or PC/Windows
521hosts.
522
523The available layouts are:
524@example
525ar de-ch es fo fr-ca hu ja mk no pt-br sv
526da en-gb et fr fr-ch is lt nl pl ru th
527de en-us fi fr-be hr it lv nl-be pt sl tr
528@end example
529
530The default is @code{en-us}.
531
532@end table
533
bellardb389dbf2005-11-06 16:49:55 +0000534USB options:
535@table @option
536
537@item -usb
538Enable the USB driver (will be the default soon)
539
ths89dfe892007-11-21 22:38:37 +0000540@item -usbdevice @var{devname}
pbrook0aff66b2006-05-26 00:49:52 +0000541Add the USB device @var{devname}. @xref{usb_devices}.
ths8fccda82008-01-09 12:14:45 +0000542
543@table @code
544
545@item mouse
546Virtual Mouse. This will override the PS/2 mouse emulation when activated.
547
548@item tablet
549Pointer device that uses absolute coordinates (like a touchscreen). This
550means qemu is able to report the mouse position without having to grab the
551mouse. Also overrides the PS/2 mouse emulation when activated.
552
aurel32334c0242008-08-21 22:24:32 +0000553@item disk:[format=@var{format}]:file
554Mass storage device based on file. The optional @var{format} argument
555will be used rather than detecting the format. Can be used to specifiy
556format=raw to avoid interpreting an untrusted format header.
ths8fccda82008-01-09 12:14:45 +0000557
558@item host:bus.addr
559Pass through the host device identified by bus.addr (Linux only).
560
561@item host:vendor_id:product_id
562Pass through the host device identified by vendor_id:product_id (Linux only).
563
balrogdb380c02008-01-17 22:22:45 +0000564@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
565Serial converter to host character device @var{dev}, see @code{-serial} for the
566available devices.
567
aurel322e4d9fb2008-04-08 06:01:02 +0000568@item braille
569Braille device. This will use BrlAPI to display the braille output on a real
570or fake device.
571
balrog9ad97e62008-07-29 13:16:31 +0000572@item net:options
balrog6c9f8862008-07-17 20:47:13 +0000573Network adapter that supports CDC ethernet and RNDIS protocols.
574
ths8fccda82008-01-09 12:14:45 +0000575@end table
576
bellardb389dbf2005-11-06 16:49:55 +0000577@end table
578
bellard1f673132004-04-04 15:21:17 +0000579Network options:
580
581@table @option
582
ths89dfe892007-11-21 22:38:37 +0000583@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
bellard41d03942005-11-15 23:02:53 +0000584Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
blueswir1c4a70602007-05-27 19:41:17 +0000585= 0 is the default). The NIC is an ne2k_pci by default on the PC
bellard41d03942005-11-15 23:02:53 +0000586target. Optionally, the MAC address can be changed. If no
587@option{-net} option is specified, a single NIC is created.
balrog549444e2007-05-01 17:53:37 +0000588Qemu can emulate several different models of network card.
589Valid values for @var{type} are
590@code{i82551}, @code{i82557b}, @code{i82559er},
591@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
balrog9ad97e62008-07-29 13:16:31 +0000592@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
blueswir1c4a70602007-05-27 19:41:17 +0000593Not all devices are supported on all targets. Use -net nic,model=?
594for a list of available devices for your target.
bellard1f673132004-04-04 15:21:17 +0000595
ths89dfe892007-11-21 22:38:37 +0000596@item -net user[,vlan=@var{n}][,hostname=@var{name}]
bellard7e894632005-11-19 17:42:52 +0000597Use the user mode network stack which requires no administrator
ths4be456f2007-06-03 13:41:28 +0000598privilege to run. @option{hostname=name} can be used to specify the client
pbrook115defd2006-04-16 11:06:58 +0000599hostname reported by the builtin DHCP server.
bellard3f1a88f2005-06-05 16:48:41 +0000600
ths89dfe892007-11-21 22:38:37 +0000601@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}]
bellard41d03942005-11-15 23:02:53 +0000602Connect the host TAP network interface @var{name} to VLAN @var{n} and
603use the network script @var{file} to configure it. The default
ths6a1cbf62007-02-02 00:37:56 +0000604network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
605disable script execution. If @var{name} is not
ths89dfe892007-11-21 22:38:37 +0000606provided, the OS automatically provides one. @option{fd}=@var{h} can be
bellard41d03942005-11-15 23:02:53 +0000607used to specify the handle of an already opened host TAP interface. Example:
bellard3f1a88f2005-06-05 16:48:41 +0000608
bellard41d03942005-11-15 23:02:53 +0000609@example
610qemu linux.img -net nic -net tap
611@end example
bellard1f673132004-04-04 15:21:17 +0000612
bellard41d03942005-11-15 23:02:53 +0000613More complicated example (two NICs, each one connected to a TAP device)
614@example
615qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
616 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
617@end example
bellard1f673132004-04-04 15:21:17 +0000618
bellard52c00a52004-04-25 21:27:03 +0000619
ths89dfe892007-11-21 22:38:37 +0000620@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
bellard41d03942005-11-15 23:02:53 +0000621
622Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
623machine using a TCP socket connection. If @option{listen} is
624specified, QEMU waits for incoming connections on @var{port}
625(@var{host} is optional). @option{connect} is used to connect to
ths89dfe892007-11-21 22:38:37 +0000626another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
bellard3d830452005-12-18 16:36:49 +0000627specifies an already opened TCP socket.
bellard41d03942005-11-15 23:02:53 +0000628
629Example:
630@example
631# launch a first QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000632qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
633 -net socket,listen=:1234
634# connect the VLAN 0 of this instance to the VLAN 0
635# of the first instance
636qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
637 -net socket,connect=127.0.0.1:1234
bellard41d03942005-11-15 23:02:53 +0000638@end example
639
ths89dfe892007-11-21 22:38:37 +0000640@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
bellard3d830452005-12-18 16:36:49 +0000641
642Create a VLAN @var{n} shared with another QEMU virtual
ths5fafdf22007-09-16 21:08:06 +0000643machines using a UDP multicast socket, effectively making a bus for
bellard3d830452005-12-18 16:36:49 +0000644every QEMU with same multicast address @var{maddr} and @var{port}.
645NOTES:
646@enumerate
ths5fafdf22007-09-16 21:08:06 +0000647@item
648Several QEMU can be running on different hosts and share same bus (assuming
bellard3d830452005-12-18 16:36:49 +0000649correct multicast setup for these hosts).
650@item
651mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
652@url{http://user-mode-linux.sf.net}.
ths4be456f2007-06-03 13:41:28 +0000653@item
654Use @option{fd=h} to specify an already opened UDP multicast socket.
bellard3d830452005-12-18 16:36:49 +0000655@end enumerate
656
657Example:
658@example
659# launch one QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000660qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
661 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000662# launch another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000663qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
664 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000665# launch yet another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000666qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
667 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000668@end example
669
670Example (User Mode Linux compat.):
671@example
bellarddebc7062006-04-30 21:58:41 +0000672# launch QEMU instance (note mcast address selected
673# is UML's default)
674qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
675 -net socket,mcast=239.192.168.1:1102
bellard3d830452005-12-18 16:36:49 +0000676# launch UML
677/path/to/linux ubd0=/path/to/root_fs eth0=mcast
678@end example
679
ths8a16d272008-07-19 09:56:24 +0000680@item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
681Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
682listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
683and MODE @var{octalmode} to change default ownership and permissions for
684communication port. This option is available only if QEMU has been compiled
685with vde support enabled.
686
687Example:
688@example
689# launch vde switch
690vde_switch -F -sock /tmp/myswitch
691# launch QEMU instance
692qemu linux.img -net nic -net vde,sock=/tmp/myswitch
693@end example
694
bellard41d03942005-11-15 23:02:53 +0000695@item -net none
696Indicate that no network devices should be configured. It is used to
bellard039af322006-02-01 21:30:55 +0000697override the default configuration (@option{-net nic -net user}) which
698is activated if no @option{-net} options are provided.
bellard52c00a52004-04-25 21:27:03 +0000699
ths89dfe892007-11-21 22:38:37 +0000700@item -tftp @var{dir}
bellard9bf05442004-08-25 22:12:49 +0000701When using the user mode network stack, activate a built-in TFTP
ths0db11372007-02-20 00:12:07 +0000702server. The files in @var{dir} will be exposed as the root of a TFTP server.
703The TFTP client on the guest must be configured in binary mode (use the command
704@code{bin} of the Unix TFTP client). The host IP address on the guest is as
705usual 10.0.2.2.
bellard9bf05442004-08-25 22:12:49 +0000706
ths89dfe892007-11-21 22:38:37 +0000707@item -bootp @var{file}
ths47d5d012007-02-20 00:05:08 +0000708When using the user mode network stack, broadcast @var{file} as the BOOTP
709filename. In conjunction with @option{-tftp}, this can be used to network boot
710a guest from a local directory.
711
712Example (using pxelinux):
713@example
714qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
715@end example
716
ths89dfe892007-11-21 22:38:37 +0000717@item -smb @var{dir}
bellard2518bd02004-09-30 22:35:13 +0000718When using the user mode network stack, activate a built-in SMB
ths89dfe892007-11-21 22:38:37 +0000719server so that Windows OSes can access to the host files in @file{@var{dir}}
bellard2518bd02004-09-30 22:35:13 +0000720transparently.
721
722In the guest Windows OS, the line:
723@example
72410.0.2.4 smbserver
725@end example
726must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
727or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
728
ths89dfe892007-11-21 22:38:37 +0000729Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
bellard2518bd02004-09-30 22:35:13 +0000730
731Note that a SAMBA server must be installed on the host OS in
ths366dfc52006-12-11 18:35:08 +0000732@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
bellard6cc721c2005-07-28 22:27:28 +00007332.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
bellard2518bd02004-09-30 22:35:13 +0000734
ths89dfe892007-11-21 22:38:37 +0000735@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
bellard9bf05442004-08-25 22:12:49 +0000736
737When using the user mode network stack, redirect incoming TCP or UDP
738connections to the host port @var{host-port} to the guest
739@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
740is not specified, its value is 10.0.2.15 (default address given by the
741built-in DHCP server).
742
743For example, to redirect host X11 connection from screen 1 to guest
744screen 0, use the following:
745
746@example
747# on the host
748qemu -redir tcp:6001::6000 [...]
749# this host xterm should open in the guest X11 server
750xterm -display :1
751@end example
752
753To redirect telnet connections from host port 5555 to telnet port on
754the guest, use the following:
755
756@example
757# on the host
758qemu -redir tcp:5555::23 [...]
759telnet localhost 5555
760@end example
761
762Then when you use on the host @code{telnet localhost 5555}, you
763connect to the guest telnet server.
764
bellard1f673132004-04-04 15:21:17 +0000765@end table
766
bellard41d03942005-11-15 23:02:53 +0000767Linux boot specific: When using these options, you can use a given
bellard1f673132004-04-04 15:21:17 +0000768Linux kernel without installing it in the disk image. It can be useful
769for easier testing of various kernels.
770
771@table @option
772
ths89dfe892007-11-21 22:38:37 +0000773@item -kernel @var{bzImage}
bellard1f673132004-04-04 15:21:17 +0000774Use @var{bzImage} as kernel image.
775
ths89dfe892007-11-21 22:38:37 +0000776@item -append @var{cmdline}
bellard1f673132004-04-04 15:21:17 +0000777Use @var{cmdline} as kernel command line
778
ths89dfe892007-11-21 22:38:37 +0000779@item -initrd @var{file}
bellard1f673132004-04-04 15:21:17 +0000780Use @var{file} as initial ram disk.
781
782@end table
783
bellard15a34c62004-07-08 21:26:26 +0000784Debug/Expert options:
bellard1f673132004-04-04 15:21:17 +0000785@table @option
bellarda0a821a2004-07-14 17:38:57 +0000786
ths89dfe892007-11-21 22:38:37 +0000787@item -serial @var{dev}
bellard0bab00f2006-06-25 14:49:44 +0000788Redirect the virtual serial port to host character device
789@var{dev}. The default device is @code{vc} in graphical mode and
790@code{stdio} in non graphical mode.
791
792This option can be used several times to simulate up to 4 serials
793ports.
794
bellardc03b0f02006-09-03 14:10:53 +0000795Use @code{-serial none} to disable all serial ports.
796
bellard0bab00f2006-06-25 14:49:44 +0000797Available character devices are:
bellarda0a821a2004-07-14 17:38:57 +0000798@table @code
thsaf3a9032007-07-11 23:14:59 +0000799@item vc[:WxH]
800Virtual console. Optionally, a width and height can be given in pixel with
801@example
802vc:800x600
803@end example
804It is also possible to specify width or height in characters:
805@example
806vc:80Cx24C
807@end example
bellarda0a821a2004-07-14 17:38:57 +0000808@item pty
809[Linux only] Pseudo TTY (a new PTY is automatically allocated)
bellardc03b0f02006-09-03 14:10:53 +0000810@item none
811No device is allocated.
bellarda0a821a2004-07-14 17:38:57 +0000812@item null
813void device
bellardf8d179e2005-11-08 22:30:36 +0000814@item /dev/XXX
bellarde57a8c02005-11-10 23:58:52 +0000815[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
bellardf8d179e2005-11-08 22:30:36 +0000816parameters are set according to the emulated ones.
ths89dfe892007-11-21 22:38:37 +0000817@item /dev/parport@var{N}
bellarde57a8c02005-11-10 23:58:52 +0000818[Linux only, parallel port only] Use host parallel port
ths5867c882007-02-17 23:44:43 +0000819@var{N}. Currently SPP and EPP parallel port features can be used.
ths89dfe892007-11-21 22:38:37 +0000820@item file:@var{filename}
821Write output to @var{filename}. No character can be read.
bellarda0a821a2004-07-14 17:38:57 +0000822@item stdio
823[Unix only] standard input/output
ths89dfe892007-11-21 22:38:37 +0000824@item pipe:@var{filename}
bellard0bab00f2006-06-25 14:49:44 +0000825name pipe @var{filename}
ths89dfe892007-11-21 22:38:37 +0000826@item COM@var{n}
bellard0bab00f2006-06-25 14:49:44 +0000827[Windows only] Use host serial port @var{n}
ths89dfe892007-11-21 22:38:37 +0000828@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
829This implements UDP Net Console.
830When @var{remote_host} or @var{src_ip} are not specified
831they default to @code{0.0.0.0}.
832When not using a specified @var{src_port} a random port is automatically chosen.
bellarda0a821a2004-07-14 17:38:57 +0000833
bellard951f1352006-06-27 21:02:43 +0000834If you just want a simple readonly console you can use @code{netcat} or
835@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
836@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
837will appear in the netconsole session.
bellard0bab00f2006-06-25 14:49:44 +0000838
839If you plan to send characters back via netconsole or you want to stop
840and start qemu a lot of times, you should have qemu use the same
841source port each time by using something like @code{-serial
bellard951f1352006-06-27 21:02:43 +0000842udp::4555@@:4556} to qemu. Another approach is to use a patched
bellard0bab00f2006-06-25 14:49:44 +0000843version of netcat which can listen to a TCP port and send and receive
844characters via udp. If you have a patched version of netcat which
845activates telnet remote echo and single char transfer, then you can
846use the following options to step up a netcat redirector to allow
847telnet on port 5555 to access the qemu port.
848@table @code
bellard951f1352006-06-27 21:02:43 +0000849@item Qemu Options:
850-serial udp::4555@@:4556
851@item netcat options:
852-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
853@item telnet options:
854localhost 5555
bellard0bab00f2006-06-25 14:49:44 +0000855@end table
856
857
ths89dfe892007-11-21 22:38:37 +0000858@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000859The TCP Net Console has two modes of operation. It can send the serial
860I/O to a location or wait for a connection from a location. By default
861the TCP Net Console is sent to @var{host} at the @var{port}. If you use
bellardf5420862006-08-21 20:26:44 +0000862the @var{server} option QEMU will wait for a client socket application
863to connect to the port before continuing, unless the @code{nowait}
pbrookf7499982007-01-28 00:10:01 +0000864option was specified. The @code{nodelay} option disables the Nagle buffering
ths4be456f2007-06-03 13:41:28 +0000865algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
bellard951f1352006-06-27 21:02:43 +0000866one TCP connection at a time is accepted. You can use @code{telnet} to
867connect to the corresponding character device.
868@table @code
869@item Example to send tcp console to 192.168.0.2 port 4444
870-serial tcp:192.168.0.2:4444
871@item Example to listen and wait on port 4444 for connection
872-serial tcp::4444,server
873@item Example to not wait and listen on ip 192.168.0.100 port 4444
874-serial tcp:192.168.0.100:4444,server,nowait
875@end table
876
ths89dfe892007-11-21 22:38:37 +0000877@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000878The telnet protocol is used instead of raw tcp sockets. The options
879work the same as if you had specified @code{-serial tcp}. The
880difference is that the port acts like a telnet server or client using
881telnet option negotiation. This will also allow you to send the
882MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
883sequence. Typically in unix telnet you do it with Control-] and then
884type "send break" followed by pressing the enter key.
885
ths89dfe892007-11-21 22:38:37 +0000886@item unix:@var{path}[,server][,nowait]
thsffd843b2006-12-21 19:46:43 +0000887A unix domain socket is used instead of a tcp socket. The option works the
888same as if you had specified @code{-serial tcp} except the unix domain socket
889@var{path} is used for connections.
890
ths89dfe892007-11-21 22:38:37 +0000891@item mon:@var{dev_string}
ths20d8a3e2007-02-18 17:04:49 +0000892This is a special option to allow the monitor to be multiplexed onto
893another serial port. The monitor is accessed with key sequence of
894@key{Control-a} and then pressing @key{c}. See monitor access
895@ref{pcsys_keys} in the -nographic section for more keys.
896@var{dev_string} should be any one of the serial devices specified
897above. An example to multiplex the monitor onto a telnet server
898listening on port 4444 would be:
899@table @code
900@item -serial mon:telnet::4444,server,nowait
901@end table
902
aurel322e4d9fb2008-04-08 06:01:02 +0000903@item braille
904Braille device. This will use BrlAPI to display the braille output on a real
905or fake device.
906
bellard0bab00f2006-06-25 14:49:44 +0000907@end table
bellard05d58182004-08-24 21:12:04 +0000908
ths89dfe892007-11-21 22:38:37 +0000909@item -parallel @var{dev}
bellarde57a8c02005-11-10 23:58:52 +0000910Redirect the virtual parallel port to host device @var{dev} (same
911devices as the serial port). On Linux hosts, @file{/dev/parportN} can
912be used to use hardware devices connected on the corresponding host
913parallel port.
914
915This option can be used several times to simulate up to 3 parallel
916ports.
917
bellardc03b0f02006-09-03 14:10:53 +0000918Use @code{-parallel none} to disable all parallel ports.
919
ths89dfe892007-11-21 22:38:37 +0000920@item -monitor @var{dev}
bellarda0a821a2004-07-14 17:38:57 +0000921Redirect the monitor to host device @var{dev} (same devices as the
922serial port).
923The default device is @code{vc} in graphical mode and @code{stdio} in
924non graphical mode.
925
ths20d8a3e2007-02-18 17:04:49 +0000926@item -echr numeric_ascii_value
927Change the escape character used for switching to the monitor when using
928monitor and serial sharing. The default is @code{0x01} when using the
929@code{-nographic} option. @code{0x01} is equal to pressing
930@code{Control-a}. You can select a different character from the ascii
931control keys where 1 through 26 map to Control-a through Control-z. For
932instance you could use the either of the following to change the escape
933character to Control-t.
934@table @code
935@item -echr 0x14
936@item -echr 20
937@end table
938
bellard1f673132004-04-04 15:21:17 +0000939@item -s
ths5fafdf22007-09-16 21:08:06 +0000940Wait gdb connection to port 1234 (@pxref{gdb_usage}).
ths89dfe892007-11-21 22:38:37 +0000941@item -p @var{port}
pbrook4046d912007-01-28 01:53:16 +0000942Change gdb connection port. @var{port} can be either a decimal number
943to specify a TCP port, or a host device (same devices as the serial port).
bellard52c00a52004-04-25 21:27:03 +0000944@item -S
945Do not start CPU at startup (you must type 'c' in the monitor).
ths3b46e622007-09-17 08:09:54 +0000946@item -d
bellard1f673132004-04-04 15:21:17 +0000947Output log in /tmp/qemu.log
ths89dfe892007-11-21 22:38:37 +0000948@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
bellard46d47672004-11-16 01:45:27 +0000949Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
950@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
951translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
ths4be456f2007-06-03 13:41:28 +0000952all those parameters. This option is useful for old MS-DOS disk
bellard46d47672004-11-16 01:45:27 +0000953images.
bellard7c3fc842005-02-10 21:46:47 +0000954
bellard87b47352006-08-17 17:22:54 +0000955@item -L path
956Set the directory for the BIOS, VGA BIOS and keymaps.
957
bellard15a34c62004-07-08 21:26:26 +0000958@item -std-vga
959Simulate a standard VGA card with Bochs VBE extensions (default is
bellard3cb08532006-06-21 21:19:50 +0000960Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
961VBE extensions (e.g. Windows XP) and if you want to use high
962resolution modes (>= 1280x1024x16) then you should use this option.
963
bellard3c656342006-07-14 13:13:51 +0000964@item -no-acpi
965Disable ACPI (Advanced Configuration and Power Interface) support. Use
966it if your guest OS complains about ACPI problems (PC target machine
967only).
968
bellardd1beab82006-10-02 19:44:22 +0000969@item -no-reboot
970Exit instead of rebooting.
971
aurel3299aa9e42008-04-11 21:35:59 +0000972@item -no-shutdown
973Don't exit QEMU on guest shutdown, but instead only stop the emulation.
974This allows for instance switching to monitor to commit changes to the
975disk image.
976
bellardd63d3072004-10-03 13:29:03 +0000977@item -loadvm file
978Start right away with a saved state (@code{loadvm} in monitor)
pbrook8e716212007-01-20 17:12:09 +0000979
980@item -semihosting
pbrooka87295e2007-05-26 15:09:38 +0000981Enable semihosting syscall emulation (ARM and M68K target machines only).
982
983On ARM this implements the "Angel" interface.
984On M68K this implements the "ColdFire GDB" interface used by libgloss.
985
pbrook8e716212007-01-20 17:12:09 +0000986Note that this allows guest direct access to the host filesystem,
987so should only be used with trusted guest OS.
pbrook2e70f6e2008-06-29 01:03:05 +0000988
989@item -icount [N|auto]
990Enable virtual instruction counter. The virtual cpu will execute one
991instruction every 2^N ns of virtual time. If @code{auto} is specified
992then the virtual cpu speed will be automatically adjusted to keep virtual
993time within a few seconds of real time.
994
995Note that while this option can give deterministic behavior, it does not
996provide cycle accurate emulation. Modern CPUs contain superscalar out of
pbrookdd5d6fe2008-06-29 10:43:16 +0000997order cores with complex cache hierarchies. The number of instructions
pbrook2e70f6e2008-06-29 01:03:05 +0000998executed often has little or no correlation with actual performance.
bellard1f673132004-04-04 15:21:17 +0000999@end table
1000
bellard3e11db92004-07-14 17:47:14 +00001001@c man end
1002
bellarddebc7062006-04-30 21:58:41 +00001003@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +00001004@section Keys
1005
1006@c man begin OPTIONS
1007
bellarda1b74fe2004-05-08 13:26:35 +00001008During the graphical emulation, you can use the following keys:
1009@table @key
bellardf9859312004-10-03 14:33:10 +00001010@item Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +00001011Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +00001012
bellardf9859312004-10-03 14:33:10 +00001013@item Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +00001014Switch to virtual console 'n'. Standard console mappings are:
1015@table @emph
1016@item 1
1017Target system display
1018@item 2
1019Monitor
1020@item 3
1021Serial port
bellarda1b74fe2004-05-08 13:26:35 +00001022@end table
1023
bellardf9859312004-10-03 14:33:10 +00001024@item Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +00001025Toggle mouse and keyboard grab.
1026@end table
1027
bellard3e11db92004-07-14 17:47:14 +00001028In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
1029@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
1030
bellarda0a821a2004-07-14 17:38:57 +00001031During emulation, if you are using the @option{-nographic} option, use
1032@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +00001033
1034@table @key
bellarda1b74fe2004-05-08 13:26:35 +00001035@item Ctrl-a h
bellard1f673132004-04-04 15:21:17 +00001036Print this help
ths3b46e622007-09-17 08:09:54 +00001037@item Ctrl-a x
ths366dfc52006-12-11 18:35:08 +00001038Exit emulator
ths3b46e622007-09-17 08:09:54 +00001039@item Ctrl-a s
bellard1f673132004-04-04 15:21:17 +00001040Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +00001041@item Ctrl-a t
1042toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +00001043@item Ctrl-a b
bellard1f673132004-04-04 15:21:17 +00001044Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +00001045@item Ctrl-a c
bellard1f673132004-04-04 15:21:17 +00001046Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +00001047@item Ctrl-a Ctrl-a
1048Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +00001049@end table
1050@c man end
1051
1052@ignore
1053
bellard1f673132004-04-04 15:21:17 +00001054@c man begin SEEALSO
1055The HTML documentation of QEMU for more precise information and Linux
1056user mode emulator invocation.
1057@c man end
1058
1059@c man begin AUTHOR
1060Fabrice Bellard
1061@c man end
1062
1063@end ignore
1064
bellarddebc7062006-04-30 21:58:41 +00001065@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +00001066@section QEMU Monitor
1067
1068The QEMU monitor is used to give complex commands to the QEMU
1069emulator. You can use it to:
1070
1071@itemize @minus
1072
1073@item
thse5987522007-03-30 18:58:01 +00001074Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +00001075(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +00001076
ths5fafdf22007-09-16 21:08:06 +00001077@item
bellard1f673132004-04-04 15:21:17 +00001078Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
1079from a disk file.
1080
1081@item Inspect the VM state without an external debugger.
1082
1083@end itemize
1084
1085@subsection Commands
1086
1087The following commands are available:
1088
1089@table @option
1090
ths89dfe892007-11-21 22:38:37 +00001091@item help or ? [@var{cmd}]
bellard1f673132004-04-04 15:21:17 +00001092Show the help for all commands or just for command @var{cmd}.
1093
ths3b46e622007-09-17 08:09:54 +00001094@item commit
ths89dfe892007-11-21 22:38:37 +00001095Commit changes to the disk images (if -snapshot is used).
bellard1f673132004-04-04 15:21:17 +00001096
ths89dfe892007-11-21 22:38:37 +00001097@item info @var{subcommand}
1098Show various information about the system state.
bellard1f673132004-04-04 15:21:17 +00001099
1100@table @option
1101@item info network
bellard41d03942005-11-15 23:02:53 +00001102show the various VLANs and the associated devices
bellard1f673132004-04-04 15:21:17 +00001103@item info block
1104show the block devices
1105@item info registers
1106show the cpu registers
1107@item info history
1108show the command line history
bellardb389dbf2005-11-06 16:49:55 +00001109@item info pci
1110show emulated PCI device
1111@item info usb
1112show USB devices plugged on the virtual USB hub
1113@item info usbhost
1114show all USB host devices
bellarda3c25992006-07-18 21:09:59 +00001115@item info capture
1116show information about active capturing
bellard13a2e802006-08-06 14:50:31 +00001117@item info snapshots
1118show list of VM snapshots
ths455204e2007-01-05 16:42:13 +00001119@item info mice
1120show which guest mouse is receiving events
bellard1f673132004-04-04 15:21:17 +00001121@end table
1122
1123@item q or quit
1124Quit the emulator.
1125
ths89dfe892007-11-21 22:38:37 +00001126@item eject [-f] @var{device}
thse5987522007-03-30 18:58:01 +00001127Eject a removable medium (use -f to force it).
bellard1f673132004-04-04 15:21:17 +00001128
ths89dfe892007-11-21 22:38:37 +00001129@item change @var{device} @var{setting}
thsf858dca2007-08-25 01:40:37 +00001130
ths89dfe892007-11-21 22:38:37 +00001131Change the configuration of a device.
thsf858dca2007-08-25 01:40:37 +00001132
1133@table @option
1134@item change @var{diskdevice} @var{filename}
1135Change the medium for a removable disk device to point to @var{filename}. eg
1136
1137@example
aurel324bf27c22008-03-18 06:52:14 +00001138(qemu) change ide1-cd0 /path/to/some.iso
thsf858dca2007-08-25 01:40:37 +00001139@end example
1140
ths89dfe892007-11-21 22:38:37 +00001141@item change vnc @var{display},@var{options}
thsf858dca2007-08-25 01:40:37 +00001142Change the configuration of the VNC server. The valid syntax for @var{display}
1143and @var{options} are described at @ref{sec_invocation}. eg
1144
1145@example
1146(qemu) change vnc localhost:1
1147@end example
1148
1149@item change vnc password
1150
1151Change the password associated with the VNC server. The monitor will prompt for
1152the new password to be entered. VNC passwords are only significant upto 8 letters.
1153eg.
1154
1155@example
1156(qemu) change vnc password
1157Password: ********
1158@end example
1159
1160@end table
bellard1f673132004-04-04 15:21:17 +00001161
ths89dfe892007-11-21 22:38:37 +00001162@item screendump @var{filename}
bellard1f673132004-04-04 15:21:17 +00001163Save screen into PPM image @var{filename}.
1164
ths89dfe892007-11-21 22:38:37 +00001165@item mouse_move @var{dx} @var{dy} [@var{dz}]
ths455204e2007-01-05 16:42:13 +00001166Move the active mouse to the specified coordinates @var{dx} @var{dy}
1167with optional scroll axis @var{dz}.
1168
ths89dfe892007-11-21 22:38:37 +00001169@item mouse_button @var{val}
ths455204e2007-01-05 16:42:13 +00001170Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1171
ths89dfe892007-11-21 22:38:37 +00001172@item mouse_set @var{index}
ths455204e2007-01-05 16:42:13 +00001173Set which mouse device receives events at given @var{index}, index
1174can be obtained with
1175@example
1176info mice
1177@end example
1178
ths89dfe892007-11-21 22:38:37 +00001179@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
bellarda3c25992006-07-18 21:09:59 +00001180Capture audio into @var{filename}. Using sample rate @var{frequency}
1181bits per sample @var{bits} and number of channels @var{channels}.
1182
1183Defaults:
1184@itemize @minus
1185@item Sample rate = 44100 Hz - CD quality
1186@item Bits = 16
1187@item Number of channels = 2 - Stereo
1188@end itemize
1189
ths89dfe892007-11-21 22:38:37 +00001190@item stopcapture @var{index}
bellarda3c25992006-07-18 21:09:59 +00001191Stop capture with a given @var{index}, index can be obtained with
1192@example
1193info capture
1194@end example
1195
ths89dfe892007-11-21 22:38:37 +00001196@item log @var{item1}[,...]
bellard1f673132004-04-04 15:21:17 +00001197Activate logging of the specified items to @file{/tmp/qemu.log}.
1198
ths89dfe892007-11-21 22:38:37 +00001199@item savevm [@var{tag}|@var{id}]
bellard13a2e802006-08-06 14:50:31 +00001200Create a snapshot of the whole virtual machine. If @var{tag} is
1201provided, it is used as human readable identifier. If there is already
1202a snapshot with the same tag or ID, it is replaced. More info at
1203@ref{vm_snapshots}.
bellard1f673132004-04-04 15:21:17 +00001204
ths89dfe892007-11-21 22:38:37 +00001205@item loadvm @var{tag}|@var{id}
bellard13a2e802006-08-06 14:50:31 +00001206Set the whole virtual machine to the snapshot identified by the tag
1207@var{tag} or the unique snapshot ID @var{id}.
1208
ths89dfe892007-11-21 22:38:37 +00001209@item delvm @var{tag}|@var{id}
bellard13a2e802006-08-06 14:50:31 +00001210Delete the snapshot identified by @var{tag} or @var{id}.
bellard1f673132004-04-04 15:21:17 +00001211
1212@item stop
1213Stop emulation.
1214
1215@item c or cont
1216Resume emulation.
1217
ths89dfe892007-11-21 22:38:37 +00001218@item gdbserver [@var{port}]
1219Start gdbserver session (default @var{port}=1234)
bellard1f673132004-04-04 15:21:17 +00001220
ths89dfe892007-11-21 22:38:37 +00001221@item x/fmt @var{addr}
bellard1f673132004-04-04 15:21:17 +00001222Virtual memory dump starting at @var{addr}.
1223
ths89dfe892007-11-21 22:38:37 +00001224@item xp /@var{fmt} @var{addr}
bellard1f673132004-04-04 15:21:17 +00001225Physical memory dump starting at @var{addr}.
1226
1227@var{fmt} is a format which tells the command how to format the
1228data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1229
1230@table @var
ths5fafdf22007-09-16 21:08:06 +00001231@item count
bellard1f673132004-04-04 15:21:17 +00001232is the number of items to be dumped.
1233
1234@item format
ths4be456f2007-06-03 13:41:28 +00001235can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
bellard1f673132004-04-04 15:21:17 +00001236c (char) or i (asm instruction).
1237
1238@item size
bellard52c00a52004-04-25 21:27:03 +00001239can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1240@code{h} or @code{w} can be specified with the @code{i} format to
1241respectively select 16 or 32 bit code instruction size.
bellard1f673132004-04-04 15:21:17 +00001242
1243@end table
1244
ths5fafdf22007-09-16 21:08:06 +00001245Examples:
bellard1f673132004-04-04 15:21:17 +00001246@itemize
1247@item
1248Dump 10 instructions at the current instruction pointer:
ths5fafdf22007-09-16 21:08:06 +00001249@example
bellard1f673132004-04-04 15:21:17 +00001250(qemu) x/10i $eip
12510x90107063: ret
12520x90107064: sti
12530x90107065: lea 0x0(%esi,1),%esi
12540x90107069: lea 0x0(%edi,1),%edi
12550x90107070: ret
12560x90107071: jmp 0x90107080
12570x90107073: nop
12580x90107074: nop
12590x90107075: nop
12600x90107076: nop
1261@end example
1262
1263@item
1264Dump 80 16 bit values at the start of the video memory.
ths5fafdf22007-09-16 21:08:06 +00001265@smallexample
bellard1f673132004-04-04 15:21:17 +00001266(qemu) xp/80hx 0xb8000
12670x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
12680x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
12690x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
12700x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
12710x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
12720x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
12730x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
12740x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
12750x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
12760x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
bellarddebc7062006-04-30 21:58:41 +00001277@end smallexample
bellard1f673132004-04-04 15:21:17 +00001278@end itemize
1279
ths89dfe892007-11-21 22:38:37 +00001280@item p or print/@var{fmt} @var{expr}
bellard1f673132004-04-04 15:21:17 +00001281
1282Print expression value. Only the @var{format} part of @var{fmt} is
1283used.
1284
ths89dfe892007-11-21 22:38:37 +00001285@item sendkey @var{keys}
bellarda3a91a32004-06-04 11:06:21 +00001286
1287Send @var{keys} to the emulator. Use @code{-} to press several keys
1288simultaneously. Example:
1289@example
1290sendkey ctrl-alt-f1
1291@end example
1292
1293This command is useful to send keys that your graphical user interface
1294intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1295
bellard15a34c62004-07-08 21:26:26 +00001296@item system_reset
1297
1298Reset the system.
1299
aurel320ecdffb2008-05-04 20:11:34 +00001300@item boot_set @var{bootdevicelist}
1301
1302Define new values for the boot device list. Those values will override
1303the values specified on the command line through the @code{-boot} option.
1304
1305The values that can be specified here depend on the machine type, but are
1306the same that can be specified in the @code{-boot} command line option.
1307
ths89dfe892007-11-21 22:38:37 +00001308@item usb_add @var{devname}
bellardb389dbf2005-11-06 16:49:55 +00001309
pbrook0aff66b2006-05-26 00:49:52 +00001310Add the USB device @var{devname}. For details of available devices see
1311@ref{usb_devices}
bellardb389dbf2005-11-06 16:49:55 +00001312
ths89dfe892007-11-21 22:38:37 +00001313@item usb_del @var{devname}
bellardb389dbf2005-11-06 16:49:55 +00001314
1315Remove the USB device @var{devname} from the QEMU virtual USB
1316hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1317command @code{info usb} to see the devices you can remove.
1318
bellard1f673132004-04-04 15:21:17 +00001319@end table
1320
1321@subsection Integer expressions
1322
1323The monitor understands integers expressions for every integer
1324argument. You can use register names to get the value of specifics
1325CPU registers by prefixing them with @emph{$}.
1326
1327@node disk_images
1328@section Disk Images
1329
bellardacd935e2004-11-15 22:57:26 +00001330Since version 0.6.1, QEMU supports many disk image formats, including
1331growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +00001332written), compressed and encrypted disk images. Version 0.8.3 added
1333the new qcow2 disk image format which is essential to support VM
1334snapshots.
bellard1f673132004-04-04 15:21:17 +00001335
bellarddebc7062006-04-30 21:58:41 +00001336@menu
1337* disk_images_quickstart:: Quick start for disk image creation
1338* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +00001339* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +00001340* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +00001341* qemu_nbd_invocation:: qemu-nbd Invocation
bellard19cb3732006-08-19 11:45:59 +00001342* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +00001343* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +00001344* disk_images_nbd:: NBD access
bellarddebc7062006-04-30 21:58:41 +00001345@end menu
1346
1347@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +00001348@subsection Quick start for disk image creation
1349
1350You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +00001351@example
bellardacd935e2004-11-15 22:57:26 +00001352qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +00001353@end example
bellardacd935e2004-11-15 22:57:26 +00001354where @var{myimage.img} is the disk image filename and @var{mysize} is its
1355size in kilobytes. You can add an @code{M} suffix to give the size in
1356megabytes and a @code{G} suffix for gigabytes.
1357
bellarddebc7062006-04-30 21:58:41 +00001358See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +00001359
bellarddebc7062006-04-30 21:58:41 +00001360@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +00001361@subsection Snapshot mode
1362
1363If you use the option @option{-snapshot}, all disk images are
1364considered as read only. When sectors in written, they are written in
1365a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +00001366write back to the raw disk images by using the @code{commit} monitor
1367command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +00001368
bellard13a2e802006-08-06 14:50:31 +00001369@node vm_snapshots
1370@subsection VM snapshots
1371
1372VM snapshots are snapshots of the complete virtual machine including
1373CPU state, RAM, device state and the content of all the writable
1374disks. In order to use VM snapshots, you must have at least one non
1375removable and writable block device using the @code{qcow2} disk image
1376format. Normally this device is the first virtual hard drive.
1377
1378Use the monitor command @code{savevm} to create a new VM snapshot or
1379replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +00001380snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +00001381
1382Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1383a VM snapshot. @code{info snapshots} lists the available snapshots
1384with their associated information:
1385
1386@example
1387(qemu) info snapshots
1388Snapshot devices: hda
1389Snapshot list (from hda):
1390ID TAG VM SIZE DATE VM CLOCK
13911 start 41M 2006-08-06 12:38:02 00:00:14.954
13922 40M 2006-08-06 12:43:29 00:00:18.633
13933 msys 40M 2006-08-06 12:44:04 00:00:23.514
1394@end example
1395
1396A VM snapshot is made of a VM state info (its size is shown in
1397@code{info snapshots}) and a snapshot of every writable disk image.
1398The VM state info is stored in the first @code{qcow2} non removable
1399and writable block device. The disk image snapshots are stored in
1400every disk image. The size of a snapshot in a disk image is difficult
1401to evaluate and is not shown by @code{info snapshots} because the
1402associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +00001403disk space (otherwise each snapshot would need a full copy of all the
1404disk images).
bellard13a2e802006-08-06 14:50:31 +00001405
1406When using the (unrelated) @code{-snapshot} option
1407(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1408but they are deleted as soon as you exit QEMU.
1409
1410VM snapshots currently have the following known limitations:
1411@itemize
ths5fafdf22007-09-16 21:08:06 +00001412@item
bellard13a2e802006-08-06 14:50:31 +00001413They cannot cope with removable devices if they are removed or
1414inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +00001415@item
bellard13a2e802006-08-06 14:50:31 +00001416A few device drivers still have incomplete snapshot support so their
1417state is not saved or restored properly (in particular USB).
1418@end itemize
1419
bellardacd935e2004-11-15 22:57:26 +00001420@node qemu_img_invocation
1421@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +00001422
bellardacd935e2004-11-15 22:57:26 +00001423@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +00001424
ths975b0922008-07-02 21:18:00 +00001425@node qemu_nbd_invocation
1426@subsection @code{qemu-nbd} Invocation
1427
1428@include qemu-nbd.texi
1429
bellard19cb3732006-08-19 11:45:59 +00001430@node host_drives
1431@subsection Using host drives
1432
1433In addition to disk image files, QEMU can directly access host
1434devices. We describe here the usage for QEMU version >= 0.8.3.
1435
1436@subsubsection Linux
1437
1438On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +00001439disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +00001440it. For example, use @file{/dev/cdrom} to access to the CDROM or
1441@file{/dev/fd0} for the floppy.
1442
bellardf5420862006-08-21 20:26:44 +00001443@table @code
bellard19cb3732006-08-19 11:45:59 +00001444@item CD
1445You can specify a CDROM device even if no CDROM is loaded. QEMU has
1446specific code to detect CDROM insertion or removal. CDROM ejection by
1447the guest OS is supported. Currently only data CDs are supported.
1448@item Floppy
1449You can specify a floppy device even if no floppy is loaded. Floppy
1450removal is currently not detected accurately (if you change floppy
1451without doing floppy access while the floppy is not loaded, the guest
1452OS will think that the same floppy is loaded).
1453@item Hard disks
1454Hard disks can be used. Normally you must specify the whole disk
1455(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1456see it as a partitioned disk. WARNING: unless you know what you do, it
1457is better to only make READ-ONLY accesses to the hard disk otherwise
1458you may corrupt your host data (use the @option{-snapshot} command
1459line option or modify the device permissions accordingly).
1460@end table
1461
1462@subsubsection Windows
1463
bellard01781962007-01-07 22:43:30 +00001464@table @code
1465@item CD
ths4be456f2007-06-03 13:41:28 +00001466The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +00001467alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1468supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +00001469
thse5987522007-03-30 18:58:01 +00001470Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +00001471is better to use the @code{change} or @code{eject} monitor commands to
1472change or eject media.
bellard01781962007-01-07 22:43:30 +00001473@item Hard disks
ths89dfe892007-11-21 22:38:37 +00001474Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +00001475where @var{N} is the drive number (0 is the first hard disk).
1476
1477WARNING: unless you know what you do, it is better to only make
1478READ-ONLY accesses to the hard disk otherwise you may corrupt your
1479host data (use the @option{-snapshot} command line so that the
1480modifications are written in a temporary file).
1481@end table
1482
bellard19cb3732006-08-19 11:45:59 +00001483
1484@subsubsection Mac OS X
1485
ths5fafdf22007-09-16 21:08:06 +00001486@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +00001487
thse5987522007-03-30 18:58:01 +00001488Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +00001489is better to use the @code{change} or @code{eject} monitor commands to
1490change or eject media.
1491
bellarddebc7062006-04-30 21:58:41 +00001492@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +00001493@subsection Virtual FAT disk images
1494
1495QEMU can automatically create a virtual FAT disk image from a
1496directory tree. In order to use it, just type:
1497
ths5fafdf22007-09-16 21:08:06 +00001498@example
bellard2c6cadd2005-12-18 18:31:45 +00001499qemu linux.img -hdb fat:/my_directory
1500@end example
1501
1502Then you access access to all the files in the @file{/my_directory}
1503directory without having to copy them in a disk image or to export
1504them via SAMBA or NFS. The default access is @emph{read-only}.
1505
1506Floppies can be emulated with the @code{:floppy:} option:
1507
ths5fafdf22007-09-16 21:08:06 +00001508@example
bellard2c6cadd2005-12-18 18:31:45 +00001509qemu linux.img -fda fat:floppy:/my_directory
1510@end example
1511
1512A read/write support is available for testing (beta stage) with the
1513@code{:rw:} option:
1514
ths5fafdf22007-09-16 21:08:06 +00001515@example
bellard2c6cadd2005-12-18 18:31:45 +00001516qemu linux.img -fda fat:floppy:rw:/my_directory
1517@end example
1518
1519What you should @emph{never} do:
1520@itemize
1521@item use non-ASCII filenames ;
1522@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +00001523@item expect it to work when loadvm'ing ;
1524@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +00001525@end itemize
1526
ths75818252008-07-03 13:41:03 +00001527@node disk_images_nbd
1528@subsection NBD access
1529
1530QEMU can access directly to block device exported using the Network Block Device
1531protocol.
1532
1533@example
1534qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
1535@end example
1536
1537If the NBD server is located on the same host, you can use an unix socket instead
1538of an inet socket:
1539
1540@example
1541qemu linux.img -hdb nbd:unix:/tmp/my_socket
1542@end example
1543
1544In this case, the block device must be exported using qemu-nbd:
1545
1546@example
1547qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
1548@end example
1549
1550The use of qemu-nbd allows to share a disk between several guests:
1551@example
1552qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
1553@end example
1554
1555and then you can use it with two guests:
1556@example
1557qemu linux1.img -hdb nbd:unix:/tmp/my_socket
1558qemu linux2.img -hdb nbd:unix:/tmp/my_socket
1559@end example
1560
bellarddebc7062006-04-30 21:58:41 +00001561@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001562@section Network emulation
1563
ths4be456f2007-06-03 13:41:28 +00001564QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001565target) and can connect them to an arbitrary number of Virtual Local
1566Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1567VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001568simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001569network stack can replace the TAP device to have a basic network
1570connection.
bellard9d4fb822004-04-26 20:55:38 +00001571
bellard41d03942005-11-15 23:02:53 +00001572@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001573
bellard41d03942005-11-15 23:02:53 +00001574QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1575connection between several network devices. These devices can be for
1576example QEMU virtual Ethernet cards or virtual Host ethernet devices
1577(TAP devices).
1578
1579@subsection Using TAP network interfaces
1580
1581This is the standard way to connect QEMU to a real network. QEMU adds
1582a virtual network device on your host (called @code{tapN}), and you
1583can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001584
bellard8f40c382006-09-20 20:28:05 +00001585@subsubsection Linux host
1586
bellard9d4fb822004-04-26 20:55:38 +00001587As an example, you can download the @file{linux-test-xxx.tar.gz}
1588archive and copy the script @file{qemu-ifup} in @file{/etc} and
1589configure properly @code{sudo} so that the command @code{ifconfig}
1590contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001591that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001592device @file{/dev/net/tun} must be present.
1593
bellardee0f4752006-08-19 16:56:18 +00001594See @ref{sec_invocation} to have examples of command lines using the
1595TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001596
bellard8f40c382006-09-20 20:28:05 +00001597@subsubsection Windows host
1598
1599There is a virtual ethernet driver for Windows 2000/XP systems, called
1600TAP-Win32. But it is not included in standard QEMU for Windows,
1601so you will need to get it separately. It is part of OpenVPN package,
1602so download OpenVPN from : @url{http://openvpn.net/}.
1603
bellard9d4fb822004-04-26 20:55:38 +00001604@subsection Using the user mode network stack
1605
bellard41d03942005-11-15 23:02:53 +00001606By using the option @option{-net user} (default configuration if no
1607@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001608network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001609network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001610
1611@example
1612
bellard41d03942005-11-15 23:02:53 +00001613 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1614 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001615 |
bellard2518bd02004-09-30 22:35:13 +00001616 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001617 |
bellard2518bd02004-09-30 22:35:13 +00001618 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001619@end example
1620
1621The QEMU VM behaves as if it was behind a firewall which blocks all
1622incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001623configure the network in the QEMU VM. The DHCP server assign addresses
1624to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001625
1626In order to check that the user mode network is working, you can ping
1627the address 10.0.2.2 and verify that you got an address in the range
162810.0.2.x from the QEMU virtual DHCP server.
1629
bellardb415a402004-05-23 21:04:06 +00001630Note that @code{ping} is not supported reliably to the internet as it
ths4be456f2007-06-03 13:41:28 +00001631would require root privileges. It means you can only ping the local
bellardb415a402004-05-23 21:04:06 +00001632router (10.0.2.2).
1633
bellard9bf05442004-08-25 22:12:49 +00001634When using the built-in TFTP server, the router is also the TFTP
1635server.
1636
1637When using the @option{-redir} option, TCP or UDP connections can be
1638redirected from the host to the guest. It allows for example to
1639redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001640
bellard41d03942005-11-15 23:02:53 +00001641@subsection Connecting VLANs between QEMU instances
1642
1643Using the @option{-net socket} option, it is possible to make VLANs
1644that span several QEMU instances. See @ref{sec_invocation} to have a
1645basic example.
1646
bellard9d4fb822004-04-26 20:55:38 +00001647@node direct_linux_boot
1648@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001649
1650This section explains how to launch a Linux kernel inside QEMU without
1651having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001652kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001653
bellardee0f4752006-08-19 16:56:18 +00001654The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001655@example
bellardee0f4752006-08-19 16:56:18 +00001656qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001657@end example
1658
bellardee0f4752006-08-19 16:56:18 +00001659Use @option{-kernel} to provide the Linux kernel image and
1660@option{-append} to give the kernel command line arguments. The
1661@option{-initrd} option can be used to provide an INITRD image.
1662
1663When using the direct Linux boot, a disk image for the first hard disk
1664@file{hda} is required because its boot sector is used to launch the
1665Linux kernel.
1666
1667If you do not need graphical output, you can disable it and redirect
1668the virtual serial port and the QEMU monitor to the console with the
1669@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001670@example
bellardee0f4752006-08-19 16:56:18 +00001671qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1672 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001673@end example
1674
bellardee0f4752006-08-19 16:56:18 +00001675Use @key{Ctrl-a c} to switch between the serial console and the
1676monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001677
bellarddebc7062006-04-30 21:58:41 +00001678@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001679@section USB emulation
1680
pbrook0aff66b2006-05-26 00:49:52 +00001681QEMU emulates a PCI UHCI USB controller. You can virtually plug
1682virtual USB devices or real host USB devices (experimental, works only
1683on Linux hosts). Qemu will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001684as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001685
pbrook0aff66b2006-05-26 00:49:52 +00001686@menu
1687* usb_devices::
1688* host_usb_devices::
1689@end menu
1690@node usb_devices
1691@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001692
pbrook0aff66b2006-05-26 00:49:52 +00001693USB devices can be connected with the @option{-usbdevice} commandline option
1694or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001695
balrogdb380c02008-01-17 22:22:45 +00001696@table @code
1697@item mouse
pbrook0aff66b2006-05-26 00:49:52 +00001698Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001699@item tablet
bellardc6d46c22006-09-03 17:10:41 +00001700Pointer device that uses absolute coordinates (like a touchscreen).
pbrook0aff66b2006-05-26 00:49:52 +00001701This means qemu is able to report the mouse position without having
1702to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001703@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +00001704Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +00001705@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +00001706Pass through the host device identified by @var{bus.addr}
1707(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001708@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +00001709Pass through the host device identified by @var{vendor_id:product_id}
1710(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001711@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +00001712Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1713above but it can be used with the tslib library because in addition to touch
1714coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +00001715@item keyboard
balrog47b2d332007-06-22 08:16:00 +00001716Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +00001717@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1718Serial converter. This emulates an FTDI FT232BM chip connected to host character
1719device @var{dev}. The available character devices are the same as for the
1720@code{-serial} option. The @code{vendorid} and @code{productid} options can be
balroga11d0702008-01-19 13:00:43 +00001721used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +00001722@example
1723usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1724@end example
1725will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1726serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +00001727@item braille
1728Braille device. This will use BrlAPI to display the braille output on a real
1729or fake device.
balrog9ad97e62008-07-29 13:16:31 +00001730@item net:@var{options}
1731Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1732specifies NIC options as with @code{-net nic,}@var{options} (see description).
1733For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +00001734@example
balrog9ad97e62008-07-29 13:16:31 +00001735qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +00001736@end example
1737Currently this cannot be used in machines that support PCI NICs.
pbrook0aff66b2006-05-26 00:49:52 +00001738@end table
bellardb389dbf2005-11-06 16:49:55 +00001739
pbrook0aff66b2006-05-26 00:49:52 +00001740@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001741@subsection Using host USB devices on a Linux host
1742
1743WARNING: this is an experimental feature. QEMU will slow down when
1744using it. USB devices requiring real time streaming (i.e. USB Video
1745Cameras) are not supported yet.
1746
1747@enumerate
ths5fafdf22007-09-16 21:08:06 +00001748@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001749is actually using the USB device. A simple way to do that is simply to
1750disable the corresponding kernel module by renaming it from @file{mydriver.o}
1751to @file{mydriver.o.disabled}.
1752
1753@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1754@example
1755ls /proc/bus/usb
1756001 devices drivers
1757@end example
1758
1759@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1760@example
1761chown -R myuid /proc/bus/usb
1762@end example
1763
1764@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001765@example
bellardb389dbf2005-11-06 16:49:55 +00001766info usbhost
1767 Device 1.2, speed 480 Mb/s
1768 Class 00: USB device 1234:5678, USB DISK
1769@end example
1770You should see the list of the devices you can use (Never try to use
1771hubs, it won't work).
1772
1773@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001774@example
bellardb389dbf2005-11-06 16:49:55 +00001775usb_add host:1234:5678
1776@end example
1777
1778Normally the guest OS should report that a new USB device is
1779plugged. You can use the option @option{-usbdevice} to do the same.
1780
1781@item Now you can try to use the host USB device in QEMU.
1782
1783@end enumerate
1784
1785When relaunching QEMU, you may have to unplug and plug again the USB
1786device to make it work again (this is a bug).
1787
thsf858dca2007-08-25 01:40:37 +00001788@node vnc_security
1789@section VNC security
1790
1791The VNC server capability provides access to the graphical console
1792of the guest VM across the network. This has a number of security
1793considerations depending on the deployment scenarios.
1794
1795@menu
1796* vnc_sec_none::
1797* vnc_sec_password::
1798* vnc_sec_certificate::
1799* vnc_sec_certificate_verify::
1800* vnc_sec_certificate_pw::
1801* vnc_generate_cert::
1802@end menu
1803@node vnc_sec_none
1804@subsection Without passwords
1805
1806The simplest VNC server setup does not include any form of authentication.
1807For this setup it is recommended to restrict it to listen on a UNIX domain
1808socket only. For example
1809
1810@example
1811qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1812@end example
1813
1814This ensures that only users on local box with read/write access to that
1815path can access the VNC server. To securely access the VNC server from a
1816remote machine, a combination of netcat+ssh can be used to provide a secure
1817tunnel.
1818
1819@node vnc_sec_password
1820@subsection With passwords
1821
1822The VNC protocol has limited support for password based authentication. Since
1823the protocol limits passwords to 8 characters it should not be considered
1824to provide high security. The password can be fairly easily brute-forced by
1825a client making repeat connections. For this reason, a VNC server using password
1826authentication should be restricted to only listen on the loopback interface
1827or UNIX domain sockets. Password ayuthentication is requested with the @code{password}
1828option, and then once QEMU is running the password is set with the monitor. Until
1829the monitor is used to set the password all clients will be rejected.
1830
1831@example
1832qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1833(qemu) change vnc password
1834Password: ********
1835(qemu)
1836@end example
1837
1838@node vnc_sec_certificate
1839@subsection With x509 certificates
1840
1841The QEMU VNC server also implements the VeNCrypt extension allowing use of
1842TLS for encryption of the session, and x509 certificates for authentication.
1843The use of x509 certificates is strongly recommended, because TLS on its
1844own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1845support provides a secure session, but no authentication. This allows any
1846client to connect, and provides an encrypted session.
1847
1848@example
1849qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1850@end example
1851
1852In the above example @code{/etc/pki/qemu} should contain at least three files,
1853@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1854users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1855NB the @code{server-key.pem} file should be protected with file mode 0600 to
1856only be readable by the user owning it.
1857
1858@node vnc_sec_certificate_verify
1859@subsection With x509 certificates and client verification
1860
1861Certificates can also provide a means to authenticate the client connecting.
1862The server will request that the client provide a certificate, which it will
1863then validate against the CA certificate. This is a good choice if deploying
1864in an environment with a private internal certificate authority.
1865
1866@example
1867qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1868@end example
1869
1870
1871@node vnc_sec_certificate_pw
1872@subsection With x509 certificates, client verification and passwords
1873
1874Finally, the previous method can be combined with VNC password authentication
1875to provide two layers of authentication for clients.
1876
1877@example
1878qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1879(qemu) change vnc password
1880Password: ********
1881(qemu)
1882@end example
1883
1884@node vnc_generate_cert
1885@subsection Generating certificates for VNC
1886
1887The GNU TLS packages provides a command called @code{certtool} which can
1888be used to generate certificates and keys in PEM format. At a minimum it
1889is neccessary to setup a certificate authority, and issue certificates to
1890each server. If using certificates for authentication, then each client
1891will also need to be issued a certificate. The recommendation is for the
1892server to keep its certificates in either @code{/etc/pki/qemu} or for
1893unprivileged users in @code{$HOME/.pki/qemu}.
1894
1895@menu
1896* vnc_generate_ca::
1897* vnc_generate_server::
1898* vnc_generate_client::
1899@end menu
1900@node vnc_generate_ca
1901@subsubsection Setup the Certificate Authority
1902
1903This step only needs to be performed once per organization / organizational
1904unit. First the CA needs a private key. This key must be kept VERY secret
1905and secure. If this key is compromised the entire trust chain of the certificates
1906issued with it is lost.
1907
1908@example
1909# certtool --generate-privkey > ca-key.pem
1910@end example
1911
1912A CA needs to have a public certificate. For simplicity it can be a self-signed
1913certificate, or one issue by a commercial certificate issuing authority. To
1914generate a self-signed certificate requires one core piece of information, the
1915name of the organization.
1916
1917@example
1918# cat > ca.info <<EOF
1919cn = Name of your organization
1920ca
1921cert_signing_key
1922EOF
1923# certtool --generate-self-signed \
1924 --load-privkey ca-key.pem
1925 --template ca.info \
1926 --outfile ca-cert.pem
1927@end example
1928
1929The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1930TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1931
1932@node vnc_generate_server
1933@subsubsection Issuing server certificates
1934
1935Each server (or host) needs to be issued with a key and certificate. When connecting
1936the certificate is sent to the client which validates it against the CA certificate.
1937The core piece of information for a server certificate is the hostname. This should
1938be the fully qualified hostname that the client will connect with, since the client
1939will typically also verify the hostname in the certificate. On the host holding the
1940secure CA private key:
1941
1942@example
1943# cat > server.info <<EOF
1944organization = Name of your organization
1945cn = server.foo.example.com
1946tls_www_server
1947encryption_key
1948signing_key
1949EOF
1950# certtool --generate-privkey > server-key.pem
1951# certtool --generate-certificate \
1952 --load-ca-certificate ca-cert.pem \
1953 --load-ca-privkey ca-key.pem \
1954 --load-privkey server server-key.pem \
1955 --template server.info \
1956 --outfile server-cert.pem
1957@end example
1958
1959The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1960to the server for which they were generated. The @code{server-key.pem} is security
1961sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1962
1963@node vnc_generate_client
1964@subsubsection Issuing client certificates
1965
1966If the QEMU VNC server is to use the @code{x509verify} option to validate client
1967certificates as its authentication mechanism, each client also needs to be issued
1968a certificate. The client certificate contains enough metadata to uniquely identify
1969the client, typically organization, state, city, building, etc. On the host holding
1970the secure CA private key:
1971
1972@example
1973# cat > client.info <<EOF
1974country = GB
1975state = London
1976locality = London
1977organiazation = Name of your organization
1978cn = client.foo.example.com
1979tls_www_client
1980encryption_key
1981signing_key
1982EOF
1983# certtool --generate-privkey > client-key.pem
1984# certtool --generate-certificate \
1985 --load-ca-certificate ca-cert.pem \
1986 --load-ca-privkey ca-key.pem \
1987 --load-privkey client-key.pem \
1988 --template client.info \
1989 --outfile client-cert.pem
1990@end example
1991
1992The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1993copied to the client for which they were generated.
1994
bellard0806e3f2003-10-01 00:15:32 +00001995@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001996@section GDB usage
1997
1998QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001999'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00002000
bellard9d4520d2003-10-28 01:38:57 +00002001In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00002002gdb connection:
2003@example
bellarddebc7062006-04-30 21:58:41 +00002004> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
2005 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00002006Connected to host network interface: tun0
2007Waiting gdb connection on port 1234
2008@end example
2009
2010Then launch gdb on the 'vmlinux' executable:
2011@example
2012> gdb vmlinux
2013@end example
2014
2015In gdb, connect to QEMU:
2016@example
bellard6c9bf892004-01-24 13:46:56 +00002017(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00002018@end example
2019
2020Then you can use gdb normally. For example, type 'c' to launch the kernel:
2021@example
2022(gdb) c
2023@end example
2024
bellard0806e3f2003-10-01 00:15:32 +00002025Here are some useful tips in order to use gdb on system code:
2026
2027@enumerate
2028@item
2029Use @code{info reg} to display all the CPU registers.
2030@item
2031Use @code{x/10i $eip} to display the code at the PC position.
2032@item
2033Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00002034@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00002035@end enumerate
2036
edgar_igl60897d32008-05-09 08:25:14 +00002037Advanced debugging options:
2038
2039The default single stepping behavior is step with the IRQs and timer service routines off. It is set this way because when gdb executes a single step it expects to advance beyond the current instruction. With the IRQs and and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed. Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB. There are three commands you can query and set the single step behavior:
edgar_igl94d45e42008-05-10 19:37:44 +00002040@table @code
edgar_igl60897d32008-05-09 08:25:14 +00002041@item maintenance packet qqemu.sstepbits
2042
2043This will display the MASK bits used to control the single stepping IE:
2044@example
2045(gdb) maintenance packet qqemu.sstepbits
2046sending: "qqemu.sstepbits"
2047received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
2048@end example
2049@item maintenance packet qqemu.sstep
2050
2051This will display the current value of the mask used when single stepping IE:
2052@example
2053(gdb) maintenance packet qqemu.sstep
2054sending: "qqemu.sstep"
2055received: "0x7"
2056@end example
2057@item maintenance packet Qqemu.sstep=HEX_VALUE
2058
2059This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
2060@example
2061(gdb) maintenance packet Qqemu.sstep=0x5
2062sending: "qemu.sstep=0x5"
2063received: "OK"
2064@end example
edgar_igl94d45e42008-05-10 19:37:44 +00002065@end table
edgar_igl60897d32008-05-09 08:25:14 +00002066
bellarddebc7062006-04-30 21:58:41 +00002067@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00002068@section Target OS specific information
2069
2070@subsection Linux
2071
bellard15a34c62004-07-08 21:26:26 +00002072To have access to SVGA graphic modes under X11, use the @code{vesa} or
2073the @code{cirrus} X11 driver. For optimal performances, use 16 bit
2074color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00002075
bellarde3371e62004-07-10 16:26:02 +00002076When using a 2.6 guest Linux kernel, you should add the option
2077@code{clock=pit} on the kernel command line because the 2.6 Linux
2078kernels make very strict real time clock checks by default that QEMU
2079cannot simulate exactly.
2080
bellard7c3fc842005-02-10 21:46:47 +00002081When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
2082not activated because QEMU is slower with this patch. The QEMU
2083Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00002084Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00002085patch by default. Newer kernels don't have it.
2086
bellard1a084f32004-05-13 22:34:49 +00002087@subsection Windows
2088
2089If you have a slow host, using Windows 95 is better as it gives the
2090best speed. Windows 2000 is also a good choice.
2091
bellarde3371e62004-07-10 16:26:02 +00002092@subsubsection SVGA graphic modes support
2093
2094QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00002095card. All Windows versions starting from Windows 95 should recognize
2096and use this graphic card. For optimal performances, use 16 bit color
2097depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00002098
bellard3cb08532006-06-21 21:19:50 +00002099If you are using Windows XP as guest OS and if you want to use high
2100resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
21011280x1024x16), then you should use the VESA VBE virtual graphic card
2102(option @option{-std-vga}).
2103
bellarde3371e62004-07-10 16:26:02 +00002104@subsubsection CPU usage reduction
2105
2106Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00002107instruction. The result is that it takes host CPU cycles even when
2108idle. You can install the utility from
2109@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
2110problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00002111
bellard9d0a8e62005-07-03 17:34:05 +00002112@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00002113
bellard9d0a8e62005-07-03 17:34:05 +00002114Windows 2000 has a bug which gives a disk full problem during its
2115installation. When installing it, use the @option{-win2k-hack} QEMU
2116option to enable a specific workaround. After Windows 2000 is
2117installed, you no longer need this option (this option slows down the
2118IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00002119
bellard6cc721c2005-07-28 22:27:28 +00002120@subsubsection Windows 2000 shutdown
2121
2122Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2123can. It comes from the fact that Windows 2000 does not automatically
2124use the APM driver provided by the BIOS.
2125
2126In order to correct that, do the following (thanks to Struan
2127Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
2128Add/Troubleshoot a device => Add a new device & Next => No, select the
2129hardware from a list & Next => NT Apm/Legacy Support & Next => Next
2130(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00002131correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00002132
2133@subsubsection Share a directory between Unix and Windows
2134
2135See @ref{sec_invocation} about the help of the option @option{-smb}.
2136
bellard2192c332006-08-21 20:28:18 +00002137@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00002138
2139Some releases of Windows XP install correctly but give a security
2140error when booting:
2141@example
2142A problem is preventing Windows from accurately checking the
2143license for this computer. Error code: 0x800703e6.
2144@end example
bellarde3371e62004-07-10 16:26:02 +00002145
bellard2192c332006-08-21 20:28:18 +00002146The workaround is to install a service pack for XP after a boot in safe
2147mode. Then reboot, and the problem should go away. Since there is no
2148network while in safe mode, its recommended to download the full
2149installation of SP1 or SP2 and transfer that via an ISO or using the
2150vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00002151
bellarda0a821a2004-07-14 17:38:57 +00002152@subsection MS-DOS and FreeDOS
2153
2154@subsubsection CPU usage reduction
2155
2156DOS does not correctly use the CPU HLT instruction. The result is that
2157it takes host CPU cycles even when idle. You can install the utility
2158from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
2159problem.
2160
bellarddebc7062006-04-30 21:58:41 +00002161@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00002162@chapter QEMU System emulator for non PC targets
2163
2164QEMU is a generic emulator and it emulates many non PC
2165machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00002166differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00002167
bellarddebc7062006-04-30 21:58:41 +00002168@menu
2169* QEMU PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00002170* Sparc32 System emulator::
2171* Sparc64 System emulator::
2172* MIPS System emulator::
2173* ARM System emulator::
2174* ColdFire System emulator::
bellarddebc7062006-04-30 21:58:41 +00002175@end menu
2176
2177@node QEMU PowerPC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +00002178@section QEMU PowerPC System emulator
bellard52c00a52004-04-25 21:27:03 +00002179
2180Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00002181or PowerMac PowerPC system.
2182
bellardb671f9e2005-04-30 15:08:33 +00002183QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00002184
2185@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002186@item
2187UniNorth PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00002188@item
2189PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00002190@item
bellard15a34c62004-07-08 21:26:26 +000021912 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00002192@item
bellard15a34c62004-07-08 21:26:26 +00002193NE2000 PCI adapters
2194@item
2195Non Volatile RAM
2196@item
2197VIA-CUDA with ADB keyboard and mouse.
2198@end itemize
bellard52c00a52004-04-25 21:27:03 +00002199
bellardb671f9e2005-04-30 15:08:33 +00002200QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00002201
2202@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002203@item
bellard15a34c62004-07-08 21:26:26 +00002204PCI Bridge
2205@item
2206PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00002207@item
bellard52c00a52004-04-25 21:27:03 +000022082 IDE interfaces with hard disk and CD-ROM support
2209@item
2210Floppy disk
ths5fafdf22007-09-16 21:08:06 +00002211@item
bellard15a34c62004-07-08 21:26:26 +00002212NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00002213@item
2214Serial port
2215@item
2216PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00002217@item
2218PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00002219@end itemize
2220
bellard15a34c62004-07-08 21:26:26 +00002221QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00002222@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00002223
bellard15a34c62004-07-08 21:26:26 +00002224@c man begin OPTIONS
2225
2226The following options are specific to the PowerPC emulation:
2227
2228@table @option
2229
ths3b46e622007-09-17 08:09:54 +00002230@item -g WxH[xDEPTH]
bellard15a34c62004-07-08 21:26:26 +00002231
2232Set the initial VGA graphic mode. The default is 800x600x15.
2233
2234@end table
2235
ths5fafdf22007-09-16 21:08:06 +00002236@c man end
bellard15a34c62004-07-08 21:26:26 +00002237
2238
bellard52c00a52004-04-25 21:27:03 +00002239More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00002240@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00002241
ths24d4de42007-07-11 10:24:28 +00002242@node Sparc32 System emulator
2243@section Sparc32 System emulator
bellarde80cfcf2004-12-19 23:18:01 +00002244
blueswir16a3b9cc2007-11-11 17:56:38 +00002245Use the executable @file{qemu-system-sparc} to simulate a SPARCstation
blueswir1ee76f822007-12-28 20:59:23 +000022465, SPARCstation 10, SPARCstation 20, SPARCserver 600MP (sun4m
2247architecture), SPARCstation 2 (sun4c architecture), SPARCserver 1000,
2248or SPARCcenter 2000 (sun4d architecture). The emulation is somewhat
2249complete. SMP up to 16 CPUs is supported, but Linux limits the number
2250of usable CPUs to 4.
bellarde80cfcf2004-12-19 23:18:01 +00002251
blueswir17d858922007-12-28 20:57:43 +00002252QEMU emulates the following sun4m/sun4d peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00002253
2254@itemize @minus
bellard34751872005-07-02 14:31:34 +00002255@item
blueswir17d858922007-12-28 20:57:43 +00002256IOMMU or IO-UNITs
bellarde80cfcf2004-12-19 23:18:01 +00002257@item
2258TCX Frame buffer
ths5fafdf22007-09-16 21:08:06 +00002259@item
bellarde80cfcf2004-12-19 23:18:01 +00002260Lance (Am7990) Ethernet
2261@item
2262Non Volatile RAM M48T08
2263@item
bellard34751872005-07-02 14:31:34 +00002264Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2265and power/reset logic
2266@item
2267ESP SCSI controller with hard disk and CD-ROM support
2268@item
blueswir16a3b9cc2007-11-11 17:56:38 +00002269Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00002270@item
2271CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00002272@end itemize
2273
blueswir16a3b9cc2007-11-11 17:56:38 +00002274The number of peripherals is fixed in the architecture. Maximum
2275memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00002276others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00002277
bellard30a604f2006-06-14 18:35:18 +00002278Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00002279@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2280firmware implementation. The goal is to implement a 100% IEEE
22811275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00002282
2283A sample Linux 2.6 series kernel and ram disk image are available on
bellard0986ac32006-06-14 12:36:32 +00002284the QEMU web site. Please note that currently NetBSD, OpenBSD or
2285Solaris kernels don't work.
bellard34751872005-07-02 14:31:34 +00002286
2287@c man begin OPTIONS
2288
blueswir1a2502b52007-06-10 17:01:00 +00002289The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00002290
2291@table @option
2292
blueswir1a2502b52007-06-10 17:01:00 +00002293@item -g WxHx[xDEPTH]
bellard34751872005-07-02 14:31:34 +00002294
blueswir1a2502b52007-06-10 17:01:00 +00002295Set the initial TCX graphic mode. The default is 1024x768x8, currently
2296the only other possible mode is 1024x768x24.
bellard34751872005-07-02 14:31:34 +00002297
blueswir166508602007-05-01 14:16:52 +00002298@item -prom-env string
2299
2300Set OpenBIOS variables in NVRAM, for example:
2301
2302@example
2303qemu-system-sparc -prom-env 'auto-boot?=false' \
2304 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2305@end example
2306
blueswir1ee76f822007-12-28 20:59:23 +00002307@item -M [SS-5|SS-10|SS-20|SS-600MP|SS-2|SS-1000|SS-2000]
blueswir1a2502b52007-06-10 17:01:00 +00002308
2309Set the emulated machine type. Default is SS-5.
2310
bellard34751872005-07-02 14:31:34 +00002311@end table
2312
ths5fafdf22007-09-16 21:08:06 +00002313@c man end
bellard34751872005-07-02 14:31:34 +00002314
ths24d4de42007-07-11 10:24:28 +00002315@node Sparc64 System emulator
2316@section Sparc64 System emulator
bellard34751872005-07-02 14:31:34 +00002317
blueswir1c7ba2182008-07-22 07:07:34 +00002318Use the executable @file{qemu-system-sparc64} to simulate a Sun4u or
2319Sun4v machine. The emulator is not usable for anything yet.
bellardb7569212005-03-13 09:43:05 +00002320
blueswir1c7ba2182008-07-22 07:07:34 +00002321QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00002322
2323@itemize @minus
2324@item
ths5fafdf22007-09-16 21:08:06 +00002325UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00002326@item
2327PCI VGA compatible card with VESA Bochs Extensions
2328@item
2329Non Volatile RAM M48T59
2330@item
2331PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00002332@item
23332 PCI IDE interfaces with hard disk and CD-ROM support
bellard83469012005-07-23 14:27:54 +00002334@end itemize
2335
blueswir1c7ba2182008-07-22 07:07:34 +00002336@c man begin OPTIONS
2337
2338The following options are specific to the Sparc64 emulation:
2339
2340@table @option
2341
2342@item -M [sun4u|sun4v]
2343
2344Set the emulated machine type. The default is sun4u.
2345
2346@end table
2347
2348@c man end
2349
ths24d4de42007-07-11 10:24:28 +00002350@node MIPS System emulator
2351@section MIPS System emulator
bellard9d0a8e62005-07-03 17:34:05 +00002352
thsd9aedc32007-12-17 03:47:55 +00002353Four executables cover simulation of 32 and 64-bit MIPS systems in
2354both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2355@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00002356Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002357
2358@itemize @minus
2359@item
2360A generic ISA PC-like machine "mips"
2361@item
2362The MIPS Malta prototype board "malta"
2363@item
thsd9aedc32007-12-17 03:47:55 +00002364An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002365@item
thsf0fc6f82007-10-17 13:39:42 +00002366MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00002367@item
2368A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00002369@end itemize
2370
2371The generic emulation is supported by Debian 'Etch' and is able to
2372install Debian into a virtual disk image. The following devices are
2373emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002374
bellard3f9f3aa2005-12-18 20:11:37 +00002375@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002376@item
ths6bf5b4e2007-10-17 13:08:32 +00002377A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002378@item
2379PC style serial port
2380@item
ths24d4de42007-07-11 10:24:28 +00002381PC style IDE disk
2382@item
bellard3f9f3aa2005-12-18 20:11:37 +00002383NE2000 network card
2384@end itemize
2385
ths24d4de42007-07-11 10:24:28 +00002386The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002387
ths24d4de42007-07-11 10:24:28 +00002388@itemize @minus
2389@item
ths0b64d002007-07-11 21:43:14 +00002390Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002391@item
2392PIIX4 PCI/USB/SMbus controller
2393@item
2394The Multi-I/O chip's serial device
2395@item
2396PCnet32 PCI network card
2397@item
2398Malta FPGA serial device
2399@item
2400Cirrus VGA graphics card
2401@end itemize
2402
2403The ACER Pica emulation supports:
2404
2405@itemize @minus
2406@item
2407MIPS R4000 CPU
2408@item
2409PC-style IRQ and DMA controllers
2410@item
2411PC Keyboard
2412@item
2413IDE controller
2414@end itemize
2415
thsf0fc6f82007-10-17 13:39:42 +00002416The mipssim pseudo board emulation provides an environment similiar
2417to what the proprietary MIPS emulator uses for running Linux.
2418It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002419
2420@itemize @minus
2421@item
2422A range of MIPS CPUs, default is the 24Kf
2423@item
2424PC style serial port
2425@item
2426MIPSnet network emulation
2427@end itemize
2428
aurel3288cb0a02008-04-08 05:57:37 +00002429The MIPS Magnum R4000 emulation supports:
2430
2431@itemize @minus
2432@item
2433MIPS R4000 CPU
2434@item
2435PC-style IRQ controller
2436@item
2437PC Keyboard
2438@item
2439SCSI controller
2440@item
2441G364 framebuffer
2442@end itemize
2443
2444
ths24d4de42007-07-11 10:24:28 +00002445@node ARM System emulator
2446@section ARM System emulator
bellard3f9f3aa2005-12-18 20:11:37 +00002447
2448Use the executable @file{qemu-system-arm} to simulate a ARM
2449machine. The ARM Integrator/CP board is emulated with the following
2450devices:
2451
2452@itemize @minus
2453@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002454ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002455@item
2456Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002457@item
bellard3f9f3aa2005-12-18 20:11:37 +00002458SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002459@item
2460PL110 LCD controller
2461@item
2462PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002463@item
2464PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002465@end itemize
2466
2467The ARM Versatile baseboard is emulated with the following devices:
2468
2469@itemize @minus
2470@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002471ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002472@item
2473PL190 Vectored Interrupt Controller
2474@item
2475Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002476@item
pbrook00a9bf12006-05-13 16:55:46 +00002477SMC 91c111 Ethernet adapter
2478@item
2479PL110 LCD controller
2480@item
2481PL050 KMI with PS/2 keyboard and mouse.
2482@item
2483PCI host bridge. Note the emulated PCI bridge only provides access to
2484PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002485This means some devices (eg. ne2k_pci NIC) are not usable, and others
2486(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002487mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002488@item
2489PCI OHCI USB controller.
2490@item
2491LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002492@item
2493PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002494@end itemize
2495
pbrookd7739d72007-02-28 16:25:17 +00002496The ARM RealView Emulation baseboard is emulated with the following devices:
2497
2498@itemize @minus
2499@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002500ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
pbrookd7739d72007-02-28 16:25:17 +00002501@item
2502ARM AMBA Generic/Distributed Interrupt Controller
2503@item
2504Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002505@item
pbrookd7739d72007-02-28 16:25:17 +00002506SMC 91c111 Ethernet adapter
2507@item
2508PL110 LCD controller
2509@item
2510PL050 KMI with PS/2 keyboard and mouse
2511@item
2512PCI host bridge
2513@item
2514PCI OHCI USB controller
2515@item
2516LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002517@item
2518PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002519@end itemize
2520
balrogb00052e2007-04-30 02:22:06 +00002521The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2522and "Terrier") emulation includes the following peripherals:
2523
2524@itemize @minus
2525@item
2526Intel PXA270 System-on-chip (ARM V5TE core)
2527@item
2528NAND Flash memory
2529@item
2530IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2531@item
2532On-chip OHCI USB controller
2533@item
2534On-chip LCD controller
2535@item
2536On-chip Real Time Clock
2537@item
2538TI ADS7846 touchscreen controller on SSP bus
2539@item
2540Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2541@item
2542GPIO-connected keyboard controller and LEDs
2543@item
balrog549444e2007-05-01 17:53:37 +00002544Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002545@item
2546Three on-chip UARTs
2547@item
2548WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2549@end itemize
2550
balrog02645922007-11-03 12:50:46 +00002551The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2552following elements:
2553
2554@itemize @minus
2555@item
2556Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2557@item
2558ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2559@item
2560On-chip LCD controller
2561@item
2562On-chip Real Time Clock
2563@item
2564TI TSC2102i touchscreen controller / analog-digital converter / Audio
2565CODEC, connected through MicroWire and I@math{^2}S busses
2566@item
2567GPIO-connected matrix keypad
2568@item
2569Secure Digital card connected to OMAP MMC/SD host
2570@item
2571Three on-chip UARTs
2572@end itemize
2573
balrogc30bb262008-05-18 13:01:40 +00002574Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2575emulation supports the following elements:
2576
2577@itemize @minus
2578@item
2579Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2580@item
2581RAM and non-volatile OneNAND Flash memories
2582@item
2583Display connected to EPSON remote framebuffer chip and OMAP on-chip
2584display controller and a LS041y3 MIPI DBI-C controller
2585@item
2586TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2587driven through SPI bus
2588@item
2589National Semiconductor LM8323-controlled qwerty keyboard driven
2590through I@math{^2}C bus
2591@item
2592Secure Digital card connected to OMAP MMC/SD host
2593@item
2594Three OMAP on-chip UARTs and on-chip STI debugging console
2595@item
2596Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2597TUSB6010 chip - only USB host mode is supported
2598@item
2599TI TMP105 temperature sensor driven through I@math{^2}C bus
2600@item
2601TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2602@item
2603Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2604through CBUS
2605@end itemize
2606
pbrook9ee6e8b2007-11-11 00:04:49 +00002607The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2608devices:
2609
2610@itemize @minus
2611@item
2612Cortex-M3 CPU core.
2613@item
261464k Flash and 8k SRAM.
2615@item
2616Timers, UARTs, ADC and I@math{^2}C interface.
2617@item
2618OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2619@end itemize
2620
2621The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2622devices:
2623
2624@itemize @minus
2625@item
2626Cortex-M3 CPU core.
2627@item
2628256k Flash and 64k SRAM.
2629@item
2630Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2631@item
2632OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2633@end itemize
2634
balrog57cd6e92008-05-07 12:23:32 +00002635The Freecom MusicPal internet radio emulation includes the following
2636elements:
2637
2638@itemize @minus
2639@item
2640Marvell MV88W8618 ARM core.
2641@item
264232 MB RAM, 256 KB SRAM, 8 MB flash.
2643@item
2644Up to 2 16550 UARTs
2645@item
2646MV88W8xx8 Ethernet controller
2647@item
2648MV88W8618 audio controller, WM8750 CODEC and mixer
2649@item
2650128×64 display with brightness control
2651@item
26522 buttons, 2 navigation wheels with button function
2653@end itemize
2654
bellard3f9f3aa2005-12-18 20:11:37 +00002655A Linux 2.6 test image is available on the QEMU web site. More
2656information is available in the QEMU mailing-list archive.
2657
ths24d4de42007-07-11 10:24:28 +00002658@node ColdFire System emulator
2659@section ColdFire System emulator
pbrook209a4e62007-05-23 20:16:15 +00002660
2661Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2662The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002663
2664The M5208EVB emulation includes the following devices:
2665
2666@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002667@item
pbrook707e0112007-06-04 00:50:06 +00002668MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2669@item
2670Three Two on-chip UARTs.
2671@item
2672Fast Ethernet Controller (FEC)
2673@end itemize
2674
2675The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002676
2677@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002678@item
pbrook209a4e62007-05-23 20:16:15 +00002679MCF5206 ColdFire V2 Microprocessor.
2680@item
2681Two on-chip UARTs.
2682@end itemize
2683
ths5fafdf22007-09-16 21:08:06 +00002684@node QEMU User space emulator
2685@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002686
2687@menu
2688* Supported Operating Systems ::
2689* Linux User space emulator::
2690* Mac OS X/Darwin User space emulator ::
2691@end menu
2692
2693@node Supported Operating Systems
2694@section Supported Operating Systems
2695
2696The following OS are supported in user space emulation:
2697
2698@itemize @minus
2699@item
ths4be456f2007-06-03 13:41:28 +00002700Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002701@item
ths4be456f2007-06-03 13:41:28 +00002702Mac OS X/Darwin (referred as qemu-darwin-user)
bellard83195232007-02-05 19:42:07 +00002703@end itemize
2704
2705@node Linux User space emulator
2706@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002707
bellarddebc7062006-04-30 21:58:41 +00002708@menu
2709* Quick Start::
2710* Wine launch::
2711* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002712* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002713@end menu
2714
2715@node Quick Start
bellard83195232007-02-05 19:42:07 +00002716@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002717
bellard1f673132004-04-04 15:21:17 +00002718In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002719itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002720
bellard1f673132004-04-04 15:21:17 +00002721@itemize
bellard386405f2003-03-23 21:28:45 +00002722
bellard1f673132004-04-04 15:21:17 +00002723@item On x86, you can just try to launch any process by using the native
2724libraries:
bellard386405f2003-03-23 21:28:45 +00002725
ths5fafdf22007-09-16 21:08:06 +00002726@example
bellard1f673132004-04-04 15:21:17 +00002727qemu-i386 -L / /bin/ls
2728@end example
bellardfd429f22003-03-30 20:59:46 +00002729
bellard1f673132004-04-04 15:21:17 +00002730@code{-L /} tells that the x86 dynamic linker must be searched with a
2731@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002732
thsdbcf5e82007-02-10 22:14:55 +00002733@item Since QEMU is also a linux process, you can launch qemu with
2734qemu (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002735
ths5fafdf22007-09-16 21:08:06 +00002736@example
bellard1f673132004-04-04 15:21:17 +00002737qemu-i386 -L / qemu-i386 -L / /bin/ls
2738@end example
bellard386405f2003-03-23 21:28:45 +00002739
bellard1f673132004-04-04 15:21:17 +00002740@item On non x86 CPUs, you need first to download at least an x86 glibc
2741(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2742@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002743
bellard1f673132004-04-04 15:21:17 +00002744@example
ths5fafdf22007-09-16 21:08:06 +00002745unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002746@end example
bellard386405f2003-03-23 21:28:45 +00002747
bellard1f673132004-04-04 15:21:17 +00002748Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002749
bellard1f673132004-04-04 15:21:17 +00002750@example
2751qemu-i386 tests/i386/ls
2752@end example
2753You can look at @file{qemu-binfmt-conf.sh} so that
2754QEMU is automatically launched by the Linux kernel when you try to
2755launch x86 executables. It requires the @code{binfmt_misc} module in the
2756Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002757
bellard1f673132004-04-04 15:21:17 +00002758@item The x86 version of QEMU is also included. You can try weird things such as:
2759@example
bellarddebc7062006-04-30 21:58:41 +00002760qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2761 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002762@end example
bellard386405f2003-03-23 21:28:45 +00002763
bellard1f673132004-04-04 15:21:17 +00002764@end itemize
bellard386405f2003-03-23 21:28:45 +00002765
bellarddebc7062006-04-30 21:58:41 +00002766@node Wine launch
bellard83195232007-02-05 19:42:07 +00002767@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002768
bellard1f673132004-04-04 15:21:17 +00002769@itemize
bellard386405f2003-03-23 21:28:45 +00002770
bellard1f673132004-04-04 15:21:17 +00002771@item Ensure that you have a working QEMU with the x86 glibc
2772distribution (see previous section). In order to verify it, you must be
2773able to do:
bellard386405f2003-03-23 21:28:45 +00002774
bellard1f673132004-04-04 15:21:17 +00002775@example
2776qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2777@end example
bellard386405f2003-03-23 21:28:45 +00002778
bellard1f673132004-04-04 15:21:17 +00002779@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002780(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002781
bellard1f673132004-04-04 15:21:17 +00002782@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002783@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002784@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002785
bellard1f673132004-04-04 15:21:17 +00002786@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002787
bellard1f673132004-04-04 15:21:17 +00002788@example
bellarddebc7062006-04-30 21:58:41 +00002789qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2790 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002791@end example
bellard386405f2003-03-23 21:28:45 +00002792
bellard1f673132004-04-04 15:21:17 +00002793@end itemize
bellard386405f2003-03-23 21:28:45 +00002794
bellarddebc7062006-04-30 21:58:41 +00002795@node Command line options
bellard83195232007-02-05 19:42:07 +00002796@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002797
bellard1f673132004-04-04 15:21:17 +00002798@example
2799usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2800@end example
bellard386405f2003-03-23 21:28:45 +00002801
bellard1f673132004-04-04 15:21:17 +00002802@table @option
2803@item -h
2804Print the help
ths3b46e622007-09-17 08:09:54 +00002805@item -L path
bellard1f673132004-04-04 15:21:17 +00002806Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2807@item -s size
2808Set the x86 stack size in bytes (default=524288)
bellard386405f2003-03-23 21:28:45 +00002809@end table
2810
bellard1f673132004-04-04 15:21:17 +00002811Debug options:
bellard386405f2003-03-23 21:28:45 +00002812
bellard1f673132004-04-04 15:21:17 +00002813@table @option
2814@item -d
2815Activate log (logfile=/tmp/qemu.log)
2816@item -p pagesize
2817Act as if the host page size was 'pagesize' bytes
2818@end table
bellard386405f2003-03-23 21:28:45 +00002819
balrogb01bcae2007-12-16 13:05:59 +00002820Environment variables:
2821
2822@table @env
2823@item QEMU_STRACE
2824Print system calls and arguments similar to the 'strace' program
2825(NOTE: the actual 'strace' program will not work because the user
2826space emulator hasn't implemented ptrace). At the moment this is
2827incomplete. All system calls that don't have a specific argument
2828format are printed with information for six arguments. Many
2829flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002830@end table
balrogb01bcae2007-12-16 13:05:59 +00002831
pbrook79737e42006-06-11 16:28:41 +00002832@node Other binaries
bellard83195232007-02-05 19:42:07 +00002833@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002834
2835@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2836binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2837configurations), and arm-uclinux bFLT format binaries.
2838
pbrooke6e59062006-10-22 00:18:54 +00002839@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2840(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2841coldfire uClinux bFLT format binaries.
2842
pbrook79737e42006-06-11 16:28:41 +00002843The binary format is detected automatically.
2844
blueswir1a785e422007-10-20 08:09:05 +00002845@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2846(Sparc64 CPU, 32 bit ABI).
2847
2848@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2849SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2850
bellard83195232007-02-05 19:42:07 +00002851@node Mac OS X/Darwin User space emulator
2852@section Mac OS X/Darwin User space emulator
2853
2854@menu
2855* Mac OS X/Darwin Status::
2856* Mac OS X/Darwin Quick Start::
2857* Mac OS X/Darwin Command line options::
2858@end menu
2859
2860@node Mac OS X/Darwin Status
2861@subsection Mac OS X/Darwin Status
2862
2863@itemize @minus
2864@item
2865target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2866@item
2867target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2868@item
thsdbcf5e82007-02-10 22:14:55 +00002869target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
bellard83195232007-02-05 19:42:07 +00002870@item
2871target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2872@end itemize
2873
2874[1] If you're host commpage can be executed by qemu.
2875
2876@node Mac OS X/Darwin Quick Start
2877@subsection Quick Start
2878
2879In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2880itself and all the target dynamic libraries used by it. If you don't have the FAT
2881libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2882CD or compile them by hand.
2883
2884@itemize
2885
2886@item On x86, you can just try to launch any process by using the native
2887libraries:
2888
ths5fafdf22007-09-16 21:08:06 +00002889@example
thsdbcf5e82007-02-10 22:14:55 +00002890qemu-i386 /bin/ls
bellard83195232007-02-05 19:42:07 +00002891@end example
2892
2893or to run the ppc version of the executable:
2894
ths5fafdf22007-09-16 21:08:06 +00002895@example
thsdbcf5e82007-02-10 22:14:55 +00002896qemu-ppc /bin/ls
bellard83195232007-02-05 19:42:07 +00002897@end example
2898
2899@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2900are installed:
2901
ths5fafdf22007-09-16 21:08:06 +00002902@example
thsdbcf5e82007-02-10 22:14:55 +00002903qemu-i386 -L /opt/x86_root/ /bin/ls
bellard83195232007-02-05 19:42:07 +00002904@end example
2905
2906@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2907@file{/opt/x86_root/usr/bin/dyld}.
2908
2909@end itemize
2910
2911@node Mac OS X/Darwin Command line options
2912@subsection Command line options
2913
2914@example
thsdbcf5e82007-02-10 22:14:55 +00002915usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
bellard83195232007-02-05 19:42:07 +00002916@end example
2917
2918@table @option
2919@item -h
2920Print the help
ths3b46e622007-09-17 08:09:54 +00002921@item -L path
bellard83195232007-02-05 19:42:07 +00002922Set the library root path (default=/)
2923@item -s size
2924Set the stack size in bytes (default=524288)
2925@end table
2926
2927Debug options:
2928
2929@table @option
2930@item -d
2931Activate log (logfile=/tmp/qemu.log)
2932@item -p pagesize
2933Act as if the host page size was 'pagesize' bytes
2934@end table
2935
bellard15a34c62004-07-08 21:26:26 +00002936@node compilation
2937@chapter Compilation from the sources
2938
bellarddebc7062006-04-30 21:58:41 +00002939@menu
2940* Linux/Unix::
2941* Windows::
2942* Cross compilation for Windows with Linux::
2943* Mac OS X::
2944@end menu
2945
2946@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002947@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002948
bellard7c3fc842005-02-10 21:46:47 +00002949@subsection Compilation
2950
2951First you must decompress the sources:
2952@example
2953cd /tmp
2954tar zxvf qemu-x.y.z.tar.gz
2955cd qemu-x.y.z
2956@end example
2957
2958Then you configure QEMU and build it (usually no options are needed):
2959@example
2960./configure
2961make
2962@end example
2963
2964Then type as root user:
2965@example
2966make install
2967@end example
2968to install QEMU in @file{/usr/local}.
2969
bellard4fe8b872007-02-05 19:38:35 +00002970@subsection GCC version
bellard7c3fc842005-02-10 21:46:47 +00002971
ths366dfc52006-12-11 18:35:08 +00002972In order to compile QEMU successfully, it is very important that you
bellard4fe8b872007-02-05 19:38:35 +00002973have the right tools. The most important one is gcc. On most hosts and
2974in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
2975Linux distribution includes a gcc 4.x compiler, you can usually
2976install an older version (it is invoked by @code{gcc32} or
2977@code{gcc34}). The QEMU configure script automatically probes for
ths4be456f2007-06-03 13:41:28 +00002978these older versions so that usually you don't have to do anything.
bellard15a34c62004-07-08 21:26:26 +00002979
bellarddebc7062006-04-30 21:58:41 +00002980@node Windows
bellard15a34c62004-07-08 21:26:26 +00002981@section Windows
2982
2983@itemize
2984@item Install the current versions of MSYS and MinGW from
2985@url{http://www.mingw.org/}. You can find detailed installation
2986instructions in the download section and the FAQ.
2987
ths5fafdf22007-09-16 21:08:06 +00002988@item Download
bellard15a34c62004-07-08 21:26:26 +00002989the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002990(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
bellard15a34c62004-07-08 21:26:26 +00002991@url{http://www.libsdl.org}. Unpack it in a temporary place, and
2992unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2993directory. Edit the @file{sdl-config} script so that it gives the
2994correct SDL directory when invoked.
2995
2996@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002997
bellard15a34c62004-07-08 21:26:26 +00002998@item Start the MSYS shell (file @file{msys.bat}).
2999
ths5fafdf22007-09-16 21:08:06 +00003000@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00003001@file{make}. If you have problems using SDL, verify that
3002@file{sdl-config} can be launched from the MSYS command line.
3003
ths5fafdf22007-09-16 21:08:06 +00003004@item You can install QEMU in @file{Program Files/Qemu} by typing
bellard15a34c62004-07-08 21:26:26 +00003005@file{make install}. Don't forget to copy @file{SDL.dll} in
3006@file{Program Files/Qemu}.
3007
3008@end itemize
3009
bellarddebc7062006-04-30 21:58:41 +00003010@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00003011@section Cross compilation for Windows with Linux
3012
3013@itemize
3014@item
3015Install the MinGW cross compilation tools available at
3016@url{http://www.mingw.org/}.
3017
ths5fafdf22007-09-16 21:08:06 +00003018@item
bellard15a34c62004-07-08 21:26:26 +00003019Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
3020unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
3021variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
3022the QEMU configuration script.
3023
ths5fafdf22007-09-16 21:08:06 +00003024@item
bellard15a34c62004-07-08 21:26:26 +00003025Configure QEMU for Windows cross compilation:
3026@example
3027./configure --enable-mingw32
3028@end example
3029If necessary, you can change the cross-prefix according to the prefix
ths4be456f2007-06-03 13:41:28 +00003030chosen for the MinGW tools with --cross-prefix. You can also use
bellard15a34c62004-07-08 21:26:26 +00003031--prefix to set the Win32 install path.
3032
ths5fafdf22007-09-16 21:08:06 +00003033@item You can install QEMU in the installation directory by typing
bellard15a34c62004-07-08 21:26:26 +00003034@file{make install}. Don't forget to copy @file{SDL.dll} in the
ths5fafdf22007-09-16 21:08:06 +00003035installation directory.
bellard15a34c62004-07-08 21:26:26 +00003036
3037@end itemize
3038
3039Note: Currently, Wine does not seem able to launch
3040QEMU for Win32.
3041
bellarddebc7062006-04-30 21:58:41 +00003042@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00003043@section Mac OS X
3044
3045The Mac OS X patches are not fully merged in QEMU, so you should look
3046at the QEMU mailing list archive to have all the necessary
3047information.
3048
bellarddebc7062006-04-30 21:58:41 +00003049@node Index
3050@chapter Index
3051@printindex cp
3052
3053@bye