blob: 6d7f50d8323ae4dcee1d88b8b1998555e30fd65f [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
Stefan Weile1b43822012-07-16 23:37:07 +020081QEMU can run without a 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)
Edgar E. Iglesias48c50a62009-05-27 01:34:02 +0200110@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
111@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
Max Filippov3aeaea62011-10-10 14:48:23 +0400112@item Avnet LX60/LX110/LX200 boards (Xtensa)
bellard52c00a52004-04-25 21:27:03 +0000113@end itemize
bellard386405f2003-03-23 21:28:45 +0000114
Stefan Weil7544a042010-02-05 23:52:03 +0100115@cindex supported user mode targets
116For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
117ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
118Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +0000119
bellarddebc7062006-04-30 21:58:41 +0000120@node Installation
bellard5b9f4572003-10-28 00:49:54 +0000121@chapter Installation
122
bellard15a34c62004-07-08 21:26:26 +0000123If you want to compile QEMU yourself, see @ref{compilation}.
124
bellarddebc7062006-04-30 21:58:41 +0000125@menu
126* install_linux:: Linux
127* install_windows:: Windows
128* install_mac:: Macintosh
129@end menu
130
131@node install_linux
bellard1f673132004-04-04 15:21:17 +0000132@section Linux
Stefan Weil7544a042010-02-05 23:52:03 +0100133@cindex installation (Linux)
bellard1f673132004-04-04 15:21:17 +0000134
bellard7c3fc842005-02-10 21:46:47 +0000135If a precompiled package is available for your distribution - you just
136have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000137
bellarddebc7062006-04-30 21:58:41 +0000138@node install_windows
bellard1f673132004-04-04 15:21:17 +0000139@section Windows
Stefan Weil7544a042010-02-05 23:52:03 +0100140@cindex installation (Windows)
bellard8cd0ac22004-05-12 19:09:16 +0000141
bellard15a34c62004-07-08 21:26:26 +0000142Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000143@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100144TODO (no longer available)
bellardd691f662003-03-24 21:58:34 +0000145
bellarddebc7062006-04-30 21:58:41 +0000146@node install_mac
bellard1f673132004-04-04 15:21:17 +0000147@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000148
bellard15a34c62004-07-08 21:26:26 +0000149Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000150@url{http://www.free.oszoo.org/@/download.html}.
Stefan Weil7544a042010-02-05 23:52:03 +0100151TODO (no longer available)
bellarddf0f11a2003-05-28 00:27:57 +0000152
bellarddebc7062006-04-30 21:58:41 +0000153@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000154@chapter QEMU PC System emulator
Stefan Weil7544a042010-02-05 23:52:03 +0100155@cindex system emulation (PC)
bellard1eb20522003-06-25 16:21:49 +0000156
bellarddebc7062006-04-30 21:58:41 +0000157@menu
158* pcsys_introduction:: Introduction
159* pcsys_quickstart:: Quick Start
160* sec_invocation:: Invocation
161* pcsys_keys:: Keys
162* pcsys_monitor:: QEMU Monitor
163* disk_images:: Disk Images
164* pcsys_network:: Network emulation
Stefan Weil576fd0a2011-01-07 18:59:14 +0100165* pcsys_other_devs:: Other Devices
bellarddebc7062006-04-30 21:58:41 +0000166* direct_linux_boot:: Direct Linux Boot
167* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000168* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000169* gdb_usage:: GDB usage
170* pcsys_os_specific:: Target OS specific information
171@end menu
172
173@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000174@section Introduction
175
176@c man begin DESCRIPTION
177
bellard3f9f3aa2005-12-18 20:11:37 +0000178The QEMU PC System emulator simulates the
179following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000180
181@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000182@item
bellard15a34c62004-07-08 21:26:26 +0000183i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000184@item
bellard15a34c62004-07-08 21:26:26 +0000185Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
186extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000187@item
188PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000189@item
bellard15a34c62004-07-08 21:26:26 +00001902 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000191@item
192Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000193@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +0200194PCI and ISA network adapters
bellard0806e3f2003-10-01 00:15:32 +0000195@item
bellard05d58182004-08-24 21:12:04 +0000196Serial ports
197@item
bellardc0fe3822005-11-05 18:55:28 +0000198Creative SoundBlaster 16 sound card
199@item
200ENSONIQ AudioPCI ES1370 sound card
201@item
balroge5c9a132008-01-14 04:27:55 +0000202Intel 82801AA AC97 Audio compatible sound card
203@item
Gerd Hoffmann7d72e762010-11-01 16:57:48 +0100204Intel HD Audio Controller and HDA codec
205@item
Stefan Weil2d983442011-01-07 18:59:15 +0100206Adlib (OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000207@item
balrog26463db2008-01-17 21:47:25 +0000208Gravis Ultrasound GF1 sound card
209@item
malccc53d262008-06-13 10:48:22 +0000210CS4231A compatible sound card
211@item
bellardb389dbf2005-11-06 16:49:55 +0000212PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000213@end itemize
214
bellard3f9f3aa2005-12-18 20:11:37 +0000215SMP is supported with up to 255 CPUs.
216
malc1d1f8c32009-01-09 10:46:37 +0000217Note that adlib, gus and cs4231a are only available when QEMU was
218configured with --audio-card-list option containing the name(s) of
malce5178e82008-06-28 19:13:02 +0000219required card(s).
bellardc0fe3822005-11-05 18:55:28 +0000220
bellard15a34c62004-07-08 21:26:26 +0000221QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
222VGA BIOS.
223
bellardc0fe3822005-11-05 18:55:28 +0000224QEMU uses YM3812 emulation by Tatsuyuki Satoh.
225
Stefan Weil2d983442011-01-07 18:59:15 +0100226QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
balrog26463db2008-01-17 21:47:25 +0000227by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000228
Bernhard Reutner-Fischer1a1a0e22011-10-25 10:22:18 +0200229Note that, by default, GUS shares IRQ(7) with parallel ports and so
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200230QEMU must be told to not have parallel ports to have working GUS.
malc720036a2009-09-10 20:05:59 +0400231
232@example
Stefan Weil3804da92012-05-11 22:21:50 +0200233qemu-system-i386 dos.img -soundhw gus -parallel none
malc720036a2009-09-10 20:05:59 +0400234@end example
235
236Alternatively:
237@example
Stefan Weil3804da92012-05-11 22:21:50 +0200238qemu-system-i386 dos.img -device gus,irq=5
malc720036a2009-09-10 20:05:59 +0400239@end example
240
241Or some other unclaimed IRQ.
242
malccc53d262008-06-13 10:48:22 +0000243CS4231A is the chip used in Windows Sound System and GUSMAX products
244
bellard0806e3f2003-10-01 00:15:32 +0000245@c man end
246
bellarddebc7062006-04-30 21:58:41 +0000247@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000248@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100249@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000250
bellard285dc332003-10-27 23:58:04 +0000251Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000252
253@example
Stefan Weil3804da92012-05-11 22:21:50 +0200254qemu-system-i386 linux.img
bellard0806e3f2003-10-01 00:15:32 +0000255@end example
256
257Linux should boot and give you a prompt.
258
bellard6cc721c2005-07-28 22:27:28 +0000259@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000260@section Invocation
261
262@example
263@c man begin SYNOPSIS
Stefan Weil3804da92012-05-11 22:21:50 +0200264usage: qemu-system-i386 [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000265@c man end
266@end example
267
268@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000269@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
270targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000271
blueswir15824d652009-03-28 06:44:27 +0000272@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000273
bellard3e11db92004-07-14 17:47:14 +0000274@c man end
275
bellarddebc7062006-04-30 21:58:41 +0000276@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000277@section Keys
278
279@c man begin OPTIONS
280
Brad Hardsde1db2a2011-04-29 21:46:12 +1000281During the graphical emulation, you can use special key combinations to change
282modes. The default key mappings are shown below, but if you use @code{-alt-grab}
283then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
284@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
285
bellarda1b74fe2004-05-08 13:26:35 +0000286@table @key
bellardf9859312004-10-03 14:33:10 +0000287@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100288@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000289Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000290
Jan Kiszkad6a65ba2011-07-30 11:39:16 +0200291@item Ctrl-Alt-+
292@kindex Ctrl-Alt-+
293Enlarge the screen
294
295@item Ctrl-Alt--
296@kindex Ctrl-Alt--
297Shrink the screen
298
malcc4a735f2009-09-10 05:15:07 +0400299@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100300@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400301Restore the screen's un-scaled dimensions
302
bellardf9859312004-10-03 14:33:10 +0000303@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100304@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000305Switch to virtual console 'n'. Standard console mappings are:
306@table @emph
307@item 1
308Target system display
309@item 2
310Monitor
311@item 3
312Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000313@end table
314
bellardf9859312004-10-03 14:33:10 +0000315@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100316@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000317Toggle mouse and keyboard grab.
318@end table
319
Stefan Weil7544a042010-02-05 23:52:03 +0100320@kindex Ctrl-Up
321@kindex Ctrl-Down
322@kindex Ctrl-PageUp
323@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000324In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
325@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
326
Stefan Weil7544a042010-02-05 23:52:03 +0100327@kindex Ctrl-a h
bellarda0a821a2004-07-14 17:38:57 +0000328During emulation, if you are using the @option{-nographic} option, use
329@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000330
331@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000332@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100333@kindex Ctrl-a h
blueswir1d2c639d2009-01-24 18:19:25 +0000334@item Ctrl-a ?
Stefan Weil7544a042010-02-05 23:52:03 +0100335@kindex Ctrl-a ?
bellard1f673132004-04-04 15:21:17 +0000336Print this help
ths3b46e622007-09-17 08:09:54 +0000337@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100338@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000339Exit emulator
ths3b46e622007-09-17 08:09:54 +0000340@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100341@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000342Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000343@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100344@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000345Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000346@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100347@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000348Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000349@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100350@kindex Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000351Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000352@item Ctrl-a Ctrl-a
Stefan Weil7544a042010-02-05 23:52:03 +0100353@kindex Ctrl-a a
bellarda1b74fe2004-05-08 13:26:35 +0000354Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000355@end table
356@c man end
357
358@ignore
359
bellard1f673132004-04-04 15:21:17 +0000360@c man begin SEEALSO
361The HTML documentation of QEMU for more precise information and Linux
362user mode emulator invocation.
363@c man end
364
365@c man begin AUTHOR
366Fabrice Bellard
367@c man end
368
369@end ignore
370
bellarddebc7062006-04-30 21:58:41 +0000371@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000372@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100373@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000374
375The QEMU monitor is used to give complex commands to the QEMU
376emulator. You can use it to:
377
378@itemize @minus
379
380@item
thse5987522007-03-30 18:58:01 +0000381Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000382(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000383
ths5fafdf22007-09-16 21:08:06 +0000384@item
bellard1f673132004-04-04 15:21:17 +0000385Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
386from a disk file.
387
388@item Inspect the VM state without an external debugger.
389
390@end itemize
391
392@subsection Commands
393
394The following commands are available:
395
Blue Swirl23130862009-06-06 08:22:04 +0000396@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000397
398@subsection Integer expressions
399
400The monitor understands integers expressions for every integer
401argument. You can use register names to get the value of specifics
402CPU registers by prefixing them with @emph{$}.
403
404@node disk_images
405@section Disk Images
406
bellardacd935e2004-11-15 22:57:26 +0000407Since version 0.6.1, QEMU supports many disk image formats, including
408growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000409written), compressed and encrypted disk images. Version 0.8.3 added
410the new qcow2 disk image format which is essential to support VM
411snapshots.
bellard1f673132004-04-04 15:21:17 +0000412
bellarddebc7062006-04-30 21:58:41 +0000413@menu
414* disk_images_quickstart:: Quick start for disk image creation
415* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000416* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000417* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000418* qemu_nbd_invocation:: qemu-nbd Invocation
Kevin Wolfd3067b02012-11-21 14:21:47 +0100419* disk_images_formats:: Disk image file formats
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
Bharata B Rao8809e282012-10-24 17:17:53 +0530425* disk_images_gluster:: GlusterFS disk images
bellarddebc7062006-04-30 21:58:41 +0000426@end menu
427
428@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000429@subsection Quick start for disk image creation
430
431You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000432@example
bellardacd935e2004-11-15 22:57:26 +0000433qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000434@end example
bellardacd935e2004-11-15 22:57:26 +0000435where @var{myimage.img} is the disk image filename and @var{mysize} is its
436size in kilobytes. You can add an @code{M} suffix to give the size in
437megabytes and a @code{G} suffix for gigabytes.
438
bellarddebc7062006-04-30 21:58:41 +0000439See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000440
bellarddebc7062006-04-30 21:58:41 +0000441@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000442@subsection Snapshot mode
443
444If you use the option @option{-snapshot}, all disk images are
445considered as read only. When sectors in written, they are written in
446a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000447write back to the raw disk images by using the @code{commit} monitor
448command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000449
bellard13a2e802006-08-06 14:50:31 +0000450@node vm_snapshots
451@subsection VM snapshots
452
453VM snapshots are snapshots of the complete virtual machine including
454CPU state, RAM, device state and the content of all the writable
455disks. In order to use VM snapshots, you must have at least one non
456removable and writable block device using the @code{qcow2} disk image
457format. Normally this device is the first virtual hard drive.
458
459Use the monitor command @code{savevm} to create a new VM snapshot or
460replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000461snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000462
463Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
464a VM snapshot. @code{info snapshots} lists the available snapshots
465with their associated information:
466
467@example
468(qemu) info snapshots
469Snapshot devices: hda
470Snapshot list (from hda):
471ID TAG VM SIZE DATE VM CLOCK
4721 start 41M 2006-08-06 12:38:02 00:00:14.954
4732 40M 2006-08-06 12:43:29 00:00:18.633
4743 msys 40M 2006-08-06 12:44:04 00:00:23.514
475@end example
476
477A VM snapshot is made of a VM state info (its size is shown in
478@code{info snapshots}) and a snapshot of every writable disk image.
479The VM state info is stored in the first @code{qcow2} non removable
480and writable block device. The disk image snapshots are stored in
481every disk image. The size of a snapshot in a disk image is difficult
482to evaluate and is not shown by @code{info snapshots} because the
483associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000484disk space (otherwise each snapshot would need a full copy of all the
485disk images).
bellard13a2e802006-08-06 14:50:31 +0000486
487When using the (unrelated) @code{-snapshot} option
488(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
489but they are deleted as soon as you exit QEMU.
490
491VM snapshots currently have the following known limitations:
492@itemize
ths5fafdf22007-09-16 21:08:06 +0000493@item
bellard13a2e802006-08-06 14:50:31 +0000494They cannot cope with removable devices if they are removed or
495inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000496@item
bellard13a2e802006-08-06 14:50:31 +0000497A few device drivers still have incomplete snapshot support so their
498state is not saved or restored properly (in particular USB).
499@end itemize
500
bellardacd935e2004-11-15 22:57:26 +0000501@node qemu_img_invocation
502@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000503
bellardacd935e2004-11-15 22:57:26 +0000504@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000505
ths975b0922008-07-02 21:18:00 +0000506@node qemu_nbd_invocation
507@subsection @code{qemu-nbd} Invocation
508
509@include qemu-nbd.texi
510
Kevin Wolfd3067b02012-11-21 14:21:47 +0100511@node disk_images_formats
512@subsection Disk image file formats
513
514QEMU supports many image file formats that can be used with VMs as well as with
515any of the tools (like @code{qemu-img}). This includes the preferred formats
516raw and qcow2 as well as formats that are supported for compatibility with
517older QEMU versions or other hypervisors.
518
519Depending on the image format, different options can be passed to
520@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
521This section describes each format and the options that are supported for it.
522
523@table @option
524@item raw
525
526Raw disk image format. This format has the advantage of
527being simple and easily exportable to all other emulators. If your
528file system supports @emph{holes} (for example in ext2 or ext3 on
529Linux or NTFS on Windows), then only the written sectors will reserve
530space. Use @code{qemu-img info} to know the real size used by the
531image or @code{ls -ls} on Unix/Linux.
532
533@item qcow2
534QEMU image format, the most versatile format. Use it to have smaller
535images (useful if your filesystem does not supports holes, for example
536on Windows), optional AES encryption, zlib based compression and
537support of multiple VM snapshots.
538
539Supported options:
540@table @code
541@item compat
542Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
543image format that can be read by any QEMU since 0.10 (this is the default).
544@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
545newer understand. Amongst others, this includes zero clusters, which allow
546efficient copy-on-read for sparse images.
547
548@item backing_file
549File name of a base image (see @option{create} subcommand)
550@item backing_fmt
551Image format of the base image
552@item encryption
553If this option is set to @code{on}, the image is encrypted.
554
555Encryption uses the AES format which is very secure (128 bit keys). Use
556a long password (16 characters) to get maximum protection.
557
558@item cluster_size
559Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
560sizes can improve the image file size whereas larger cluster sizes generally
561provide better performance.
562
563@item preallocation
564Preallocation mode (allowed values: off, metadata). An image with preallocated
565metadata is initially larger but can improve performance when the image needs
566to grow.
567
568@item lazy_refcounts
569If this option is set to @code{on}, reference count updates are postponed with
570the goal of avoiding metadata I/O and improving performance. This is
571particularly interesting with @option{cache=writethrough} which doesn't batch
572metadata updates. The tradeoff is that after a host crash, the reference count
573tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
574check -r all} is required, which may take some time.
575
576This option can only be enabled if @code{compat=1.1} is specified.
577
578@end table
579
580@item qed
581Old QEMU image format with support for backing files and compact image files
582(when your filesystem or transport medium does not support holes).
583
584When converting QED images to qcow2, you might want to consider using the
585@code{lazy_refcounts=on} option to get a more QED-like behaviour.
586
587Supported options:
588@table @code
589@item backing_file
590File name of a base image (see @option{create} subcommand).
591@item backing_fmt
592Image file format of backing file (optional). Useful if the format cannot be
593autodetected because it has no header, like some vhd/vpc files.
594@item cluster_size
595Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
596cluster sizes can improve the image file size whereas larger cluster sizes
597generally provide better performance.
598@item table_size
599Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
600and 16). There is normally no need to change this value but this option can be
601used for performance benchmarking.
602@end table
603
604@item qcow
605Old QEMU image format with support for backing files, compact image files,
606encryption and compression.
607
608Supported options:
609@table @code
610@item backing_file
611File name of a base image (see @option{create} subcommand)
612@item encryption
613If this option is set to @code{on}, the image is encrypted.
614@end table
615
616@item cow
617User Mode Linux Copy On Write image format. It is supported only for
618compatibility with previous versions.
619Supported options:
620@table @code
621@item backing_file
622File name of a base image (see @option{create} subcommand)
623@end table
624
625@item vdi
626VirtualBox 1.1 compatible image format.
627Supported options:
628@table @code
629@item static
630If this option is set to @code{on}, the image is created with metadata
631preallocation.
632@end table
633
634@item vmdk
635VMware 3 and 4 compatible image format.
636
637Supported options:
638@table @code
639@item backing_file
640File name of a base image (see @option{create} subcommand).
641@item compat6
642Create a VMDK version 6 image (instead of version 4)
643@item subformat
644Specifies which VMDK subformat to use. Valid options are
645@code{monolithicSparse} (default),
646@code{monolithicFlat},
647@code{twoGbMaxExtentSparse},
648@code{twoGbMaxExtentFlat} and
649@code{streamOptimized}.
650@end table
651
652@item vpc
653VirtualPC compatible image format (VHD).
654Supported options:
655@table @code
656@item subformat
657Specifies which VHD subformat to use. Valid options are
658@code{dynamic} (default) and @code{fixed}.
659@end table
660@end table
661
662@subsubsection Read-only formats
663More disk image file formats are supported in a read-only mode.
664@table @option
665@item bochs
666Bochs images of @code{growing} type.
667@item cloop
668Linux Compressed Loop image, useful only to reuse directly compressed
669CD-ROM images present for example in the Knoppix CD-ROMs.
670@item dmg
671Apple disk image.
672@item parallels
673Parallels disk image format.
674@end table
675
676
bellard19cb3732006-08-19 11:45:59 +0000677@node host_drives
678@subsection Using host drives
679
680In addition to disk image files, QEMU can directly access host
681devices. We describe here the usage for QEMU version >= 0.8.3.
682
683@subsubsection Linux
684
685On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000686disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +0000687it. For example, use @file{/dev/cdrom} to access to the CDROM or
688@file{/dev/fd0} for the floppy.
689
bellardf5420862006-08-21 20:26:44 +0000690@table @code
bellard19cb3732006-08-19 11:45:59 +0000691@item CD
692You can specify a CDROM device even if no CDROM is loaded. QEMU has
693specific code to detect CDROM insertion or removal. CDROM ejection by
694the guest OS is supported. Currently only data CDs are supported.
695@item Floppy
696You can specify a floppy device even if no floppy is loaded. Floppy
697removal is currently not detected accurately (if you change floppy
698without doing floppy access while the floppy is not loaded, the guest
699OS will think that the same floppy is loaded).
700@item Hard disks
701Hard disks can be used. Normally you must specify the whole disk
702(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
703see it as a partitioned disk. WARNING: unless you know what you do, it
704is better to only make READ-ONLY accesses to the hard disk otherwise
705you may corrupt your host data (use the @option{-snapshot} command
706line option or modify the device permissions accordingly).
707@end table
708
709@subsubsection Windows
710
bellard01781962007-01-07 22:43:30 +0000711@table @code
712@item CD
ths4be456f2007-06-03 13:41:28 +0000713The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000714alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
715supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000716
thse5987522007-03-30 18:58:01 +0000717Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000718is better to use the @code{change} or @code{eject} monitor commands to
719change or eject media.
bellard01781962007-01-07 22:43:30 +0000720@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000721Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000722where @var{N} is the drive number (0 is the first hard disk).
723
724WARNING: unless you know what you do, it is better to only make
725READ-ONLY accesses to the hard disk otherwise you may corrupt your
726host data (use the @option{-snapshot} command line so that the
727modifications are written in a temporary file).
728@end table
729
bellard19cb3732006-08-19 11:45:59 +0000730
731@subsubsection Mac OS X
732
ths5fafdf22007-09-16 21:08:06 +0000733@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000734
thse5987522007-03-30 18:58:01 +0000735Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000736is better to use the @code{change} or @code{eject} monitor commands to
737change or eject media.
738
bellarddebc7062006-04-30 21:58:41 +0000739@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000740@subsection Virtual FAT disk images
741
742QEMU can automatically create a virtual FAT disk image from a
743directory tree. In order to use it, just type:
744
ths5fafdf22007-09-16 21:08:06 +0000745@example
Stefan Weil3804da92012-05-11 22:21:50 +0200746qemu-system-i386 linux.img -hdb fat:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000747@end example
748
749Then you access access to all the files in the @file{/my_directory}
750directory without having to copy them in a disk image or to export
751them via SAMBA or NFS. The default access is @emph{read-only}.
752
753Floppies can be emulated with the @code{:floppy:} option:
754
ths5fafdf22007-09-16 21:08:06 +0000755@example
Stefan Weil3804da92012-05-11 22:21:50 +0200756qemu-system-i386 linux.img -fda fat:floppy:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000757@end example
758
759A read/write support is available for testing (beta stage) with the
760@code{:rw:} option:
761
ths5fafdf22007-09-16 21:08:06 +0000762@example
Stefan Weil3804da92012-05-11 22:21:50 +0200763qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000764@end example
765
766What you should @emph{never} do:
767@itemize
768@item use non-ASCII filenames ;
769@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000770@item expect it to work when loadvm'ing ;
771@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000772@end itemize
773
ths75818252008-07-03 13:41:03 +0000774@node disk_images_nbd
775@subsection NBD access
776
777QEMU can access directly to block device exported using the Network Block Device
778protocol.
779
780@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100781qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
ths75818252008-07-03 13:41:03 +0000782@end example
783
784If the NBD server is located on the same host, you can use an unix socket instead
785of an inet socket:
786
787@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100788qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000789@end example
790
791In this case, the block device must be exported using qemu-nbd:
792
793@example
794qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
795@end example
796
797The use of qemu-nbd allows to share a disk between several guests:
798@example
799qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
800@end example
801
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100802@noindent
ths75818252008-07-03 13:41:03 +0000803and then you can use it with two guests:
804@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100805qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
806qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000807@end example
808
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100809If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
810own embedded NBD server), you must specify an export name in the URI:
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200811@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100812qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
813qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
814@end example
815
816The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
817also available. Here are some example of the older syntax:
818@example
819qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
820qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
821qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200822@end example
823
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900824@node disk_images_sheepdog
825@subsection Sheepdog disk images
826
827Sheepdog is a distributed storage system for QEMU. It provides highly
828available block level storage volumes that can be attached to
829QEMU-based virtual machines.
830
831You can create a Sheepdog disk image with the command:
832@example
833qemu-img create sheepdog:@var{image} @var{size}
834@end example
835where @var{image} is the Sheepdog image name and @var{size} is its
836size.
837
838To import the existing @var{filename} to Sheepdog, you can use a
839convert command.
840@example
841qemu-img convert @var{filename} sheepdog:@var{image}
842@end example
843
844You can boot from the Sheepdog disk image with the command:
845@example
Stefan Weil3804da92012-05-11 22:21:50 +0200846qemu-system-i386 sheepdog:@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900847@end example
848
849You can also create a snapshot of the Sheepdog image like qcow2.
850@example
851qemu-img snapshot -c @var{tag} sheepdog:@var{image}
852@end example
853where @var{tag} is a tag name of the newly created snapshot.
854
855To boot from the Sheepdog snapshot, specify the tag name of the
856snapshot.
857@example
Stefan Weil3804da92012-05-11 22:21:50 +0200858qemu-system-i386 sheepdog:@var{image}:@var{tag}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900859@end example
860
861You can create a cloned image from the existing snapshot.
862@example
863qemu-img create -b sheepdog:@var{base}:@var{tag} sheepdog:@var{image}
864@end example
865where @var{base} is a image name of the source snapshot and @var{tag}
866is its tag name.
867
868If the Sheepdog daemon doesn't run on the local host, you need to
869specify one of the Sheepdog servers to connect to.
870@example
871qemu-img create sheepdog:@var{hostname}:@var{port}:@var{image} @var{size}
Stefan Weil3804da92012-05-11 22:21:50 +0200872qemu-system-i386 sheepdog:@var{hostname}:@var{port}:@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900873@end example
874
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100875@node disk_images_iscsi
876@subsection iSCSI LUNs
877
878iSCSI is a popular protocol used to access SCSI devices across a computer
879network.
880
881There are two different ways iSCSI devices can be used by QEMU.
882
883The first method is to mount the iSCSI LUN on the host, and make it appear as
884any other ordinary SCSI device on the host and then to access this device as a
885/dev/sd device from QEMU. How to do this differs between host OSes.
886
887The second method involves using the iSCSI initiator that is built into
888QEMU. This provides a mechanism that works the same way regardless of which
889host OS you are running QEMU on. This section will describe this second method
890of using iSCSI together with QEMU.
891
892In QEMU, iSCSI devices are described using special iSCSI URLs
893
894@example
895URL syntax:
896iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
897@end example
898
899Username and password are optional and only used if your target is set up
900using CHAP authentication for access control.
901Alternatively the username and password can also be set via environment
902variables to have these not show up in the process list
903
904@example
905export LIBISCSI_CHAP_USERNAME=<username>
906export LIBISCSI_CHAP_PASSWORD=<password>
907iscsi://<host>/<target-iqn-name>/<lun>
908@end example
909
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100910Various session related parameters can be set via special options, either
911in a configuration file provided via '-readconfig' or directly on the
912command line.
913
Ronnie Sahlberg31459f42012-08-06 18:24:55 +1000914If the initiator-name is not specified qemu will use a default name
915of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
916virtual machine.
917
918
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100919@example
920Setting a specific initiator name to use when logging in to the target
921-iscsi initiator-name=iqn.qemu.test:my-initiator
922@end example
923
924@example
925Controlling which type of header digest to negotiate with the target
926-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
927@end example
928
929These can also be set via a configuration file
930@example
931[iscsi]
932 user = "CHAP username"
933 password = "CHAP password"
934 initiator-name = "iqn.qemu.test:my-initiator"
935 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
936 header-digest = "CRC32C"
937@end example
938
939
940Setting the target name allows different options for different targets
941@example
942[iscsi "iqn.target.name"]
943 user = "CHAP username"
944 password = "CHAP password"
945 initiator-name = "iqn.qemu.test:my-initiator"
946 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
947 header-digest = "CRC32C"
948@end example
949
950
951Howto use a configuration file to set iSCSI configuration options:
952@example
953cat >iscsi.conf <<EOF
954[iscsi]
955 user = "me"
956 password = "my password"
957 initiator-name = "iqn.qemu.test:my-initiator"
958 header-digest = "CRC32C"
959EOF
960
961qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
962 -readconfig iscsi.conf
963@end example
964
965
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100966Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
967@example
968This example shows how to set up an iSCSI target with one CDROM and one DISK
969using the Linux STGT software target. This target is available on Red Hat based
970systems as the package 'scsi-target-utils'.
971
972tgtd --iscsi portal=127.0.0.1:3260
973tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
974tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
975 -b /IMAGES/disk.img --device-type=disk
976tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
977 -b /IMAGES/cd.iso --device-type=cd
978tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
979
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100980qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
981 -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100982 -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
983@end example
984
Bharata B Rao8809e282012-10-24 17:17:53 +0530985@node disk_images_gluster
986@subsection GlusterFS disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100987
Bharata B Rao8809e282012-10-24 17:17:53 +0530988GlusterFS is an user space distributed file system.
989
990You can boot from the GlusterFS disk image with the command:
991@example
992qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
993@end example
994
995@var{gluster} is the protocol.
996
997@var{transport} specifies the transport type used to connect to gluster
998management daemon (glusterd). Valid transport types are
999tcp, unix and rdma. If a transport type isn't specified, then tcp
1000type is assumed.
1001
1002@var{server} specifies the server where the volume file specification for
1003the given volume resides. This can be either hostname, ipv4 address
1004or ipv6 address. ipv6 address needs to be within square brackets [ ].
1005If transport type is unix, then @var{server} field should not be specifed.
1006Instead @var{socket} field needs to be populated with the path to unix domain
1007socket.
1008
1009@var{port} is the port number on which glusterd is listening. This is optional
1010and if not specified, QEMU will send 0 which will make gluster to use the
1011default port. If the transport type is unix, then @var{port} should not be
1012specified.
1013
1014@var{volname} is the name of the gluster volume which contains the disk image.
1015
1016@var{image} is the path to the actual disk image that resides on gluster volume.
1017
1018You can create a GlusterFS disk image with the command:
1019@example
1020qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
1021@end example
1022
1023Examples
1024@example
1025qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1026qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1027qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1028qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1029qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1030qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1031qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1032qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
1033@end example
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001034
bellarddebc7062006-04-30 21:58:41 +00001035@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001036@section Network emulation
1037
ths4be456f2007-06-03 13:41:28 +00001038QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001039target) and can connect them to an arbitrary number of Virtual Local
1040Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1041VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001042simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001043network stack can replace the TAP device to have a basic network
1044connection.
bellard9d4fb822004-04-26 20:55:38 +00001045
bellard41d03942005-11-15 23:02:53 +00001046@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001047
bellard41d03942005-11-15 23:02:53 +00001048QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1049connection between several network devices. These devices can be for
1050example QEMU virtual Ethernet cards or virtual Host ethernet devices
1051(TAP devices).
1052
1053@subsection Using TAP network interfaces
1054
1055This is the standard way to connect QEMU to a real network. QEMU adds
1056a virtual network device on your host (called @code{tapN}), and you
1057can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001058
bellard8f40c382006-09-20 20:28:05 +00001059@subsubsection Linux host
1060
bellard9d4fb822004-04-26 20:55:38 +00001061As an example, you can download the @file{linux-test-xxx.tar.gz}
1062archive and copy the script @file{qemu-ifup} in @file{/etc} and
1063configure properly @code{sudo} so that the command @code{ifconfig}
1064contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001065that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001066device @file{/dev/net/tun} must be present.
1067
bellardee0f4752006-08-19 16:56:18 +00001068See @ref{sec_invocation} to have examples of command lines using the
1069TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001070
bellard8f40c382006-09-20 20:28:05 +00001071@subsubsection Windows host
1072
1073There is a virtual ethernet driver for Windows 2000/XP systems, called
1074TAP-Win32. But it is not included in standard QEMU for Windows,
1075so you will need to get it separately. It is part of OpenVPN package,
1076so download OpenVPN from : @url{http://openvpn.net/}.
1077
bellard9d4fb822004-04-26 20:55:38 +00001078@subsection Using the user mode network stack
1079
bellard41d03942005-11-15 23:02:53 +00001080By using the option @option{-net user} (default configuration if no
1081@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001082network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001083network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001084
1085@example
1086
bellard41d03942005-11-15 23:02:53 +00001087 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1088 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001089 |
bellard2518bd02004-09-30 22:35:13 +00001090 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001091 |
bellard2518bd02004-09-30 22:35:13 +00001092 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001093@end example
1094
1095The QEMU VM behaves as if it was behind a firewall which blocks all
1096incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001097configure the network in the QEMU VM. The DHCP server assign addresses
1098to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001099
1100In order to check that the user mode network is working, you can ping
1101the address 10.0.2.2 and verify that you got an address in the range
110210.0.2.x from the QEMU virtual DHCP server.
1103
bellardb415a402004-05-23 21:04:06 +00001104Note that @code{ping} is not supported reliably to the internet as it
ths4be456f2007-06-03 13:41:28 +00001105would require root privileges. It means you can only ping the local
bellardb415a402004-05-23 21:04:06 +00001106router (10.0.2.2).
1107
bellard9bf05442004-08-25 22:12:49 +00001108When using the built-in TFTP server, the router is also the TFTP
1109server.
1110
1111When using the @option{-redir} option, TCP or UDP connections can be
1112redirected from the host to the guest. It allows for example to
1113redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001114
bellard41d03942005-11-15 23:02:53 +00001115@subsection Connecting VLANs between QEMU instances
1116
1117Using the @option{-net socket} option, it is possible to make VLANs
1118that span several QEMU instances. See @ref{sec_invocation} to have a
1119basic example.
1120
Stefan Weil576fd0a2011-01-07 18:59:14 +01001121@node pcsys_other_devs
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001122@section Other Devices
1123
1124@subsection Inter-VM Shared Memory device
1125
1126With KVM enabled on a Linux host, a shared memory device is available. Guests
1127map a POSIX shared memory region into the guest as a PCI device that enables
1128zero-copy communication to the application level of the guests. The basic
1129syntax is:
1130
1131@example
Stefan Weil3804da92012-05-11 22:21:50 +02001132qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001133@end example
1134
1135If desired, interrupts can be sent between guest VMs accessing the same shared
1136memory region. Interrupt support requires using a shared memory server and
1137using a chardev socket to connect to it. The code for the shared memory server
1138is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
1139memory server is:
1140
1141@example
Stefan Weil3804da92012-05-11 22:21:50 +02001142qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
1143 [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
1144qemu-system-i386 -chardev socket,path=<path>,id=<id>
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001145@end example
1146
1147When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1148using the same server to communicate via interrupts. Guests can read their
1149VM ID from a device register (see example code). Since receiving the shared
1150memory region from the server is asynchronous, there is a (small) chance the
1151guest may boot before the shared memory is attached. To allow an application
1152to ensure shared memory is attached, the VM ID register will return -1 (an
1153invalid VM ID) until the memory is attached. Once the shared memory is
1154attached, the VM ID will return the guest's valid VM ID. With these semantics,
1155the guest application can check to ensure the shared memory is attached to the
1156guest before proceeding.
1157
1158The @option{role} argument can be set to either master or peer and will affect
1159how the shared memory is migrated. With @option{role=master}, the guest will
1160copy the shared memory on migration to the destination host. With
1161@option{role=peer}, the guest will not be able to migrate with the device attached.
1162With the @option{peer} case, the device should be detached and then reattached
1163after migration using the PCI hotplug support.
1164
bellard9d4fb822004-04-26 20:55:38 +00001165@node direct_linux_boot
1166@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001167
1168This section explains how to launch a Linux kernel inside QEMU without
1169having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001170kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001171
bellardee0f4752006-08-19 16:56:18 +00001172The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001173@example
Stefan Weil3804da92012-05-11 22:21:50 +02001174qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001175@end example
1176
bellardee0f4752006-08-19 16:56:18 +00001177Use @option{-kernel} to provide the Linux kernel image and
1178@option{-append} to give the kernel command line arguments. The
1179@option{-initrd} option can be used to provide an INITRD image.
1180
1181When using the direct Linux boot, a disk image for the first hard disk
1182@file{hda} is required because its boot sector is used to launch the
1183Linux kernel.
1184
1185If you do not need graphical output, you can disable it and redirect
1186the virtual serial port and the QEMU monitor to the console with the
1187@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001188@example
Stefan Weil3804da92012-05-11 22:21:50 +02001189qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1190 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001191@end example
1192
bellardee0f4752006-08-19 16:56:18 +00001193Use @key{Ctrl-a c} to switch between the serial console and the
1194monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001195
bellarddebc7062006-04-30 21:58:41 +00001196@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001197@section USB emulation
1198
pbrook0aff66b2006-05-26 00:49:52 +00001199QEMU emulates a PCI UHCI USB controller. You can virtually plug
1200virtual USB devices or real host USB devices (experimental, works only
Stefan Weil071c9392012-04-07 09:23:36 +02001201on Linux hosts). QEMU will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001202as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001203
pbrook0aff66b2006-05-26 00:49:52 +00001204@menu
1205* usb_devices::
1206* host_usb_devices::
1207@end menu
1208@node usb_devices
1209@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001210
pbrook0aff66b2006-05-26 00:49:52 +00001211USB devices can be connected with the @option{-usbdevice} commandline option
1212or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001213
balrogdb380c02008-01-17 22:22:45 +00001214@table @code
1215@item mouse
pbrook0aff66b2006-05-26 00:49:52 +00001216Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001217@item tablet
bellardc6d46c22006-09-03 17:10:41 +00001218Pointer device that uses absolute coordinates (like a touchscreen).
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001219This means QEMU is able to report the mouse position without having
pbrook0aff66b2006-05-26 00:49:52 +00001220to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001221@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +00001222Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +00001223@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +00001224Pass through the host device identified by @var{bus.addr}
1225(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001226@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +00001227Pass through the host device identified by @var{vendor_id:product_id}
1228(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001229@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +00001230Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1231above but it can be used with the tslib library because in addition to touch
1232coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +00001233@item keyboard
balrog47b2d332007-06-22 08:16:00 +00001234Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +00001235@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1236Serial converter. This emulates an FTDI FT232BM chip connected to host character
1237device @var{dev}. The available character devices are the same as for the
1238@code{-serial} option. The @code{vendorid} and @code{productid} options can be
Stefan Weil0d6753e2011-01-07 18:59:13 +01001239used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +00001240@example
1241usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1242@end example
1243will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1244serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +00001245@item braille
1246Braille device. This will use BrlAPI to display the braille output on a real
1247or fake device.
balrog9ad97e62008-07-29 13:16:31 +00001248@item net:@var{options}
1249Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1250specifies NIC options as with @code{-net nic,}@var{options} (see description).
1251For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +00001252@example
Stefan Weil3804da92012-05-11 22:21:50 +02001253qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +00001254@end example
1255Currently this cannot be used in machines that support PCI NICs.
balrog2d564692008-11-09 02:24:54 +00001256@item bt[:@var{hci-type}]
1257Bluetooth dongle whose type is specified in the same format as with
1258the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
1259no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1260This USB device implements the USB Transport Layer of HCI. Example
1261usage:
1262@example
Stefan Weil3804da92012-05-11 22:21:50 +02001263qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
balrog2d564692008-11-09 02:24:54 +00001264@end example
pbrook0aff66b2006-05-26 00:49:52 +00001265@end table
bellardb389dbf2005-11-06 16:49:55 +00001266
pbrook0aff66b2006-05-26 00:49:52 +00001267@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001268@subsection Using host USB devices on a Linux host
1269
1270WARNING: this is an experimental feature. QEMU will slow down when
1271using it. USB devices requiring real time streaming (i.e. USB Video
1272Cameras) are not supported yet.
1273
1274@enumerate
ths5fafdf22007-09-16 21:08:06 +00001275@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001276is actually using the USB device. A simple way to do that is simply to
1277disable the corresponding kernel module by renaming it from @file{mydriver.o}
1278to @file{mydriver.o.disabled}.
1279
1280@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1281@example
1282ls /proc/bus/usb
1283001 devices drivers
1284@end example
1285
1286@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:
1287@example
1288chown -R myuid /proc/bus/usb
1289@end example
1290
1291@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001292@example
bellardb389dbf2005-11-06 16:49:55 +00001293info usbhost
1294 Device 1.2, speed 480 Mb/s
1295 Class 00: USB device 1234:5678, USB DISK
1296@end example
1297You should see the list of the devices you can use (Never try to use
1298hubs, it won't work).
1299
1300@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001301@example
bellardb389dbf2005-11-06 16:49:55 +00001302usb_add host:1234:5678
1303@end example
1304
1305Normally the guest OS should report that a new USB device is
1306plugged. You can use the option @option{-usbdevice} to do the same.
1307
1308@item Now you can try to use the host USB device in QEMU.
1309
1310@end enumerate
1311
1312When relaunching QEMU, you may have to unplug and plug again the USB
1313device to make it work again (this is a bug).
1314
thsf858dca2007-08-25 01:40:37 +00001315@node vnc_security
1316@section VNC security
1317
1318The VNC server capability provides access to the graphical console
1319of the guest VM across the network. This has a number of security
1320considerations depending on the deployment scenarios.
1321
1322@menu
1323* vnc_sec_none::
1324* vnc_sec_password::
1325* vnc_sec_certificate::
1326* vnc_sec_certificate_verify::
1327* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +00001328* vnc_sec_sasl::
1329* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +00001330* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +00001331* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +00001332@end menu
1333@node vnc_sec_none
1334@subsection Without passwords
1335
1336The simplest VNC server setup does not include any form of authentication.
1337For this setup it is recommended to restrict it to listen on a UNIX domain
1338socket only. For example
1339
1340@example
Stefan Weil3804da92012-05-11 22:21:50 +02001341qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
thsf858dca2007-08-25 01:40:37 +00001342@end example
1343
1344This ensures that only users on local box with read/write access to that
1345path can access the VNC server. To securely access the VNC server from a
1346remote machine, a combination of netcat+ssh can be used to provide a secure
1347tunnel.
1348
1349@node vnc_sec_password
1350@subsection With passwords
1351
1352The VNC protocol has limited support for password based authentication. Since
1353the protocol limits passwords to 8 characters it should not be considered
1354to provide high security. The password can be fairly easily brute-forced by
1355a client making repeat connections. For this reason, a VNC server using password
1356authentication should be restricted to only listen on the loopback interface
Paul Moore0f669982012-08-03 14:39:21 -04001357or UNIX domain sockets. Password authentication is not supported when operating
1358in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1359authentication is requested with the @code{password} option, and then once QEMU
1360is running the password is set with the monitor. Until the monitor is used to
1361set the password all clients will be rejected.
thsf858dca2007-08-25 01:40:37 +00001362
1363@example
Stefan Weil3804da92012-05-11 22:21:50 +02001364qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001365(qemu) change vnc password
1366Password: ********
1367(qemu)
1368@end example
1369
1370@node vnc_sec_certificate
1371@subsection With x509 certificates
1372
1373The QEMU VNC server also implements the VeNCrypt extension allowing use of
1374TLS for encryption of the session, and x509 certificates for authentication.
1375The use of x509 certificates is strongly recommended, because TLS on its
1376own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1377support provides a secure session, but no authentication. This allows any
1378client to connect, and provides an encrypted session.
1379
1380@example
Stefan Weil3804da92012-05-11 22:21:50 +02001381qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001382@end example
1383
1384In the above example @code{/etc/pki/qemu} should contain at least three files,
1385@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1386users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1387NB the @code{server-key.pem} file should be protected with file mode 0600 to
1388only be readable by the user owning it.
1389
1390@node vnc_sec_certificate_verify
1391@subsection With x509 certificates and client verification
1392
1393Certificates can also provide a means to authenticate the client connecting.
1394The server will request that the client provide a certificate, which it will
1395then validate against the CA certificate. This is a good choice if deploying
1396in an environment with a private internal certificate authority.
1397
1398@example
Stefan Weil3804da92012-05-11 22:21:50 +02001399qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001400@end example
1401
1402
1403@node vnc_sec_certificate_pw
1404@subsection With x509 certificates, client verification and passwords
1405
1406Finally, the previous method can be combined with VNC password authentication
1407to provide two layers of authentication for clients.
1408
1409@example
Stefan Weil3804da92012-05-11 22:21:50 +02001410qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001411(qemu) change vnc password
1412Password: ********
1413(qemu)
1414@end example
1415
aliguori2f9606b2009-03-06 20:27:28 +00001416
1417@node vnc_sec_sasl
1418@subsection With SASL authentication
1419
1420The SASL authentication method is a VNC extension, that provides an
1421easily extendable, pluggable authentication method. This allows for
1422integration with a wide range of authentication mechanisms, such as
1423PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1424The strength of the authentication depends on the exact mechanism
1425configured. If the chosen mechanism also provides a SSF layer, then
1426it will encrypt the datastream as well.
1427
1428Refer to the later docs on how to choose the exact SASL mechanism
1429used for authentication, but assuming use of one supporting SSF,
1430then QEMU can be launched with:
1431
1432@example
Stefan Weil3804da92012-05-11 22:21:50 +02001433qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001434@end example
1435
1436@node vnc_sec_certificate_sasl
1437@subsection With x509 certificates and SASL authentication
1438
1439If the desired SASL authentication mechanism does not supported
1440SSF layers, then it is strongly advised to run it in combination
1441with TLS and x509 certificates. This provides securely encrypted
1442data stream, avoiding risk of compromising of the security
1443credentials. This can be enabled, by combining the 'sasl' option
1444with the aforementioned TLS + x509 options:
1445
1446@example
Stefan Weil3804da92012-05-11 22:21:50 +02001447qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001448@end example
1449
1450
thsf858dca2007-08-25 01:40:37 +00001451@node vnc_generate_cert
1452@subsection Generating certificates for VNC
1453
1454The GNU TLS packages provides a command called @code{certtool} which can
1455be used to generate certificates and keys in PEM format. At a minimum it
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001456is necessary to setup a certificate authority, and issue certificates to
thsf858dca2007-08-25 01:40:37 +00001457each server. If using certificates for authentication, then each client
1458will also need to be issued a certificate. The recommendation is for the
1459server to keep its certificates in either @code{/etc/pki/qemu} or for
1460unprivileged users in @code{$HOME/.pki/qemu}.
1461
1462@menu
1463* vnc_generate_ca::
1464* vnc_generate_server::
1465* vnc_generate_client::
1466@end menu
1467@node vnc_generate_ca
1468@subsubsection Setup the Certificate Authority
1469
1470This step only needs to be performed once per organization / organizational
1471unit. First the CA needs a private key. This key must be kept VERY secret
1472and secure. If this key is compromised the entire trust chain of the certificates
1473issued with it is lost.
1474
1475@example
1476# certtool --generate-privkey > ca-key.pem
1477@end example
1478
1479A CA needs to have a public certificate. For simplicity it can be a self-signed
1480certificate, or one issue by a commercial certificate issuing authority. To
1481generate a self-signed certificate requires one core piece of information, the
1482name of the organization.
1483
1484@example
1485# cat > ca.info <<EOF
1486cn = Name of your organization
1487ca
1488cert_signing_key
1489EOF
1490# certtool --generate-self-signed \
1491 --load-privkey ca-key.pem
1492 --template ca.info \
1493 --outfile ca-cert.pem
1494@end example
1495
1496The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1497TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1498
1499@node vnc_generate_server
1500@subsubsection Issuing server certificates
1501
1502Each server (or host) needs to be issued with a key and certificate. When connecting
1503the certificate is sent to the client which validates it against the CA certificate.
1504The core piece of information for a server certificate is the hostname. This should
1505be the fully qualified hostname that the client will connect with, since the client
1506will typically also verify the hostname in the certificate. On the host holding the
1507secure CA private key:
1508
1509@example
1510# cat > server.info <<EOF
1511organization = Name of your organization
1512cn = server.foo.example.com
1513tls_www_server
1514encryption_key
1515signing_key
1516EOF
1517# certtool --generate-privkey > server-key.pem
1518# certtool --generate-certificate \
1519 --load-ca-certificate ca-cert.pem \
1520 --load-ca-privkey ca-key.pem \
1521 --load-privkey server server-key.pem \
1522 --template server.info \
1523 --outfile server-cert.pem
1524@end example
1525
1526The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1527to the server for which they were generated. The @code{server-key.pem} is security
1528sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1529
1530@node vnc_generate_client
1531@subsubsection Issuing client certificates
1532
1533If the QEMU VNC server is to use the @code{x509verify} option to validate client
1534certificates as its authentication mechanism, each client also needs to be issued
1535a certificate. The client certificate contains enough metadata to uniquely identify
1536the client, typically organization, state, city, building, etc. On the host holding
1537the secure CA private key:
1538
1539@example
1540# cat > client.info <<EOF
1541country = GB
1542state = London
1543locality = London
1544organiazation = Name of your organization
1545cn = client.foo.example.com
1546tls_www_client
1547encryption_key
1548signing_key
1549EOF
1550# certtool --generate-privkey > client-key.pem
1551# certtool --generate-certificate \
1552 --load-ca-certificate ca-cert.pem \
1553 --load-ca-privkey ca-key.pem \
1554 --load-privkey client-key.pem \
1555 --template client.info \
1556 --outfile client-cert.pem
1557@end example
1558
1559The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1560copied to the client for which they were generated.
1561
aliguori2f9606b2009-03-06 20:27:28 +00001562
1563@node vnc_setup_sasl
1564
1565@subsection Configuring SASL mechanisms
1566
1567The following documentation assumes use of the Cyrus SASL implementation on a
1568Linux host, but the principals should apply to any other SASL impl. When SASL
1569is enabled, the mechanism configuration will be loaded from system default
1570SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1571unprivileged user, an environment variable SASL_CONF_PATH can be used
1572to make it search alternate locations for the service config.
1573
1574The default configuration might contain
1575
1576@example
1577mech_list: digest-md5
1578sasldb_path: /etc/qemu/passwd.db
1579@end example
1580
1581This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1582Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1583in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1584command. While this mechanism is easy to configure and use, it is not
1585considered secure by modern standards, so only suitable for developers /
1586ad-hoc testing.
1587
1588A more serious deployment might use Kerberos, which is done with the 'gssapi'
1589mechanism
1590
1591@example
1592mech_list: gssapi
1593keytab: /etc/qemu/krb5.tab
1594@end example
1595
1596For this to work the administrator of your KDC must generate a Kerberos
1597principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
1598replacing 'somehost.example.com' with the fully qualified host name of the
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001599machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
aliguori2f9606b2009-03-06 20:27:28 +00001600
1601Other configurations will be left as an exercise for the reader. It should
1602be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1603encryption. For all other mechanisms, VNC should always be configured to
1604use TLS and x509 certificates to protect security credentials from snooping.
1605
bellard0806e3f2003-10-01 00:15:32 +00001606@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001607@section GDB usage
1608
1609QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001610'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001611
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001612In order to use gdb, launch QEMU with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001613gdb connection:
1614@example
Stefan Weil3804da92012-05-11 22:21:50 +02001615qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1616 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001617Connected to host network interface: tun0
1618Waiting gdb connection on port 1234
1619@end example
1620
1621Then launch gdb on the 'vmlinux' executable:
1622@example
1623> gdb vmlinux
1624@end example
1625
1626In gdb, connect to QEMU:
1627@example
bellard6c9bf892004-01-24 13:46:56 +00001628(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001629@end example
1630
1631Then you can use gdb normally. For example, type 'c' to launch the kernel:
1632@example
1633(gdb) c
1634@end example
1635
bellard0806e3f2003-10-01 00:15:32 +00001636Here are some useful tips in order to use gdb on system code:
1637
1638@enumerate
1639@item
1640Use @code{info reg} to display all the CPU registers.
1641@item
1642Use @code{x/10i $eip} to display the code at the PC position.
1643@item
1644Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001645@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001646@end enumerate
1647
edgar_igl60897d32008-05-09 08:25:14 +00001648Advanced debugging options:
1649
1650The 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 +00001651@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001652@item maintenance packet qqemu.sstepbits
1653
1654This will display the MASK bits used to control the single stepping IE:
1655@example
1656(gdb) maintenance packet qqemu.sstepbits
1657sending: "qqemu.sstepbits"
1658received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1659@end example
1660@item maintenance packet qqemu.sstep
1661
1662This will display the current value of the mask used when single stepping IE:
1663@example
1664(gdb) maintenance packet qqemu.sstep
1665sending: "qqemu.sstep"
1666received: "0x7"
1667@end example
1668@item maintenance packet Qqemu.sstep=HEX_VALUE
1669
1670This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1671@example
1672(gdb) maintenance packet Qqemu.sstep=0x5
1673sending: "qemu.sstep=0x5"
1674received: "OK"
1675@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001676@end table
edgar_igl60897d32008-05-09 08:25:14 +00001677
bellarddebc7062006-04-30 21:58:41 +00001678@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001679@section Target OS specific information
1680
1681@subsection Linux
1682
bellard15a34c62004-07-08 21:26:26 +00001683To have access to SVGA graphic modes under X11, use the @code{vesa} or
1684the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1685color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001686
bellarde3371e62004-07-10 16:26:02 +00001687When using a 2.6 guest Linux kernel, you should add the option
1688@code{clock=pit} on the kernel command line because the 2.6 Linux
1689kernels make very strict real time clock checks by default that QEMU
1690cannot simulate exactly.
1691
bellard7c3fc842005-02-10 21:46:47 +00001692When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1693not activated because QEMU is slower with this patch. The QEMU
1694Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001695Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001696patch by default. Newer kernels don't have it.
1697
bellard1a084f32004-05-13 22:34:49 +00001698@subsection Windows
1699
1700If you have a slow host, using Windows 95 is better as it gives the
1701best speed. Windows 2000 is also a good choice.
1702
bellarde3371e62004-07-10 16:26:02 +00001703@subsubsection SVGA graphic modes support
1704
1705QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001706card. All Windows versions starting from Windows 95 should recognize
1707and use this graphic card. For optimal performances, use 16 bit color
1708depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001709
bellard3cb08532006-06-21 21:19:50 +00001710If you are using Windows XP as guest OS and if you want to use high
1711resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
17121280x1024x16), then you should use the VESA VBE virtual graphic card
1713(option @option{-std-vga}).
1714
bellarde3371e62004-07-10 16:26:02 +00001715@subsubsection CPU usage reduction
1716
1717Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001718instruction. The result is that it takes host CPU cycles even when
1719idle. You can install the utility from
1720@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1721problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001722
bellard9d0a8e62005-07-03 17:34:05 +00001723@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001724
bellard9d0a8e62005-07-03 17:34:05 +00001725Windows 2000 has a bug which gives a disk full problem during its
1726installation. When installing it, use the @option{-win2k-hack} QEMU
1727option to enable a specific workaround. After Windows 2000 is
1728installed, you no longer need this option (this option slows down the
1729IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001730
bellard6cc721c2005-07-28 22:27:28 +00001731@subsubsection Windows 2000 shutdown
1732
1733Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1734can. It comes from the fact that Windows 2000 does not automatically
1735use the APM driver provided by the BIOS.
1736
1737In order to correct that, do the following (thanks to Struan
1738Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1739Add/Troubleshoot a device => Add a new device & Next => No, select the
1740hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1741(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001742correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001743
1744@subsubsection Share a directory between Unix and Windows
1745
1746See @ref{sec_invocation} about the help of the option @option{-smb}.
1747
bellard2192c332006-08-21 20:28:18 +00001748@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001749
1750Some releases of Windows XP install correctly but give a security
1751error when booting:
1752@example
1753A problem is preventing Windows from accurately checking the
1754license for this computer. Error code: 0x800703e6.
1755@end example
bellarde3371e62004-07-10 16:26:02 +00001756
bellard2192c332006-08-21 20:28:18 +00001757The workaround is to install a service pack for XP after a boot in safe
1758mode. Then reboot, and the problem should go away. Since there is no
1759network while in safe mode, its recommended to download the full
1760installation of SP1 or SP2 and transfer that via an ISO or using the
1761vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001762
bellarda0a821a2004-07-14 17:38:57 +00001763@subsection MS-DOS and FreeDOS
1764
1765@subsubsection CPU usage reduction
1766
1767DOS does not correctly use the CPU HLT instruction. The result is that
1768it takes host CPU cycles even when idle. You can install the utility
1769from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1770problem.
1771
bellarddebc7062006-04-30 21:58:41 +00001772@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001773@chapter QEMU System emulator for non PC targets
1774
1775QEMU is a generic emulator and it emulates many non PC
1776machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001777differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001778
bellarddebc7062006-04-30 21:58:41 +00001779@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001780* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001781* Sparc32 System emulator::
1782* Sparc64 System emulator::
1783* MIPS System emulator::
1784* ARM System emulator::
1785* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001786* Cris System emulator::
1787* Microblaze System emulator::
1788* SH4 System emulator::
Max Filippov3aeaea62011-10-10 14:48:23 +04001789* Xtensa System emulator::
bellarddebc7062006-04-30 21:58:41 +00001790@end menu
1791
Stefan Weil7544a042010-02-05 23:52:03 +01001792@node PowerPC System emulator
1793@section PowerPC System emulator
1794@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001795
1796Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001797or PowerMac PowerPC system.
1798
bellardb671f9e2005-04-30 15:08:33 +00001799QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001800
1801@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001802@item
blueswir1006f3a42009-02-08 15:59:36 +00001803UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001804@item
1805PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001806@item
bellard15a34c62004-07-08 21:26:26 +000018072 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001808@item
bellard15a34c62004-07-08 21:26:26 +00001809NE2000 PCI adapters
1810@item
1811Non Volatile RAM
1812@item
1813VIA-CUDA with ADB keyboard and mouse.
1814@end itemize
bellard52c00a52004-04-25 21:27:03 +00001815
bellardb671f9e2005-04-30 15:08:33 +00001816QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001817
1818@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001819@item
bellard15a34c62004-07-08 21:26:26 +00001820PCI Bridge
1821@item
1822PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001823@item
bellard52c00a52004-04-25 21:27:03 +000018242 IDE interfaces with hard disk and CD-ROM support
1825@item
1826Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001827@item
bellard15a34c62004-07-08 21:26:26 +00001828NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001829@item
1830Serial port
1831@item
1832PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001833@item
1834PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001835@end itemize
1836
bellard15a34c62004-07-08 21:26:26 +00001837QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001838@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001839
blueswir1992e5ac2008-12-24 20:23:51 +00001840Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00001841for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1842v2) portable firmware implementation. The goal is to implement a 100%
1843IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00001844
bellard15a34c62004-07-08 21:26:26 +00001845@c man begin OPTIONS
1846
1847The following options are specific to the PowerPC emulation:
1848
1849@table @option
1850
Kevin Wolf4e257e52009-10-09 10:58:36 +02001851@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00001852
1853Set the initial VGA graphic mode. The default is 800x600x15.
1854
Kevin Wolf4e257e52009-10-09 10:58:36 +02001855@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00001856
1857Set OpenBIOS variables in NVRAM, for example:
1858
1859@example
1860qemu-system-ppc -prom-env 'auto-boot?=false' \
1861 -prom-env 'boot-device=hd:2,\yaboot' \
1862 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1863@end example
1864
1865These variables are not used by Open Hack'Ware.
1866
bellard15a34c62004-07-08 21:26:26 +00001867@end table
1868
ths5fafdf22007-09-16 21:08:06 +00001869@c man end
bellard15a34c62004-07-08 21:26:26 +00001870
1871
bellard52c00a52004-04-25 21:27:03 +00001872More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00001873@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00001874
ths24d4de42007-07-11 10:24:28 +00001875@node Sparc32 System emulator
1876@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001877@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00001878
blueswir134a3d232008-10-04 20:43:39 +00001879Use the executable @file{qemu-system-sparc} to simulate the following
1880Sun4m architecture machines:
1881@itemize @minus
1882@item
1883SPARCstation 4
1884@item
1885SPARCstation 5
1886@item
1887SPARCstation 10
1888@item
1889SPARCstation 20
1890@item
1891SPARCserver 600MP
1892@item
1893SPARCstation LX
1894@item
1895SPARCstation Voyager
1896@item
1897SPARCclassic
1898@item
1899SPARCbook
1900@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00001901
blueswir134a3d232008-10-04 20:43:39 +00001902The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1903but Linux limits the number of usable CPUs to 4.
1904
1905It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1906SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1907emulators are not usable yet.
1908
1909QEMU emulates the following sun4m/sun4c/sun4d peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00001910
1911@itemize @minus
bellard34751872005-07-02 14:31:34 +00001912@item
blueswir17d858922007-12-28 20:57:43 +00001913IOMMU or IO-UNITs
bellarde80cfcf2004-12-19 23:18:01 +00001914@item
1915TCX Frame buffer
ths5fafdf22007-09-16 21:08:06 +00001916@item
bellarde80cfcf2004-12-19 23:18:01 +00001917Lance (Am7990) Ethernet
1918@item
blueswir134a3d232008-10-04 20:43:39 +00001919Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00001920@item
bellard34751872005-07-02 14:31:34 +00001921Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1922and power/reset logic
1923@item
1924ESP SCSI controller with hard disk and CD-ROM support
1925@item
blueswir16a3b9cc2007-11-11 17:56:38 +00001926Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00001927@item
1928CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00001929@end itemize
1930
blueswir16a3b9cc2007-11-11 17:56:38 +00001931The number of peripherals is fixed in the architecture. Maximum
1932memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00001933others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00001934
bellard30a604f2006-06-14 18:35:18 +00001935Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00001936@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1937firmware implementation. The goal is to implement a 100% IEEE
19381275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00001939
1940A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00001941the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1942some kernel versions work. Please note that currently Solaris kernels
1943don't work probably due to interface issues between OpenBIOS and
1944Solaris.
bellard34751872005-07-02 14:31:34 +00001945
1946@c man begin OPTIONS
1947
blueswir1a2502b52007-06-10 17:01:00 +00001948The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00001949
1950@table @option
1951
Kevin Wolf4e257e52009-10-09 10:58:36 +02001952@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00001953
blueswir1a2502b52007-06-10 17:01:00 +00001954Set the initial TCX graphic mode. The default is 1024x768x8, currently
1955the only other possible mode is 1024x768x24.
bellard34751872005-07-02 14:31:34 +00001956
Kevin Wolf4e257e52009-10-09 10:58:36 +02001957@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00001958
1959Set OpenBIOS variables in NVRAM, for example:
1960
1961@example
1962qemu-system-sparc -prom-env 'auto-boot?=false' \
1963 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1964@end example
1965
Blue Swirl609c1da2010-03-18 18:41:49 +00001966@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 +00001967
1968Set the emulated machine type. Default is SS-5.
1969
bellard34751872005-07-02 14:31:34 +00001970@end table
1971
ths5fafdf22007-09-16 21:08:06 +00001972@c man end
bellard34751872005-07-02 14:31:34 +00001973
ths24d4de42007-07-11 10:24:28 +00001974@node Sparc64 System emulator
1975@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001976@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00001977
blueswir134a3d232008-10-04 20:43:39 +00001978Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1979(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1980Niagara (T1) machine. The emulator is not usable for anything yet, but
1981it can launch some kernels.
bellardb7569212005-03-13 09:43:05 +00001982
blueswir1c7ba2182008-07-22 07:07:34 +00001983QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00001984
1985@itemize @minus
1986@item
ths5fafdf22007-09-16 21:08:06 +00001987UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00001988@item
1989PCI VGA compatible card with VESA Bochs Extensions
1990@item
blueswir134a3d232008-10-04 20:43:39 +00001991PS/2 mouse and keyboard
1992@item
bellard83469012005-07-23 14:27:54 +00001993Non Volatile RAM M48T59
1994@item
1995PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00001996@item
19972 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00001998@item
1999Floppy disk
bellard83469012005-07-23 14:27:54 +00002000@end itemize
2001
blueswir1c7ba2182008-07-22 07:07:34 +00002002@c man begin OPTIONS
2003
2004The following options are specific to the Sparc64 emulation:
2005
2006@table @option
2007
Kevin Wolf4e257e52009-10-09 10:58:36 +02002008@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00002009
2010Set OpenBIOS variables in NVRAM, for example:
2011
2012@example
2013qemu-system-sparc64 -prom-env 'auto-boot?=false'
2014@end example
2015
2016@item -M [sun4u|sun4v|Niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00002017
2018Set the emulated machine type. The default is sun4u.
2019
2020@end table
2021
2022@c man end
2023
ths24d4de42007-07-11 10:24:28 +00002024@node MIPS System emulator
2025@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002026@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00002027
thsd9aedc32007-12-17 03:47:55 +00002028Four executables cover simulation of 32 and 64-bit MIPS systems in
2029both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2030@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00002031Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002032
2033@itemize @minus
2034@item
2035A generic ISA PC-like machine "mips"
2036@item
2037The MIPS Malta prototype board "malta"
2038@item
thsd9aedc32007-12-17 03:47:55 +00002039An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002040@item
thsf0fc6f82007-10-17 13:39:42 +00002041MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00002042@item
2043A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00002044@end itemize
2045
2046The generic emulation is supported by Debian 'Etch' and is able to
2047install Debian into a virtual disk image. The following devices are
2048emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002049
bellard3f9f3aa2005-12-18 20:11:37 +00002050@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002051@item
ths6bf5b4e2007-10-17 13:08:32 +00002052A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002053@item
2054PC style serial port
2055@item
ths24d4de42007-07-11 10:24:28 +00002056PC style IDE disk
2057@item
bellard3f9f3aa2005-12-18 20:11:37 +00002058NE2000 network card
2059@end itemize
2060
ths24d4de42007-07-11 10:24:28 +00002061The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002062
ths24d4de42007-07-11 10:24:28 +00002063@itemize @minus
2064@item
ths0b64d002007-07-11 21:43:14 +00002065Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002066@item
2067PIIX4 PCI/USB/SMbus controller
2068@item
2069The Multi-I/O chip's serial device
2070@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02002071PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00002072@item
2073Malta FPGA serial device
2074@item
aurel321f605a72009-02-08 14:51:19 +00002075Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00002076@end itemize
2077
2078The ACER Pica emulation supports:
2079
2080@itemize @minus
2081@item
2082MIPS R4000 CPU
2083@item
2084PC-style IRQ and DMA controllers
2085@item
2086PC Keyboard
2087@item
2088IDE controller
2089@end itemize
2090
Stefan Weilb5e49462011-11-13 22:24:26 +01002091The mipssim pseudo board emulation provides an environment similar
thsf0fc6f82007-10-17 13:39:42 +00002092to what the proprietary MIPS emulator uses for running Linux.
2093It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002094
2095@itemize @minus
2096@item
2097A range of MIPS CPUs, default is the 24Kf
2098@item
2099PC style serial port
2100@item
2101MIPSnet network emulation
2102@end itemize
2103
aurel3288cb0a02008-04-08 05:57:37 +00002104The MIPS Magnum R4000 emulation supports:
2105
2106@itemize @minus
2107@item
2108MIPS R4000 CPU
2109@item
2110PC-style IRQ controller
2111@item
2112PC Keyboard
2113@item
2114SCSI controller
2115@item
2116G364 framebuffer
2117@end itemize
2118
2119
ths24d4de42007-07-11 10:24:28 +00002120@node ARM System emulator
2121@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002122@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00002123
2124Use the executable @file{qemu-system-arm} to simulate a ARM
2125machine. The ARM Integrator/CP board is emulated with the following
2126devices:
2127
2128@itemize @minus
2129@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002130ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002131@item
2132Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002133@item
bellard3f9f3aa2005-12-18 20:11:37 +00002134SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002135@item
2136PL110 LCD controller
2137@item
2138PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002139@item
2140PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002141@end itemize
2142
2143The ARM Versatile baseboard is emulated with the following devices:
2144
2145@itemize @minus
2146@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002147ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002148@item
2149PL190 Vectored Interrupt Controller
2150@item
2151Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002152@item
pbrook00a9bf12006-05-13 16:55:46 +00002153SMC 91c111 Ethernet adapter
2154@item
2155PL110 LCD controller
2156@item
2157PL050 KMI with PS/2 keyboard and mouse.
2158@item
2159PCI host bridge. Note the emulated PCI bridge only provides access to
2160PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002161This means some devices (eg. ne2k_pci NIC) are not usable, and others
2162(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002163mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002164@item
2165PCI OHCI USB controller.
2166@item
2167LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002168@item
2169PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002170@end itemize
2171
Paul Brook21a88942009-12-21 20:19:12 +00002172Several variants of the ARM RealView baseboard are emulated,
2173including the EB, PB-A8 and PBX-A9. Due to interactions with the
2174bootloader, only certain Linux kernel configurations work out
2175of the box on these boards.
2176
2177Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2178enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
2179should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2180disabled and expect 1024M RAM.
2181
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002182The following devices are emulated:
pbrookd7739d72007-02-28 16:25:17 +00002183
2184@itemize @minus
2185@item
Paul Brookf7c70322009-11-19 16:45:21 +00002186ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00002187@item
2188ARM AMBA Generic/Distributed Interrupt Controller
2189@item
2190Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002191@item
Paul Brook0ef849d2009-11-16 17:06:43 +00002192SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00002193@item
2194PL110 LCD controller
2195@item
2196PL050 KMI with PS/2 keyboard and mouse
2197@item
2198PCI host bridge
2199@item
2200PCI OHCI USB controller
2201@item
2202LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002203@item
2204PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002205@end itemize
2206
balrogb00052e2007-04-30 02:22:06 +00002207The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2208and "Terrier") emulation includes the following peripherals:
2209
2210@itemize @minus
2211@item
2212Intel PXA270 System-on-chip (ARM V5TE core)
2213@item
2214NAND Flash memory
2215@item
2216IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2217@item
2218On-chip OHCI USB controller
2219@item
2220On-chip LCD controller
2221@item
2222On-chip Real Time Clock
2223@item
2224TI ADS7846 touchscreen controller on SSP bus
2225@item
2226Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2227@item
2228GPIO-connected keyboard controller and LEDs
2229@item
balrog549444e2007-05-01 17:53:37 +00002230Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002231@item
2232Three on-chip UARTs
2233@item
2234WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2235@end itemize
2236
balrog02645922007-11-03 12:50:46 +00002237The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2238following elements:
2239
2240@itemize @minus
2241@item
2242Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2243@item
2244ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2245@item
2246On-chip LCD controller
2247@item
2248On-chip Real Time Clock
2249@item
2250TI TSC2102i touchscreen controller / analog-digital converter / Audio
2251CODEC, connected through MicroWire and I@math{^2}S busses
2252@item
2253GPIO-connected matrix keypad
2254@item
2255Secure Digital card connected to OMAP MMC/SD host
2256@item
2257Three on-chip UARTs
2258@end itemize
2259
balrogc30bb262008-05-18 13:01:40 +00002260Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2261emulation supports the following elements:
2262
2263@itemize @minus
2264@item
2265Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2266@item
2267RAM and non-volatile OneNAND Flash memories
2268@item
2269Display connected to EPSON remote framebuffer chip and OMAP on-chip
2270display controller and a LS041y3 MIPI DBI-C controller
2271@item
2272TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2273driven through SPI bus
2274@item
2275National Semiconductor LM8323-controlled qwerty keyboard driven
2276through I@math{^2}C bus
2277@item
2278Secure Digital card connected to OMAP MMC/SD host
2279@item
2280Three OMAP on-chip UARTs and on-chip STI debugging console
2281@item
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002282A Bluetooth(R) transceiver and HCI connected to an UART
balrog2d564692008-11-09 02:24:54 +00002283@item
balrogc30bb262008-05-18 13:01:40 +00002284Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2285TUSB6010 chip - only USB host mode is supported
2286@item
2287TI TMP105 temperature sensor driven through I@math{^2}C bus
2288@item
2289TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2290@item
2291Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2292through CBUS
2293@end itemize
2294
pbrook9ee6e8b2007-11-11 00:04:49 +00002295The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2296devices:
2297
2298@itemize @minus
2299@item
2300Cortex-M3 CPU core.
2301@item
230264k Flash and 8k SRAM.
2303@item
2304Timers, UARTs, ADC and I@math{^2}C interface.
2305@item
2306OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2307@end itemize
2308
2309The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2310devices:
2311
2312@itemize @minus
2313@item
2314Cortex-M3 CPU core.
2315@item
2316256k Flash and 64k SRAM.
2317@item
2318Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2319@item
2320OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2321@end itemize
2322
balrog57cd6e92008-05-07 12:23:32 +00002323The Freecom MusicPal internet radio emulation includes the following
2324elements:
2325
2326@itemize @minus
2327@item
2328Marvell MV88W8618 ARM core.
2329@item
233032 MB RAM, 256 KB SRAM, 8 MB flash.
2331@item
2332Up to 2 16550 UARTs
2333@item
2334MV88W8xx8 Ethernet controller
2335@item
2336MV88W8618 audio controller, WM8750 CODEC and mixer
2337@item
Stefan Weile080e782010-02-05 23:52:00 +01002338128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00002339@item
23402 buttons, 2 navigation wheels with button function
2341@end itemize
2342
balrog997641a2008-12-15 02:05:00 +00002343The Siemens SX1 models v1 and v2 (default) basic emulation.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002344The emulation includes the following elements:
balrog997641a2008-12-15 02:05:00 +00002345
2346@itemize @minus
2347@item
2348Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2349@item
2350ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2351V1
23521 Flash of 16MB and 1 Flash of 8MB
2353V2
23541 Flash of 32MB
2355@item
2356On-chip LCD controller
2357@item
2358On-chip Real Time Clock
2359@item
2360Secure Digital card connected to OMAP MMC/SD host
2361@item
2362Three on-chip UARTs
2363@end itemize
2364
bellard3f9f3aa2005-12-18 20:11:37 +00002365A Linux 2.6 test image is available on the QEMU web site. More
2366information is available in the QEMU mailing-list archive.
2367
blueswir1d2c639d2009-01-24 18:19:25 +00002368@c man begin OPTIONS
2369
2370The following options are specific to the ARM emulation:
2371
2372@table @option
2373
2374@item -semihosting
2375Enable semihosting syscall emulation.
2376
2377On ARM this implements the "Angel" interface.
2378
2379Note that this allows guest direct access to the host filesystem,
2380so should only be used with trusted guest OS.
2381
2382@end table
2383
ths24d4de42007-07-11 10:24:28 +00002384@node ColdFire System emulator
2385@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002386@cindex system emulation (ColdFire)
2387@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002388
2389Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2390The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002391
2392The M5208EVB emulation includes the following devices:
2393
2394@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002395@item
pbrook707e0112007-06-04 00:50:06 +00002396MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2397@item
2398Three Two on-chip UARTs.
2399@item
2400Fast Ethernet Controller (FEC)
2401@end itemize
2402
2403The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002404
2405@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002406@item
pbrook209a4e62007-05-23 20:16:15 +00002407MCF5206 ColdFire V2 Microprocessor.
2408@item
2409Two on-chip UARTs.
2410@end itemize
2411
blueswir1d2c639d2009-01-24 18:19:25 +00002412@c man begin OPTIONS
2413
Stefan Weil7544a042010-02-05 23:52:03 +01002414The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002415
2416@table @option
2417
2418@item -semihosting
2419Enable semihosting syscall emulation.
2420
2421On M68K this implements the "ColdFire GDB" interface used by libgloss.
2422
2423Note that this allows guest direct access to the host filesystem,
2424so should only be used with trusted guest OS.
2425
2426@end table
2427
Stefan Weil7544a042010-02-05 23:52:03 +01002428@node Cris System emulator
2429@section Cris System emulator
2430@cindex system emulation (Cris)
2431
2432TODO
2433
2434@node Microblaze System emulator
2435@section Microblaze System emulator
2436@cindex system emulation (Microblaze)
2437
2438TODO
2439
2440@node SH4 System emulator
2441@section SH4 System emulator
2442@cindex system emulation (SH4)
2443
2444TODO
2445
Max Filippov3aeaea62011-10-10 14:48:23 +04002446@node Xtensa System emulator
2447@section Xtensa System emulator
2448@cindex system emulation (Xtensa)
2449
2450Two executables cover simulation of both Xtensa endian options,
2451@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2452Two different machine types are emulated:
2453
2454@itemize @minus
2455@item
2456Xtensa emulator pseudo board "sim"
2457@item
2458Avnet LX60/LX110/LX200 board
2459@end itemize
2460
Stefan Weilb5e49462011-11-13 22:24:26 +01002461The sim pseudo board emulation provides an environment similar
Max Filippov3aeaea62011-10-10 14:48:23 +04002462to one provided by the proprietary Tensilica ISS.
2463It supports:
2464
2465@itemize @minus
2466@item
2467A range of Xtensa CPUs, default is the DC232B
2468@item
2469Console and filesystem access via semihosting calls
2470@end itemize
2471
2472The Avnet LX60/LX110/LX200 emulation supports:
2473
2474@itemize @minus
2475@item
2476A range of Xtensa CPUs, default is the DC232B
2477@item
247816550 UART
2479@item
2480OpenCores 10/100 Mbps Ethernet MAC
2481@end itemize
2482
2483@c man begin OPTIONS
2484
2485The following options are specific to the Xtensa emulation:
2486
2487@table @option
2488
2489@item -semihosting
2490Enable semihosting syscall emulation.
2491
2492Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2493Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2494
2495Note that this allows guest direct access to the host filesystem,
2496so should only be used with trusted guest OS.
2497
2498@end table
ths5fafdf22007-09-16 21:08:06 +00002499@node QEMU User space emulator
2500@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002501
2502@menu
2503* Supported Operating Systems ::
2504* Linux User space emulator::
blueswir184778502008-10-26 20:33:16 +00002505* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002506@end menu
2507
2508@node Supported Operating Systems
2509@section Supported Operating Systems
2510
2511The following OS are supported in user space emulation:
2512
2513@itemize @minus
2514@item
ths4be456f2007-06-03 13:41:28 +00002515Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002516@item
blueswir184778502008-10-26 20:33:16 +00002517BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002518@end itemize
2519
2520@node Linux User space emulator
2521@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002522
bellarddebc7062006-04-30 21:58:41 +00002523@menu
2524* Quick Start::
2525* Wine launch::
2526* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002527* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002528@end menu
2529
2530@node Quick Start
bellard83195232007-02-05 19:42:07 +00002531@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002532
bellard1f673132004-04-04 15:21:17 +00002533In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002534itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002535
bellard1f673132004-04-04 15:21:17 +00002536@itemize
bellard386405f2003-03-23 21:28:45 +00002537
bellard1f673132004-04-04 15:21:17 +00002538@item On x86, you can just try to launch any process by using the native
2539libraries:
bellard386405f2003-03-23 21:28:45 +00002540
ths5fafdf22007-09-16 21:08:06 +00002541@example
bellard1f673132004-04-04 15:21:17 +00002542qemu-i386 -L / /bin/ls
2543@end example
bellardfd429f22003-03-30 20:59:46 +00002544
bellard1f673132004-04-04 15:21:17 +00002545@code{-L /} tells that the x86 dynamic linker must be searched with a
2546@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002547
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002548@item Since QEMU is also a linux process, you can launch QEMU with
2549QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002550
ths5fafdf22007-09-16 21:08:06 +00002551@example
bellard1f673132004-04-04 15:21:17 +00002552qemu-i386 -L / qemu-i386 -L / /bin/ls
2553@end example
bellard386405f2003-03-23 21:28:45 +00002554
bellard1f673132004-04-04 15:21:17 +00002555@item On non x86 CPUs, you need first to download at least an x86 glibc
2556(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2557@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002558
bellard1f673132004-04-04 15:21:17 +00002559@example
ths5fafdf22007-09-16 21:08:06 +00002560unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002561@end example
bellard386405f2003-03-23 21:28:45 +00002562
bellard1f673132004-04-04 15:21:17 +00002563Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002564
bellard1f673132004-04-04 15:21:17 +00002565@example
2566qemu-i386 tests/i386/ls
2567@end example
Blue Swirl4c3b5a42011-01-20 20:54:21 +00002568You can look at @file{scripts/qemu-binfmt-conf.sh} so that
bellard1f673132004-04-04 15:21:17 +00002569QEMU is automatically launched by the Linux kernel when you try to
2570launch x86 executables. It requires the @code{binfmt_misc} module in the
2571Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002572
bellard1f673132004-04-04 15:21:17 +00002573@item The x86 version of QEMU is also included. You can try weird things such as:
2574@example
bellarddebc7062006-04-30 21:58:41 +00002575qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2576 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002577@end example
bellard386405f2003-03-23 21:28:45 +00002578
bellard1f673132004-04-04 15:21:17 +00002579@end itemize
bellard386405f2003-03-23 21:28:45 +00002580
bellarddebc7062006-04-30 21:58:41 +00002581@node Wine launch
bellard83195232007-02-05 19:42:07 +00002582@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002583
bellard1f673132004-04-04 15:21:17 +00002584@itemize
bellard386405f2003-03-23 21:28:45 +00002585
bellard1f673132004-04-04 15:21:17 +00002586@item Ensure that you have a working QEMU with the x86 glibc
2587distribution (see previous section). In order to verify it, you must be
2588able to do:
bellard386405f2003-03-23 21:28:45 +00002589
bellard1f673132004-04-04 15:21:17 +00002590@example
2591qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2592@end example
bellard386405f2003-03-23 21:28:45 +00002593
bellard1f673132004-04-04 15:21:17 +00002594@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002595(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002596
bellard1f673132004-04-04 15:21:17 +00002597@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002598@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002599@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002600
bellard1f673132004-04-04 15:21:17 +00002601@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002602
bellard1f673132004-04-04 15:21:17 +00002603@example
bellarddebc7062006-04-30 21:58:41 +00002604qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2605 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002606@end example
bellard386405f2003-03-23 21:28:45 +00002607
bellard1f673132004-04-04 15:21:17 +00002608@end itemize
bellard386405f2003-03-23 21:28:45 +00002609
bellarddebc7062006-04-30 21:58:41 +00002610@node Command line options
bellard83195232007-02-05 19:42:07 +00002611@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002612
bellard1f673132004-04-04 15:21:17 +00002613@example
Paul Brook68a1c812010-05-29 02:27:35 +01002614usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
bellard1f673132004-04-04 15:21:17 +00002615@end example
bellard386405f2003-03-23 21:28:45 +00002616
bellard1f673132004-04-04 15:21:17 +00002617@table @option
2618@item -h
2619Print the help
ths3b46e622007-09-17 08:09:54 +00002620@item -L path
bellard1f673132004-04-04 15:21:17 +00002621Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2622@item -s size
2623Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002624@item -cpu model
Peter Maydellc8057f92012-08-02 13:45:54 +01002625Select CPU model (-cpu help for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002626@item -ignore-environment
2627Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002628the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002629@item -E @var{var}=@var{value}
2630Set environment @var{var} to @var{value}.
2631@item -U @var{var}
2632Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002633@item -B offset
2634Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002635the address region required by guest applications is reserved on the host.
2636This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002637@item -R size
2638Pre-allocate a guest virtual address space of the given size (in bytes).
Stefan Weil0d6753e2011-01-07 18:59:13 +01002639"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002640@end table
2641
bellard1f673132004-04-04 15:21:17 +00002642Debug options:
bellard386405f2003-03-23 21:28:45 +00002643
bellard1f673132004-04-04 15:21:17 +00002644@table @option
2645@item -d
2646Activate log (logfile=/tmp/qemu.log)
2647@item -p pagesize
2648Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002649@item -g port
2650Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002651@item -singlestep
2652Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002653@end table
bellard386405f2003-03-23 21:28:45 +00002654
balrogb01bcae2007-12-16 13:05:59 +00002655Environment variables:
2656
2657@table @env
2658@item QEMU_STRACE
2659Print system calls and arguments similar to the 'strace' program
2660(NOTE: the actual 'strace' program will not work because the user
2661space emulator hasn't implemented ptrace). At the moment this is
2662incomplete. All system calls that don't have a specific argument
2663format are printed with information for six arguments. Many
2664flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002665@end table
balrogb01bcae2007-12-16 13:05:59 +00002666
pbrook79737e42006-06-11 16:28:41 +00002667@node Other binaries
bellard83195232007-02-05 19:42:07 +00002668@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002669
Stefan Weil7544a042010-02-05 23:52:03 +01002670@cindex user mode (Alpha)
2671@command{qemu-alpha} TODO.
2672
2673@cindex user mode (ARM)
2674@command{qemu-armeb} TODO.
2675
2676@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002677@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2678binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2679configurations), and arm-uclinux bFLT format binaries.
2680
Stefan Weil7544a042010-02-05 23:52:03 +01002681@cindex user mode (ColdFire)
2682@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002683@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2684(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2685coldfire uClinux bFLT format binaries.
2686
pbrook79737e42006-06-11 16:28:41 +00002687The binary format is detected automatically.
2688
Stefan Weil7544a042010-02-05 23:52:03 +01002689@cindex user mode (Cris)
2690@command{qemu-cris} TODO.
2691
2692@cindex user mode (i386)
2693@command{qemu-i386} TODO.
2694@command{qemu-x86_64} TODO.
2695
2696@cindex user mode (Microblaze)
2697@command{qemu-microblaze} TODO.
2698
2699@cindex user mode (MIPS)
2700@command{qemu-mips} TODO.
2701@command{qemu-mipsel} TODO.
2702
2703@cindex user mode (PowerPC)
2704@command{qemu-ppc64abi32} TODO.
2705@command{qemu-ppc64} TODO.
2706@command{qemu-ppc} TODO.
2707
2708@cindex user mode (SH4)
2709@command{qemu-sh4eb} TODO.
2710@command{qemu-sh4} TODO.
2711
2712@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002713@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2714
blueswir1a785e422007-10-20 08:09:05 +00002715@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2716(Sparc64 CPU, 32 bit ABI).
2717
2718@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2719SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2720
blueswir184778502008-10-26 20:33:16 +00002721@node BSD User space emulator
2722@section BSD User space emulator
2723
2724@menu
2725* BSD Status::
2726* BSD Quick Start::
2727* BSD Command line options::
2728@end menu
2729
2730@node BSD Status
2731@subsection BSD Status
2732
2733@itemize @minus
2734@item
2735target Sparc64 on Sparc64: Some trivial programs work.
2736@end itemize
2737
2738@node BSD Quick Start
2739@subsection Quick Start
2740
2741In order to launch a BSD process, QEMU needs the process executable
2742itself and all the target dynamic libraries used by it.
2743
2744@itemize
2745
2746@item On Sparc64, you can just try to launch any process by using the native
2747libraries:
2748
2749@example
2750qemu-sparc64 /bin/ls
2751@end example
2752
2753@end itemize
2754
2755@node BSD Command line options
2756@subsection Command line options
2757
2758@example
2759usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2760@end example
2761
2762@table @option
2763@item -h
2764Print the help
2765@item -L path
2766Set the library root path (default=/)
2767@item -s size
2768Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002769@item -ignore-environment
2770Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002771the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002772@item -E @var{var}=@var{value}
2773Set environment @var{var} to @var{value}.
2774@item -U @var{var}
2775Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00002776@item -bsd type
2777Set the type of the emulated BSD Operating system. Valid values are
2778FreeBSD, NetBSD and OpenBSD (default).
2779@end table
2780
2781Debug options:
2782
2783@table @option
2784@item -d
2785Activate log (logfile=/tmp/qemu.log)
2786@item -p pagesize
2787Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002788@item -singlestep
2789Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00002790@end table
2791
bellard15a34c62004-07-08 21:26:26 +00002792@node compilation
2793@chapter Compilation from the sources
2794
bellarddebc7062006-04-30 21:58:41 +00002795@menu
2796* Linux/Unix::
2797* Windows::
2798* Cross compilation for Windows with Linux::
2799* Mac OS X::
Stefan Weil47eacb42010-02-05 23:52:01 +01002800* Make targets::
bellarddebc7062006-04-30 21:58:41 +00002801@end menu
2802
2803@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002804@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002805
bellard7c3fc842005-02-10 21:46:47 +00002806@subsection Compilation
2807
2808First you must decompress the sources:
2809@example
2810cd /tmp
2811tar zxvf qemu-x.y.z.tar.gz
2812cd qemu-x.y.z
2813@end example
2814
2815Then you configure QEMU and build it (usually no options are needed):
2816@example
2817./configure
2818make
2819@end example
2820
2821Then type as root user:
2822@example
2823make install
2824@end example
2825to install QEMU in @file{/usr/local}.
2826
bellarddebc7062006-04-30 21:58:41 +00002827@node Windows
bellard15a34c62004-07-08 21:26:26 +00002828@section Windows
2829
2830@itemize
2831@item Install the current versions of MSYS and MinGW from
2832@url{http://www.mingw.org/}. You can find detailed installation
2833instructions in the download section and the FAQ.
2834
ths5fafdf22007-09-16 21:08:06 +00002835@item Download
bellard15a34c62004-07-08 21:26:26 +00002836the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002837(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
Scott Tsaid0a96f32010-01-30 03:28:58 +08002838@url{http://www.libsdl.org}. Unpack it in a temporary place and
2839edit the @file{sdl-config} script so that it gives the
bellard15a34c62004-07-08 21:26:26 +00002840correct SDL directory when invoked.
2841
Scott Tsaid0a96f32010-01-30 03:28:58 +08002842@item Install the MinGW version of zlib and make sure
2843@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002844MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002845
bellard15a34c62004-07-08 21:26:26 +00002846@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002847
bellard15a34c62004-07-08 21:26:26 +00002848@item Start the MSYS shell (file @file{msys.bat}).
2849
ths5fafdf22007-09-16 21:08:06 +00002850@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00002851@file{make}. If you have problems using SDL, verify that
2852@file{sdl-config} can be launched from the MSYS command line.
2853
Stefan Weilc5ec15e2012-04-07 09:23:38 +02002854@item You can install QEMU in @file{Program Files/QEMU} by typing
bellard15a34c62004-07-08 21:26:26 +00002855@file{make install}. Don't forget to copy @file{SDL.dll} in
Stefan Weilc5ec15e2012-04-07 09:23:38 +02002856@file{Program Files/QEMU}.
bellard15a34c62004-07-08 21:26:26 +00002857
2858@end itemize
2859
bellarddebc7062006-04-30 21:58:41 +00002860@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00002861@section Cross compilation for Windows with Linux
2862
2863@itemize
2864@item
2865Install the MinGW cross compilation tools available at
2866@url{http://www.mingw.org/}.
2867
Scott Tsaid0a96f32010-01-30 03:28:58 +08002868@item Download
2869the MinGW development library of SDL 1.2.x
2870(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2871@url{http://www.libsdl.org}. Unpack it in a temporary place and
2872edit the @file{sdl-config} script so that it gives the
2873correct SDL directory when invoked. Set up the @code{PATH} environment
2874variable so that @file{sdl-config} can be launched by
bellard15a34c62004-07-08 21:26:26 +00002875the QEMU configuration script.
2876
Scott Tsaid0a96f32010-01-30 03:28:58 +08002877@item Install the MinGW version of zlib and make sure
2878@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002879MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002880
ths5fafdf22007-09-16 21:08:06 +00002881@item
bellard15a34c62004-07-08 21:26:26 +00002882Configure QEMU for Windows cross compilation:
2883@example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002884PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
bellard15a34c62004-07-08 21:26:26 +00002885@end example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002886The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
2887MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002888We 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 +08002889use --cross-prefix to specify the name of the cross compiler.
Stefan Weilc5ec15e2012-04-07 09:23:38 +02002890You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002891
2892Under Fedora Linux, you can run:
2893@example
2894yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
2895@end example
2896to get a suitable cross compilation environment.
bellard15a34c62004-07-08 21:26:26 +00002897
ths5fafdf22007-09-16 21:08:06 +00002898@item You can install QEMU in the installation directory by typing
Scott Tsaid0a96f32010-01-30 03:28:58 +08002899@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
ths5fafdf22007-09-16 21:08:06 +00002900installation directory.
bellard15a34c62004-07-08 21:26:26 +00002901
2902@end itemize
2903
Stefan Weil3804da92012-05-11 22:21:50 +02002904Wine can be used to launch the resulting qemu-system-i386.exe
2905and all other qemu-system-@var{target}.exe compiled for Win32.
bellard15a34c62004-07-08 21:26:26 +00002906
bellarddebc7062006-04-30 21:58:41 +00002907@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00002908@section Mac OS X
2909
2910The Mac OS X patches are not fully merged in QEMU, so you should look
2911at the QEMU mailing list archive to have all the necessary
2912information.
2913
Stefan Weil47eacb42010-02-05 23:52:01 +01002914@node Make targets
2915@section Make targets
2916
2917@table @code
2918
2919@item make
2920@item make all
2921Make everything which is typically needed.
2922
2923@item install
2924TODO
2925
2926@item install-doc
2927TODO
2928
2929@item make clean
2930Remove most files which were built during make.
2931
2932@item make distclean
2933Remove everything which was built during make.
2934
2935@item make dvi
2936@item make html
2937@item make info
2938@item make pdf
2939Create documentation in dvi, html, info or pdf format.
2940
2941@item make cscope
2942TODO
2943
2944@item make defconfig
2945(Re-)create some build configuration files.
2946User made changes will be overwritten.
2947
2948@item tar
2949@item tarbin
2950TODO
2951
2952@end table
2953
Stefan Weil7544a042010-02-05 23:52:03 +01002954@node License
2955@appendix License
2956
2957QEMU is a trademark of Fabrice Bellard.
2958
2959QEMU is released under the GNU General Public License (TODO: add link).
2960Parts of QEMU have specific licenses, see file LICENSE.
2961
2962TODO (refer to file LICENSE, include it, include the GPL?)
2963
bellarddebc7062006-04-30 21:58:41 +00002964@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01002965@appendix Index
2966@menu
2967* Concept Index::
2968* Function Index::
2969* Keystroke Index::
2970* Program Index::
2971* Data Type Index::
2972* Variable Index::
2973@end menu
2974
2975@node Concept Index
2976@section Concept Index
2977This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00002978@printindex cp
2979
Stefan Weil7544a042010-02-05 23:52:03 +01002980@node Function Index
2981@section Function Index
2982This index could be used for command line options and monitor functions.
2983@printindex fn
2984
2985@node Keystroke Index
2986@section Keystroke Index
2987
2988This is a list of all keystrokes which have a special function
2989in system emulation.
2990
2991@printindex ky
2992
2993@node Program Index
2994@section Program Index
2995@printindex pg
2996
2997@node Data Type Index
2998@section Data Type Index
2999
3000This index could be used for qdev device names and options.
3001
3002@printindex tp
3003
3004@node Variable Index
3005@section Variable Index
3006@printindex vr
3007
bellarddebc7062006-04-30 21:58:41 +00003008@bye