blob: 9c3cb62ee3765ad0402ed7ff3a94d769d9e5714a [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).
Max Filippov3aeaea62011-10-10 14:48:23 +0400113@item Avnet LX60/LX110/LX200 boards (Xtensa)
bellard52c00a52004-04-25 21:27:03 +0000114@end itemize
bellard386405f2003-03-23 21:28:45 +0000115
Stefan Weil7544a042010-02-05 23:52:03 +0100116@cindex supported user mode targets
117For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
118ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
119Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +0000120
bellarddebc7062006-04-30 21:58:41 +0000121@node Installation
bellard5b9f4572003-10-28 00:49:54 +0000122@chapter Installation
123
bellard15a34c62004-07-08 21:26:26 +0000124If you want to compile QEMU yourself, see @ref{compilation}.
125
bellarddebc7062006-04-30 21:58:41 +0000126@menu
127* install_linux:: Linux
128* install_windows:: Windows
129* install_mac:: Macintosh
130@end menu
131
132@node install_linux
bellard1f673132004-04-04 15:21:17 +0000133@section Linux
Stefan Weil7544a042010-02-05 23:52:03 +0100134@cindex installation (Linux)
bellard1f673132004-04-04 15:21:17 +0000135
bellard7c3fc842005-02-10 21:46:47 +0000136If a precompiled package is available for your distribution - you just
137have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000138
bellarddebc7062006-04-30 21:58:41 +0000139@node install_windows
bellard1f673132004-04-04 15:21:17 +0000140@section Windows
Stefan Weil7544a042010-02-05 23:52:03 +0100141@cindex installation (Windows)
bellard8cd0ac22004-05-12 19:09:16 +0000142
bellard15a34c62004-07-08 21:26:26 +0000143Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000144@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100145TODO (no longer available)
bellardd691f662003-03-24 21:58:34 +0000146
bellarddebc7062006-04-30 21:58:41 +0000147@node install_mac
bellard1f673132004-04-04 15:21:17 +0000148@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000149
bellard15a34c62004-07-08 21:26:26 +0000150Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000151@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100152TODO (no longer available)
bellarddf0f11a2003-05-28 00:27:57 +0000153
bellarddebc7062006-04-30 21:58:41 +0000154@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000155@chapter QEMU PC System emulator
Stefan Weil7544a042010-02-05 23:52:03 +0100156@cindex system emulation (PC)
bellard1eb20522003-06-25 16:21:49 +0000157
bellarddebc7062006-04-30 21:58:41 +0000158@menu
159* pcsys_introduction:: Introduction
160* pcsys_quickstart:: Quick Start
161* sec_invocation:: Invocation
162* pcsys_keys:: Keys
163* pcsys_monitor:: QEMU Monitor
164* disk_images:: Disk Images
165* pcsys_network:: Network emulation
Stefan Weil576fd0a2011-01-07 18:59:14 +0100166* pcsys_other_devs:: Other Devices
bellarddebc7062006-04-30 21:58:41 +0000167* direct_linux_boot:: Direct Linux Boot
168* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000169* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000170* gdb_usage:: GDB usage
171* pcsys_os_specific:: Target OS specific information
172@end menu
173
174@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000175@section Introduction
176
177@c man begin DESCRIPTION
178
bellard3f9f3aa2005-12-18 20:11:37 +0000179The QEMU PC System emulator simulates the
180following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000181
182@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000183@item
bellard15a34c62004-07-08 21:26:26 +0000184i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000185@item
bellard15a34c62004-07-08 21:26:26 +0000186Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
187extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000188@item
189PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000190@item
bellard15a34c62004-07-08 21:26:26 +00001912 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000192@item
193Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000194@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +0200195PCI and ISA network adapters
bellard0806e3f2003-10-01 00:15:32 +0000196@item
bellard05d58182004-08-24 21:12:04 +0000197Serial ports
198@item
bellardc0fe3822005-11-05 18:55:28 +0000199Creative SoundBlaster 16 sound card
200@item
201ENSONIQ AudioPCI ES1370 sound card
202@item
balroge5c9a132008-01-14 04:27:55 +0000203Intel 82801AA AC97 Audio compatible sound card
204@item
Gerd Hoffmann7d72e762010-11-01 16:57:48 +0100205Intel HD Audio Controller and HDA codec
206@item
Stefan Weil2d983442011-01-07 18:59:15 +0100207Adlib (OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000208@item
balrog26463db2008-01-17 21:47:25 +0000209Gravis Ultrasound GF1 sound card
210@item
malccc53d262008-06-13 10:48:22 +0000211CS4231A compatible sound card
212@item
bellardb389dbf2005-11-06 16:49:55 +0000213PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000214@end itemize
215
bellard3f9f3aa2005-12-18 20:11:37 +0000216SMP is supported with up to 255 CPUs.
217
malc1d1f8c32009-01-09 10:46:37 +0000218Note that adlib, gus and cs4231a are only available when QEMU was
219configured with --audio-card-list option containing the name(s) of
malce5178e82008-06-28 19:13:02 +0000220required card(s).
bellardc0fe3822005-11-05 18:55:28 +0000221
bellard15a34c62004-07-08 21:26:26 +0000222QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
223VGA BIOS.
224
bellardc0fe3822005-11-05 18:55:28 +0000225QEMU uses YM3812 emulation by Tatsuyuki Satoh.
226
Stefan Weil2d983442011-01-07 18:59:15 +0100227QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
balrog26463db2008-01-17 21:47:25 +0000228by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000229
Bernhard Reutner-Fischer1a1a0e22011-10-25 10:22:18 +0200230Note that, by default, GUS shares IRQ(7) with parallel ports and so
malc720036a2009-09-10 20:05:59 +0400231qemu must be told to not have parallel ports to have working GUS
232
233@example
234qemu dos.img -soundhw gus -parallel none
235@end example
236
237Alternatively:
238@example
239qemu dos.img -device gus,irq=5
240@end example
241
242Or some other unclaimed IRQ.
243
malccc53d262008-06-13 10:48:22 +0000244CS4231A is the chip used in Windows Sound System and GUSMAX products
245
bellard0806e3f2003-10-01 00:15:32 +0000246@c man end
247
bellarddebc7062006-04-30 21:58:41 +0000248@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000249@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100250@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000251
bellard285dc332003-10-27 23:58:04 +0000252Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000253
254@example
bellard285dc332003-10-27 23:58:04 +0000255qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000256@end example
257
258Linux should boot and give you a prompt.
259
bellard6cc721c2005-07-28 22:27:28 +0000260@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000261@section Invocation
262
263@example
264@c man begin SYNOPSIS
ths89dfe892007-11-21 22:38:37 +0000265usage: qemu [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000266@c man end
267@end example
268
269@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000270@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
271targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000272
blueswir15824d652009-03-28 06:44:27 +0000273@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000274
bellard3e11db92004-07-14 17:47:14 +0000275@c man end
276
bellarddebc7062006-04-30 21:58:41 +0000277@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000278@section Keys
279
280@c man begin OPTIONS
281
Brad Hardsde1db2a2011-04-29 21:46:12 +1000282During the graphical emulation, you can use special key combinations to change
283modes. The default key mappings are shown below, but if you use @code{-alt-grab}
284then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
285@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
286
bellarda1b74fe2004-05-08 13:26:35 +0000287@table @key
bellardf9859312004-10-03 14:33:10 +0000288@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100289@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000290Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000291
Jan Kiszkad6a65ba2011-07-30 11:39:16 +0200292@item Ctrl-Alt-+
293@kindex Ctrl-Alt-+
294Enlarge the screen
295
296@item Ctrl-Alt--
297@kindex Ctrl-Alt--
298Shrink the screen
299
malcc4a735f2009-09-10 05:15:07 +0400300@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100301@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400302Restore the screen's un-scaled dimensions
303
bellardf9859312004-10-03 14:33:10 +0000304@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100305@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000306Switch to virtual console 'n'. Standard console mappings are:
307@table @emph
308@item 1
309Target system display
310@item 2
311Monitor
312@item 3
313Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000314@end table
315
bellardf9859312004-10-03 14:33:10 +0000316@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100317@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000318Toggle mouse and keyboard grab.
319@end table
320
Stefan Weil7544a042010-02-05 23:52:03 +0100321@kindex Ctrl-Up
322@kindex Ctrl-Down
323@kindex Ctrl-PageUp
324@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000325In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
326@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
327
Stefan Weil7544a042010-02-05 23:52:03 +0100328@kindex Ctrl-a h
bellarda0a821a2004-07-14 17:38:57 +0000329During emulation, if you are using the @option{-nographic} option, use
330@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000331
332@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000333@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100334@kindex Ctrl-a h
blueswir1d2c639d2009-01-24 18:19:25 +0000335@item Ctrl-a ?
Stefan Weil7544a042010-02-05 23:52:03 +0100336@kindex Ctrl-a ?
bellard1f673132004-04-04 15:21:17 +0000337Print this help
ths3b46e622007-09-17 08:09:54 +0000338@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100339@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000340Exit emulator
ths3b46e622007-09-17 08:09:54 +0000341@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100342@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000343Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000344@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100345@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000346Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000347@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100348@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000349Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000350@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100351@kindex Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000352Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000353@item Ctrl-a Ctrl-a
Stefan Weil7544a042010-02-05 23:52:03 +0100354@kindex Ctrl-a a
bellarda1b74fe2004-05-08 13:26:35 +0000355Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000356@end table
357@c man end
358
359@ignore
360
bellard1f673132004-04-04 15:21:17 +0000361@c man begin SEEALSO
362The HTML documentation of QEMU for more precise information and Linux
363user mode emulator invocation.
364@c man end
365
366@c man begin AUTHOR
367Fabrice Bellard
368@c man end
369
370@end ignore
371
bellarddebc7062006-04-30 21:58:41 +0000372@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000373@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100374@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000375
376The QEMU monitor is used to give complex commands to the QEMU
377emulator. You can use it to:
378
379@itemize @minus
380
381@item
thse5987522007-03-30 18:58:01 +0000382Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000383(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000384
ths5fafdf22007-09-16 21:08:06 +0000385@item
bellard1f673132004-04-04 15:21:17 +0000386Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
387from a disk file.
388
389@item Inspect the VM state without an external debugger.
390
391@end itemize
392
393@subsection Commands
394
395The following commands are available:
396
Blue Swirl23130862009-06-06 08:22:04 +0000397@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000398
399@subsection Integer expressions
400
401The monitor understands integers expressions for every integer
402argument. You can use register names to get the value of specifics
403CPU registers by prefixing them with @emph{$}.
404
405@node disk_images
406@section Disk Images
407
bellardacd935e2004-11-15 22:57:26 +0000408Since version 0.6.1, QEMU supports many disk image formats, including
409growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000410written), compressed and encrypted disk images. Version 0.8.3 added
411the new qcow2 disk image format which is essential to support VM
412snapshots.
bellard1f673132004-04-04 15:21:17 +0000413
bellarddebc7062006-04-30 21:58:41 +0000414@menu
415* disk_images_quickstart:: Quick start for disk image creation
416* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000417* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000418* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000419* qemu_nbd_invocation:: qemu-nbd Invocation
bellard19cb3732006-08-19 11:45:59 +0000420* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000421* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +0000422* disk_images_nbd:: NBD access
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900423* disk_images_sheepdog:: Sheepdog disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100424* disk_images_iscsi:: iSCSI LUNs
bellarddebc7062006-04-30 21:58:41 +0000425@end menu
426
427@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000428@subsection Quick start for disk image creation
429
430You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000431@example
bellardacd935e2004-11-15 22:57:26 +0000432qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000433@end example
bellardacd935e2004-11-15 22:57:26 +0000434where @var{myimage.img} is the disk image filename and @var{mysize} is its
435size in kilobytes. You can add an @code{M} suffix to give the size in
436megabytes and a @code{G} suffix for gigabytes.
437
bellarddebc7062006-04-30 21:58:41 +0000438See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000439
bellarddebc7062006-04-30 21:58:41 +0000440@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000441@subsection Snapshot mode
442
443If you use the option @option{-snapshot}, all disk images are
444considered as read only. When sectors in written, they are written in
445a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000446write back to the raw disk images by using the @code{commit} monitor
447command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000448
bellard13a2e802006-08-06 14:50:31 +0000449@node vm_snapshots
450@subsection VM snapshots
451
452VM snapshots are snapshots of the complete virtual machine including
453CPU state, RAM, device state and the content of all the writable
454disks. In order to use VM snapshots, you must have at least one non
455removable and writable block device using the @code{qcow2} disk image
456format. Normally this device is the first virtual hard drive.
457
458Use the monitor command @code{savevm} to create a new VM snapshot or
459replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000460snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000461
462Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
463a VM snapshot. @code{info snapshots} lists the available snapshots
464with their associated information:
465
466@example
467(qemu) info snapshots
468Snapshot devices: hda
469Snapshot list (from hda):
470ID TAG VM SIZE DATE VM CLOCK
4711 start 41M 2006-08-06 12:38:02 00:00:14.954
4722 40M 2006-08-06 12:43:29 00:00:18.633
4733 msys 40M 2006-08-06 12:44:04 00:00:23.514
474@end example
475
476A VM snapshot is made of a VM state info (its size is shown in
477@code{info snapshots}) and a snapshot of every writable disk image.
478The VM state info is stored in the first @code{qcow2} non removable
479and writable block device. The disk image snapshots are stored in
480every disk image. The size of a snapshot in a disk image is difficult
481to evaluate and is not shown by @code{info snapshots} because the
482associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000483disk space (otherwise each snapshot would need a full copy of all the
484disk images).
bellard13a2e802006-08-06 14:50:31 +0000485
486When using the (unrelated) @code{-snapshot} option
487(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
488but they are deleted as soon as you exit QEMU.
489
490VM snapshots currently have the following known limitations:
491@itemize
ths5fafdf22007-09-16 21:08:06 +0000492@item
bellard13a2e802006-08-06 14:50:31 +0000493They cannot cope with removable devices if they are removed or
494inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000495@item
bellard13a2e802006-08-06 14:50:31 +0000496A few device drivers still have incomplete snapshot support so their
497state is not saved or restored properly (in particular USB).
498@end itemize
499
bellardacd935e2004-11-15 22:57:26 +0000500@node qemu_img_invocation
501@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000502
bellardacd935e2004-11-15 22:57:26 +0000503@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000504
ths975b0922008-07-02 21:18:00 +0000505@node qemu_nbd_invocation
506@subsection @code{qemu-nbd} Invocation
507
508@include qemu-nbd.texi
509
bellard19cb3732006-08-19 11:45:59 +0000510@node host_drives
511@subsection Using host drives
512
513In addition to disk image files, QEMU can directly access host
514devices. We describe here the usage for QEMU version >= 0.8.3.
515
516@subsubsection Linux
517
518On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000519disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +0000520it. For example, use @file{/dev/cdrom} to access to the CDROM or
521@file{/dev/fd0} for the floppy.
522
bellardf5420862006-08-21 20:26:44 +0000523@table @code
bellard19cb3732006-08-19 11:45:59 +0000524@item CD
525You can specify a CDROM device even if no CDROM is loaded. QEMU has
526specific code to detect CDROM insertion or removal. CDROM ejection by
527the guest OS is supported. Currently only data CDs are supported.
528@item Floppy
529You can specify a floppy device even if no floppy is loaded. Floppy
530removal is currently not detected accurately (if you change floppy
531without doing floppy access while the floppy is not loaded, the guest
532OS will think that the same floppy is loaded).
533@item Hard disks
534Hard disks can be used. Normally you must specify the whole disk
535(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
536see it as a partitioned disk. WARNING: unless you know what you do, it
537is better to only make READ-ONLY accesses to the hard disk otherwise
538you may corrupt your host data (use the @option{-snapshot} command
539line option or modify the device permissions accordingly).
540@end table
541
542@subsubsection Windows
543
bellard01781962007-01-07 22:43:30 +0000544@table @code
545@item CD
ths4be456f2007-06-03 13:41:28 +0000546The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000547alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
548supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000549
thse5987522007-03-30 18:58:01 +0000550Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000551is better to use the @code{change} or @code{eject} monitor commands to
552change or eject media.
bellard01781962007-01-07 22:43:30 +0000553@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000554Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000555where @var{N} is the drive number (0 is the first hard disk).
556
557WARNING: unless you know what you do, it is better to only make
558READ-ONLY accesses to the hard disk otherwise you may corrupt your
559host data (use the @option{-snapshot} command line so that the
560modifications are written in a temporary file).
561@end table
562
bellard19cb3732006-08-19 11:45:59 +0000563
564@subsubsection Mac OS X
565
ths5fafdf22007-09-16 21:08:06 +0000566@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000567
thse5987522007-03-30 18:58:01 +0000568Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000569is better to use the @code{change} or @code{eject} monitor commands to
570change or eject media.
571
bellarddebc7062006-04-30 21:58:41 +0000572@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000573@subsection Virtual FAT disk images
574
575QEMU can automatically create a virtual FAT disk image from a
576directory tree. In order to use it, just type:
577
ths5fafdf22007-09-16 21:08:06 +0000578@example
bellard2c6cadd2005-12-18 18:31:45 +0000579qemu linux.img -hdb fat:/my_directory
580@end example
581
582Then you access access to all the files in the @file{/my_directory}
583directory without having to copy them in a disk image or to export
584them via SAMBA or NFS. The default access is @emph{read-only}.
585
586Floppies can be emulated with the @code{:floppy:} option:
587
ths5fafdf22007-09-16 21:08:06 +0000588@example
bellard2c6cadd2005-12-18 18:31:45 +0000589qemu linux.img -fda fat:floppy:/my_directory
590@end example
591
592A read/write support is available for testing (beta stage) with the
593@code{:rw:} option:
594
ths5fafdf22007-09-16 21:08:06 +0000595@example
bellard2c6cadd2005-12-18 18:31:45 +0000596qemu linux.img -fda fat:floppy:rw:/my_directory
597@end example
598
599What you should @emph{never} do:
600@itemize
601@item use non-ASCII filenames ;
602@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000603@item expect it to work when loadvm'ing ;
604@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000605@end itemize
606
ths75818252008-07-03 13:41:03 +0000607@node disk_images_nbd
608@subsection NBD access
609
610QEMU can access directly to block device exported using the Network Block Device
611protocol.
612
613@example
614qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
615@end example
616
617If the NBD server is located on the same host, you can use an unix socket instead
618of an inet socket:
619
620@example
621qemu linux.img -hdb nbd:unix:/tmp/my_socket
622@end example
623
624In this case, the block device must be exported using qemu-nbd:
625
626@example
627qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
628@end example
629
630The use of qemu-nbd allows to share a disk between several guests:
631@example
632qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
633@end example
634
635and then you can use it with two guests:
636@example
637qemu linux1.img -hdb nbd:unix:/tmp/my_socket
638qemu linux2.img -hdb nbd:unix:/tmp/my_socket
639@end example
640
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200641If the nbd-server uses named exports (since NBD 2.9.18), you must use the
642"exportname" option:
643@example
644qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
645qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
646@end example
647
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900648@node disk_images_sheepdog
649@subsection Sheepdog disk images
650
651Sheepdog is a distributed storage system for QEMU. It provides highly
652available block level storage volumes that can be attached to
653QEMU-based virtual machines.
654
655You can create a Sheepdog disk image with the command:
656@example
657qemu-img create sheepdog:@var{image} @var{size}
658@end example
659where @var{image} is the Sheepdog image name and @var{size} is its
660size.
661
662To import the existing @var{filename} to Sheepdog, you can use a
663convert command.
664@example
665qemu-img convert @var{filename} sheepdog:@var{image}
666@end example
667
668You can boot from the Sheepdog disk image with the command:
669@example
670qemu sheepdog:@var{image}
671@end example
672
673You can also create a snapshot of the Sheepdog image like qcow2.
674@example
675qemu-img snapshot -c @var{tag} sheepdog:@var{image}
676@end example
677where @var{tag} is a tag name of the newly created snapshot.
678
679To boot from the Sheepdog snapshot, specify the tag name of the
680snapshot.
681@example
682qemu sheepdog:@var{image}:@var{tag}
683@end example
684
685You can create a cloned image from the existing snapshot.
686@example
687qemu-img create -b sheepdog:@var{base}:@var{tag} sheepdog:@var{image}
688@end example
689where @var{base} is a image name of the source snapshot and @var{tag}
690is its tag name.
691
692If the Sheepdog daemon doesn't run on the local host, you need to
693specify one of the Sheepdog servers to connect to.
694@example
695qemu-img create sheepdog:@var{hostname}:@var{port}:@var{image} @var{size}
696qemu sheepdog:@var{hostname}:@var{port}:@var{image}
697@end example
698
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100699@node disk_images_iscsi
700@subsection iSCSI LUNs
701
702iSCSI is a popular protocol used to access SCSI devices across a computer
703network.
704
705There are two different ways iSCSI devices can be used by QEMU.
706
707The first method is to mount the iSCSI LUN on the host, and make it appear as
708any other ordinary SCSI device on the host and then to access this device as a
709/dev/sd device from QEMU. How to do this differs between host OSes.
710
711The second method involves using the iSCSI initiator that is built into
712QEMU. This provides a mechanism that works the same way regardless of which
713host OS you are running QEMU on. This section will describe this second method
714of using iSCSI together with QEMU.
715
716In QEMU, iSCSI devices are described using special iSCSI URLs
717
718@example
719URL syntax:
720iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
721@end example
722
723Username and password are optional and only used if your target is set up
724using CHAP authentication for access control.
725Alternatively the username and password can also be set via environment
726variables to have these not show up in the process list
727
728@example
729export LIBISCSI_CHAP_USERNAME=<username>
730export LIBISCSI_CHAP_PASSWORD=<password>
731iscsi://<host>/<target-iqn-name>/<lun>
732@end example
733
734Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
735@example
736This example shows how to set up an iSCSI target with one CDROM and one DISK
737using the Linux STGT software target. This target is available on Red Hat based
738systems as the package 'scsi-target-utils'.
739
740tgtd --iscsi portal=127.0.0.1:3260
741tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
742tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
743 -b /IMAGES/disk.img --device-type=disk
744tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
745 -b /IMAGES/cd.iso --device-type=cd
746tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
747
748qemu-system-i386 -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
749 -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
750@end example
751
752
753
bellarddebc7062006-04-30 21:58:41 +0000754@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +0000755@section Network emulation
756
ths4be456f2007-06-03 13:41:28 +0000757QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +0000758target) and can connect them to an arbitrary number of Virtual Local
759Area Networks (VLANs). Host TAP devices can be connected to any QEMU
760VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +0000761simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +0000762network stack can replace the TAP device to have a basic network
763connection.
bellard9d4fb822004-04-26 20:55:38 +0000764
bellard41d03942005-11-15 23:02:53 +0000765@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +0000766
bellard41d03942005-11-15 23:02:53 +0000767QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
768connection between several network devices. These devices can be for
769example QEMU virtual Ethernet cards or virtual Host ethernet devices
770(TAP devices).
771
772@subsection Using TAP network interfaces
773
774This is the standard way to connect QEMU to a real network. QEMU adds
775a virtual network device on your host (called @code{tapN}), and you
776can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +0000777
bellard8f40c382006-09-20 20:28:05 +0000778@subsubsection Linux host
779
bellard9d4fb822004-04-26 20:55:38 +0000780As an example, you can download the @file{linux-test-xxx.tar.gz}
781archive and copy the script @file{qemu-ifup} in @file{/etc} and
782configure properly @code{sudo} so that the command @code{ifconfig}
783contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +0000784that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +0000785device @file{/dev/net/tun} must be present.
786
bellardee0f4752006-08-19 16:56:18 +0000787See @ref{sec_invocation} to have examples of command lines using the
788TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +0000789
bellard8f40c382006-09-20 20:28:05 +0000790@subsubsection Windows host
791
792There is a virtual ethernet driver for Windows 2000/XP systems, called
793TAP-Win32. But it is not included in standard QEMU for Windows,
794so you will need to get it separately. It is part of OpenVPN package,
795so download OpenVPN from : @url{http://openvpn.net/}.
796
bellard9d4fb822004-04-26 20:55:38 +0000797@subsection Using the user mode network stack
798
bellard41d03942005-11-15 23:02:53 +0000799By using the option @option{-net user} (default configuration if no
800@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +0000801network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +0000802network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +0000803
804@example
805
bellard41d03942005-11-15 23:02:53 +0000806 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
807 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +0000808 |
bellard2518bd02004-09-30 22:35:13 +0000809 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +0000810 |
bellard2518bd02004-09-30 22:35:13 +0000811 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +0000812@end example
813
814The QEMU VM behaves as if it was behind a firewall which blocks all
815incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +0000816configure the network in the QEMU VM. The DHCP server assign addresses
817to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +0000818
819In order to check that the user mode network is working, you can ping
820the address 10.0.2.2 and verify that you got an address in the range
82110.0.2.x from the QEMU virtual DHCP server.
822
bellardb415a402004-05-23 21:04:06 +0000823Note that @code{ping} is not supported reliably to the internet as it
ths4be456f2007-06-03 13:41:28 +0000824would require root privileges. It means you can only ping the local
bellardb415a402004-05-23 21:04:06 +0000825router (10.0.2.2).
826
bellard9bf05442004-08-25 22:12:49 +0000827When using the built-in TFTP server, the router is also the TFTP
828server.
829
830When using the @option{-redir} option, TCP or UDP connections can be
831redirected from the host to the guest. It allows for example to
832redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +0000833
bellard41d03942005-11-15 23:02:53 +0000834@subsection Connecting VLANs between QEMU instances
835
836Using the @option{-net socket} option, it is possible to make VLANs
837that span several QEMU instances. See @ref{sec_invocation} to have a
838basic example.
839
Stefan Weil576fd0a2011-01-07 18:59:14 +0100840@node pcsys_other_devs
Cam Macdonell6cbf4c82010-07-27 10:54:13 -0600841@section Other Devices
842
843@subsection Inter-VM Shared Memory device
844
845With KVM enabled on a Linux host, a shared memory device is available. Guests
846map a POSIX shared memory region into the guest as a PCI device that enables
847zero-copy communication to the application level of the guests. The basic
848syntax is:
849
850@example
851qemu -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
852@end example
853
854If desired, interrupts can be sent between guest VMs accessing the same shared
855memory region. Interrupt support requires using a shared memory server and
856using a chardev socket to connect to it. The code for the shared memory server
857is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
858memory server is:
859
860@example
861qemu -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
862 [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
863qemu -chardev socket,path=<path>,id=<id>
864@end example
865
866When using the server, the guest will be assigned a VM ID (>=0) that allows guests
867using the same server to communicate via interrupts. Guests can read their
868VM ID from a device register (see example code). Since receiving the shared
869memory region from the server is asynchronous, there is a (small) chance the
870guest may boot before the shared memory is attached. To allow an application
871to ensure shared memory is attached, the VM ID register will return -1 (an
872invalid VM ID) until the memory is attached. Once the shared memory is
873attached, the VM ID will return the guest's valid VM ID. With these semantics,
874the guest application can check to ensure the shared memory is attached to the
875guest before proceeding.
876
877The @option{role} argument can be set to either master or peer and will affect
878how the shared memory is migrated. With @option{role=master}, the guest will
879copy the shared memory on migration to the destination host. With
880@option{role=peer}, the guest will not be able to migrate with the device attached.
881With the @option{peer} case, the device should be detached and then reattached
882after migration using the PCI hotplug support.
883
bellard9d4fb822004-04-26 20:55:38 +0000884@node direct_linux_boot
885@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +0000886
887This section explains how to launch a Linux kernel inside QEMU without
888having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +0000889kernel testing.
bellard1eb20522003-06-25 16:21:49 +0000890
bellardee0f4752006-08-19 16:56:18 +0000891The syntax is:
bellard1eb20522003-06-25 16:21:49 +0000892@example
bellardee0f4752006-08-19 16:56:18 +0000893qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +0000894@end example
895
bellardee0f4752006-08-19 16:56:18 +0000896Use @option{-kernel} to provide the Linux kernel image and
897@option{-append} to give the kernel command line arguments. The
898@option{-initrd} option can be used to provide an INITRD image.
899
900When using the direct Linux boot, a disk image for the first hard disk
901@file{hda} is required because its boot sector is used to launch the
902Linux kernel.
903
904If you do not need graphical output, you can disable it and redirect
905the virtual serial port and the QEMU monitor to the console with the
906@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +0000907@example
bellardee0f4752006-08-19 16:56:18 +0000908qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
909 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +0000910@end example
911
bellardee0f4752006-08-19 16:56:18 +0000912Use @key{Ctrl-a c} to switch between the serial console and the
913monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +0000914
bellarddebc7062006-04-30 21:58:41 +0000915@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +0000916@section USB emulation
917
pbrook0aff66b2006-05-26 00:49:52 +0000918QEMU emulates a PCI UHCI USB controller. You can virtually plug
919virtual USB devices or real host USB devices (experimental, works only
920on Linux hosts). Qemu will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +0000921as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +0000922
pbrook0aff66b2006-05-26 00:49:52 +0000923@menu
924* usb_devices::
925* host_usb_devices::
926@end menu
927@node usb_devices
928@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +0000929
pbrook0aff66b2006-05-26 00:49:52 +0000930USB devices can be connected with the @option{-usbdevice} commandline option
931or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +0000932
balrogdb380c02008-01-17 22:22:45 +0000933@table @code
934@item mouse
pbrook0aff66b2006-05-26 00:49:52 +0000935Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +0000936@item tablet
bellardc6d46c22006-09-03 17:10:41 +0000937Pointer device that uses absolute coordinates (like a touchscreen).
pbrook0aff66b2006-05-26 00:49:52 +0000938This means qemu is able to report the mouse position without having
939to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +0000940@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +0000941Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +0000942@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +0000943Pass through the host device identified by @var{bus.addr}
944(Linux only)
balrogdb380c02008-01-17 22:22:45 +0000945@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +0000946Pass through the host device identified by @var{vendor_id:product_id}
947(Linux only)
balrogdb380c02008-01-17 22:22:45 +0000948@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +0000949Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
950above but it can be used with the tslib library because in addition to touch
951coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +0000952@item keyboard
balrog47b2d332007-06-22 08:16:00 +0000953Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +0000954@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
955Serial converter. This emulates an FTDI FT232BM chip connected to host character
956device @var{dev}. The available character devices are the same as for the
957@code{-serial} option. The @code{vendorid} and @code{productid} options can be
Stefan Weil0d6753e2011-01-07 18:59:13 +0100958used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +0000959@example
960usb_add serial:productid=FA00:tcp:192.168.0.2:4444
961@end example
962will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
963serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +0000964@item braille
965Braille device. This will use BrlAPI to display the braille output on a real
966or fake device.
balrog9ad97e62008-07-29 13:16:31 +0000967@item net:@var{options}
968Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
969specifies NIC options as with @code{-net nic,}@var{options} (see description).
970For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +0000971@example
balrog9ad97e62008-07-29 13:16:31 +0000972qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +0000973@end example
974Currently this cannot be used in machines that support PCI NICs.
balrog2d564692008-11-09 02:24:54 +0000975@item bt[:@var{hci-type}]
976Bluetooth dongle whose type is specified in the same format as with
977the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
978no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
979This USB device implements the USB Transport Layer of HCI. Example
980usage:
981@example
982qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
983@end example
pbrook0aff66b2006-05-26 00:49:52 +0000984@end table
bellardb389dbf2005-11-06 16:49:55 +0000985
pbrook0aff66b2006-05-26 00:49:52 +0000986@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +0000987@subsection Using host USB devices on a Linux host
988
989WARNING: this is an experimental feature. QEMU will slow down when
990using it. USB devices requiring real time streaming (i.e. USB Video
991Cameras) are not supported yet.
992
993@enumerate
ths5fafdf22007-09-16 21:08:06 +0000994@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +0000995is actually using the USB device. A simple way to do that is simply to
996disable the corresponding kernel module by renaming it from @file{mydriver.o}
997to @file{mydriver.o.disabled}.
998
999@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1000@example
1001ls /proc/bus/usb
1002001 devices drivers
1003@end example
1004
1005@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:
1006@example
1007chown -R myuid /proc/bus/usb
1008@end example
1009
1010@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001011@example
bellardb389dbf2005-11-06 16:49:55 +00001012info usbhost
1013 Device 1.2, speed 480 Mb/s
1014 Class 00: USB device 1234:5678, USB DISK
1015@end example
1016You should see the list of the devices you can use (Never try to use
1017hubs, it won't work).
1018
1019@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001020@example
bellardb389dbf2005-11-06 16:49:55 +00001021usb_add host:1234:5678
1022@end example
1023
1024Normally the guest OS should report that a new USB device is
1025plugged. You can use the option @option{-usbdevice} to do the same.
1026
1027@item Now you can try to use the host USB device in QEMU.
1028
1029@end enumerate
1030
1031When relaunching QEMU, you may have to unplug and plug again the USB
1032device to make it work again (this is a bug).
1033
thsf858dca2007-08-25 01:40:37 +00001034@node vnc_security
1035@section VNC security
1036
1037The VNC server capability provides access to the graphical console
1038of the guest VM across the network. This has a number of security
1039considerations depending on the deployment scenarios.
1040
1041@menu
1042* vnc_sec_none::
1043* vnc_sec_password::
1044* vnc_sec_certificate::
1045* vnc_sec_certificate_verify::
1046* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +00001047* vnc_sec_sasl::
1048* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +00001049* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +00001050* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +00001051@end menu
1052@node vnc_sec_none
1053@subsection Without passwords
1054
1055The simplest VNC server setup does not include any form of authentication.
1056For this setup it is recommended to restrict it to listen on a UNIX domain
1057socket only. For example
1058
1059@example
1060qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1061@end example
1062
1063This ensures that only users on local box with read/write access to that
1064path can access the VNC server. To securely access the VNC server from a
1065remote machine, a combination of netcat+ssh can be used to provide a secure
1066tunnel.
1067
1068@node vnc_sec_password
1069@subsection With passwords
1070
1071The VNC protocol has limited support for password based authentication. Since
1072the protocol limits passwords to 8 characters it should not be considered
1073to provide high security. The password can be fairly easily brute-forced by
1074a client making repeat connections. For this reason, a VNC server using password
1075authentication should be restricted to only listen on the loopback interface
blueswir134a3d232008-10-04 20:43:39 +00001076or UNIX domain sockets. Password authentication is requested with the @code{password}
thsf858dca2007-08-25 01:40:37 +00001077option, and then once QEMU is running the password is set with the monitor. Until
1078the monitor is used to set the password all clients will be rejected.
1079
1080@example
1081qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1082(qemu) change vnc password
1083Password: ********
1084(qemu)
1085@end example
1086
1087@node vnc_sec_certificate
1088@subsection With x509 certificates
1089
1090The QEMU VNC server also implements the VeNCrypt extension allowing use of
1091TLS for encryption of the session, and x509 certificates for authentication.
1092The use of x509 certificates is strongly recommended, because TLS on its
1093own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1094support provides a secure session, but no authentication. This allows any
1095client to connect, and provides an encrypted session.
1096
1097@example
1098qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1099@end example
1100
1101In the above example @code{/etc/pki/qemu} should contain at least three files,
1102@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1103users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1104NB the @code{server-key.pem} file should be protected with file mode 0600 to
1105only be readable by the user owning it.
1106
1107@node vnc_sec_certificate_verify
1108@subsection With x509 certificates and client verification
1109
1110Certificates can also provide a means to authenticate the client connecting.
1111The server will request that the client provide a certificate, which it will
1112then validate against the CA certificate. This is a good choice if deploying
1113in an environment with a private internal certificate authority.
1114
1115@example
1116qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1117@end example
1118
1119
1120@node vnc_sec_certificate_pw
1121@subsection With x509 certificates, client verification and passwords
1122
1123Finally, the previous method can be combined with VNC password authentication
1124to provide two layers of authentication for clients.
1125
1126@example
1127qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1128(qemu) change vnc password
1129Password: ********
1130(qemu)
1131@end example
1132
aliguori2f9606b2009-03-06 20:27:28 +00001133
1134@node vnc_sec_sasl
1135@subsection With SASL authentication
1136
1137The SASL authentication method is a VNC extension, that provides an
1138easily extendable, pluggable authentication method. This allows for
1139integration with a wide range of authentication mechanisms, such as
1140PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1141The strength of the authentication depends on the exact mechanism
1142configured. If the chosen mechanism also provides a SSF layer, then
1143it will encrypt the datastream as well.
1144
1145Refer to the later docs on how to choose the exact SASL mechanism
1146used for authentication, but assuming use of one supporting SSF,
1147then QEMU can be launched with:
1148
1149@example
1150qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
1151@end example
1152
1153@node vnc_sec_certificate_sasl
1154@subsection With x509 certificates and SASL authentication
1155
1156If the desired SASL authentication mechanism does not supported
1157SSF layers, then it is strongly advised to run it in combination
1158with TLS and x509 certificates. This provides securely encrypted
1159data stream, avoiding risk of compromising of the security
1160credentials. This can be enabled, by combining the 'sasl' option
1161with the aforementioned TLS + x509 options:
1162
1163@example
1164qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1165@end example
1166
1167
thsf858dca2007-08-25 01:40:37 +00001168@node vnc_generate_cert
1169@subsection Generating certificates for VNC
1170
1171The GNU TLS packages provides a command called @code{certtool} which can
1172be used to generate certificates and keys in PEM format. At a minimum it
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001173is necessary to setup a certificate authority, and issue certificates to
thsf858dca2007-08-25 01:40:37 +00001174each server. If using certificates for authentication, then each client
1175will also need to be issued a certificate. The recommendation is for the
1176server to keep its certificates in either @code{/etc/pki/qemu} or for
1177unprivileged users in @code{$HOME/.pki/qemu}.
1178
1179@menu
1180* vnc_generate_ca::
1181* vnc_generate_server::
1182* vnc_generate_client::
1183@end menu
1184@node vnc_generate_ca
1185@subsubsection Setup the Certificate Authority
1186
1187This step only needs to be performed once per organization / organizational
1188unit. First the CA needs a private key. This key must be kept VERY secret
1189and secure. If this key is compromised the entire trust chain of the certificates
1190issued with it is lost.
1191
1192@example
1193# certtool --generate-privkey > ca-key.pem
1194@end example
1195
1196A CA needs to have a public certificate. For simplicity it can be a self-signed
1197certificate, or one issue by a commercial certificate issuing authority. To
1198generate a self-signed certificate requires one core piece of information, the
1199name of the organization.
1200
1201@example
1202# cat > ca.info <<EOF
1203cn = Name of your organization
1204ca
1205cert_signing_key
1206EOF
1207# certtool --generate-self-signed \
1208 --load-privkey ca-key.pem
1209 --template ca.info \
1210 --outfile ca-cert.pem
1211@end example
1212
1213The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1214TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1215
1216@node vnc_generate_server
1217@subsubsection Issuing server certificates
1218
1219Each server (or host) needs to be issued with a key and certificate. When connecting
1220the certificate is sent to the client which validates it against the CA certificate.
1221The core piece of information for a server certificate is the hostname. This should
1222be the fully qualified hostname that the client will connect with, since the client
1223will typically also verify the hostname in the certificate. On the host holding the
1224secure CA private key:
1225
1226@example
1227# cat > server.info <<EOF
1228organization = Name of your organization
1229cn = server.foo.example.com
1230tls_www_server
1231encryption_key
1232signing_key
1233EOF
1234# certtool --generate-privkey > server-key.pem
1235# certtool --generate-certificate \
1236 --load-ca-certificate ca-cert.pem \
1237 --load-ca-privkey ca-key.pem \
1238 --load-privkey server server-key.pem \
1239 --template server.info \
1240 --outfile server-cert.pem
1241@end example
1242
1243The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1244to the server for which they were generated. The @code{server-key.pem} is security
1245sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1246
1247@node vnc_generate_client
1248@subsubsection Issuing client certificates
1249
1250If the QEMU VNC server is to use the @code{x509verify} option to validate client
1251certificates as its authentication mechanism, each client also needs to be issued
1252a certificate. The client certificate contains enough metadata to uniquely identify
1253the client, typically organization, state, city, building, etc. On the host holding
1254the secure CA private key:
1255
1256@example
1257# cat > client.info <<EOF
1258country = GB
1259state = London
1260locality = London
1261organiazation = Name of your organization
1262cn = client.foo.example.com
1263tls_www_client
1264encryption_key
1265signing_key
1266EOF
1267# certtool --generate-privkey > client-key.pem
1268# certtool --generate-certificate \
1269 --load-ca-certificate ca-cert.pem \
1270 --load-ca-privkey ca-key.pem \
1271 --load-privkey client-key.pem \
1272 --template client.info \
1273 --outfile client-cert.pem
1274@end example
1275
1276The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1277copied to the client for which they were generated.
1278
aliguori2f9606b2009-03-06 20:27:28 +00001279
1280@node vnc_setup_sasl
1281
1282@subsection Configuring SASL mechanisms
1283
1284The following documentation assumes use of the Cyrus SASL implementation on a
1285Linux host, but the principals should apply to any other SASL impl. When SASL
1286is enabled, the mechanism configuration will be loaded from system default
1287SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1288unprivileged user, an environment variable SASL_CONF_PATH can be used
1289to make it search alternate locations for the service config.
1290
1291The default configuration might contain
1292
1293@example
1294mech_list: digest-md5
1295sasldb_path: /etc/qemu/passwd.db
1296@end example
1297
1298This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1299Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1300in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1301command. While this mechanism is easy to configure and use, it is not
1302considered secure by modern standards, so only suitable for developers /
1303ad-hoc testing.
1304
1305A more serious deployment might use Kerberos, which is done with the 'gssapi'
1306mechanism
1307
1308@example
1309mech_list: gssapi
1310keytab: /etc/qemu/krb5.tab
1311@end example
1312
1313For this to work the administrator of your KDC must generate a Kerberos
1314principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
1315replacing 'somehost.example.com' with the fully qualified host name of the
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001316machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
aliguori2f9606b2009-03-06 20:27:28 +00001317
1318Other configurations will be left as an exercise for the reader. It should
1319be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1320encryption. For all other mechanisms, VNC should always be configured to
1321use TLS and x509 certificates to protect security credentials from snooping.
1322
bellard0806e3f2003-10-01 00:15:32 +00001323@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001324@section GDB usage
1325
1326QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001327'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001328
bellard9d4520d2003-10-28 01:38:57 +00001329In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001330gdb connection:
1331@example
bellarddebc7062006-04-30 21:58:41 +00001332> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1333 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001334Connected to host network interface: tun0
1335Waiting gdb connection on port 1234
1336@end example
1337
1338Then launch gdb on the 'vmlinux' executable:
1339@example
1340> gdb vmlinux
1341@end example
1342
1343In gdb, connect to QEMU:
1344@example
bellard6c9bf892004-01-24 13:46:56 +00001345(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001346@end example
1347
1348Then you can use gdb normally. For example, type 'c' to launch the kernel:
1349@example
1350(gdb) c
1351@end example
1352
bellard0806e3f2003-10-01 00:15:32 +00001353Here are some useful tips in order to use gdb on system code:
1354
1355@enumerate
1356@item
1357Use @code{info reg} to display all the CPU registers.
1358@item
1359Use @code{x/10i $eip} to display the code at the PC position.
1360@item
1361Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001362@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001363@end enumerate
1364
edgar_igl60897d32008-05-09 08:25:14 +00001365Advanced debugging options:
1366
1367The 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 +00001368@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001369@item maintenance packet qqemu.sstepbits
1370
1371This will display the MASK bits used to control the single stepping IE:
1372@example
1373(gdb) maintenance packet qqemu.sstepbits
1374sending: "qqemu.sstepbits"
1375received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1376@end example
1377@item maintenance packet qqemu.sstep
1378
1379This will display the current value of the mask used when single stepping IE:
1380@example
1381(gdb) maintenance packet qqemu.sstep
1382sending: "qqemu.sstep"
1383received: "0x7"
1384@end example
1385@item maintenance packet Qqemu.sstep=HEX_VALUE
1386
1387This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1388@example
1389(gdb) maintenance packet Qqemu.sstep=0x5
1390sending: "qemu.sstep=0x5"
1391received: "OK"
1392@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001393@end table
edgar_igl60897d32008-05-09 08:25:14 +00001394
bellarddebc7062006-04-30 21:58:41 +00001395@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001396@section Target OS specific information
1397
1398@subsection Linux
1399
bellard15a34c62004-07-08 21:26:26 +00001400To have access to SVGA graphic modes under X11, use the @code{vesa} or
1401the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1402color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001403
bellarde3371e62004-07-10 16:26:02 +00001404When using a 2.6 guest Linux kernel, you should add the option
1405@code{clock=pit} on the kernel command line because the 2.6 Linux
1406kernels make very strict real time clock checks by default that QEMU
1407cannot simulate exactly.
1408
bellard7c3fc842005-02-10 21:46:47 +00001409When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1410not activated because QEMU is slower with this patch. The QEMU
1411Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001412Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001413patch by default. Newer kernels don't have it.
1414
bellard1a084f32004-05-13 22:34:49 +00001415@subsection Windows
1416
1417If you have a slow host, using Windows 95 is better as it gives the
1418best speed. Windows 2000 is also a good choice.
1419
bellarde3371e62004-07-10 16:26:02 +00001420@subsubsection SVGA graphic modes support
1421
1422QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001423card. All Windows versions starting from Windows 95 should recognize
1424and use this graphic card. For optimal performances, use 16 bit color
1425depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001426
bellard3cb08532006-06-21 21:19:50 +00001427If you are using Windows XP as guest OS and if you want to use high
1428resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
14291280x1024x16), then you should use the VESA VBE virtual graphic card
1430(option @option{-std-vga}).
1431
bellarde3371e62004-07-10 16:26:02 +00001432@subsubsection CPU usage reduction
1433
1434Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001435instruction. The result is that it takes host CPU cycles even when
1436idle. You can install the utility from
1437@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1438problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001439
bellard9d0a8e62005-07-03 17:34:05 +00001440@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001441
bellard9d0a8e62005-07-03 17:34:05 +00001442Windows 2000 has a bug which gives a disk full problem during its
1443installation. When installing it, use the @option{-win2k-hack} QEMU
1444option to enable a specific workaround. After Windows 2000 is
1445installed, you no longer need this option (this option slows down the
1446IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001447
bellard6cc721c2005-07-28 22:27:28 +00001448@subsubsection Windows 2000 shutdown
1449
1450Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1451can. It comes from the fact that Windows 2000 does not automatically
1452use the APM driver provided by the BIOS.
1453
1454In order to correct that, do the following (thanks to Struan
1455Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1456Add/Troubleshoot a device => Add a new device & Next => No, select the
1457hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1458(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001459correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001460
1461@subsubsection Share a directory between Unix and Windows
1462
1463See @ref{sec_invocation} about the help of the option @option{-smb}.
1464
bellard2192c332006-08-21 20:28:18 +00001465@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001466
1467Some releases of Windows XP install correctly but give a security
1468error when booting:
1469@example
1470A problem is preventing Windows from accurately checking the
1471license for this computer. Error code: 0x800703e6.
1472@end example
bellarde3371e62004-07-10 16:26:02 +00001473
bellard2192c332006-08-21 20:28:18 +00001474The workaround is to install a service pack for XP after a boot in safe
1475mode. Then reboot, and the problem should go away. Since there is no
1476network while in safe mode, its recommended to download the full
1477installation of SP1 or SP2 and transfer that via an ISO or using the
1478vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001479
bellarda0a821a2004-07-14 17:38:57 +00001480@subsection MS-DOS and FreeDOS
1481
1482@subsubsection CPU usage reduction
1483
1484DOS does not correctly use the CPU HLT instruction. The result is that
1485it takes host CPU cycles even when idle. You can install the utility
1486from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1487problem.
1488
bellarddebc7062006-04-30 21:58:41 +00001489@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001490@chapter QEMU System emulator for non PC targets
1491
1492QEMU is a generic emulator and it emulates many non PC
1493machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001494differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001495
bellarddebc7062006-04-30 21:58:41 +00001496@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001497* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001498* Sparc32 System emulator::
1499* Sparc64 System emulator::
1500* MIPS System emulator::
1501* ARM System emulator::
1502* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001503* Cris System emulator::
1504* Microblaze System emulator::
1505* SH4 System emulator::
Max Filippov3aeaea62011-10-10 14:48:23 +04001506* Xtensa System emulator::
bellarddebc7062006-04-30 21:58:41 +00001507@end menu
1508
Stefan Weil7544a042010-02-05 23:52:03 +01001509@node PowerPC System emulator
1510@section PowerPC System emulator
1511@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001512
1513Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001514or PowerMac PowerPC system.
1515
bellardb671f9e2005-04-30 15:08:33 +00001516QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001517
1518@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001519@item
blueswir1006f3a42009-02-08 15:59:36 +00001520UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001521@item
1522PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001523@item
bellard15a34c62004-07-08 21:26:26 +000015242 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001525@item
bellard15a34c62004-07-08 21:26:26 +00001526NE2000 PCI adapters
1527@item
1528Non Volatile RAM
1529@item
1530VIA-CUDA with ADB keyboard and mouse.
1531@end itemize
bellard52c00a52004-04-25 21:27:03 +00001532
bellardb671f9e2005-04-30 15:08:33 +00001533QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001534
1535@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001536@item
bellard15a34c62004-07-08 21:26:26 +00001537PCI Bridge
1538@item
1539PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001540@item
bellard52c00a52004-04-25 21:27:03 +000015412 IDE interfaces with hard disk and CD-ROM support
1542@item
1543Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001544@item
bellard15a34c62004-07-08 21:26:26 +00001545NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001546@item
1547Serial port
1548@item
1549PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001550@item
1551PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001552@end itemize
1553
bellard15a34c62004-07-08 21:26:26 +00001554QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001555@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001556
blueswir1992e5ac2008-12-24 20:23:51 +00001557Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00001558for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1559v2) portable firmware implementation. The goal is to implement a 100%
1560IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00001561
bellard15a34c62004-07-08 21:26:26 +00001562@c man begin OPTIONS
1563
1564The following options are specific to the PowerPC emulation:
1565
1566@table @option
1567
Kevin Wolf4e257e52009-10-09 10:58:36 +02001568@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00001569
1570Set the initial VGA graphic mode. The default is 800x600x15.
1571
Kevin Wolf4e257e52009-10-09 10:58:36 +02001572@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00001573
1574Set OpenBIOS variables in NVRAM, for example:
1575
1576@example
1577qemu-system-ppc -prom-env 'auto-boot?=false' \
1578 -prom-env 'boot-device=hd:2,\yaboot' \
1579 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1580@end example
1581
1582These variables are not used by Open Hack'Ware.
1583
bellard15a34c62004-07-08 21:26:26 +00001584@end table
1585
ths5fafdf22007-09-16 21:08:06 +00001586@c man end
bellard15a34c62004-07-08 21:26:26 +00001587
1588
bellard52c00a52004-04-25 21:27:03 +00001589More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00001590@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00001591
ths24d4de42007-07-11 10:24:28 +00001592@node Sparc32 System emulator
1593@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001594@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00001595
blueswir134a3d232008-10-04 20:43:39 +00001596Use the executable @file{qemu-system-sparc} to simulate the following
1597Sun4m architecture machines:
1598@itemize @minus
1599@item
1600SPARCstation 4
1601@item
1602SPARCstation 5
1603@item
1604SPARCstation 10
1605@item
1606SPARCstation 20
1607@item
1608SPARCserver 600MP
1609@item
1610SPARCstation LX
1611@item
1612SPARCstation Voyager
1613@item
1614SPARCclassic
1615@item
1616SPARCbook
1617@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00001618
blueswir134a3d232008-10-04 20:43:39 +00001619The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1620but Linux limits the number of usable CPUs to 4.
1621
1622It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1623SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1624emulators are not usable yet.
1625
1626QEMU emulates the following sun4m/sun4c/sun4d peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00001627
1628@itemize @minus
bellard34751872005-07-02 14:31:34 +00001629@item
blueswir17d858922007-12-28 20:57:43 +00001630IOMMU or IO-UNITs
bellarde80cfcf2004-12-19 23:18:01 +00001631@item
1632TCX Frame buffer
ths5fafdf22007-09-16 21:08:06 +00001633@item
bellarde80cfcf2004-12-19 23:18:01 +00001634Lance (Am7990) Ethernet
1635@item
blueswir134a3d232008-10-04 20:43:39 +00001636Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00001637@item
bellard34751872005-07-02 14:31:34 +00001638Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1639and power/reset logic
1640@item
1641ESP SCSI controller with hard disk and CD-ROM support
1642@item
blueswir16a3b9cc2007-11-11 17:56:38 +00001643Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00001644@item
1645CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00001646@end itemize
1647
blueswir16a3b9cc2007-11-11 17:56:38 +00001648The number of peripherals is fixed in the architecture. Maximum
1649memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00001650others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00001651
bellard30a604f2006-06-14 18:35:18 +00001652Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00001653@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1654firmware implementation. The goal is to implement a 100% IEEE
16551275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00001656
1657A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00001658the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1659some kernel versions work. Please note that currently Solaris kernels
1660don't work probably due to interface issues between OpenBIOS and
1661Solaris.
bellard34751872005-07-02 14:31:34 +00001662
1663@c man begin OPTIONS
1664
blueswir1a2502b52007-06-10 17:01:00 +00001665The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00001666
1667@table @option
1668
Kevin Wolf4e257e52009-10-09 10:58:36 +02001669@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00001670
blueswir1a2502b52007-06-10 17:01:00 +00001671Set the initial TCX graphic mode. The default is 1024x768x8, currently
1672the only other possible mode is 1024x768x24.
bellard34751872005-07-02 14:31:34 +00001673
Kevin Wolf4e257e52009-10-09 10:58:36 +02001674@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00001675
1676Set OpenBIOS variables in NVRAM, for example:
1677
1678@example
1679qemu-system-sparc -prom-env 'auto-boot?=false' \
1680 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1681@end example
1682
Blue Swirl609c1da2010-03-18 18:41:49 +00001683@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 +00001684
1685Set the emulated machine type. Default is SS-5.
1686
bellard34751872005-07-02 14:31:34 +00001687@end table
1688
ths5fafdf22007-09-16 21:08:06 +00001689@c man end
bellard34751872005-07-02 14:31:34 +00001690
ths24d4de42007-07-11 10:24:28 +00001691@node Sparc64 System emulator
1692@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001693@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00001694
blueswir134a3d232008-10-04 20:43:39 +00001695Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1696(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1697Niagara (T1) machine. The emulator is not usable for anything yet, but
1698it can launch some kernels.
bellardb7569212005-03-13 09:43:05 +00001699
blueswir1c7ba2182008-07-22 07:07:34 +00001700QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00001701
1702@itemize @minus
1703@item
ths5fafdf22007-09-16 21:08:06 +00001704UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00001705@item
1706PCI VGA compatible card with VESA Bochs Extensions
1707@item
blueswir134a3d232008-10-04 20:43:39 +00001708PS/2 mouse and keyboard
1709@item
bellard83469012005-07-23 14:27:54 +00001710Non Volatile RAM M48T59
1711@item
1712PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00001713@item
17142 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00001715@item
1716Floppy disk
bellard83469012005-07-23 14:27:54 +00001717@end itemize
1718
blueswir1c7ba2182008-07-22 07:07:34 +00001719@c man begin OPTIONS
1720
1721The following options are specific to the Sparc64 emulation:
1722
1723@table @option
1724
Kevin Wolf4e257e52009-10-09 10:58:36 +02001725@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00001726
1727Set OpenBIOS variables in NVRAM, for example:
1728
1729@example
1730qemu-system-sparc64 -prom-env 'auto-boot?=false'
1731@end example
1732
1733@item -M [sun4u|sun4v|Niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00001734
1735Set the emulated machine type. The default is sun4u.
1736
1737@end table
1738
1739@c man end
1740
ths24d4de42007-07-11 10:24:28 +00001741@node MIPS System emulator
1742@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001743@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00001744
thsd9aedc32007-12-17 03:47:55 +00001745Four executables cover simulation of 32 and 64-bit MIPS systems in
1746both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1747@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00001748Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00001749
1750@itemize @minus
1751@item
1752A generic ISA PC-like machine "mips"
1753@item
1754The MIPS Malta prototype board "malta"
1755@item
thsd9aedc32007-12-17 03:47:55 +00001756An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00001757@item
thsf0fc6f82007-10-17 13:39:42 +00001758MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00001759@item
1760A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00001761@end itemize
1762
1763The generic emulation is supported by Debian 'Etch' and is able to
1764install Debian into a virtual disk image. The following devices are
1765emulated:
bellard9d0a8e62005-07-03 17:34:05 +00001766
bellard3f9f3aa2005-12-18 20:11:37 +00001767@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001768@item
ths6bf5b4e2007-10-17 13:08:32 +00001769A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00001770@item
1771PC style serial port
1772@item
ths24d4de42007-07-11 10:24:28 +00001773PC style IDE disk
1774@item
bellard3f9f3aa2005-12-18 20:11:37 +00001775NE2000 network card
1776@end itemize
1777
ths24d4de42007-07-11 10:24:28 +00001778The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00001779
ths24d4de42007-07-11 10:24:28 +00001780@itemize @minus
1781@item
ths0b64d002007-07-11 21:43:14 +00001782Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00001783@item
1784PIIX4 PCI/USB/SMbus controller
1785@item
1786The Multi-I/O chip's serial device
1787@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02001788PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00001789@item
1790Malta FPGA serial device
1791@item
aurel321f605a72009-02-08 14:51:19 +00001792Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00001793@end itemize
1794
1795The ACER Pica emulation supports:
1796
1797@itemize @minus
1798@item
1799MIPS R4000 CPU
1800@item
1801PC-style IRQ and DMA controllers
1802@item
1803PC Keyboard
1804@item
1805IDE controller
1806@end itemize
1807
Stefan Weilb5e49462011-11-13 22:24:26 +01001808The mipssim pseudo board emulation provides an environment similar
thsf0fc6f82007-10-17 13:39:42 +00001809to what the proprietary MIPS emulator uses for running Linux.
1810It supports:
ths6bf5b4e2007-10-17 13:08:32 +00001811
1812@itemize @minus
1813@item
1814A range of MIPS CPUs, default is the 24Kf
1815@item
1816PC style serial port
1817@item
1818MIPSnet network emulation
1819@end itemize
1820
aurel3288cb0a02008-04-08 05:57:37 +00001821The MIPS Magnum R4000 emulation supports:
1822
1823@itemize @minus
1824@item
1825MIPS R4000 CPU
1826@item
1827PC-style IRQ controller
1828@item
1829PC Keyboard
1830@item
1831SCSI controller
1832@item
1833G364 framebuffer
1834@end itemize
1835
1836
ths24d4de42007-07-11 10:24:28 +00001837@node ARM System emulator
1838@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001839@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00001840
1841Use the executable @file{qemu-system-arm} to simulate a ARM
1842machine. The ARM Integrator/CP board is emulated with the following
1843devices:
1844
1845@itemize @minus
1846@item
pbrook9ee6e8b2007-11-11 00:04:49 +00001847ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00001848@item
1849Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001850@item
bellard3f9f3aa2005-12-18 20:11:37 +00001851SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00001852@item
1853PL110 LCD controller
1854@item
1855PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00001856@item
1857PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00001858@end itemize
1859
1860The ARM Versatile baseboard is emulated with the following devices:
1861
1862@itemize @minus
1863@item
pbrook9ee6e8b2007-11-11 00:04:49 +00001864ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00001865@item
1866PL190 Vectored Interrupt Controller
1867@item
1868Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001869@item
pbrook00a9bf12006-05-13 16:55:46 +00001870SMC 91c111 Ethernet adapter
1871@item
1872PL110 LCD controller
1873@item
1874PL050 KMI with PS/2 keyboard and mouse.
1875@item
1876PCI host bridge. Note the emulated PCI bridge only provides access to
1877PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00001878This means some devices (eg. ne2k_pci NIC) are not usable, and others
1879(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00001880mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00001881@item
1882PCI OHCI USB controller.
1883@item
1884LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00001885@item
1886PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00001887@end itemize
1888
Paul Brook21a88942009-12-21 20:19:12 +00001889Several variants of the ARM RealView baseboard are emulated,
1890including the EB, PB-A8 and PBX-A9. Due to interactions with the
1891bootloader, only certain Linux kernel configurations work out
1892of the box on these boards.
1893
1894Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1895enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
1896should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1897disabled and expect 1024M RAM.
1898
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001899The following devices are emulated:
pbrookd7739d72007-02-28 16:25:17 +00001900
1901@itemize @minus
1902@item
Paul Brookf7c70322009-11-19 16:45:21 +00001903ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00001904@item
1905ARM AMBA Generic/Distributed Interrupt Controller
1906@item
1907Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00001908@item
Paul Brook0ef849d2009-11-16 17:06:43 +00001909SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00001910@item
1911PL110 LCD controller
1912@item
1913PL050 KMI with PS/2 keyboard and mouse
1914@item
1915PCI host bridge
1916@item
1917PCI OHCI USB controller
1918@item
1919LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00001920@item
1921PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00001922@end itemize
1923
balrogb00052e2007-04-30 02:22:06 +00001924The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1925and "Terrier") emulation includes the following peripherals:
1926
1927@itemize @minus
1928@item
1929Intel PXA270 System-on-chip (ARM V5TE core)
1930@item
1931NAND Flash memory
1932@item
1933IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1934@item
1935On-chip OHCI USB controller
1936@item
1937On-chip LCD controller
1938@item
1939On-chip Real Time Clock
1940@item
1941TI ADS7846 touchscreen controller on SSP bus
1942@item
1943Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1944@item
1945GPIO-connected keyboard controller and LEDs
1946@item
balrog549444e2007-05-01 17:53:37 +00001947Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00001948@item
1949Three on-chip UARTs
1950@item
1951WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1952@end itemize
1953
balrog02645922007-11-03 12:50:46 +00001954The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1955following elements:
1956
1957@itemize @minus
1958@item
1959Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1960@item
1961ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1962@item
1963On-chip LCD controller
1964@item
1965On-chip Real Time Clock
1966@item
1967TI TSC2102i touchscreen controller / analog-digital converter / Audio
1968CODEC, connected through MicroWire and I@math{^2}S busses
1969@item
1970GPIO-connected matrix keypad
1971@item
1972Secure Digital card connected to OMAP MMC/SD host
1973@item
1974Three on-chip UARTs
1975@end itemize
1976
balrogc30bb262008-05-18 13:01:40 +00001977Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1978emulation supports the following elements:
1979
1980@itemize @minus
1981@item
1982Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1983@item
1984RAM and non-volatile OneNAND Flash memories
1985@item
1986Display connected to EPSON remote framebuffer chip and OMAP on-chip
1987display controller and a LS041y3 MIPI DBI-C controller
1988@item
1989TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1990driven through SPI bus
1991@item
1992National Semiconductor LM8323-controlled qwerty keyboard driven
1993through I@math{^2}C bus
1994@item
1995Secure Digital card connected to OMAP MMC/SD host
1996@item
1997Three OMAP on-chip UARTs and on-chip STI debugging console
1998@item
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001999A Bluetooth(R) transceiver and HCI connected to an UART
balrog2d564692008-11-09 02:24:54 +00002000@item
balrogc30bb262008-05-18 13:01:40 +00002001Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2002TUSB6010 chip - only USB host mode is supported
2003@item
2004TI TMP105 temperature sensor driven through I@math{^2}C bus
2005@item
2006TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2007@item
2008Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2009through CBUS
2010@end itemize
2011
pbrook9ee6e8b2007-11-11 00:04:49 +00002012The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2013devices:
2014
2015@itemize @minus
2016@item
2017Cortex-M3 CPU core.
2018@item
201964k Flash and 8k SRAM.
2020@item
2021Timers, UARTs, ADC and I@math{^2}C interface.
2022@item
2023OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2024@end itemize
2025
2026The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2027devices:
2028
2029@itemize @minus
2030@item
2031Cortex-M3 CPU core.
2032@item
2033256k Flash and 64k SRAM.
2034@item
2035Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2036@item
2037OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2038@end itemize
2039
balrog57cd6e92008-05-07 12:23:32 +00002040The Freecom MusicPal internet radio emulation includes the following
2041elements:
2042
2043@itemize @minus
2044@item
2045Marvell MV88W8618 ARM core.
2046@item
204732 MB RAM, 256 KB SRAM, 8 MB flash.
2048@item
2049Up to 2 16550 UARTs
2050@item
2051MV88W8xx8 Ethernet controller
2052@item
2053MV88W8618 audio controller, WM8750 CODEC and mixer
2054@item
Stefan Weile080e782010-02-05 23:52:00 +01002055128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00002056@item
20572 buttons, 2 navigation wheels with button function
2058@end itemize
2059
balrog997641a2008-12-15 02:05:00 +00002060The Siemens SX1 models v1 and v2 (default) basic emulation.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002061The emulation includes the following elements:
balrog997641a2008-12-15 02:05:00 +00002062
2063@itemize @minus
2064@item
2065Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2066@item
2067ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2068V1
20691 Flash of 16MB and 1 Flash of 8MB
2070V2
20711 Flash of 32MB
2072@item
2073On-chip LCD controller
2074@item
2075On-chip Real Time Clock
2076@item
2077Secure Digital card connected to OMAP MMC/SD host
2078@item
2079Three on-chip UARTs
2080@end itemize
2081
Paul Brook4af39612009-05-14 23:11:09 +01002082The "Syborg" Symbian Virtual Platform base model includes the following
2083elements:
2084
2085@itemize @minus
2086@item
2087ARM Cortex-A8 CPU
2088@item
2089Interrupt controller
2090@item
2091Timer
2092@item
2093Real Time Clock
2094@item
2095Keyboard
2096@item
2097Framebuffer
2098@item
2099Touchscreen
2100@item
2101UARTs
2102@end itemize
2103
bellard3f9f3aa2005-12-18 20:11:37 +00002104A Linux 2.6 test image is available on the QEMU web site. More
2105information is available in the QEMU mailing-list archive.
2106
blueswir1d2c639d2009-01-24 18:19:25 +00002107@c man begin OPTIONS
2108
2109The following options are specific to the ARM emulation:
2110
2111@table @option
2112
2113@item -semihosting
2114Enable semihosting syscall emulation.
2115
2116On ARM this implements the "Angel" interface.
2117
2118Note that this allows guest direct access to the host filesystem,
2119so should only be used with trusted guest OS.
2120
2121@end table
2122
ths24d4de42007-07-11 10:24:28 +00002123@node ColdFire System emulator
2124@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002125@cindex system emulation (ColdFire)
2126@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002127
2128Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2129The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002130
2131The M5208EVB emulation includes the following devices:
2132
2133@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002134@item
pbrook707e0112007-06-04 00:50:06 +00002135MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2136@item
2137Three Two on-chip UARTs.
2138@item
2139Fast Ethernet Controller (FEC)
2140@end itemize
2141
2142The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002143
2144@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002145@item
pbrook209a4e62007-05-23 20:16:15 +00002146MCF5206 ColdFire V2 Microprocessor.
2147@item
2148Two on-chip UARTs.
2149@end itemize
2150
blueswir1d2c639d2009-01-24 18:19:25 +00002151@c man begin OPTIONS
2152
Stefan Weil7544a042010-02-05 23:52:03 +01002153The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002154
2155@table @option
2156
2157@item -semihosting
2158Enable semihosting syscall emulation.
2159
2160On M68K this implements the "ColdFire GDB" interface used by libgloss.
2161
2162Note that this allows guest direct access to the host filesystem,
2163so should only be used with trusted guest OS.
2164
2165@end table
2166
Stefan Weil7544a042010-02-05 23:52:03 +01002167@node Cris System emulator
2168@section Cris System emulator
2169@cindex system emulation (Cris)
2170
2171TODO
2172
2173@node Microblaze System emulator
2174@section Microblaze System emulator
2175@cindex system emulation (Microblaze)
2176
2177TODO
2178
2179@node SH4 System emulator
2180@section SH4 System emulator
2181@cindex system emulation (SH4)
2182
2183TODO
2184
Max Filippov3aeaea62011-10-10 14:48:23 +04002185@node Xtensa System emulator
2186@section Xtensa System emulator
2187@cindex system emulation (Xtensa)
2188
2189Two executables cover simulation of both Xtensa endian options,
2190@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2191Two different machine types are emulated:
2192
2193@itemize @minus
2194@item
2195Xtensa emulator pseudo board "sim"
2196@item
2197Avnet LX60/LX110/LX200 board
2198@end itemize
2199
Stefan Weilb5e49462011-11-13 22:24:26 +01002200The sim pseudo board emulation provides an environment similar
Max Filippov3aeaea62011-10-10 14:48:23 +04002201to one provided by the proprietary Tensilica ISS.
2202It supports:
2203
2204@itemize @minus
2205@item
2206A range of Xtensa CPUs, default is the DC232B
2207@item
2208Console and filesystem access via semihosting calls
2209@end itemize
2210
2211The Avnet LX60/LX110/LX200 emulation supports:
2212
2213@itemize @minus
2214@item
2215A range of Xtensa CPUs, default is the DC232B
2216@item
221716550 UART
2218@item
2219OpenCores 10/100 Mbps Ethernet MAC
2220@end itemize
2221
2222@c man begin OPTIONS
2223
2224The following options are specific to the Xtensa emulation:
2225
2226@table @option
2227
2228@item -semihosting
2229Enable semihosting syscall emulation.
2230
2231Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2232Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2233
2234Note that this allows guest direct access to the host filesystem,
2235so should only be used with trusted guest OS.
2236
2237@end table
ths5fafdf22007-09-16 21:08:06 +00002238@node QEMU User space emulator
2239@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002240
2241@menu
2242* Supported Operating Systems ::
2243* Linux User space emulator::
2244* Mac OS X/Darwin User space emulator ::
blueswir184778502008-10-26 20:33:16 +00002245* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002246@end menu
2247
2248@node Supported Operating Systems
2249@section Supported Operating Systems
2250
2251The following OS are supported in user space emulation:
2252
2253@itemize @minus
2254@item
ths4be456f2007-06-03 13:41:28 +00002255Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002256@item
ths4be456f2007-06-03 13:41:28 +00002257Mac OS X/Darwin (referred as qemu-darwin-user)
blueswir184778502008-10-26 20:33:16 +00002258@item
2259BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002260@end itemize
2261
2262@node Linux User space emulator
2263@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002264
bellarddebc7062006-04-30 21:58:41 +00002265@menu
2266* Quick Start::
2267* Wine launch::
2268* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002269* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002270@end menu
2271
2272@node Quick Start
bellard83195232007-02-05 19:42:07 +00002273@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002274
bellard1f673132004-04-04 15:21:17 +00002275In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002276itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002277
bellard1f673132004-04-04 15:21:17 +00002278@itemize
bellard386405f2003-03-23 21:28:45 +00002279
bellard1f673132004-04-04 15:21:17 +00002280@item On x86, you can just try to launch any process by using the native
2281libraries:
bellard386405f2003-03-23 21:28:45 +00002282
ths5fafdf22007-09-16 21:08:06 +00002283@example
bellard1f673132004-04-04 15:21:17 +00002284qemu-i386 -L / /bin/ls
2285@end example
bellardfd429f22003-03-30 20:59:46 +00002286
bellard1f673132004-04-04 15:21:17 +00002287@code{-L /} tells that the x86 dynamic linker must be searched with a
2288@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002289
thsdbcf5e82007-02-10 22:14:55 +00002290@item Since QEMU is also a linux process, you can launch qemu with
2291qemu (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002292
ths5fafdf22007-09-16 21:08:06 +00002293@example
bellard1f673132004-04-04 15:21:17 +00002294qemu-i386 -L / qemu-i386 -L / /bin/ls
2295@end example
bellard386405f2003-03-23 21:28:45 +00002296
bellard1f673132004-04-04 15:21:17 +00002297@item On non x86 CPUs, you need first to download at least an x86 glibc
2298(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2299@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002300
bellard1f673132004-04-04 15:21:17 +00002301@example
ths5fafdf22007-09-16 21:08:06 +00002302unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002303@end example
bellard386405f2003-03-23 21:28:45 +00002304
bellard1f673132004-04-04 15:21:17 +00002305Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002306
bellard1f673132004-04-04 15:21:17 +00002307@example
2308qemu-i386 tests/i386/ls
2309@end example
Blue Swirl4c3b5a42011-01-20 20:54:21 +00002310You can look at @file{scripts/qemu-binfmt-conf.sh} so that
bellard1f673132004-04-04 15:21:17 +00002311QEMU is automatically launched by the Linux kernel when you try to
2312launch x86 executables. It requires the @code{binfmt_misc} module in the
2313Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002314
bellard1f673132004-04-04 15:21:17 +00002315@item The x86 version of QEMU is also included. You can try weird things such as:
2316@example
bellarddebc7062006-04-30 21:58:41 +00002317qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2318 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002319@end example
bellard386405f2003-03-23 21:28:45 +00002320
bellard1f673132004-04-04 15:21:17 +00002321@end itemize
bellard386405f2003-03-23 21:28:45 +00002322
bellarddebc7062006-04-30 21:58:41 +00002323@node Wine launch
bellard83195232007-02-05 19:42:07 +00002324@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002325
bellard1f673132004-04-04 15:21:17 +00002326@itemize
bellard386405f2003-03-23 21:28:45 +00002327
bellard1f673132004-04-04 15:21:17 +00002328@item Ensure that you have a working QEMU with the x86 glibc
2329distribution (see previous section). In order to verify it, you must be
2330able to do:
bellard386405f2003-03-23 21:28:45 +00002331
bellard1f673132004-04-04 15:21:17 +00002332@example
2333qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2334@end example
bellard386405f2003-03-23 21:28:45 +00002335
bellard1f673132004-04-04 15:21:17 +00002336@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002337(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002338
bellard1f673132004-04-04 15:21:17 +00002339@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002340@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002341@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002342
bellard1f673132004-04-04 15:21:17 +00002343@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002344
bellard1f673132004-04-04 15:21:17 +00002345@example
bellarddebc7062006-04-30 21:58:41 +00002346qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2347 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002348@end example
bellard386405f2003-03-23 21:28:45 +00002349
bellard1f673132004-04-04 15:21:17 +00002350@end itemize
bellard386405f2003-03-23 21:28:45 +00002351
bellarddebc7062006-04-30 21:58:41 +00002352@node Command line options
bellard83195232007-02-05 19:42:07 +00002353@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002354
bellard1f673132004-04-04 15:21:17 +00002355@example
Paul Brook68a1c812010-05-29 02:27:35 +01002356usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
bellard1f673132004-04-04 15:21:17 +00002357@end example
bellard386405f2003-03-23 21:28:45 +00002358
bellard1f673132004-04-04 15:21:17 +00002359@table @option
2360@item -h
2361Print the help
ths3b46e622007-09-17 08:09:54 +00002362@item -L path
bellard1f673132004-04-04 15:21:17 +00002363Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2364@item -s size
2365Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002366@item -cpu model
2367Select CPU model (-cpu ? for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002368@item -ignore-environment
2369Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002370the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002371@item -E @var{var}=@var{value}
2372Set environment @var{var} to @var{value}.
2373@item -U @var{var}
2374Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002375@item -B offset
2376Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002377the address region required by guest applications is reserved on the host.
2378This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002379@item -R size
2380Pre-allocate a guest virtual address space of the given size (in bytes).
Stefan Weil0d6753e2011-01-07 18:59:13 +01002381"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002382@end table
2383
bellard1f673132004-04-04 15:21:17 +00002384Debug options:
bellard386405f2003-03-23 21:28:45 +00002385
bellard1f673132004-04-04 15:21:17 +00002386@table @option
2387@item -d
2388Activate log (logfile=/tmp/qemu.log)
2389@item -p pagesize
2390Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002391@item -g port
2392Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002393@item -singlestep
2394Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002395@end table
bellard386405f2003-03-23 21:28:45 +00002396
balrogb01bcae2007-12-16 13:05:59 +00002397Environment variables:
2398
2399@table @env
2400@item QEMU_STRACE
2401Print system calls and arguments similar to the 'strace' program
2402(NOTE: the actual 'strace' program will not work because the user
2403space emulator hasn't implemented ptrace). At the moment this is
2404incomplete. All system calls that don't have a specific argument
2405format are printed with information for six arguments. Many
2406flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002407@end table
balrogb01bcae2007-12-16 13:05:59 +00002408
pbrook79737e42006-06-11 16:28:41 +00002409@node Other binaries
bellard83195232007-02-05 19:42:07 +00002410@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002411
Stefan Weil7544a042010-02-05 23:52:03 +01002412@cindex user mode (Alpha)
2413@command{qemu-alpha} TODO.
2414
2415@cindex user mode (ARM)
2416@command{qemu-armeb} TODO.
2417
2418@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002419@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2420binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2421configurations), and arm-uclinux bFLT format binaries.
2422
Stefan Weil7544a042010-02-05 23:52:03 +01002423@cindex user mode (ColdFire)
2424@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002425@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2426(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2427coldfire uClinux bFLT format binaries.
2428
pbrook79737e42006-06-11 16:28:41 +00002429The binary format is detected automatically.
2430
Stefan Weil7544a042010-02-05 23:52:03 +01002431@cindex user mode (Cris)
2432@command{qemu-cris} TODO.
2433
2434@cindex user mode (i386)
2435@command{qemu-i386} TODO.
2436@command{qemu-x86_64} TODO.
2437
2438@cindex user mode (Microblaze)
2439@command{qemu-microblaze} TODO.
2440
2441@cindex user mode (MIPS)
2442@command{qemu-mips} TODO.
2443@command{qemu-mipsel} TODO.
2444
2445@cindex user mode (PowerPC)
2446@command{qemu-ppc64abi32} TODO.
2447@command{qemu-ppc64} TODO.
2448@command{qemu-ppc} TODO.
2449
2450@cindex user mode (SH4)
2451@command{qemu-sh4eb} TODO.
2452@command{qemu-sh4} TODO.
2453
2454@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002455@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2456
blueswir1a785e422007-10-20 08:09:05 +00002457@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2458(Sparc64 CPU, 32 bit ABI).
2459
2460@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2461SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2462
bellard83195232007-02-05 19:42:07 +00002463@node Mac OS X/Darwin User space emulator
2464@section Mac OS X/Darwin User space emulator
2465
2466@menu
2467* Mac OS X/Darwin Status::
2468* Mac OS X/Darwin Quick Start::
2469* Mac OS X/Darwin Command line options::
2470@end menu
2471
2472@node Mac OS X/Darwin Status
2473@subsection Mac OS X/Darwin Status
2474
2475@itemize @minus
2476@item
2477target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2478@item
2479target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2480@item
thsdbcf5e82007-02-10 22:14:55 +00002481target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
bellard83195232007-02-05 19:42:07 +00002482@item
2483target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2484@end itemize
2485
2486[1] If you're host commpage can be executed by qemu.
2487
2488@node Mac OS X/Darwin Quick Start
2489@subsection Quick Start
2490
2491In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2492itself and all the target dynamic libraries used by it. If you don't have the FAT
2493libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2494CD or compile them by hand.
2495
2496@itemize
2497
2498@item On x86, you can just try to launch any process by using the native
2499libraries:
2500
ths5fafdf22007-09-16 21:08:06 +00002501@example
thsdbcf5e82007-02-10 22:14:55 +00002502qemu-i386 /bin/ls
bellard83195232007-02-05 19:42:07 +00002503@end example
2504
2505or to run the ppc version of the executable:
2506
ths5fafdf22007-09-16 21:08:06 +00002507@example
thsdbcf5e82007-02-10 22:14:55 +00002508qemu-ppc /bin/ls
bellard83195232007-02-05 19:42:07 +00002509@end example
2510
2511@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2512are installed:
2513
ths5fafdf22007-09-16 21:08:06 +00002514@example
thsdbcf5e82007-02-10 22:14:55 +00002515qemu-i386 -L /opt/x86_root/ /bin/ls
bellard83195232007-02-05 19:42:07 +00002516@end example
2517
2518@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2519@file{/opt/x86_root/usr/bin/dyld}.
2520
2521@end itemize
2522
2523@node Mac OS X/Darwin Command line options
2524@subsection Command line options
2525
2526@example
thsdbcf5e82007-02-10 22:14:55 +00002527usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
bellard83195232007-02-05 19:42:07 +00002528@end example
2529
2530@table @option
2531@item -h
2532Print the help
ths3b46e622007-09-17 08:09:54 +00002533@item -L path
bellard83195232007-02-05 19:42:07 +00002534Set the library root path (default=/)
2535@item -s size
2536Set the stack size in bytes (default=524288)
2537@end table
2538
2539Debug options:
2540
2541@table @option
2542@item -d
2543Activate log (logfile=/tmp/qemu.log)
2544@item -p pagesize
2545Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002546@item -singlestep
2547Run the emulation in single step mode.
bellard83195232007-02-05 19:42:07 +00002548@end table
2549
blueswir184778502008-10-26 20:33:16 +00002550@node BSD User space emulator
2551@section BSD User space emulator
2552
2553@menu
2554* BSD Status::
2555* BSD Quick Start::
2556* BSD Command line options::
2557@end menu
2558
2559@node BSD Status
2560@subsection BSD Status
2561
2562@itemize @minus
2563@item
2564target Sparc64 on Sparc64: Some trivial programs work.
2565@end itemize
2566
2567@node BSD Quick Start
2568@subsection Quick Start
2569
2570In order to launch a BSD process, QEMU needs the process executable
2571itself and all the target dynamic libraries used by it.
2572
2573@itemize
2574
2575@item On Sparc64, you can just try to launch any process by using the native
2576libraries:
2577
2578@example
2579qemu-sparc64 /bin/ls
2580@end example
2581
2582@end itemize
2583
2584@node BSD Command line options
2585@subsection Command line options
2586
2587@example
2588usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2589@end example
2590
2591@table @option
2592@item -h
2593Print the help
2594@item -L path
2595Set the library root path (default=/)
2596@item -s size
2597Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002598@item -ignore-environment
2599Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002600the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002601@item -E @var{var}=@var{value}
2602Set environment @var{var} to @var{value}.
2603@item -U @var{var}
2604Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00002605@item -bsd type
2606Set the type of the emulated BSD Operating system. Valid values are
2607FreeBSD, NetBSD and OpenBSD (default).
2608@end table
2609
2610Debug options:
2611
2612@table @option
2613@item -d
2614Activate log (logfile=/tmp/qemu.log)
2615@item -p pagesize
2616Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002617@item -singlestep
2618Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00002619@end table
2620
bellard15a34c62004-07-08 21:26:26 +00002621@node compilation
2622@chapter Compilation from the sources
2623
bellarddebc7062006-04-30 21:58:41 +00002624@menu
2625* Linux/Unix::
2626* Windows::
2627* Cross compilation for Windows with Linux::
2628* Mac OS X::
Stefan Weil47eacb42010-02-05 23:52:01 +01002629* Make targets::
bellarddebc7062006-04-30 21:58:41 +00002630@end menu
2631
2632@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002633@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002634
bellard7c3fc842005-02-10 21:46:47 +00002635@subsection Compilation
2636
2637First you must decompress the sources:
2638@example
2639cd /tmp
2640tar zxvf qemu-x.y.z.tar.gz
2641cd qemu-x.y.z
2642@end example
2643
2644Then you configure QEMU and build it (usually no options are needed):
2645@example
2646./configure
2647make
2648@end example
2649
2650Then type as root user:
2651@example
2652make install
2653@end example
2654to install QEMU in @file{/usr/local}.
2655
bellarddebc7062006-04-30 21:58:41 +00002656@node Windows
bellard15a34c62004-07-08 21:26:26 +00002657@section Windows
2658
2659@itemize
2660@item Install the current versions of MSYS and MinGW from
2661@url{http://www.mingw.org/}. You can find detailed installation
2662instructions in the download section and the FAQ.
2663
ths5fafdf22007-09-16 21:08:06 +00002664@item Download
bellard15a34c62004-07-08 21:26:26 +00002665the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002666(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
Scott Tsaid0a96f32010-01-30 03:28:58 +08002667@url{http://www.libsdl.org}. Unpack it in a temporary place and
2668edit the @file{sdl-config} script so that it gives the
bellard15a34c62004-07-08 21:26:26 +00002669correct SDL directory when invoked.
2670
Scott Tsaid0a96f32010-01-30 03:28:58 +08002671@item Install the MinGW version of zlib and make sure
2672@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002673MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002674
bellard15a34c62004-07-08 21:26:26 +00002675@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002676
bellard15a34c62004-07-08 21:26:26 +00002677@item Start the MSYS shell (file @file{msys.bat}).
2678
ths5fafdf22007-09-16 21:08:06 +00002679@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00002680@file{make}. If you have problems using SDL, verify that
2681@file{sdl-config} can be launched from the MSYS command line.
2682
ths5fafdf22007-09-16 21:08:06 +00002683@item You can install QEMU in @file{Program Files/Qemu} by typing
bellard15a34c62004-07-08 21:26:26 +00002684@file{make install}. Don't forget to copy @file{SDL.dll} in
2685@file{Program Files/Qemu}.
2686
2687@end itemize
2688
bellarddebc7062006-04-30 21:58:41 +00002689@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00002690@section Cross compilation for Windows with Linux
2691
2692@itemize
2693@item
2694Install the MinGW cross compilation tools available at
2695@url{http://www.mingw.org/}.
2696
Scott Tsaid0a96f32010-01-30 03:28:58 +08002697@item Download
2698the MinGW development library of SDL 1.2.x
2699(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2700@url{http://www.libsdl.org}. Unpack it in a temporary place and
2701edit the @file{sdl-config} script so that it gives the
2702correct SDL directory when invoked. Set up the @code{PATH} environment
2703variable so that @file{sdl-config} can be launched by
bellard15a34c62004-07-08 21:26:26 +00002704the QEMU configuration script.
2705
Scott Tsaid0a96f32010-01-30 03:28:58 +08002706@item Install the MinGW version of zlib and make sure
2707@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002708MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002709
ths5fafdf22007-09-16 21:08:06 +00002710@item
bellard15a34c62004-07-08 21:26:26 +00002711Configure QEMU for Windows cross compilation:
2712@example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002713PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
bellard15a34c62004-07-08 21:26:26 +00002714@end example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002715The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
2716MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002717We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
Scott Tsaid0a96f32010-01-30 03:28:58 +08002718use --cross-prefix to specify the name of the cross compiler.
2719You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
2720
2721Under Fedora Linux, you can run:
2722@example
2723yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
2724@end example
2725to get a suitable cross compilation environment.
bellard15a34c62004-07-08 21:26:26 +00002726
ths5fafdf22007-09-16 21:08:06 +00002727@item You can install QEMU in the installation directory by typing
Scott Tsaid0a96f32010-01-30 03:28:58 +08002728@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
ths5fafdf22007-09-16 21:08:06 +00002729installation directory.
bellard15a34c62004-07-08 21:26:26 +00002730
2731@end itemize
2732
Scott Tsaid0a96f32010-01-30 03:28:58 +08002733Wine can be used to launch the resulting qemu.exe compiled for Win32.
bellard15a34c62004-07-08 21:26:26 +00002734
bellarddebc7062006-04-30 21:58:41 +00002735@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00002736@section Mac OS X
2737
2738The Mac OS X patches are not fully merged in QEMU, so you should look
2739at the QEMU mailing list archive to have all the necessary
2740information.
2741
Stefan Weil47eacb42010-02-05 23:52:01 +01002742@node Make targets
2743@section Make targets
2744
2745@table @code
2746
2747@item make
2748@item make all
2749Make everything which is typically needed.
2750
2751@item install
2752TODO
2753
2754@item install-doc
2755TODO
2756
2757@item make clean
2758Remove most files which were built during make.
2759
2760@item make distclean
2761Remove everything which was built during make.
2762
2763@item make dvi
2764@item make html
2765@item make info
2766@item make pdf
2767Create documentation in dvi, html, info or pdf format.
2768
2769@item make cscope
2770TODO
2771
2772@item make defconfig
2773(Re-)create some build configuration files.
2774User made changes will be overwritten.
2775
2776@item tar
2777@item tarbin
2778TODO
2779
2780@end table
2781
Stefan Weil7544a042010-02-05 23:52:03 +01002782@node License
2783@appendix License
2784
2785QEMU is a trademark of Fabrice Bellard.
2786
2787QEMU is released under the GNU General Public License (TODO: add link).
2788Parts of QEMU have specific licenses, see file LICENSE.
2789
2790TODO (refer to file LICENSE, include it, include the GPL?)
2791
bellarddebc7062006-04-30 21:58:41 +00002792@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01002793@appendix Index
2794@menu
2795* Concept Index::
2796* Function Index::
2797* Keystroke Index::
2798* Program Index::
2799* Data Type Index::
2800* Variable Index::
2801@end menu
2802
2803@node Concept Index
2804@section Concept Index
2805This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00002806@printindex cp
2807
Stefan Weil7544a042010-02-05 23:52:03 +01002808@node Function Index
2809@section Function Index
2810This index could be used for command line options and monitor functions.
2811@printindex fn
2812
2813@node Keystroke Index
2814@section Keystroke Index
2815
2816This is a list of all keystrokes which have a special function
2817in system emulation.
2818
2819@printindex ky
2820
2821@node Program Index
2822@section Program Index
2823@printindex pg
2824
2825@node Data Type Index
2826@section Data Type Index
2827
2828This index could be used for qdev device names and options.
2829
2830@printindex tp
2831
2832@node Variable Index
2833@section Variable Index
2834@printindex vr
2835
bellarddebc7062006-04-30 21:58:41 +00002836@bye