blob: 7ce8999e81717ef4cd7e9df3f17c969cae0cc60c [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
Stefan Weile080e782010-02-05 23:52:00 +01004
5@documentlanguage en
6@documentencoding UTF-8
7
bellard8f40c382006-09-20 20:28:05 +00008@settitle QEMU Emulator User Documentation
bellarddebc7062006-04-30 21:58:41 +00009@exampleindent 0
10@paragraphindent 0
11@c %**end of header
bellard386405f2003-03-23 21:28:45 +000012
Stefan Weila1a32b02010-02-05 23:51:59 +010013@ifinfo
14@direntry
15* QEMU: (qemu-doc). The QEMU Emulator User Documentation.
16@end direntry
17@end ifinfo
18
bellard0806e3f2003-10-01 00:15:32 +000019@iftex
bellard386405f2003-03-23 21:28:45 +000020@titlepage
21@sp 7
bellard8f40c382006-09-20 20:28:05 +000022@center @titlefont{QEMU Emulator}
bellarddebc7062006-04-30 21:58:41 +000023@sp 1
24@center @titlefont{User Documentation}
bellard386405f2003-03-23 21:28:45 +000025@sp 3
26@end titlepage
bellard0806e3f2003-10-01 00:15:32 +000027@end iftex
bellard386405f2003-03-23 21:28:45 +000028
bellarddebc7062006-04-30 21:58:41 +000029@ifnottex
30@node Top
31@top
32
33@menu
34* Introduction::
35* Installation::
36* QEMU PC System emulator::
37* QEMU System emulator for non PC targets::
bellard83195232007-02-05 19:42:07 +000038* QEMU User space emulator::
bellarddebc7062006-04-30 21:58:41 +000039* compilation:: Compilation from the sources
Stefan Weil7544a042010-02-05 23:52:03 +010040* License::
bellarddebc7062006-04-30 21:58:41 +000041* Index::
42@end menu
43@end ifnottex
44
45@contents
46
47@node Introduction
bellard386405f2003-03-23 21:28:45 +000048@chapter Introduction
49
bellarddebc7062006-04-30 21:58:41 +000050@menu
51* intro_features:: Features
52@end menu
53
54@node intro_features
bellard322d0c62003-06-15 23:29:28 +000055@section Features
bellard386405f2003-03-23 21:28:45 +000056
bellard1f673132004-04-04 15:21:17 +000057QEMU is a FAST! processor emulator using dynamic translation to
58achieve good emulation speed.
bellard1eb20522003-06-25 16:21:49 +000059
60QEMU has two operating modes:
bellard0806e3f2003-10-01 00:15:32 +000061
Stefan Weild7e5edc2010-02-05 23:52:02 +010062@itemize
Stefan Weil7544a042010-02-05 23:52:03 +010063@cindex operating modes
bellard0806e3f2003-10-01 00:15:32 +000064
ths5fafdf22007-09-16 21:08:06 +000065@item
Stefan Weil7544a042010-02-05 23:52:03 +010066@cindex system emulation
bellard1f673132004-04-04 15:21:17 +000067Full system emulation. In this mode, QEMU emulates a full system (for
bellard3f9f3aa2005-12-18 20:11:37 +000068example a PC), including one or several processors and various
69peripherals. It can be used to launch different Operating Systems
70without rebooting the PC or to debug system code.
bellard1eb20522003-06-25 16:21:49 +000071
ths5fafdf22007-09-16 21:08:06 +000072@item
Stefan Weil7544a042010-02-05 23:52:03 +010073@cindex user mode emulation
bellard83195232007-02-05 19:42:07 +000074User mode emulation. In this mode, QEMU can launch
75processes compiled for one CPU on another CPU. It can be used to
bellard1f673132004-04-04 15:21:17 +000076launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
77to ease cross-compilation and cross-debugging.
bellard1eb20522003-06-25 16:21:49 +000078
79@end itemize
80
bellard7c3fc842005-02-10 21:46:47 +000081QEMU can run without an host kernel driver and yet gives acceptable
ths5fafdf22007-09-16 21:08:06 +000082performance.
bellard322d0c62003-06-15 23:29:28 +000083
bellard52c00a52004-04-25 21:27:03 +000084For system emulation, the following hardware targets are supported:
85@itemize
Stefan Weil7544a042010-02-05 23:52:03 +010086@cindex emulated target systems
87@cindex supported target systems
bellard9d0a8e62005-07-03 17:34:05 +000088@item PC (x86 or x86_64 processor)
bellard3f9f3aa2005-12-18 20:11:37 +000089@item ISA PC (old style PC without PCI bus)
bellard52c00a52004-04-25 21:27:03 +000090@item PREP (PowerPC processor)
aurel32d45952a2009-01-08 16:01:13 +000091@item G3 Beige PowerMac (PowerPC processor)
bellard9d0a8e62005-07-03 17:34:05 +000092@item Mac99 PowerMac (PowerPC processor, in progress)
blueswir1ee76f822007-12-28 20:59:23 +000093@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
blueswir1c7ba2182008-07-22 07:07:34 +000094@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
thsd9aedc32007-12-17 03:47:55 +000095@item Malta board (32-bit and 64-bit MIPS processors)
aurel3288cb0a02008-04-08 05:57:37 +000096@item MIPS Magnum (64-bit MIPS processor)
pbrook9ee6e8b2007-11-11 00:04:49 +000097@item ARM Integrator/CP (ARM)
98@item ARM Versatile baseboard (ARM)
Paul Brook0ef849d2009-11-16 17:06:43 +000099@item ARM RealView Emulation/Platform baseboard (ARM)
balrogef4c3852008-12-15 02:12:20 +0000100@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
pbrook9ee6e8b2007-11-11 00:04:49 +0000101@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
102@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
pbrook707e0112007-06-04 00:50:06 +0000103@item Freescale MCF5208EVB (ColdFire V2).
pbrook209a4e62007-05-23 20:16:15 +0000104@item Arnewsh MCF5206 evaluation board (ColdFire V2).
balrog02645922007-11-03 12:50:46 +0000105@item Palm Tungsten|E PDA (OMAP310 processor)
balrogc30bb262008-05-18 13:01:40 +0000106@item N800 and N810 tablets (OMAP2420 processor)
balrog57cd6e92008-05-07 12:23:32 +0000107@item MusicPal (MV88W8618 ARM processor)
balrogef4c3852008-12-15 02:12:20 +0000108@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
109@item Siemens SX1 smartphone (OMAP310 processor)
Paul Brook4af39612009-05-14 23:11:09 +0100110@item Syborg SVP base model (ARM Cortex-A8).
Edgar E. Iglesias48c50a62009-05-27 01:34:02 +0200111@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
112@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
bellard52c00a52004-04-25 21:27:03 +0000113@end itemize
bellard386405f2003-03-23 21:28:45 +0000114
Stefan Weil7544a042010-02-05 23:52:03 +0100115@cindex supported user mode targets
116For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
117ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
118Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +0000119
bellarddebc7062006-04-30 21:58:41 +0000120@node Installation
bellard5b9f4572003-10-28 00:49:54 +0000121@chapter Installation
122
bellard15a34c62004-07-08 21:26:26 +0000123If you want to compile QEMU yourself, see @ref{compilation}.
124
bellarddebc7062006-04-30 21:58:41 +0000125@menu
126* install_linux:: Linux
127* install_windows:: Windows
128* install_mac:: Macintosh
129@end menu
130
131@node install_linux
bellard1f673132004-04-04 15:21:17 +0000132@section Linux
Stefan Weil7544a042010-02-05 23:52:03 +0100133@cindex installation (Linux)
bellard1f673132004-04-04 15:21:17 +0000134
bellard7c3fc842005-02-10 21:46:47 +0000135If a precompiled package is available for your distribution - you just
136have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000137
bellarddebc7062006-04-30 21:58:41 +0000138@node install_windows
bellard1f673132004-04-04 15:21:17 +0000139@section Windows
Stefan Weil7544a042010-02-05 23:52:03 +0100140@cindex installation (Windows)
bellard8cd0ac22004-05-12 19:09:16 +0000141
bellard15a34c62004-07-08 21:26:26 +0000142Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000143@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100144TODO (no longer available)
bellardd691f662003-03-24 21:58:34 +0000145
bellarddebc7062006-04-30 21:58:41 +0000146@node install_mac
bellard1f673132004-04-04 15:21:17 +0000147@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000148
bellard15a34c62004-07-08 21:26:26 +0000149Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000150@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100151TODO (no longer available)
bellarddf0f11a2003-05-28 00:27:57 +0000152
bellarddebc7062006-04-30 21:58:41 +0000153@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000154@chapter QEMU PC System emulator
Stefan Weil7544a042010-02-05 23:52:03 +0100155@cindex system emulation (PC)
bellard1eb20522003-06-25 16:21:49 +0000156
bellarddebc7062006-04-30 21:58:41 +0000157@menu
158* pcsys_introduction:: Introduction
159* pcsys_quickstart:: Quick Start
160* sec_invocation:: Invocation
161* pcsys_keys:: Keys
162* pcsys_monitor:: QEMU Monitor
163* disk_images:: Disk Images
164* pcsys_network:: Network emulation
165* direct_linux_boot:: Direct Linux Boot
166* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000167* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000168* gdb_usage:: GDB usage
169* pcsys_os_specific:: Target OS specific information
170@end menu
171
172@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000173@section Introduction
174
175@c man begin DESCRIPTION
176
bellard3f9f3aa2005-12-18 20:11:37 +0000177The QEMU PC System emulator simulates the
178following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000179
180@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000181@item
bellard15a34c62004-07-08 21:26:26 +0000182i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000183@item
bellard15a34c62004-07-08 21:26:26 +0000184Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
185extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000186@item
187PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000188@item
bellard15a34c62004-07-08 21:26:26 +00001892 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000190@item
191Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000192@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +0200193PCI and ISA network adapters
bellard0806e3f2003-10-01 00:15:32 +0000194@item
bellard05d58182004-08-24 21:12:04 +0000195Serial ports
196@item
bellardc0fe3822005-11-05 18:55:28 +0000197Creative SoundBlaster 16 sound card
198@item
199ENSONIQ AudioPCI ES1370 sound card
200@item
balroge5c9a132008-01-14 04:27:55 +0000201Intel 82801AA AC97 Audio compatible sound card
202@item
Gerd Hoffmann7d72e762010-11-01 16:57:48 +0100203Intel HD Audio Controller and HDA codec
204@item
bellardc0fe3822005-11-05 18:55:28 +0000205Adlib(OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000206@item
balrog26463db2008-01-17 21:47:25 +0000207Gravis Ultrasound GF1 sound card
208@item
malccc53d262008-06-13 10:48:22 +0000209CS4231A compatible sound card
210@item
bellardb389dbf2005-11-06 16:49:55 +0000211PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000212@end itemize
213
bellard3f9f3aa2005-12-18 20:11:37 +0000214SMP is supported with up to 255 CPUs.
215
malc1d1f8c32009-01-09 10:46:37 +0000216Note that adlib, gus and cs4231a are only available when QEMU was
217configured with --audio-card-list option containing the name(s) of
malce5178e82008-06-28 19:13:02 +0000218required card(s).
bellardc0fe3822005-11-05 18:55:28 +0000219
bellard15a34c62004-07-08 21:26:26 +0000220QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
221VGA BIOS.
222
bellardc0fe3822005-11-05 18:55:28 +0000223QEMU uses YM3812 emulation by Tatsuyuki Satoh.
224
balrog26463db2008-01-17 21:47:25 +0000225QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
226by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000227
malc720036a2009-09-10 20:05:59 +0400228Not that, by default, GUS shares IRQ(7) with parallel ports and so
229qemu must be told to not have parallel ports to have working GUS
230
231@example
232qemu dos.img -soundhw gus -parallel none
233@end example
234
235Alternatively:
236@example
237qemu dos.img -device gus,irq=5
238@end example
239
240Or some other unclaimed IRQ.
241
malccc53d262008-06-13 10:48:22 +0000242CS4231A is the chip used in Windows Sound System and GUSMAX products
243
bellard0806e3f2003-10-01 00:15:32 +0000244@c man end
245
bellarddebc7062006-04-30 21:58:41 +0000246@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000247@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100248@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000249
bellard285dc332003-10-27 23:58:04 +0000250Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000251
252@example
bellard285dc332003-10-27 23:58:04 +0000253qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000254@end example
255
256Linux should boot and give you a prompt.
257
bellard6cc721c2005-07-28 22:27:28 +0000258@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000259@section Invocation
260
261@example
262@c man begin SYNOPSIS
ths89dfe892007-11-21 22:38:37 +0000263usage: qemu [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000264@c man end
265@end example
266
267@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000268@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
269targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000270
blueswir15824d652009-03-28 06:44:27 +0000271@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000272
bellard3e11db92004-07-14 17:47:14 +0000273@c man end
274
bellarddebc7062006-04-30 21:58:41 +0000275@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000276@section Keys
277
278@c man begin OPTIONS
279
bellarda1b74fe2004-05-08 13:26:35 +0000280During the graphical emulation, you can use the following keys:
281@table @key
bellardf9859312004-10-03 14:33:10 +0000282@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100283@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000284Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000285
malcc4a735f2009-09-10 05:15:07 +0400286@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100287@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400288Restore the screen's un-scaled dimensions
289
bellardf9859312004-10-03 14:33:10 +0000290@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100291@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000292Switch to virtual console 'n'. Standard console mappings are:
293@table @emph
294@item 1
295Target system display
296@item 2
297Monitor
298@item 3
299Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000300@end table
301
bellardf9859312004-10-03 14:33:10 +0000302@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100303@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000304Toggle mouse and keyboard grab.
305@end table
306
Stefan Weil7544a042010-02-05 23:52:03 +0100307@kindex Ctrl-Up
308@kindex Ctrl-Down
309@kindex Ctrl-PageUp
310@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000311In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
312@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
313
Stefan Weil7544a042010-02-05 23:52:03 +0100314@kindex Ctrl-a h
bellarda0a821a2004-07-14 17:38:57 +0000315During emulation, if you are using the @option{-nographic} option, use
316@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000317
318@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000319@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100320@kindex Ctrl-a h
blueswir1d2c639d2009-01-24 18:19:25 +0000321@item Ctrl-a ?
Stefan Weil7544a042010-02-05 23:52:03 +0100322@kindex Ctrl-a ?
bellard1f673132004-04-04 15:21:17 +0000323Print this help
ths3b46e622007-09-17 08:09:54 +0000324@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100325@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000326Exit emulator
ths3b46e622007-09-17 08:09:54 +0000327@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100328@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000329Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000330@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100331@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000332Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000333@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100334@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000335Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000336@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100337@kindex Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000338Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000339@item Ctrl-a Ctrl-a
Stefan Weil7544a042010-02-05 23:52:03 +0100340@kindex Ctrl-a a
bellarda1b74fe2004-05-08 13:26:35 +0000341Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000342@end table
343@c man end
344
345@ignore
346
bellard1f673132004-04-04 15:21:17 +0000347@c man begin SEEALSO
348The HTML documentation of QEMU for more precise information and Linux
349user mode emulator invocation.
350@c man end
351
352@c man begin AUTHOR
353Fabrice Bellard
354@c man end
355
356@end ignore
357
bellarddebc7062006-04-30 21:58:41 +0000358@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000359@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100360@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000361
362The QEMU monitor is used to give complex commands to the QEMU
363emulator. You can use it to:
364
365@itemize @minus
366
367@item
thse5987522007-03-30 18:58:01 +0000368Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000369(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000370
ths5fafdf22007-09-16 21:08:06 +0000371@item
bellard1f673132004-04-04 15:21:17 +0000372Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
373from a disk file.
374
375@item Inspect the VM state without an external debugger.
376
377@end itemize
378
379@subsection Commands
380
381The following commands are available:
382
Blue Swirl23130862009-06-06 08:22:04 +0000383@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000384
385@subsection Integer expressions
386
387The monitor understands integers expressions for every integer
388argument. You can use register names to get the value of specifics
389CPU registers by prefixing them with @emph{$}.
390
391@node disk_images
392@section Disk Images
393
bellardacd935e2004-11-15 22:57:26 +0000394Since version 0.6.1, QEMU supports many disk image formats, including
395growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000396written), compressed and encrypted disk images. Version 0.8.3 added
397the new qcow2 disk image format which is essential to support VM
398snapshots.
bellard1f673132004-04-04 15:21:17 +0000399
bellarddebc7062006-04-30 21:58:41 +0000400@menu
401* disk_images_quickstart:: Quick start for disk image creation
402* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000403* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000404* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000405* qemu_nbd_invocation:: qemu-nbd Invocation
bellard19cb3732006-08-19 11:45:59 +0000406* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000407* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +0000408* disk_images_nbd:: NBD access
bellarddebc7062006-04-30 21:58:41 +0000409@end menu
410
411@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000412@subsection Quick start for disk image creation
413
414You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000415@example
bellardacd935e2004-11-15 22:57:26 +0000416qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000417@end example
bellardacd935e2004-11-15 22:57:26 +0000418where @var{myimage.img} is the disk image filename and @var{mysize} is its
419size in kilobytes. You can add an @code{M} suffix to give the size in
420megabytes and a @code{G} suffix for gigabytes.
421
bellarddebc7062006-04-30 21:58:41 +0000422See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000423
bellarddebc7062006-04-30 21:58:41 +0000424@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000425@subsection Snapshot mode
426
427If you use the option @option{-snapshot}, all disk images are
428considered as read only. When sectors in written, they are written in
429a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000430write back to the raw disk images by using the @code{commit} monitor
431command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000432
bellard13a2e802006-08-06 14:50:31 +0000433@node vm_snapshots
434@subsection VM snapshots
435
436VM snapshots are snapshots of the complete virtual machine including
437CPU state, RAM, device state and the content of all the writable
438disks. In order to use VM snapshots, you must have at least one non
439removable and writable block device using the @code{qcow2} disk image
440format. Normally this device is the first virtual hard drive.
441
442Use the monitor command @code{savevm} to create a new VM snapshot or
443replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000444snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000445
446Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
447a VM snapshot. @code{info snapshots} lists the available snapshots
448with their associated information:
449
450@example
451(qemu) info snapshots
452Snapshot devices: hda
453Snapshot list (from hda):
454ID TAG VM SIZE DATE VM CLOCK
4551 start 41M 2006-08-06 12:38:02 00:00:14.954
4562 40M 2006-08-06 12:43:29 00:00:18.633
4573 msys 40M 2006-08-06 12:44:04 00:00:23.514
458@end example
459
460A VM snapshot is made of a VM state info (its size is shown in
461@code{info snapshots}) and a snapshot of every writable disk image.
462The VM state info is stored in the first @code{qcow2} non removable
463and writable block device. The disk image snapshots are stored in
464every disk image. The size of a snapshot in a disk image is difficult
465to evaluate and is not shown by @code{info snapshots} because the
466associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000467disk space (otherwise each snapshot would need a full copy of all the
468disk images).
bellard13a2e802006-08-06 14:50:31 +0000469
470When using the (unrelated) @code{-snapshot} option
471(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
472but they are deleted as soon as you exit QEMU.
473
474VM snapshots currently have the following known limitations:
475@itemize
ths5fafdf22007-09-16 21:08:06 +0000476@item
bellard13a2e802006-08-06 14:50:31 +0000477They cannot cope with removable devices if they are removed or
478inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000479@item
bellard13a2e802006-08-06 14:50:31 +0000480A few device drivers still have incomplete snapshot support so their
481state is not saved or restored properly (in particular USB).
482@end itemize
483
bellardacd935e2004-11-15 22:57:26 +0000484@node qemu_img_invocation
485@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000486
bellardacd935e2004-11-15 22:57:26 +0000487@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000488
ths975b0922008-07-02 21:18:00 +0000489@node qemu_nbd_invocation
490@subsection @code{qemu-nbd} Invocation
491
492@include qemu-nbd.texi
493
bellard19cb3732006-08-19 11:45:59 +0000494@node host_drives
495@subsection Using host drives
496
497In addition to disk image files, QEMU can directly access host
498devices. We describe here the usage for QEMU version >= 0.8.3.
499
500@subsubsection Linux
501
502On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000503disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +0000504it. For example, use @file{/dev/cdrom} to access to the CDROM or
505@file{/dev/fd0} for the floppy.
506
bellardf5420862006-08-21 20:26:44 +0000507@table @code
bellard19cb3732006-08-19 11:45:59 +0000508@item CD
509You can specify a CDROM device even if no CDROM is loaded. QEMU has
510specific code to detect CDROM insertion or removal. CDROM ejection by
511the guest OS is supported. Currently only data CDs are supported.
512@item Floppy
513You can specify a floppy device even if no floppy is loaded. Floppy
514removal is currently not detected accurately (if you change floppy
515without doing floppy access while the floppy is not loaded, the guest
516OS will think that the same floppy is loaded).
517@item Hard disks
518Hard disks can be used. Normally you must specify the whole disk
519(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
520see it as a partitioned disk. WARNING: unless you know what you do, it
521is better to only make READ-ONLY accesses to the hard disk otherwise
522you may corrupt your host data (use the @option{-snapshot} command
523line option or modify the device permissions accordingly).
524@end table
525
526@subsubsection Windows
527
bellard01781962007-01-07 22:43:30 +0000528@table @code
529@item CD
ths4be456f2007-06-03 13:41:28 +0000530The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000531alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
532supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000533
thse5987522007-03-30 18:58:01 +0000534Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000535is better to use the @code{change} or @code{eject} monitor commands to
536change or eject media.
bellard01781962007-01-07 22:43:30 +0000537@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000538Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000539where @var{N} is the drive number (0 is the first hard disk).
540
541WARNING: unless you know what you do, it is better to only make
542READ-ONLY accesses to the hard disk otherwise you may corrupt your
543host data (use the @option{-snapshot} command line so that the
544modifications are written in a temporary file).
545@end table
546
bellard19cb3732006-08-19 11:45:59 +0000547
548@subsubsection Mac OS X
549
ths5fafdf22007-09-16 21:08:06 +0000550@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000551
thse5987522007-03-30 18:58:01 +0000552Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000553is better to use the @code{change} or @code{eject} monitor commands to
554change or eject media.
555
bellarddebc7062006-04-30 21:58:41 +0000556@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000557@subsection Virtual FAT disk images
558
559QEMU can automatically create a virtual FAT disk image from a
560directory tree. In order to use it, just type:
561
ths5fafdf22007-09-16 21:08:06 +0000562@example
bellard2c6cadd2005-12-18 18:31:45 +0000563qemu linux.img -hdb fat:/my_directory
564@end example
565
566Then you access access to all the files in the @file{/my_directory}
567directory without having to copy them in a disk image or to export
568them via SAMBA or NFS. The default access is @emph{read-only}.
569
570Floppies can be emulated with the @code{:floppy:} option:
571
ths5fafdf22007-09-16 21:08:06 +0000572@example
bellard2c6cadd2005-12-18 18:31:45 +0000573qemu linux.img -fda fat:floppy:/my_directory
574@end example
575
576A read/write support is available for testing (beta stage) with the
577@code{:rw:} option:
578
ths5fafdf22007-09-16 21:08:06 +0000579@example
bellard2c6cadd2005-12-18 18:31:45 +0000580qemu linux.img -fda fat:floppy:rw:/my_directory
581@end example
582
583What you should @emph{never} do:
584@itemize
585@item use non-ASCII filenames ;
586@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000587@item expect it to work when loadvm'ing ;
588@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000589@end itemize
590
ths75818252008-07-03 13:41:03 +0000591@node disk_images_nbd
592@subsection NBD access
593
594QEMU can access directly to block device exported using the Network Block Device
595protocol.
596
597@example
598qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
599@end example
600
601If the NBD server is located on the same host, you can use an unix socket instead
602of an inet socket:
603
604@example
605qemu linux.img -hdb nbd:unix:/tmp/my_socket
606@end example
607
608In this case, the block device must be exported using qemu-nbd:
609
610@example
611qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
612@end example
613
614The use of qemu-nbd allows to share a disk between several guests:
615@example
616qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
617@end example
618
619and then you can use it with two guests:
620@example
621qemu linux1.img -hdb nbd:unix:/tmp/my_socket
622qemu linux2.img -hdb nbd:unix:/tmp/my_socket
623@end example
624
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200625If the nbd-server uses named exports (since NBD 2.9.18), you must use the
626"exportname" option:
627@example
628qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
629qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
630@end example
631
bellarddebc7062006-04-30 21:58:41 +0000632@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +0000633@section Network emulation
634
ths4be456f2007-06-03 13:41:28 +0000635QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +0000636target) and can connect them to an arbitrary number of Virtual Local
637Area Networks (VLANs). Host TAP devices can be connected to any QEMU
638VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +0000639simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +0000640network stack can replace the TAP device to have a basic network
641connection.
bellard9d4fb822004-04-26 20:55:38 +0000642
bellard41d03942005-11-15 23:02:53 +0000643@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +0000644
bellard41d03942005-11-15 23:02:53 +0000645QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
646connection between several network devices. These devices can be for
647example QEMU virtual Ethernet cards or virtual Host ethernet devices
648(TAP devices).
649
650@subsection Using TAP network interfaces
651
652This is the standard way to connect QEMU to a real network. QEMU adds
653a virtual network device on your host (called @code{tapN}), and you
654can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +0000655
bellard8f40c382006-09-20 20:28:05 +0000656@subsubsection Linux host
657
bellard9d4fb822004-04-26 20:55:38 +0000658As an example, you can download the @file{linux-test-xxx.tar.gz}
659archive and copy the script @file{qemu-ifup} in @file{/etc} and
660configure properly @code{sudo} so that the command @code{ifconfig}
661contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +0000662that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +0000663device @file{/dev/net/tun} must be present.
664
bellardee0f4752006-08-19 16:56:18 +0000665See @ref{sec_invocation} to have examples of command lines using the
666TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +0000667
bellard8f40c382006-09-20 20:28:05 +0000668@subsubsection Windows host
669
670There is a virtual ethernet driver for Windows 2000/XP systems, called
671TAP-Win32. But it is not included in standard QEMU for Windows,
672so you will need to get it separately. It is part of OpenVPN package,
673so download OpenVPN from : @url{http://openvpn.net/}.
674
bellard9d4fb822004-04-26 20:55:38 +0000675@subsection Using the user mode network stack
676
bellard41d03942005-11-15 23:02:53 +0000677By using the option @option{-net user} (default configuration if no
678@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +0000679network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +0000680network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +0000681
682@example
683
bellard41d03942005-11-15 23:02:53 +0000684 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
685 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +0000686 |
bellard2518bd02004-09-30 22:35:13 +0000687 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +0000688 |
bellard2518bd02004-09-30 22:35:13 +0000689 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +0000690@end example
691
692The QEMU VM behaves as if it was behind a firewall which blocks all
693incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +0000694configure the network in the QEMU VM. The DHCP server assign addresses
695to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +0000696
697In order to check that the user mode network is working, you can ping
698the address 10.0.2.2 and verify that you got an address in the range
69910.0.2.x from the QEMU virtual DHCP server.
700
bellardb415a402004-05-23 21:04:06 +0000701Note that @code{ping} is not supported reliably to the internet as it
ths4be456f2007-06-03 13:41:28 +0000702would require root privileges. It means you can only ping the local
bellardb415a402004-05-23 21:04:06 +0000703router (10.0.2.2).
704
bellard9bf05442004-08-25 22:12:49 +0000705When using the built-in TFTP server, the router is also the TFTP
706server.
707
708When using the @option{-redir} option, TCP or UDP connections can be
709redirected from the host to the guest. It allows for example to
710redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +0000711
bellard41d03942005-11-15 23:02:53 +0000712@subsection Connecting VLANs between QEMU instances
713
714Using the @option{-net socket} option, it is possible to make VLANs
715that span several QEMU instances. See @ref{sec_invocation} to have a
716basic example.
717
Cam Macdonell6cbf4c82010-07-27 10:54:13 -0600718@section Other Devices
719
720@subsection Inter-VM Shared Memory device
721
722With KVM enabled on a Linux host, a shared memory device is available. Guests
723map a POSIX shared memory region into the guest as a PCI device that enables
724zero-copy communication to the application level of the guests. The basic
725syntax is:
726
727@example
728qemu -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
729@end example
730
731If desired, interrupts can be sent between guest VMs accessing the same shared
732memory region. Interrupt support requires using a shared memory server and
733using a chardev socket to connect to it. The code for the shared memory server
734is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
735memory server is:
736
737@example
738qemu -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
739 [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
740qemu -chardev socket,path=<path>,id=<id>
741@end example
742
743When using the server, the guest will be assigned a VM ID (>=0) that allows guests
744using the same server to communicate via interrupts. Guests can read their
745VM ID from a device register (see example code). Since receiving the shared
746memory region from the server is asynchronous, there is a (small) chance the
747guest may boot before the shared memory is attached. To allow an application
748to ensure shared memory is attached, the VM ID register will return -1 (an
749invalid VM ID) until the memory is attached. Once the shared memory is
750attached, the VM ID will return the guest's valid VM ID. With these semantics,
751the guest application can check to ensure the shared memory is attached to the
752guest before proceeding.
753
754The @option{role} argument can be set to either master or peer and will affect
755how the shared memory is migrated. With @option{role=master}, the guest will
756copy the shared memory on migration to the destination host. With
757@option{role=peer}, the guest will not be able to migrate with the device attached.
758With the @option{peer} case, the device should be detached and then reattached
759after migration using the PCI hotplug support.
760
bellard9d4fb822004-04-26 20:55:38 +0000761@node direct_linux_boot
762@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +0000763
764This section explains how to launch a Linux kernel inside QEMU without
765having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +0000766kernel testing.
bellard1eb20522003-06-25 16:21:49 +0000767
bellardee0f4752006-08-19 16:56:18 +0000768The syntax is:
bellard1eb20522003-06-25 16:21:49 +0000769@example
bellardee0f4752006-08-19 16:56:18 +0000770qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +0000771@end example
772
bellardee0f4752006-08-19 16:56:18 +0000773Use @option{-kernel} to provide the Linux kernel image and
774@option{-append} to give the kernel command line arguments. The
775@option{-initrd} option can be used to provide an INITRD image.
776
777When using the direct Linux boot, a disk image for the first hard disk
778@file{hda} is required because its boot sector is used to launch the
779Linux kernel.
780
781If you do not need graphical output, you can disable it and redirect
782the virtual serial port and the QEMU monitor to the console with the
783@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +0000784@example
bellardee0f4752006-08-19 16:56:18 +0000785qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
786 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +0000787@end example
788
bellardee0f4752006-08-19 16:56:18 +0000789Use @key{Ctrl-a c} to switch between the serial console and the
790monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +0000791
bellarddebc7062006-04-30 21:58:41 +0000792@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +0000793@section USB emulation
794
pbrook0aff66b2006-05-26 00:49:52 +0000795QEMU emulates a PCI UHCI USB controller. You can virtually plug
796virtual USB devices or real host USB devices (experimental, works only
797on Linux hosts). Qemu will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +0000798as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +0000799
pbrook0aff66b2006-05-26 00:49:52 +0000800@menu
801* usb_devices::
802* host_usb_devices::
803@end menu
804@node usb_devices
805@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +0000806
pbrook0aff66b2006-05-26 00:49:52 +0000807USB devices can be connected with the @option{-usbdevice} commandline option
808or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +0000809
balrogdb380c02008-01-17 22:22:45 +0000810@table @code
811@item mouse
pbrook0aff66b2006-05-26 00:49:52 +0000812Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +0000813@item tablet
bellardc6d46c22006-09-03 17:10:41 +0000814Pointer device that uses absolute coordinates (like a touchscreen).
pbrook0aff66b2006-05-26 00:49:52 +0000815This means qemu is able to report the mouse position without having
816to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +0000817@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +0000818Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +0000819@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +0000820Pass through the host device identified by @var{bus.addr}
821(Linux only)
balrogdb380c02008-01-17 22:22:45 +0000822@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +0000823Pass through the host device identified by @var{vendor_id:product_id}
824(Linux only)
balrogdb380c02008-01-17 22:22:45 +0000825@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +0000826Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
827above but it can be used with the tslib library because in addition to touch
828coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +0000829@item keyboard
balrog47b2d332007-06-22 08:16:00 +0000830Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +0000831@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
832Serial converter. This emulates an FTDI FT232BM chip connected to host character
833device @var{dev}. The available character devices are the same as for the
834@code{-serial} option. The @code{vendorid} and @code{productid} options can be
balroga11d0702008-01-19 13:00:43 +0000835used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +0000836@example
837usb_add serial:productid=FA00:tcp:192.168.0.2:4444
838@end example
839will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
840serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +0000841@item braille
842Braille device. This will use BrlAPI to display the braille output on a real
843or fake device.
balrog9ad97e62008-07-29 13:16:31 +0000844@item net:@var{options}
845Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
846specifies NIC options as with @code{-net nic,}@var{options} (see description).
847For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +0000848@example
balrog9ad97e62008-07-29 13:16:31 +0000849qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +0000850@end example
851Currently this cannot be used in machines that support PCI NICs.
balrog2d564692008-11-09 02:24:54 +0000852@item bt[:@var{hci-type}]
853Bluetooth dongle whose type is specified in the same format as with
854the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
855no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
856This USB device implements the USB Transport Layer of HCI. Example
857usage:
858@example
859qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
860@end example
pbrook0aff66b2006-05-26 00:49:52 +0000861@end table
bellardb389dbf2005-11-06 16:49:55 +0000862
pbrook0aff66b2006-05-26 00:49:52 +0000863@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +0000864@subsection Using host USB devices on a Linux host
865
866WARNING: this is an experimental feature. QEMU will slow down when
867using it. USB devices requiring real time streaming (i.e. USB Video
868Cameras) are not supported yet.
869
870@enumerate
ths5fafdf22007-09-16 21:08:06 +0000871@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +0000872is actually using the USB device. A simple way to do that is simply to
873disable the corresponding kernel module by renaming it from @file{mydriver.o}
874to @file{mydriver.o.disabled}.
875
876@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
877@example
878ls /proc/bus/usb
879001 devices drivers
880@end example
881
882@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:
883@example
884chown -R myuid /proc/bus/usb
885@end example
886
887@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +0000888@example
bellardb389dbf2005-11-06 16:49:55 +0000889info usbhost
890 Device 1.2, speed 480 Mb/s
891 Class 00: USB device 1234:5678, USB DISK
892@end example
893You should see the list of the devices you can use (Never try to use
894hubs, it won't work).
895
896@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +0000897@example
bellardb389dbf2005-11-06 16:49:55 +0000898usb_add host:1234:5678
899@end example
900
901Normally the guest OS should report that a new USB device is
902plugged. You can use the option @option{-usbdevice} to do the same.
903
904@item Now you can try to use the host USB device in QEMU.
905
906@end enumerate
907
908When relaunching QEMU, you may have to unplug and plug again the USB
909device to make it work again (this is a bug).
910
thsf858dca2007-08-25 01:40:37 +0000911@node vnc_security
912@section VNC security
913
914The VNC server capability provides access to the graphical console
915of the guest VM across the network. This has a number of security
916considerations depending on the deployment scenarios.
917
918@menu
919* vnc_sec_none::
920* vnc_sec_password::
921* vnc_sec_certificate::
922* vnc_sec_certificate_verify::
923* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +0000924* vnc_sec_sasl::
925* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +0000926* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +0000927* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +0000928@end menu
929@node vnc_sec_none
930@subsection Without passwords
931
932The simplest VNC server setup does not include any form of authentication.
933For this setup it is recommended to restrict it to listen on a UNIX domain
934socket only. For example
935
936@example
937qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
938@end example
939
940This ensures that only users on local box with read/write access to that
941path can access the VNC server. To securely access the VNC server from a
942remote machine, a combination of netcat+ssh can be used to provide a secure
943tunnel.
944
945@node vnc_sec_password
946@subsection With passwords
947
948The VNC protocol has limited support for password based authentication. Since
949the protocol limits passwords to 8 characters it should not be considered
950to provide high security. The password can be fairly easily brute-forced by
951a client making repeat connections. For this reason, a VNC server using password
952authentication should be restricted to only listen on the loopback interface
blueswir134a3d232008-10-04 20:43:39 +0000953or UNIX domain sockets. Password authentication is requested with the @code{password}
thsf858dca2007-08-25 01:40:37 +0000954option, and then once QEMU is running the password is set with the monitor. Until
955the monitor is used to set the password all clients will be rejected.
956
957@example
958qemu [...OPTIONS...] -vnc :1,password -monitor stdio
959(qemu) change vnc password
960Password: ********
961(qemu)
962@end example
963
964@node vnc_sec_certificate
965@subsection With x509 certificates
966
967The QEMU VNC server also implements the VeNCrypt extension allowing use of
968TLS for encryption of the session, and x509 certificates for authentication.
969The use of x509 certificates is strongly recommended, because TLS on its
970own is susceptible to man-in-the-middle attacks. Basic x509 certificate
971support provides a secure session, but no authentication. This allows any
972client to connect, and provides an encrypted session.
973
974@example
975qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
976@end example
977
978In the above example @code{/etc/pki/qemu} should contain at least three files,
979@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
980users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
981NB the @code{server-key.pem} file should be protected with file mode 0600 to
982only be readable by the user owning it.
983
984@node vnc_sec_certificate_verify
985@subsection With x509 certificates and client verification
986
987Certificates can also provide a means to authenticate the client connecting.
988The server will request that the client provide a certificate, which it will
989then validate against the CA certificate. This is a good choice if deploying
990in an environment with a private internal certificate authority.
991
992@example
993qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
994@end example
995
996
997@node vnc_sec_certificate_pw
998@subsection With x509 certificates, client verification and passwords
999
1000Finally, the previous method can be combined with VNC password authentication
1001to provide two layers of authentication for clients.
1002
1003@example
1004qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1005(qemu) change vnc password
1006Password: ********
1007(qemu)
1008@end example
1009
aliguori2f9606b2009-03-06 20:27:28 +00001010
1011@node vnc_sec_sasl
1012@subsection With SASL authentication
1013
1014The SASL authentication method is a VNC extension, that provides an
1015easily extendable, pluggable authentication method. This allows for
1016integration with a wide range of authentication mechanisms, such as
1017PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1018The strength of the authentication depends on the exact mechanism
1019configured. If the chosen mechanism also provides a SSF layer, then
1020it will encrypt the datastream as well.
1021
1022Refer to the later docs on how to choose the exact SASL mechanism
1023used for authentication, but assuming use of one supporting SSF,
1024then QEMU can be launched with:
1025
1026@example
1027qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
1028@end example
1029
1030@node vnc_sec_certificate_sasl
1031@subsection With x509 certificates and SASL authentication
1032
1033If the desired SASL authentication mechanism does not supported
1034SSF layers, then it is strongly advised to run it in combination
1035with TLS and x509 certificates. This provides securely encrypted
1036data stream, avoiding risk of compromising of the security
1037credentials. This can be enabled, by combining the 'sasl' option
1038with the aforementioned TLS + x509 options:
1039
1040@example
1041qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1042@end example
1043
1044
thsf858dca2007-08-25 01:40:37 +00001045@node vnc_generate_cert
1046@subsection Generating certificates for VNC
1047
1048The GNU TLS packages provides a command called @code{certtool} which can
1049be used to generate certificates and keys in PEM format. At a minimum it
1050is neccessary to setup a certificate authority, and issue certificates to
1051each server. If using certificates for authentication, then each client
1052will also need to be issued a certificate. The recommendation is for the
1053server to keep its certificates in either @code{/etc/pki/qemu} or for
1054unprivileged users in @code{$HOME/.pki/qemu}.
1055
1056@menu
1057* vnc_generate_ca::
1058* vnc_generate_server::
1059* vnc_generate_client::
1060@end menu
1061@node vnc_generate_ca
1062@subsubsection Setup the Certificate Authority
1063
1064This step only needs to be performed once per organization / organizational
1065unit. First the CA needs a private key. This key must be kept VERY secret
1066and secure. If this key is compromised the entire trust chain of the certificates
1067issued with it is lost.
1068
1069@example
1070# certtool --generate-privkey > ca-key.pem
1071@end example
1072
1073A CA needs to have a public certificate. For simplicity it can be a self-signed
1074certificate, or one issue by a commercial certificate issuing authority. To
1075generate a self-signed certificate requires one core piece of information, the
1076name of the organization.
1077
1078@example
1079# cat > ca.info <<EOF
1080cn = Name of your organization
1081ca
1082cert_signing_key
1083EOF
1084# certtool --generate-self-signed \
1085 --load-privkey ca-key.pem
1086 --template ca.info \
1087 --outfile ca-cert.pem
1088@end example
1089
1090The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1091TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1092
1093@node vnc_generate_server
1094@subsubsection Issuing server certificates
1095
1096Each server (or host) needs to be issued with a key and certificate. When connecting
1097the certificate is sent to the client which validates it against the CA certificate.
1098The core piece of information for a server certificate is the hostname. This should
1099be the fully qualified hostname that the client will connect with, since the client
1100will typically also verify the hostname in the certificate. On the host holding the
1101secure CA private key:
1102
1103@example
1104# cat > server.info <<EOF
1105organization = Name of your organization
1106cn = server.foo.example.com
1107tls_www_server
1108encryption_key
1109signing_key
1110EOF
1111# certtool --generate-privkey > server-key.pem
1112# certtool --generate-certificate \
1113 --load-ca-certificate ca-cert.pem \
1114 --load-ca-privkey ca-key.pem \
1115 --load-privkey server server-key.pem \
1116 --template server.info \
1117 --outfile server-cert.pem
1118@end example
1119
1120The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1121to the server for which they were generated. The @code{server-key.pem} is security
1122sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1123
1124@node vnc_generate_client
1125@subsubsection Issuing client certificates
1126
1127If the QEMU VNC server is to use the @code{x509verify} option to validate client
1128certificates as its authentication mechanism, each client also needs to be issued
1129a certificate. The client certificate contains enough metadata to uniquely identify
1130the client, typically organization, state, city, building, etc. On the host holding
1131the secure CA private key:
1132
1133@example
1134# cat > client.info <<EOF
1135country = GB
1136state = London
1137locality = London
1138organiazation = Name of your organization
1139cn = client.foo.example.com
1140tls_www_client
1141encryption_key
1142signing_key
1143EOF
1144# certtool --generate-privkey > client-key.pem
1145# certtool --generate-certificate \
1146 --load-ca-certificate ca-cert.pem \
1147 --load-ca-privkey ca-key.pem \
1148 --load-privkey client-key.pem \
1149 --template client.info \
1150 --outfile client-cert.pem
1151@end example
1152
1153The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1154copied to the client for which they were generated.
1155
aliguori2f9606b2009-03-06 20:27:28 +00001156
1157@node vnc_setup_sasl
1158
1159@subsection Configuring SASL mechanisms
1160
1161The following documentation assumes use of the Cyrus SASL implementation on a
1162Linux host, but the principals should apply to any other SASL impl. When SASL
1163is enabled, the mechanism configuration will be loaded from system default
1164SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1165unprivileged user, an environment variable SASL_CONF_PATH can be used
1166to make it search alternate locations for the service config.
1167
1168The default configuration might contain
1169
1170@example
1171mech_list: digest-md5
1172sasldb_path: /etc/qemu/passwd.db
1173@end example
1174
1175This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1176Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1177in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1178command. While this mechanism is easy to configure and use, it is not
1179considered secure by modern standards, so only suitable for developers /
1180ad-hoc testing.
1181
1182A more serious deployment might use Kerberos, which is done with the 'gssapi'
1183mechanism
1184
1185@example
1186mech_list: gssapi
1187keytab: /etc/qemu/krb5.tab
1188@end example
1189
1190For this to work the administrator of your KDC must generate a Kerberos
1191principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
1192replacing 'somehost.example.com' with the fully qualified host name of the
1193machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
1194
1195Other configurations will be left as an exercise for the reader. It should
1196be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1197encryption. For all other mechanisms, VNC should always be configured to
1198use TLS and x509 certificates to protect security credentials from snooping.
1199
bellard0806e3f2003-10-01 00:15:32 +00001200@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001201@section GDB usage
1202
1203QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001204'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001205
bellard9d4520d2003-10-28 01:38:57 +00001206In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001207gdb connection:
1208@example
bellarddebc7062006-04-30 21:58:41 +00001209> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1210 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001211Connected to host network interface: tun0
1212Waiting gdb connection on port 1234
1213@end example
1214
1215Then launch gdb on the 'vmlinux' executable:
1216@example
1217> gdb vmlinux
1218@end example
1219
1220In gdb, connect to QEMU:
1221@example
bellard6c9bf892004-01-24 13:46:56 +00001222(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001223@end example
1224
1225Then you can use gdb normally. For example, type 'c' to launch the kernel:
1226@example
1227(gdb) c
1228@end example
1229
bellard0806e3f2003-10-01 00:15:32 +00001230Here are some useful tips in order to use gdb on system code:
1231
1232@enumerate
1233@item
1234Use @code{info reg} to display all the CPU registers.
1235@item
1236Use @code{x/10i $eip} to display the code at the PC position.
1237@item
1238Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001239@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001240@end enumerate
1241
edgar_igl60897d32008-05-09 08:25:14 +00001242Advanced debugging options:
1243
1244The 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 +00001245@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001246@item maintenance packet qqemu.sstepbits
1247
1248This will display the MASK bits used to control the single stepping IE:
1249@example
1250(gdb) maintenance packet qqemu.sstepbits
1251sending: "qqemu.sstepbits"
1252received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1253@end example
1254@item maintenance packet qqemu.sstep
1255
1256This will display the current value of the mask used when single stepping IE:
1257@example
1258(gdb) maintenance packet qqemu.sstep
1259sending: "qqemu.sstep"
1260received: "0x7"
1261@end example
1262@item maintenance packet Qqemu.sstep=HEX_VALUE
1263
1264This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1265@example
1266(gdb) maintenance packet Qqemu.sstep=0x5
1267sending: "qemu.sstep=0x5"
1268received: "OK"
1269@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001270@end table
edgar_igl60897d32008-05-09 08:25:14 +00001271
bellarddebc7062006-04-30 21:58:41 +00001272@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001273@section Target OS specific information
1274
1275@subsection Linux
1276
bellard15a34c62004-07-08 21:26:26 +00001277To have access to SVGA graphic modes under X11, use the @code{vesa} or
1278the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1279color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001280
bellarde3371e62004-07-10 16:26:02 +00001281When using a 2.6 guest Linux kernel, you should add the option
1282@code{clock=pit} on the kernel command line because the 2.6 Linux
1283kernels make very strict real time clock checks by default that QEMU
1284cannot simulate exactly.
1285
bellard7c3fc842005-02-10 21:46:47 +00001286When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1287not activated because QEMU is slower with this patch. The QEMU
1288Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001289Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001290patch by default. Newer kernels don't have it.
1291
bellard1a084f32004-05-13 22:34:49 +00001292@subsection Windows
1293
1294If you have a slow host, using Windows 95 is better as it gives the
1295best speed. Windows 2000 is also a good choice.
1296
bellarde3371e62004-07-10 16:26:02 +00001297@subsubsection SVGA graphic modes support
1298
1299QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001300card. All Windows versions starting from Windows 95 should recognize
1301and use this graphic card. For optimal performances, use 16 bit color
1302depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001303
bellard3cb08532006-06-21 21:19:50 +00001304If you are using Windows XP as guest OS and if you want to use high
1305resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
13061280x1024x16), then you should use the VESA VBE virtual graphic card
1307(option @option{-std-vga}).
1308
bellarde3371e62004-07-10 16:26:02 +00001309@subsubsection CPU usage reduction
1310
1311Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001312instruction. The result is that it takes host CPU cycles even when
1313idle. You can install the utility from
1314@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1315problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001316
bellard9d0a8e62005-07-03 17:34:05 +00001317@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001318
bellard9d0a8e62005-07-03 17:34:05 +00001319Windows 2000 has a bug which gives a disk full problem during its
1320installation. When installing it, use the @option{-win2k-hack} QEMU
1321option to enable a specific workaround. After Windows 2000 is
1322installed, you no longer need this option (this option slows down the
1323IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001324
bellard6cc721c2005-07-28 22:27:28 +00001325@subsubsection Windows 2000 shutdown
1326
1327Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1328can. It comes from the fact that Windows 2000 does not automatically
1329use the APM driver provided by the BIOS.
1330
1331In order to correct that, do the following (thanks to Struan
1332Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1333Add/Troubleshoot a device => Add a new device & Next => No, select the
1334hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1335(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001336correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001337
1338@subsubsection Share a directory between Unix and Windows
1339
1340See @ref{sec_invocation} about the help of the option @option{-smb}.
1341
bellard2192c332006-08-21 20:28:18 +00001342@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001343
1344Some releases of Windows XP install correctly but give a security
1345error when booting:
1346@example
1347A problem is preventing Windows from accurately checking the
1348license for this computer. Error code: 0x800703e6.
1349@end example
bellarde3371e62004-07-10 16:26:02 +00001350
bellard2192c332006-08-21 20:28:18 +00001351The workaround is to install a service pack for XP after a boot in safe
1352mode. Then reboot, and the problem should go away. Since there is no
1353network while in safe mode, its recommended to download the full
1354installation of SP1 or SP2 and transfer that via an ISO or using the
1355vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001356
bellarda0a821a2004-07-14 17:38:57 +00001357@subsection MS-DOS and FreeDOS
1358
1359@subsubsection CPU usage reduction
1360
1361DOS does not correctly use the CPU HLT instruction. The result is that
1362it takes host CPU cycles even when idle. You can install the utility
1363from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1364problem.
1365
bellarddebc7062006-04-30 21:58:41 +00001366@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001367@chapter QEMU System emulator for non PC targets
1368
1369QEMU is a generic emulator and it emulates many non PC
1370machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001371differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001372
bellarddebc7062006-04-30 21:58:41 +00001373@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001374* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001375* Sparc32 System emulator::
1376* Sparc64 System emulator::
1377* MIPS System emulator::
1378* ARM System emulator::
1379* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001380* Cris System emulator::
1381* Microblaze System emulator::
1382* SH4 System emulator::
bellarddebc7062006-04-30 21:58:41 +00001383@end menu
1384
Stefan Weil7544a042010-02-05 23:52:03 +01001385@node PowerPC System emulator
1386@section PowerPC System emulator
1387@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001388
1389Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001390or PowerMac PowerPC system.
1391
bellardb671f9e2005-04-30 15:08:33 +00001392QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001393
1394@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001395@item
blueswir1006f3a42009-02-08 15:59:36 +00001396UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001397@item
1398PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001399@item
bellard15a34c62004-07-08 21:26:26 +000014002 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001401@item
bellard15a34c62004-07-08 21:26:26 +00001402NE2000 PCI adapters
1403@item
1404Non Volatile RAM
1405@item
1406VIA-CUDA with ADB keyboard and mouse.
1407@end itemize
bellard52c00a52004-04-25 21:27:03 +00001408
bellardb671f9e2005-04-30 15:08:33 +00001409QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001410
1411@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001412@item
bellard15a34c62004-07-08 21:26:26 +00001413PCI Bridge
1414@item
1415PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001416@item
bellard52c00a52004-04-25 21:27:03 +000014172 IDE interfaces with hard disk and CD-ROM support
1418@item
1419Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001420@item
bellard15a34c62004-07-08 21:26:26 +00001421NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001422@item
1423Serial port
1424@item
1425PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001426@item
1427PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001428@end itemize
1429
bellard15a34c62004-07-08 21:26:26 +00001430QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001431@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001432
blueswir1992e5ac2008-12-24 20:23:51 +00001433Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00001434for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1435v2) portable firmware implementation. The goal is to implement a 100%
1436IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00001437
bellard15a34c62004-07-08 21:26:26 +00001438@c man begin OPTIONS
1439
1440The following options are specific to the PowerPC emulation:
1441
1442@table @option
1443
Kevin Wolf4e257e52009-10-09 10:58:36 +02001444@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00001445
1446Set the initial VGA graphic mode. The default is 800x600x15.
1447
Kevin Wolf4e257e52009-10-09 10:58:36 +02001448@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00001449
1450Set OpenBIOS variables in NVRAM, for example:
1451
1452@example
1453qemu-system-ppc -prom-env 'auto-boot?=false' \
1454 -prom-env 'boot-device=hd:2,\yaboot' \
1455 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1456@end example
1457
1458These variables are not used by Open Hack'Ware.
1459
bellard15a34c62004-07-08 21:26:26 +00001460@end table
1461
ths5fafdf22007-09-16 21:08:06 +00001462@c man end
bellard15a34c62004-07-08 21:26:26 +00001463
1464
bellard52c00a52004-04-25 21:27:03 +00001465More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00001466@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00001467
ths24d4de42007-07-11 10:24:28 +00001468@node Sparc32 System emulator
1469@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001470@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00001471
blueswir134a3d232008-10-04 20:43:39 +00001472Use the executable @file{qemu-system-sparc} to simulate the following
1473Sun4m architecture machines:
1474@itemize @minus
1475@item
1476SPARCstation 4
1477@item
1478SPARCstation 5
1479@item
1480SPARCstation 10
1481@item
1482SPARCstation 20
1483@item
1484SPARCserver 600MP
1485@item
1486SPARCstation LX
1487@item
1488SPARCstation Voyager
1489@item
1490SPARCclassic
1491@item
1492SPARCbook
1493@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00001494
blueswir134a3d232008-10-04 20:43:39 +00001495The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1496but Linux limits the number of usable CPUs to 4.
1497
1498It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1499SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1500emulators are not usable yet.
1501
1502QEMU emulates the following sun4m/sun4c/sun4d peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00001503
1504@itemize @minus
bellard34751872005-07-02 14:31:34 +00001505@item
blueswir17d858922007-12-28 20:57:43 +00001506IOMMU or IO-UNITs
bellarde80cfcf2004-12-19 23:18:01 +00001507@item
1508TCX Frame buffer
ths5fafdf22007-09-16 21:08:06 +00001509@item
bellarde80cfcf2004-12-19 23:18:01 +00001510Lance (Am7990) Ethernet
1511@item
blueswir134a3d232008-10-04 20:43:39 +00001512Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00001513@item
bellard34751872005-07-02 14:31:34 +00001514Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1515and power/reset logic
1516@item
1517ESP SCSI controller with hard disk and CD-ROM support
1518@item
blueswir16a3b9cc2007-11-11 17:56:38 +00001519Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00001520@item
1521CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00001522@end itemize
1523
blueswir16a3b9cc2007-11-11 17:56:38 +00001524The number of peripherals is fixed in the architecture. Maximum
1525memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00001526others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00001527
bellard30a604f2006-06-14 18:35:18 +00001528Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00001529@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1530firmware implementation. The goal is to implement a 100% IEEE
15311275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00001532
1533A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00001534the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1535some kernel versions work. Please note that currently Solaris kernels
1536don't work probably due to interface issues between OpenBIOS and
1537Solaris.
bellard34751872005-07-02 14:31:34 +00001538
1539@c man begin OPTIONS
1540
blueswir1a2502b52007-06-10 17:01:00 +00001541The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00001542
1543@table @option
1544
Kevin Wolf4e257e52009-10-09 10:58:36 +02001545@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00001546
blueswir1a2502b52007-06-10 17:01:00 +00001547Set the initial TCX graphic mode. The default is 1024x768x8, currently
1548the only other possible mode is 1024x768x24.
bellard34751872005-07-02 14:31:34 +00001549
Kevin Wolf4e257e52009-10-09 10:58:36 +02001550@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00001551
1552Set OpenBIOS variables in NVRAM, for example:
1553
1554@example
1555qemu-system-sparc -prom-env 'auto-boot?=false' \
1556 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1557@end example
1558
Blue Swirl609c1da2010-03-18 18:41:49 +00001559@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook|SS-2|SS-1000|SS-2000]
blueswir1a2502b52007-06-10 17:01:00 +00001560
1561Set the emulated machine type. Default is SS-5.
1562
bellard34751872005-07-02 14:31:34 +00001563@end table
1564
ths5fafdf22007-09-16 21:08:06 +00001565@c man end
bellard34751872005-07-02 14:31:34 +00001566
ths24d4de42007-07-11 10:24:28 +00001567@node Sparc64 System emulator
1568@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001569@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00001570
blueswir134a3d232008-10-04 20:43:39 +00001571Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1572(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1573Niagara (T1) machine. The emulator is not usable for anything yet, but
1574it can launch some kernels.
bellardb7569212005-03-13 09:43:05 +00001575
blueswir1c7ba2182008-07-22 07:07:34 +00001576QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00001577
1578@itemize @minus
1579@item
ths5fafdf22007-09-16 21:08:06 +00001580UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00001581@item
1582PCI VGA compatible card with VESA Bochs Extensions
1583@item
blueswir134a3d232008-10-04 20:43:39 +00001584PS/2 mouse and keyboard
1585@item
bellard83469012005-07-23 14:27:54 +00001586Non Volatile RAM M48T59
1587@item
1588PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00001589@item
15902 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00001591@item
1592Floppy disk
bellard83469012005-07-23 14:27:54 +00001593@end itemize
1594
blueswir1c7ba2182008-07-22 07:07:34 +00001595@c man begin OPTIONS
1596
1597The following options are specific to the Sparc64 emulation:
1598
1599@table @option
1600
Kevin Wolf4e257e52009-10-09 10:58:36 +02001601@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00001602
1603Set OpenBIOS variables in NVRAM, for example:
1604
1605@example
1606qemu-system-sparc64 -prom-env 'auto-boot?=false'
1607@end example
1608
1609@item -M [sun4u|sun4v|Niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00001610
1611Set the emulated machine type. The default is sun4u.
1612
1613@end table
1614
1615@c man end
1616
ths24d4de42007-07-11 10:24:28 +00001617@node MIPS System emulator
1618@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001619@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00001620
thsd9aedc32007-12-17 03:47:55 +00001621Four executables cover simulation of 32 and 64-bit MIPS systems in
1622both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1623@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00001624Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00001625
1626@itemize @minus
1627@item
1628A generic ISA PC-like machine "mips"
1629@item
1630The MIPS Malta prototype board "malta"
1631@item
thsd9aedc32007-12-17 03:47:55 +00001632An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00001633@item
thsf0fc6f82007-10-17 13:39:42 +00001634MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00001635@item
1636A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00001637@end itemize
1638
1639The generic emulation is supported by Debian 'Etch' and is able to
1640install Debian into a virtual disk image. The following devices are
1641emulated:
bellard9d0a8e62005-07-03 17:34:05 +00001642
bellard3f9f3aa2005-12-18 20:11:37 +00001643@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001644@item
ths6bf5b4e2007-10-17 13:08:32 +00001645A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00001646@item
1647PC style serial port
1648@item
ths24d4de42007-07-11 10:24:28 +00001649PC style IDE disk
1650@item
bellard3f9f3aa2005-12-18 20:11:37 +00001651NE2000 network card
1652@end itemize
1653
ths24d4de42007-07-11 10:24:28 +00001654The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00001655
ths24d4de42007-07-11 10:24:28 +00001656@itemize @minus
1657@item
ths0b64d002007-07-11 21:43:14 +00001658Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00001659@item
1660PIIX4 PCI/USB/SMbus controller
1661@item
1662The Multi-I/O chip's serial device
1663@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02001664PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00001665@item
1666Malta FPGA serial device
1667@item
aurel321f605a72009-02-08 14:51:19 +00001668Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00001669@end itemize
1670
1671The ACER Pica emulation supports:
1672
1673@itemize @minus
1674@item
1675MIPS R4000 CPU
1676@item
1677PC-style IRQ and DMA controllers
1678@item
1679PC Keyboard
1680@item
1681IDE controller
1682@end itemize
1683
thsf0fc6f82007-10-17 13:39:42 +00001684The mipssim pseudo board emulation provides an environment similiar
1685to what the proprietary MIPS emulator uses for running Linux.
1686It supports:
ths6bf5b4e2007-10-17 13:08:32 +00001687
1688@itemize @minus
1689@item
1690A range of MIPS CPUs, default is the 24Kf
1691@item
1692PC style serial port
1693@item
1694MIPSnet network emulation
1695@end itemize
1696
aurel3288cb0a02008-04-08 05:57:37 +00001697The MIPS Magnum R4000 emulation supports:
1698
1699@itemize @minus
1700@item
1701MIPS R4000 CPU
1702@item
1703PC-style IRQ controller
1704@item
1705PC Keyboard
1706@item
1707SCSI controller
1708@item
1709G364 framebuffer
1710@end itemize
1711
1712
ths24d4de42007-07-11 10:24:28 +00001713@node ARM System emulator
1714@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001715@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00001716
1717Use the executable @file{qemu-system-arm} to simulate a ARM
1718machine. The ARM Integrator/CP board is emulated with the following
1719devices:
1720
1721@itemize @minus
1722@item
pbrook9ee6e8b2007-11-11 00:04:49 +00001723ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00001724@item
1725Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001726@item
bellard3f9f3aa2005-12-18 20:11:37 +00001727SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00001728@item
1729PL110 LCD controller
1730@item
1731PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00001732@item
1733PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00001734@end itemize
1735
1736The ARM Versatile baseboard is emulated with the following devices:
1737
1738@itemize @minus
1739@item
pbrook9ee6e8b2007-11-11 00:04:49 +00001740ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00001741@item
1742PL190 Vectored Interrupt Controller
1743@item
1744Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001745@item
pbrook00a9bf12006-05-13 16:55:46 +00001746SMC 91c111 Ethernet adapter
1747@item
1748PL110 LCD controller
1749@item
1750PL050 KMI with PS/2 keyboard and mouse.
1751@item
1752PCI host bridge. Note the emulated PCI bridge only provides access to
1753PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00001754This means some devices (eg. ne2k_pci NIC) are not usable, and others
1755(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00001756mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00001757@item
1758PCI OHCI USB controller.
1759@item
1760LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00001761@item
1762PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00001763@end itemize
1764
Paul Brook21a88942009-12-21 20:19:12 +00001765Several variants of the ARM RealView baseboard are emulated,
1766including the EB, PB-A8 and PBX-A9. Due to interactions with the
1767bootloader, only certain Linux kernel configurations work out
1768of the box on these boards.
1769
1770Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1771enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
1772should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1773disabled and expect 1024M RAM.
1774
1775The following devices are emuilated:
pbrookd7739d72007-02-28 16:25:17 +00001776
1777@itemize @minus
1778@item
Paul Brookf7c70322009-11-19 16:45:21 +00001779ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00001780@item
1781ARM AMBA Generic/Distributed Interrupt Controller
1782@item
1783Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001784@item
Paul Brook0ef849d2009-11-16 17:06:43 +00001785SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00001786@item
1787PL110 LCD controller
1788@item
1789PL050 KMI with PS/2 keyboard and mouse
1790@item
1791PCI host bridge
1792@item
1793PCI OHCI USB controller
1794@item
1795LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00001796@item
1797PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00001798@end itemize
1799
balrogb00052e2007-04-30 02:22:06 +00001800The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1801and "Terrier") emulation includes the following peripherals:
1802
1803@itemize @minus
1804@item
1805Intel PXA270 System-on-chip (ARM V5TE core)
1806@item
1807NAND Flash memory
1808@item
1809IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1810@item
1811On-chip OHCI USB controller
1812@item
1813On-chip LCD controller
1814@item
1815On-chip Real Time Clock
1816@item
1817TI ADS7846 touchscreen controller on SSP bus
1818@item
1819Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1820@item
1821GPIO-connected keyboard controller and LEDs
1822@item
balrog549444e2007-05-01 17:53:37 +00001823Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00001824@item
1825Three on-chip UARTs
1826@item
1827WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1828@end itemize
1829
balrog02645922007-11-03 12:50:46 +00001830The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1831following elements:
1832
1833@itemize @minus
1834@item
1835Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1836@item
1837ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1838@item
1839On-chip LCD controller
1840@item
1841On-chip Real Time Clock
1842@item
1843TI TSC2102i touchscreen controller / analog-digital converter / Audio
1844CODEC, connected through MicroWire and I@math{^2}S busses
1845@item
1846GPIO-connected matrix keypad
1847@item
1848Secure Digital card connected to OMAP MMC/SD host
1849@item
1850Three on-chip UARTs
1851@end itemize
1852
balrogc30bb262008-05-18 13:01:40 +00001853Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1854emulation supports the following elements:
1855
1856@itemize @minus
1857@item
1858Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1859@item
1860RAM and non-volatile OneNAND Flash memories
1861@item
1862Display connected to EPSON remote framebuffer chip and OMAP on-chip
1863display controller and a LS041y3 MIPI DBI-C controller
1864@item
1865TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1866driven through SPI bus
1867@item
1868National Semiconductor LM8323-controlled qwerty keyboard driven
1869through I@math{^2}C bus
1870@item
1871Secure Digital card connected to OMAP MMC/SD host
1872@item
1873Three OMAP on-chip UARTs and on-chip STI debugging console
1874@item
balrog2d564692008-11-09 02:24:54 +00001875A Bluetooth(R) transciever and HCI connected to an UART
1876@item
balrogc30bb262008-05-18 13:01:40 +00001877Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
1878TUSB6010 chip - only USB host mode is supported
1879@item
1880TI TMP105 temperature sensor driven through I@math{^2}C bus
1881@item
1882TI TWL92230C power management companion with an RTC on I@math{^2}C bus
1883@item
1884Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
1885through CBUS
1886@end itemize
1887
pbrook9ee6e8b2007-11-11 00:04:49 +00001888The Luminary Micro Stellaris LM3S811EVB emulation includes the following
1889devices:
1890
1891@itemize @minus
1892@item
1893Cortex-M3 CPU core.
1894@item
189564k Flash and 8k SRAM.
1896@item
1897Timers, UARTs, ADC and I@math{^2}C interface.
1898@item
1899OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
1900@end itemize
1901
1902The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
1903devices:
1904
1905@itemize @minus
1906@item
1907Cortex-M3 CPU core.
1908@item
1909256k Flash and 64k SRAM.
1910@item
1911Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
1912@item
1913OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1914@end itemize
1915
balrog57cd6e92008-05-07 12:23:32 +00001916The Freecom MusicPal internet radio emulation includes the following
1917elements:
1918
1919@itemize @minus
1920@item
1921Marvell MV88W8618 ARM core.
1922@item
192332 MB RAM, 256 KB SRAM, 8 MB flash.
1924@item
1925Up to 2 16550 UARTs
1926@item
1927MV88W8xx8 Ethernet controller
1928@item
1929MV88W8618 audio controller, WM8750 CODEC and mixer
1930@item
Stefan Weile080e782010-02-05 23:52:00 +01001931128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00001932@item
19332 buttons, 2 navigation wheels with button function
1934@end itemize
1935
balrog997641a2008-12-15 02:05:00 +00001936The Siemens SX1 models v1 and v2 (default) basic emulation.
1937The emulaton includes the following elements:
1938
1939@itemize @minus
1940@item
1941Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1942@item
1943ROM and RAM memories (ROM firmware image can be loaded with -pflash)
1944V1
19451 Flash of 16MB and 1 Flash of 8MB
1946V2
19471 Flash of 32MB
1948@item
1949On-chip LCD controller
1950@item
1951On-chip Real Time Clock
1952@item
1953Secure Digital card connected to OMAP MMC/SD host
1954@item
1955Three on-chip UARTs
1956@end itemize
1957
Paul Brook4af39612009-05-14 23:11:09 +01001958The "Syborg" Symbian Virtual Platform base model includes the following
1959elements:
1960
1961@itemize @minus
1962@item
1963ARM Cortex-A8 CPU
1964@item
1965Interrupt controller
1966@item
1967Timer
1968@item
1969Real Time Clock
1970@item
1971Keyboard
1972@item
1973Framebuffer
1974@item
1975Touchscreen
1976@item
1977UARTs
1978@end itemize
1979
bellard3f9f3aa2005-12-18 20:11:37 +00001980A Linux 2.6 test image is available on the QEMU web site. More
1981information is available in the QEMU mailing-list archive.
1982
blueswir1d2c639d2009-01-24 18:19:25 +00001983@c man begin OPTIONS
1984
1985The following options are specific to the ARM emulation:
1986
1987@table @option
1988
1989@item -semihosting
1990Enable semihosting syscall emulation.
1991
1992On ARM this implements the "Angel" interface.
1993
1994Note that this allows guest direct access to the host filesystem,
1995so should only be used with trusted guest OS.
1996
1997@end table
1998
ths24d4de42007-07-11 10:24:28 +00001999@node ColdFire System emulator
2000@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002001@cindex system emulation (ColdFire)
2002@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002003
2004Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2005The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002006
2007The M5208EVB emulation includes the following devices:
2008
2009@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002010@item
pbrook707e0112007-06-04 00:50:06 +00002011MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2012@item
2013Three Two on-chip UARTs.
2014@item
2015Fast Ethernet Controller (FEC)
2016@end itemize
2017
2018The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002019
2020@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002021@item
pbrook209a4e62007-05-23 20:16:15 +00002022MCF5206 ColdFire V2 Microprocessor.
2023@item
2024Two on-chip UARTs.
2025@end itemize
2026
blueswir1d2c639d2009-01-24 18:19:25 +00002027@c man begin OPTIONS
2028
Stefan Weil7544a042010-02-05 23:52:03 +01002029The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002030
2031@table @option
2032
2033@item -semihosting
2034Enable semihosting syscall emulation.
2035
2036On M68K this implements the "ColdFire GDB" interface used by libgloss.
2037
2038Note that this allows guest direct access to the host filesystem,
2039so should only be used with trusted guest OS.
2040
2041@end table
2042
Stefan Weil7544a042010-02-05 23:52:03 +01002043@node Cris System emulator
2044@section Cris System emulator
2045@cindex system emulation (Cris)
2046
2047TODO
2048
2049@node Microblaze System emulator
2050@section Microblaze System emulator
2051@cindex system emulation (Microblaze)
2052
2053TODO
2054
2055@node SH4 System emulator
2056@section SH4 System emulator
2057@cindex system emulation (SH4)
2058
2059TODO
2060
ths5fafdf22007-09-16 21:08:06 +00002061@node QEMU User space emulator
2062@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002063
2064@menu
2065* Supported Operating Systems ::
2066* Linux User space emulator::
2067* Mac OS X/Darwin User space emulator ::
blueswir184778502008-10-26 20:33:16 +00002068* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002069@end menu
2070
2071@node Supported Operating Systems
2072@section Supported Operating Systems
2073
2074The following OS are supported in user space emulation:
2075
2076@itemize @minus
2077@item
ths4be456f2007-06-03 13:41:28 +00002078Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002079@item
ths4be456f2007-06-03 13:41:28 +00002080Mac OS X/Darwin (referred as qemu-darwin-user)
blueswir184778502008-10-26 20:33:16 +00002081@item
2082BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002083@end itemize
2084
2085@node Linux User space emulator
2086@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002087
bellarddebc7062006-04-30 21:58:41 +00002088@menu
2089* Quick Start::
2090* Wine launch::
2091* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002092* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002093@end menu
2094
2095@node Quick Start
bellard83195232007-02-05 19:42:07 +00002096@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002097
bellard1f673132004-04-04 15:21:17 +00002098In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002099itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002100
bellard1f673132004-04-04 15:21:17 +00002101@itemize
bellard386405f2003-03-23 21:28:45 +00002102
bellard1f673132004-04-04 15:21:17 +00002103@item On x86, you can just try to launch any process by using the native
2104libraries:
bellard386405f2003-03-23 21:28:45 +00002105
ths5fafdf22007-09-16 21:08:06 +00002106@example
bellard1f673132004-04-04 15:21:17 +00002107qemu-i386 -L / /bin/ls
2108@end example
bellardfd429f22003-03-30 20:59:46 +00002109
bellard1f673132004-04-04 15:21:17 +00002110@code{-L /} tells that the x86 dynamic linker must be searched with a
2111@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002112
thsdbcf5e82007-02-10 22:14:55 +00002113@item Since QEMU is also a linux process, you can launch qemu with
2114qemu (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002115
ths5fafdf22007-09-16 21:08:06 +00002116@example
bellard1f673132004-04-04 15:21:17 +00002117qemu-i386 -L / qemu-i386 -L / /bin/ls
2118@end example
bellard386405f2003-03-23 21:28:45 +00002119
bellard1f673132004-04-04 15:21:17 +00002120@item On non x86 CPUs, you need first to download at least an x86 glibc
2121(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2122@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002123
bellard1f673132004-04-04 15:21:17 +00002124@example
ths5fafdf22007-09-16 21:08:06 +00002125unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002126@end example
bellard386405f2003-03-23 21:28:45 +00002127
bellard1f673132004-04-04 15:21:17 +00002128Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002129
bellard1f673132004-04-04 15:21:17 +00002130@example
2131qemu-i386 tests/i386/ls
2132@end example
2133You can look at @file{qemu-binfmt-conf.sh} so that
2134QEMU is automatically launched by the Linux kernel when you try to
2135launch x86 executables. It requires the @code{binfmt_misc} module in the
2136Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002137
bellard1f673132004-04-04 15:21:17 +00002138@item The x86 version of QEMU is also included. You can try weird things such as:
2139@example
bellarddebc7062006-04-30 21:58:41 +00002140qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2141 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002142@end example
bellard386405f2003-03-23 21:28:45 +00002143
bellard1f673132004-04-04 15:21:17 +00002144@end itemize
bellard386405f2003-03-23 21:28:45 +00002145
bellarddebc7062006-04-30 21:58:41 +00002146@node Wine launch
bellard83195232007-02-05 19:42:07 +00002147@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002148
bellard1f673132004-04-04 15:21:17 +00002149@itemize
bellard386405f2003-03-23 21:28:45 +00002150
bellard1f673132004-04-04 15:21:17 +00002151@item Ensure that you have a working QEMU with the x86 glibc
2152distribution (see previous section). In order to verify it, you must be
2153able to do:
bellard386405f2003-03-23 21:28:45 +00002154
bellard1f673132004-04-04 15:21:17 +00002155@example
2156qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2157@end example
bellard386405f2003-03-23 21:28:45 +00002158
bellard1f673132004-04-04 15:21:17 +00002159@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002160(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002161
bellard1f673132004-04-04 15:21:17 +00002162@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002163@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002164@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002165
bellard1f673132004-04-04 15:21:17 +00002166@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002167
bellard1f673132004-04-04 15:21:17 +00002168@example
bellarddebc7062006-04-30 21:58:41 +00002169qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2170 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002171@end example
bellard386405f2003-03-23 21:28:45 +00002172
bellard1f673132004-04-04 15:21:17 +00002173@end itemize
bellard386405f2003-03-23 21:28:45 +00002174
bellarddebc7062006-04-30 21:58:41 +00002175@node Command line options
bellard83195232007-02-05 19:42:07 +00002176@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002177
bellard1f673132004-04-04 15:21:17 +00002178@example
Paul Brook68a1c812010-05-29 02:27:35 +01002179usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
bellard1f673132004-04-04 15:21:17 +00002180@end example
bellard386405f2003-03-23 21:28:45 +00002181
bellard1f673132004-04-04 15:21:17 +00002182@table @option
2183@item -h
2184Print the help
ths3b46e622007-09-17 08:09:54 +00002185@item -L path
bellard1f673132004-04-04 15:21:17 +00002186Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2187@item -s size
2188Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002189@item -cpu model
2190Select CPU model (-cpu ? for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002191@item -ignore-environment
2192Start with an empty environment. Without this option,
2193the inital environment is a copy of the caller's environment.
2194@item -E @var{var}=@var{value}
2195Set environment @var{var} to @var{value}.
2196@item -U @var{var}
2197Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002198@item -B offset
2199Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002200the address region required by guest applications is reserved on the host.
2201This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002202@item -R size
2203Pre-allocate a guest virtual address space of the given size (in bytes).
2204"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002205@end table
2206
bellard1f673132004-04-04 15:21:17 +00002207Debug options:
bellard386405f2003-03-23 21:28:45 +00002208
bellard1f673132004-04-04 15:21:17 +00002209@table @option
2210@item -d
2211Activate log (logfile=/tmp/qemu.log)
2212@item -p pagesize
2213Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002214@item -g port
2215Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002216@item -singlestep
2217Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002218@end table
bellard386405f2003-03-23 21:28:45 +00002219
balrogb01bcae2007-12-16 13:05:59 +00002220Environment variables:
2221
2222@table @env
2223@item QEMU_STRACE
2224Print system calls and arguments similar to the 'strace' program
2225(NOTE: the actual 'strace' program will not work because the user
2226space emulator hasn't implemented ptrace). At the moment this is
2227incomplete. All system calls that don't have a specific argument
2228format are printed with information for six arguments. Many
2229flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002230@end table
balrogb01bcae2007-12-16 13:05:59 +00002231
pbrook79737e42006-06-11 16:28:41 +00002232@node Other binaries
bellard83195232007-02-05 19:42:07 +00002233@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002234
Stefan Weil7544a042010-02-05 23:52:03 +01002235@cindex user mode (Alpha)
2236@command{qemu-alpha} TODO.
2237
2238@cindex user mode (ARM)
2239@command{qemu-armeb} TODO.
2240
2241@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002242@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2243binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2244configurations), and arm-uclinux bFLT format binaries.
2245
Stefan Weil7544a042010-02-05 23:52:03 +01002246@cindex user mode (ColdFire)
2247@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002248@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2249(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2250coldfire uClinux bFLT format binaries.
2251
pbrook79737e42006-06-11 16:28:41 +00002252The binary format is detected automatically.
2253
Stefan Weil7544a042010-02-05 23:52:03 +01002254@cindex user mode (Cris)
2255@command{qemu-cris} TODO.
2256
2257@cindex user mode (i386)
2258@command{qemu-i386} TODO.
2259@command{qemu-x86_64} TODO.
2260
2261@cindex user mode (Microblaze)
2262@command{qemu-microblaze} TODO.
2263
2264@cindex user mode (MIPS)
2265@command{qemu-mips} TODO.
2266@command{qemu-mipsel} TODO.
2267
2268@cindex user mode (PowerPC)
2269@command{qemu-ppc64abi32} TODO.
2270@command{qemu-ppc64} TODO.
2271@command{qemu-ppc} TODO.
2272
2273@cindex user mode (SH4)
2274@command{qemu-sh4eb} TODO.
2275@command{qemu-sh4} TODO.
2276
2277@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002278@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2279
blueswir1a785e422007-10-20 08:09:05 +00002280@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2281(Sparc64 CPU, 32 bit ABI).
2282
2283@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2284SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2285
bellard83195232007-02-05 19:42:07 +00002286@node Mac OS X/Darwin User space emulator
2287@section Mac OS X/Darwin User space emulator
2288
2289@menu
2290* Mac OS X/Darwin Status::
2291* Mac OS X/Darwin Quick Start::
2292* Mac OS X/Darwin Command line options::
2293@end menu
2294
2295@node Mac OS X/Darwin Status
2296@subsection Mac OS X/Darwin Status
2297
2298@itemize @minus
2299@item
2300target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2301@item
2302target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2303@item
thsdbcf5e82007-02-10 22:14:55 +00002304target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
bellard83195232007-02-05 19:42:07 +00002305@item
2306target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2307@end itemize
2308
2309[1] If you're host commpage can be executed by qemu.
2310
2311@node Mac OS X/Darwin Quick Start
2312@subsection Quick Start
2313
2314In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2315itself and all the target dynamic libraries used by it. If you don't have the FAT
2316libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2317CD or compile them by hand.
2318
2319@itemize
2320
2321@item On x86, you can just try to launch any process by using the native
2322libraries:
2323
ths5fafdf22007-09-16 21:08:06 +00002324@example
thsdbcf5e82007-02-10 22:14:55 +00002325qemu-i386 /bin/ls
bellard83195232007-02-05 19:42:07 +00002326@end example
2327
2328or to run the ppc version of the executable:
2329
ths5fafdf22007-09-16 21:08:06 +00002330@example
thsdbcf5e82007-02-10 22:14:55 +00002331qemu-ppc /bin/ls
bellard83195232007-02-05 19:42:07 +00002332@end example
2333
2334@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2335are installed:
2336
ths5fafdf22007-09-16 21:08:06 +00002337@example
thsdbcf5e82007-02-10 22:14:55 +00002338qemu-i386 -L /opt/x86_root/ /bin/ls
bellard83195232007-02-05 19:42:07 +00002339@end example
2340
2341@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2342@file{/opt/x86_root/usr/bin/dyld}.
2343
2344@end itemize
2345
2346@node Mac OS X/Darwin Command line options
2347@subsection Command line options
2348
2349@example
thsdbcf5e82007-02-10 22:14:55 +00002350usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
bellard83195232007-02-05 19:42:07 +00002351@end example
2352
2353@table @option
2354@item -h
2355Print the help
ths3b46e622007-09-17 08:09:54 +00002356@item -L path
bellard83195232007-02-05 19:42:07 +00002357Set the library root path (default=/)
2358@item -s size
2359Set the stack size in bytes (default=524288)
2360@end table
2361
2362Debug options:
2363
2364@table @option
2365@item -d
2366Activate log (logfile=/tmp/qemu.log)
2367@item -p pagesize
2368Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002369@item -singlestep
2370Run the emulation in single step mode.
bellard83195232007-02-05 19:42:07 +00002371@end table
2372
blueswir184778502008-10-26 20:33:16 +00002373@node BSD User space emulator
2374@section BSD User space emulator
2375
2376@menu
2377* BSD Status::
2378* BSD Quick Start::
2379* BSD Command line options::
2380@end menu
2381
2382@node BSD Status
2383@subsection BSD Status
2384
2385@itemize @minus
2386@item
2387target Sparc64 on Sparc64: Some trivial programs work.
2388@end itemize
2389
2390@node BSD Quick Start
2391@subsection Quick Start
2392
2393In order to launch a BSD process, QEMU needs the process executable
2394itself and all the target dynamic libraries used by it.
2395
2396@itemize
2397
2398@item On Sparc64, you can just try to launch any process by using the native
2399libraries:
2400
2401@example
2402qemu-sparc64 /bin/ls
2403@end example
2404
2405@end itemize
2406
2407@node BSD Command line options
2408@subsection Command line options
2409
2410@example
2411usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2412@end example
2413
2414@table @option
2415@item -h
2416Print the help
2417@item -L path
2418Set the library root path (default=/)
2419@item -s size
2420Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002421@item -ignore-environment
2422Start with an empty environment. Without this option,
2423the inital environment is a copy of the caller's environment.
2424@item -E @var{var}=@var{value}
2425Set environment @var{var} to @var{value}.
2426@item -U @var{var}
2427Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00002428@item -bsd type
2429Set the type of the emulated BSD Operating system. Valid values are
2430FreeBSD, NetBSD and OpenBSD (default).
2431@end table
2432
2433Debug options:
2434
2435@table @option
2436@item -d
2437Activate log (logfile=/tmp/qemu.log)
2438@item -p pagesize
2439Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002440@item -singlestep
2441Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00002442@end table
2443
bellard15a34c62004-07-08 21:26:26 +00002444@node compilation
2445@chapter Compilation from the sources
2446
bellarddebc7062006-04-30 21:58:41 +00002447@menu
2448* Linux/Unix::
2449* Windows::
2450* Cross compilation for Windows with Linux::
2451* Mac OS X::
Stefan Weil47eacb42010-02-05 23:52:01 +01002452* Make targets::
bellarddebc7062006-04-30 21:58:41 +00002453@end menu
2454
2455@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002456@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002457
bellard7c3fc842005-02-10 21:46:47 +00002458@subsection Compilation
2459
2460First you must decompress the sources:
2461@example
2462cd /tmp
2463tar zxvf qemu-x.y.z.tar.gz
2464cd qemu-x.y.z
2465@end example
2466
2467Then you configure QEMU and build it (usually no options are needed):
2468@example
2469./configure
2470make
2471@end example
2472
2473Then type as root user:
2474@example
2475make install
2476@end example
2477to install QEMU in @file{/usr/local}.
2478
bellarddebc7062006-04-30 21:58:41 +00002479@node Windows
bellard15a34c62004-07-08 21:26:26 +00002480@section Windows
2481
2482@itemize
2483@item Install the current versions of MSYS and MinGW from
2484@url{http://www.mingw.org/}. You can find detailed installation
2485instructions in the download section and the FAQ.
2486
ths5fafdf22007-09-16 21:08:06 +00002487@item Download
bellard15a34c62004-07-08 21:26:26 +00002488the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002489(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
Scott Tsaid0a96f32010-01-30 03:28:58 +08002490@url{http://www.libsdl.org}. Unpack it in a temporary place and
2491edit the @file{sdl-config} script so that it gives the
bellard15a34c62004-07-08 21:26:26 +00002492correct SDL directory when invoked.
2493
Scott Tsaid0a96f32010-01-30 03:28:58 +08002494@item Install the MinGW version of zlib and make sure
2495@file{zlib.h} and @file{libz.dll.a} are in
2496MingGW's default header and linker search paths.
2497
bellard15a34c62004-07-08 21:26:26 +00002498@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002499
bellard15a34c62004-07-08 21:26:26 +00002500@item Start the MSYS shell (file @file{msys.bat}).
2501
ths5fafdf22007-09-16 21:08:06 +00002502@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00002503@file{make}. If you have problems using SDL, verify that
2504@file{sdl-config} can be launched from the MSYS command line.
2505
ths5fafdf22007-09-16 21:08:06 +00002506@item You can install QEMU in @file{Program Files/Qemu} by typing
bellard15a34c62004-07-08 21:26:26 +00002507@file{make install}. Don't forget to copy @file{SDL.dll} in
2508@file{Program Files/Qemu}.
2509
2510@end itemize
2511
bellarddebc7062006-04-30 21:58:41 +00002512@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00002513@section Cross compilation for Windows with Linux
2514
2515@itemize
2516@item
2517Install the MinGW cross compilation tools available at
2518@url{http://www.mingw.org/}.
2519
Scott Tsaid0a96f32010-01-30 03:28:58 +08002520@item Download
2521the MinGW development library of SDL 1.2.x
2522(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2523@url{http://www.libsdl.org}. Unpack it in a temporary place and
2524edit the @file{sdl-config} script so that it gives the
2525correct SDL directory when invoked. Set up the @code{PATH} environment
2526variable so that @file{sdl-config} can be launched by
bellard15a34c62004-07-08 21:26:26 +00002527the QEMU configuration script.
2528
Scott Tsaid0a96f32010-01-30 03:28:58 +08002529@item Install the MinGW version of zlib and make sure
2530@file{zlib.h} and @file{libz.dll.a} are in
2531MingGW's default header and linker search paths.
2532
ths5fafdf22007-09-16 21:08:06 +00002533@item
bellard15a34c62004-07-08 21:26:26 +00002534Configure QEMU for Windows cross compilation:
2535@example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002536PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
bellard15a34c62004-07-08 21:26:26 +00002537@end example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002538The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
2539MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
2540We set the @code{PATH} environment variable to ensure the MingW version of @file{sdl-config} is used and
2541use --cross-prefix to specify the name of the cross compiler.
2542You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
2543
2544Under Fedora Linux, you can run:
2545@example
2546yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
2547@end example
2548to get a suitable cross compilation environment.
bellard15a34c62004-07-08 21:26:26 +00002549
ths5fafdf22007-09-16 21:08:06 +00002550@item You can install QEMU in the installation directory by typing
Scott Tsaid0a96f32010-01-30 03:28:58 +08002551@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
ths5fafdf22007-09-16 21:08:06 +00002552installation directory.
bellard15a34c62004-07-08 21:26:26 +00002553
2554@end itemize
2555
Scott Tsaid0a96f32010-01-30 03:28:58 +08002556Wine can be used to launch the resulting qemu.exe compiled for Win32.
bellard15a34c62004-07-08 21:26:26 +00002557
bellarddebc7062006-04-30 21:58:41 +00002558@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00002559@section Mac OS X
2560
2561The Mac OS X patches are not fully merged in QEMU, so you should look
2562at the QEMU mailing list archive to have all the necessary
2563information.
2564
Stefan Weil47eacb42010-02-05 23:52:01 +01002565@node Make targets
2566@section Make targets
2567
2568@table @code
2569
2570@item make
2571@item make all
2572Make everything which is typically needed.
2573
2574@item install
2575TODO
2576
2577@item install-doc
2578TODO
2579
2580@item make clean
2581Remove most files which were built during make.
2582
2583@item make distclean
2584Remove everything which was built during make.
2585
2586@item make dvi
2587@item make html
2588@item make info
2589@item make pdf
2590Create documentation in dvi, html, info or pdf format.
2591
2592@item make cscope
2593TODO
2594
2595@item make defconfig
2596(Re-)create some build configuration files.
2597User made changes will be overwritten.
2598
2599@item tar
2600@item tarbin
2601TODO
2602
2603@end table
2604
Stefan Weil7544a042010-02-05 23:52:03 +01002605@node License
2606@appendix License
2607
2608QEMU is a trademark of Fabrice Bellard.
2609
2610QEMU is released under the GNU General Public License (TODO: add link).
2611Parts of QEMU have specific licenses, see file LICENSE.
2612
2613TODO (refer to file LICENSE, include it, include the GPL?)
2614
bellarddebc7062006-04-30 21:58:41 +00002615@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01002616@appendix Index
2617@menu
2618* Concept Index::
2619* Function Index::
2620* Keystroke Index::
2621* Program Index::
2622* Data Type Index::
2623* Variable Index::
2624@end menu
2625
2626@node Concept Index
2627@section Concept Index
2628This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00002629@printindex cp
2630
Stefan Weil7544a042010-02-05 23:52:03 +01002631@node Function Index
2632@section Function Index
2633This index could be used for command line options and monitor functions.
2634@printindex fn
2635
2636@node Keystroke Index
2637@section Keystroke Index
2638
2639This is a list of all keystrokes which have a special function
2640in system emulation.
2641
2642@printindex ky
2643
2644@node Program Index
2645@section Program Index
2646@printindex pg
2647
2648@node Data Type Index
2649@section Data Type Index
2650
2651This index could be used for qdev device names and options.
2652
2653@printindex tp
2654
2655@node Variable Index
2656@section Variable Index
2657@printindex vr
2658
bellarddebc7062006-04-30 21:58:41 +00002659@bye