blob: aabe8df2f34da3dffdc1a1773ebab0a85f33c944 [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
Michael Tokareva8ad4152013-06-28 10:08:16 +0400217QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
bellard15a34c62004-07-08 21:26:26 +0000218VGA BIOS.
219
bellardc0fe3822005-11-05 18:55:28 +0000220QEMU uses YM3812 emulation by Tatsuyuki Satoh.
221
Stefan Weil2d983442011-01-07 18:59:15 +0100222QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
balrog26463db2008-01-17 21:47:25 +0000223by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000224
Bernhard Reutner-Fischer1a1a0e22011-10-25 10:22:18 +0200225Note that, by default, GUS shares IRQ(7) with parallel ports and so
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200226QEMU must be told to not have parallel ports to have working GUS.
malc720036a2009-09-10 20:05:59 +0400227
228@example
Stefan Weil3804da92012-05-11 22:21:50 +0200229qemu-system-i386 dos.img -soundhw gus -parallel none
malc720036a2009-09-10 20:05:59 +0400230@end example
231
232Alternatively:
233@example
Stefan Weil3804da92012-05-11 22:21:50 +0200234qemu-system-i386 dos.img -device gus,irq=5
malc720036a2009-09-10 20:05:59 +0400235@end example
236
237Or some other unclaimed IRQ.
238
malccc53d262008-06-13 10:48:22 +0000239CS4231A is the chip used in Windows Sound System and GUSMAX products
240
bellard0806e3f2003-10-01 00:15:32 +0000241@c man end
242
bellarddebc7062006-04-30 21:58:41 +0000243@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000244@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100245@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000246
bellard285dc332003-10-27 23:58:04 +0000247Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000248
249@example
Stefan Weil3804da92012-05-11 22:21:50 +0200250qemu-system-i386 linux.img
bellard0806e3f2003-10-01 00:15:32 +0000251@end example
252
253Linux should boot and give you a prompt.
254
bellard6cc721c2005-07-28 22:27:28 +0000255@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000256@section Invocation
257
258@example
259@c man begin SYNOPSIS
Stefan Weil3804da92012-05-11 22:21:50 +0200260usage: qemu-system-i386 [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000261@c man end
262@end example
263
264@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000265@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
266targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000267
blueswir15824d652009-03-28 06:44:27 +0000268@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000269
bellard3e11db92004-07-14 17:47:14 +0000270@c man end
271
bellarddebc7062006-04-30 21:58:41 +0000272@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000273@section Keys
274
275@c man begin OPTIONS
276
Brad Hardsde1db2a2011-04-29 21:46:12 +1000277During the graphical emulation, you can use special key combinations to change
278modes. The default key mappings are shown below, but if you use @code{-alt-grab}
279then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
280@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
281
bellarda1b74fe2004-05-08 13:26:35 +0000282@table @key
bellardf9859312004-10-03 14:33:10 +0000283@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100284@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000285Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000286
Jan Kiszkad6a65ba2011-07-30 11:39:16 +0200287@item Ctrl-Alt-+
288@kindex Ctrl-Alt-+
289Enlarge the screen
290
291@item Ctrl-Alt--
292@kindex Ctrl-Alt--
293Shrink the screen
294
malcc4a735f2009-09-10 05:15:07 +0400295@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100296@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400297Restore the screen's un-scaled dimensions
298
bellardf9859312004-10-03 14:33:10 +0000299@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100300@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000301Switch to virtual console 'n'. Standard console mappings are:
302@table @emph
303@item 1
304Target system display
305@item 2
306Monitor
307@item 3
308Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000309@end table
310
bellardf9859312004-10-03 14:33:10 +0000311@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100312@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000313Toggle mouse and keyboard grab.
314@end table
315
Stefan Weil7544a042010-02-05 23:52:03 +0100316@kindex Ctrl-Up
317@kindex Ctrl-Down
318@kindex Ctrl-PageUp
319@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000320In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
321@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
322
Stefan Weil7544a042010-02-05 23:52:03 +0100323@kindex Ctrl-a h
bellarda0a821a2004-07-14 17:38:57 +0000324During emulation, if you are using the @option{-nographic} option, use
325@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000326
327@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000328@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100329@kindex Ctrl-a h
blueswir1d2c639d2009-01-24 18:19:25 +0000330@item Ctrl-a ?
Stefan Weil7544a042010-02-05 23:52:03 +0100331@kindex Ctrl-a ?
bellard1f673132004-04-04 15:21:17 +0000332Print this help
ths3b46e622007-09-17 08:09:54 +0000333@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100334@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000335Exit emulator
ths3b46e622007-09-17 08:09:54 +0000336@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100337@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000338Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000339@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100340@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000341Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000342@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100343@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000344Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000345@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100346@kindex Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000347Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000348@item Ctrl-a Ctrl-a
Stefan Weil7544a042010-02-05 23:52:03 +0100349@kindex Ctrl-a a
bellarda1b74fe2004-05-08 13:26:35 +0000350Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000351@end table
352@c man end
353
354@ignore
355
bellard1f673132004-04-04 15:21:17 +0000356@c man begin SEEALSO
357The HTML documentation of QEMU for more precise information and Linux
358user mode emulator invocation.
359@c man end
360
361@c man begin AUTHOR
362Fabrice Bellard
363@c man end
364
365@end ignore
366
bellarddebc7062006-04-30 21:58:41 +0000367@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000368@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100369@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000370
371The QEMU monitor is used to give complex commands to the QEMU
372emulator. You can use it to:
373
374@itemize @minus
375
376@item
thse5987522007-03-30 18:58:01 +0000377Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000378(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000379
ths5fafdf22007-09-16 21:08:06 +0000380@item
bellard1f673132004-04-04 15:21:17 +0000381Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
382from a disk file.
383
384@item Inspect the VM state without an external debugger.
385
386@end itemize
387
388@subsection Commands
389
390The following commands are available:
391
Blue Swirl23130862009-06-06 08:22:04 +0000392@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000393
394@subsection Integer expressions
395
396The monitor understands integers expressions for every integer
397argument. You can use register names to get the value of specifics
398CPU registers by prefixing them with @emph{$}.
399
400@node disk_images
401@section Disk Images
402
bellardacd935e2004-11-15 22:57:26 +0000403Since version 0.6.1, QEMU supports many disk image formats, including
404growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000405written), compressed and encrypted disk images. Version 0.8.3 added
406the new qcow2 disk image format which is essential to support VM
407snapshots.
bellard1f673132004-04-04 15:21:17 +0000408
bellarddebc7062006-04-30 21:58:41 +0000409@menu
410* disk_images_quickstart:: Quick start for disk image creation
411* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000412* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000413* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000414* qemu_nbd_invocation:: qemu-nbd Invocation
Kevin Wolfd3067b02012-11-21 14:21:47 +0100415* disk_images_formats:: Disk image file formats
bellard19cb3732006-08-19 11:45:59 +0000416* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000417* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +0000418* disk_images_nbd:: NBD access
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900419* disk_images_sheepdog:: Sheepdog disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100420* disk_images_iscsi:: iSCSI LUNs
Bharata B Rao8809e282012-10-24 17:17:53 +0530421* disk_images_gluster:: GlusterFS disk images
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +0100422* disk_images_ssh:: Secure Shell (ssh) disk images
bellarddebc7062006-04-30 21:58:41 +0000423@end menu
424
425@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000426@subsection Quick start for disk image creation
427
428You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000429@example
bellardacd935e2004-11-15 22:57:26 +0000430qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000431@end example
bellardacd935e2004-11-15 22:57:26 +0000432where @var{myimage.img} is the disk image filename and @var{mysize} is its
433size in kilobytes. You can add an @code{M} suffix to give the size in
434megabytes and a @code{G} suffix for gigabytes.
435
bellarddebc7062006-04-30 21:58:41 +0000436See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000437
bellarddebc7062006-04-30 21:58:41 +0000438@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000439@subsection Snapshot mode
440
441If you use the option @option{-snapshot}, all disk images are
442considered as read only. When sectors in written, they are written in
443a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000444write back to the raw disk images by using the @code{commit} monitor
445command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000446
bellard13a2e802006-08-06 14:50:31 +0000447@node vm_snapshots
448@subsection VM snapshots
449
450VM snapshots are snapshots of the complete virtual machine including
451CPU state, RAM, device state and the content of all the writable
452disks. In order to use VM snapshots, you must have at least one non
453removable and writable block device using the @code{qcow2} disk image
454format. Normally this device is the first virtual hard drive.
455
456Use the monitor command @code{savevm} to create a new VM snapshot or
457replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000458snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000459
460Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
461a VM snapshot. @code{info snapshots} lists the available snapshots
462with their associated information:
463
464@example
465(qemu) info snapshots
466Snapshot devices: hda
467Snapshot list (from hda):
468ID TAG VM SIZE DATE VM CLOCK
4691 start 41M 2006-08-06 12:38:02 00:00:14.954
4702 40M 2006-08-06 12:43:29 00:00:18.633
4713 msys 40M 2006-08-06 12:44:04 00:00:23.514
472@end example
473
474A VM snapshot is made of a VM state info (its size is shown in
475@code{info snapshots}) and a snapshot of every writable disk image.
476The VM state info is stored in the first @code{qcow2} non removable
477and writable block device. The disk image snapshots are stored in
478every disk image. The size of a snapshot in a disk image is difficult
479to evaluate and is not shown by @code{info snapshots} because the
480associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000481disk space (otherwise each snapshot would need a full copy of all the
482disk images).
bellard13a2e802006-08-06 14:50:31 +0000483
484When using the (unrelated) @code{-snapshot} option
485(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
486but they are deleted as soon as you exit QEMU.
487
488VM snapshots currently have the following known limitations:
489@itemize
ths5fafdf22007-09-16 21:08:06 +0000490@item
bellard13a2e802006-08-06 14:50:31 +0000491They cannot cope with removable devices if they are removed or
492inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000493@item
bellard13a2e802006-08-06 14:50:31 +0000494A few device drivers still have incomplete snapshot support so their
495state is not saved or restored properly (in particular USB).
496@end itemize
497
bellardacd935e2004-11-15 22:57:26 +0000498@node qemu_img_invocation
499@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000500
bellardacd935e2004-11-15 22:57:26 +0000501@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000502
ths975b0922008-07-02 21:18:00 +0000503@node qemu_nbd_invocation
504@subsection @code{qemu-nbd} Invocation
505
506@include qemu-nbd.texi
507
Kevin Wolfd3067b02012-11-21 14:21:47 +0100508@node disk_images_formats
509@subsection Disk image file formats
510
511QEMU supports many image file formats that can be used with VMs as well as with
512any of the tools (like @code{qemu-img}). This includes the preferred formats
513raw and qcow2 as well as formats that are supported for compatibility with
514older QEMU versions or other hypervisors.
515
516Depending on the image format, different options can be passed to
517@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
518This section describes each format and the options that are supported for it.
519
520@table @option
521@item raw
522
523Raw disk image format. This format has the advantage of
524being simple and easily exportable to all other emulators. If your
525file system supports @emph{holes} (for example in ext2 or ext3 on
526Linux or NTFS on Windows), then only the written sectors will reserve
527space. Use @code{qemu-img info} to know the real size used by the
528image or @code{ls -ls} on Unix/Linux.
529
Hu Tao06247422014-09-10 17:05:48 +0800530Supported options:
531@table @code
532@item preallocation
533Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
534@code{falloc} mode preallocates space for image by calling posix_fallocate().
535@code{full} mode preallocates space for image by writing zeros to underlying
536storage.
537@end table
538
Kevin Wolfd3067b02012-11-21 14:21:47 +0100539@item qcow2
540QEMU image format, the most versatile format. Use it to have smaller
541images (useful if your filesystem does not supports holes, for example
542on Windows), optional AES encryption, zlib based compression and
543support of multiple VM snapshots.
544
545Supported options:
546@table @code
547@item compat
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800548Determines the qcow2 version to use. @code{compat=0.10} uses the
549traditional image format that can be read by any QEMU since 0.10.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100550@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800551newer understand (this is the default). Amongst others, this includes
552zero clusters, which allow efficient copy-on-read for sparse images.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100553
554@item backing_file
555File name of a base image (see @option{create} subcommand)
556@item backing_fmt
557Image format of the base image
558@item encryption
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000559If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100560
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000561The use of encryption in qcow and qcow2 images is considered to be flawed by
562modern cryptography standards, suffering from a number of design problems:
563
564@itemize @minus
565@item The AES-CBC cipher is used with predictable initialization vectors based
566on the sector number. This makes it vulnerable to chosen plaintext attacks
567which can reveal the existence of encrypted data.
568@item The user passphrase is directly used as the encryption key. A poorly
569chosen or short passphrase will compromise the security of the encryption.
570@item In the event of the passphrase being compromised there is no way to
571change the passphrase to protect data in any qcow images. The files must
572be cloned, using a different encryption passphrase in the new file. The
573original file must then be securely erased using a program like shred,
574though even this is ineffective with many modern storage technologies.
575@end itemize
576
577Use of qcow / qcow2 encryption is thus strongly discouraged. Users are
578recommended to use an alternative encryption technology such as the
579Linux dm-crypt / LUKS system.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100580
581@item cluster_size
582Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
583sizes can improve the image file size whereas larger cluster sizes generally
584provide better performance.
585
586@item preallocation
Hu Tao0e4271b2014-09-10 17:05:49 +0800587Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
588@code{full}). An image with preallocated metadata is initially larger but can
589improve performance when the image needs to grow. @code{falloc} and @code{full}
590preallocations are like the same options of @code{raw} format, but sets up
591metadata also.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100592
593@item lazy_refcounts
594If this option is set to @code{on}, reference count updates are postponed with
595the goal of avoiding metadata I/O and improving performance. This is
596particularly interesting with @option{cache=writethrough} which doesn't batch
597metadata updates. The tradeoff is that after a host crash, the reference count
598tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
599check -r all} is required, which may take some time.
600
601This option can only be enabled if @code{compat=1.1} is specified.
602
Chunyan Liu4ab15592014-06-30 14:29:58 +0800603@item nocow
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800604If this option is set to @code{on}, it will turn off COW of the file. It's only
Chunyan Liu4ab15592014-06-30 14:29:58 +0800605valid on btrfs, no effect on other file systems.
606
607Btrfs has low performance when hosting a VM image file, even more when the guest
608on the VM also using btrfs as file system. Turning off COW is a way to mitigate
609this bad performance. Generally there are two ways to turn off COW on btrfs:
610a) Disable it by mounting with nodatacow, then all newly created files will be
611NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
612does.
613
614Note: this option is only valid to new or empty files. If there is an existing
615file which is COW and has data blocks already, it couldn't be changed to NOCOW
616by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800617the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
Chunyan Liu4ab15592014-06-30 14:29:58 +0800618
Kevin Wolfd3067b02012-11-21 14:21:47 +0100619@end table
620
621@item qed
622Old QEMU image format with support for backing files and compact image files
623(when your filesystem or transport medium does not support holes).
624
625When converting QED images to qcow2, you might want to consider using the
626@code{lazy_refcounts=on} option to get a more QED-like behaviour.
627
628Supported options:
629@table @code
630@item backing_file
631File name of a base image (see @option{create} subcommand).
632@item backing_fmt
633Image file format of backing file (optional). Useful if the format cannot be
634autodetected because it has no header, like some vhd/vpc files.
635@item cluster_size
636Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
637cluster sizes can improve the image file size whereas larger cluster sizes
638generally provide better performance.
639@item table_size
640Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
641and 16). There is normally no need to change this value but this option can be
642used for performance benchmarking.
643@end table
644
645@item qcow
646Old QEMU image format with support for backing files, compact image files,
647encryption and compression.
648
649Supported options:
650@table @code
651@item backing_file
652File name of a base image (see @option{create} subcommand)
653@item encryption
654If this option is set to @code{on}, the image is encrypted.
655@end table
656
Kevin Wolfd3067b02012-11-21 14:21:47 +0100657@item vdi
658VirtualBox 1.1 compatible image format.
659Supported options:
660@table @code
661@item static
662If this option is set to @code{on}, the image is created with metadata
663preallocation.
664@end table
665
666@item vmdk
667VMware 3 and 4 compatible image format.
668
669Supported options:
670@table @code
671@item backing_file
672File name of a base image (see @option{create} subcommand).
673@item compat6
674Create a VMDK version 6 image (instead of version 4)
675@item subformat
676Specifies which VMDK subformat to use. Valid options are
677@code{monolithicSparse} (default),
678@code{monolithicFlat},
679@code{twoGbMaxExtentSparse},
680@code{twoGbMaxExtentFlat} and
681@code{streamOptimized}.
682@end table
683
684@item vpc
685VirtualPC compatible image format (VHD).
686Supported options:
687@table @code
688@item subformat
689Specifies which VHD subformat to use. Valid options are
690@code{dynamic} (default) and @code{fixed}.
691@end table
Jeff Cody8282db12013-12-17 13:56:06 -0500692
693@item VHDX
694Hyper-V compatible image format (VHDX).
695Supported options:
696@table @code
697@item subformat
698Specifies which VHDX subformat to use. Valid options are
699@code{dynamic} (default) and @code{fixed}.
700@item block_state_zero
Jeff Cody30af51c2014-12-08 01:07:44 -0500701Force use of payload blocks of type 'ZERO'. Can be set to @code{on} (default)
702or @code{off}. When set to @code{off}, new blocks will be created as
703@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
704arbitrary data for those blocks. Do not set to @code{off} when using
705@code{qemu-img convert} with @code{subformat=dynamic}.
Jeff Cody8282db12013-12-17 13:56:06 -0500706@item block_size
707Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
708@item log_size
709Log size; min 1 MB.
710@end table
Kevin Wolfd3067b02012-11-21 14:21:47 +0100711@end table
712
713@subsubsection Read-only formats
714More disk image file formats are supported in a read-only mode.
715@table @option
716@item bochs
717Bochs images of @code{growing} type.
718@item cloop
719Linux Compressed Loop image, useful only to reuse directly compressed
720CD-ROM images present for example in the Knoppix CD-ROMs.
721@item dmg
722Apple disk image.
723@item parallels
724Parallels disk image format.
725@end table
726
727
bellard19cb3732006-08-19 11:45:59 +0000728@node host_drives
729@subsection Using host drives
730
731In addition to disk image files, QEMU can directly access host
732devices. We describe here the usage for QEMU version >= 0.8.3.
733
734@subsubsection Linux
735
736On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000737disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +0000738it. For example, use @file{/dev/cdrom} to access to the CDROM or
739@file{/dev/fd0} for the floppy.
740
bellardf5420862006-08-21 20:26:44 +0000741@table @code
bellard19cb3732006-08-19 11:45:59 +0000742@item CD
743You can specify a CDROM device even if no CDROM is loaded. QEMU has
744specific code to detect CDROM insertion or removal. CDROM ejection by
745the guest OS is supported. Currently only data CDs are supported.
746@item Floppy
747You can specify a floppy device even if no floppy is loaded. Floppy
748removal is currently not detected accurately (if you change floppy
749without doing floppy access while the floppy is not loaded, the guest
750OS will think that the same floppy is loaded).
751@item Hard disks
752Hard disks can be used. Normally you must specify the whole disk
753(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
754see it as a partitioned disk. WARNING: unless you know what you do, it
755is better to only make READ-ONLY accesses to the hard disk otherwise
756you may corrupt your host data (use the @option{-snapshot} command
757line option or modify the device permissions accordingly).
758@end table
759
760@subsubsection Windows
761
bellard01781962007-01-07 22:43:30 +0000762@table @code
763@item CD
ths4be456f2007-06-03 13:41:28 +0000764The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000765alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
766supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000767
thse5987522007-03-30 18:58:01 +0000768Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000769is better to use the @code{change} or @code{eject} monitor commands to
770change or eject media.
bellard01781962007-01-07 22:43:30 +0000771@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000772Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000773where @var{N} is the drive number (0 is the first hard disk).
774
775WARNING: unless you know what you do, it is better to only make
776READ-ONLY accesses to the hard disk otherwise you may corrupt your
777host data (use the @option{-snapshot} command line so that the
778modifications are written in a temporary file).
779@end table
780
bellard19cb3732006-08-19 11:45:59 +0000781
782@subsubsection Mac OS X
783
ths5fafdf22007-09-16 21:08:06 +0000784@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000785
thse5987522007-03-30 18:58:01 +0000786Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000787is better to use the @code{change} or @code{eject} monitor commands to
788change or eject media.
789
bellarddebc7062006-04-30 21:58:41 +0000790@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000791@subsection Virtual FAT disk images
792
793QEMU can automatically create a virtual FAT disk image from a
794directory tree. In order to use it, just type:
795
ths5fafdf22007-09-16 21:08:06 +0000796@example
Stefan Weil3804da92012-05-11 22:21:50 +0200797qemu-system-i386 linux.img -hdb fat:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000798@end example
799
800Then you access access to all the files in the @file{/my_directory}
801directory without having to copy them in a disk image or to export
802them via SAMBA or NFS. The default access is @emph{read-only}.
803
804Floppies can be emulated with the @code{:floppy:} option:
805
ths5fafdf22007-09-16 21:08:06 +0000806@example
Stefan Weil3804da92012-05-11 22:21:50 +0200807qemu-system-i386 linux.img -fda fat:floppy:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000808@end example
809
810A read/write support is available for testing (beta stage) with the
811@code{:rw:} option:
812
ths5fafdf22007-09-16 21:08:06 +0000813@example
Stefan Weil3804da92012-05-11 22:21:50 +0200814qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000815@end example
816
817What you should @emph{never} do:
818@itemize
819@item use non-ASCII filenames ;
820@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000821@item expect it to work when loadvm'ing ;
822@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000823@end itemize
824
ths75818252008-07-03 13:41:03 +0000825@node disk_images_nbd
826@subsection NBD access
827
828QEMU can access directly to block device exported using the Network Block Device
829protocol.
830
831@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100832qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
ths75818252008-07-03 13:41:03 +0000833@end example
834
835If the NBD server is located on the same host, you can use an unix socket instead
836of an inet socket:
837
838@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100839qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000840@end example
841
842In this case, the block device must be exported using qemu-nbd:
843
844@example
845qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
846@end example
847
Michael Tokarev9d85d552014-04-07 13:34:58 +0400848The use of qemu-nbd allows sharing of a disk between several guests:
ths75818252008-07-03 13:41:03 +0000849@example
850qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
851@end example
852
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100853@noindent
ths75818252008-07-03 13:41:03 +0000854and then you can use it with two guests:
855@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100856qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
857qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000858@end example
859
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100860If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
861own embedded NBD server), you must specify an export name in the URI:
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200862@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100863qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
864qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
865@end example
866
867The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
868also available. Here are some example of the older syntax:
869@example
870qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
871qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
872qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200873@end example
874
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900875@node disk_images_sheepdog
876@subsection Sheepdog disk images
877
878Sheepdog is a distributed storage system for QEMU. It provides highly
879available block level storage volumes that can be attached to
880QEMU-based virtual machines.
881
882You can create a Sheepdog disk image with the command:
883@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900884qemu-img create sheepdog:///@var{image} @var{size}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900885@end example
886where @var{image} is the Sheepdog image name and @var{size} is its
887size.
888
889To import the existing @var{filename} to Sheepdog, you can use a
890convert command.
891@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900892qemu-img convert @var{filename} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900893@end example
894
895You can boot from the Sheepdog disk image with the command:
896@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900897qemu-system-i386 sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900898@end example
899
900You can also create a snapshot of the Sheepdog image like qcow2.
901@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900902qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900903@end example
904where @var{tag} is a tag name of the newly created snapshot.
905
906To boot from the Sheepdog snapshot, specify the tag name of the
907snapshot.
908@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900909qemu-system-i386 sheepdog:///@var{image}#@var{tag}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900910@end example
911
912You can create a cloned image from the existing snapshot.
913@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900914qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900915@end example
916where @var{base} is a image name of the source snapshot and @var{tag}
917is its tag name.
918
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +0900919You can use an unix socket instead of an inet socket:
920
921@example
922qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
923@end example
924
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900925If the Sheepdog daemon doesn't run on the local host, you need to
926specify one of the Sheepdog servers to connect to.
927@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900928qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
929qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900930@end example
931
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100932@node disk_images_iscsi
933@subsection iSCSI LUNs
934
935iSCSI is a popular protocol used to access SCSI devices across a computer
936network.
937
938There are two different ways iSCSI devices can be used by QEMU.
939
940The first method is to mount the iSCSI LUN on the host, and make it appear as
941any other ordinary SCSI device on the host and then to access this device as a
942/dev/sd device from QEMU. How to do this differs between host OSes.
943
944The second method involves using the iSCSI initiator that is built into
945QEMU. This provides a mechanism that works the same way regardless of which
946host OS you are running QEMU on. This section will describe this second method
947of using iSCSI together with QEMU.
948
949In QEMU, iSCSI devices are described using special iSCSI URLs
950
951@example
952URL syntax:
953iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
954@end example
955
956Username and password are optional and only used if your target is set up
957using CHAP authentication for access control.
958Alternatively the username and password can also be set via environment
959variables to have these not show up in the process list
960
961@example
962export LIBISCSI_CHAP_USERNAME=<username>
963export LIBISCSI_CHAP_PASSWORD=<password>
964iscsi://<host>/<target-iqn-name>/<lun>
965@end example
966
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100967Various session related parameters can be set via special options, either
968in a configuration file provided via '-readconfig' or directly on the
969command line.
970
Ronnie Sahlberg31459f42012-08-06 18:24:55 +1000971If the initiator-name is not specified qemu will use a default name
972of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
973virtual machine.
974
975
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100976@example
977Setting a specific initiator name to use when logging in to the target
978-iscsi initiator-name=iqn.qemu.test:my-initiator
979@end example
980
981@example
982Controlling which type of header digest to negotiate with the target
983-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
984@end example
985
986These can also be set via a configuration file
987@example
988[iscsi]
989 user = "CHAP username"
990 password = "CHAP password"
991 initiator-name = "iqn.qemu.test:my-initiator"
992 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
993 header-digest = "CRC32C"
994@end example
995
996
997Setting the target name allows different options for different targets
998@example
999[iscsi "iqn.target.name"]
1000 user = "CHAP username"
1001 password = "CHAP password"
1002 initiator-name = "iqn.qemu.test:my-initiator"
1003 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1004 header-digest = "CRC32C"
1005@end example
1006
1007
1008Howto use a configuration file to set iSCSI configuration options:
1009@example
1010cat >iscsi.conf <<EOF
1011[iscsi]
1012 user = "me"
1013 password = "my password"
1014 initiator-name = "iqn.qemu.test:my-initiator"
1015 header-digest = "CRC32C"
1016EOF
1017
1018qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1019 -readconfig iscsi.conf
1020@end example
1021
1022
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001023Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
1024@example
1025This example shows how to set up an iSCSI target with one CDROM and one DISK
1026using the Linux STGT software target. This target is available on Red Hat based
1027systems as the package 'scsi-target-utils'.
1028
1029tgtd --iscsi portal=127.0.0.1:3260
1030tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
1031tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
1032 -b /IMAGES/disk.img --device-type=disk
1033tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
1034 -b /IMAGES/cd.iso --device-type=cd
1035tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
1036
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11001037qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
1038 -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001039 -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
1040@end example
1041
Bharata B Rao8809e282012-10-24 17:17:53 +05301042@node disk_images_gluster
1043@subsection GlusterFS disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001044
Bharata B Rao8809e282012-10-24 17:17:53 +05301045GlusterFS is an user space distributed file system.
1046
1047You can boot from the GlusterFS disk image with the command:
1048@example
1049qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
1050@end example
1051
1052@var{gluster} is the protocol.
1053
1054@var{transport} specifies the transport type used to connect to gluster
1055management daemon (glusterd). Valid transport types are
1056tcp, unix and rdma. If a transport type isn't specified, then tcp
1057type is assumed.
1058
1059@var{server} specifies the server where the volume file specification for
1060the given volume resides. This can be either hostname, ipv4 address
1061or ipv6 address. ipv6 address needs to be within square brackets [ ].
1062If transport type is unix, then @var{server} field should not be specifed.
1063Instead @var{socket} field needs to be populated with the path to unix domain
1064socket.
1065
1066@var{port} is the port number on which glusterd is listening. This is optional
1067and if not specified, QEMU will send 0 which will make gluster to use the
1068default port. If the transport type is unix, then @var{port} should not be
1069specified.
1070
1071@var{volname} is the name of the gluster volume which contains the disk image.
1072
1073@var{image} is the path to the actual disk image that resides on gluster volume.
1074
1075You can create a GlusterFS disk image with the command:
1076@example
1077qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
1078@end example
1079
1080Examples
1081@example
1082qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1083qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1084qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1085qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1086qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1087qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1088qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1089qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
1090@end example
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001091
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001092@node disk_images_ssh
1093@subsection Secure Shell (ssh) disk images
1094
1095You can access disk images located on a remote ssh server
1096by using the ssh protocol:
1097
1098@example
1099qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
1100@end example
1101
1102Alternative syntax using properties:
1103
1104@example
1105qemu-system-x86_64 -drive file.driver=ssh[,file.user=@var{user}],file.host=@var{server}[,file.port=@var{port}],file.path=@var{path}[,file.host_key_check=@var{host_key_check}]
1106@end example
1107
1108@var{ssh} is the protocol.
1109
1110@var{user} is the remote user. If not specified, then the local
1111username is tried.
1112
1113@var{server} specifies the remote ssh server. Any ssh server can be
1114used, but it must implement the sftp-server protocol. Most Unix/Linux
1115systems should work without requiring any extra configuration.
1116
1117@var{port} is the port number on which sshd is listening. By default
1118the standard ssh port (22) is used.
1119
1120@var{path} is the path to the disk image.
1121
1122The optional @var{host_key_check} parameter controls how the remote
1123host's key is checked. The default is @code{yes} which means to use
1124the local @file{.ssh/known_hosts} file. Setting this to @code{no}
1125turns off known-hosts checking. Or you can check that the host key
1126matches a specific fingerprint:
1127@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
1128(@code{sha1:} can also be used as a prefix, but note that OpenSSH
1129tools only use MD5 to print fingerprints).
1130
1131Currently authentication must be done using ssh-agent. Other
1132authentication methods may be supported in future.
1133
Richard W.M. Jones9a2d4622013-04-09 15:30:54 +01001134Note: Many ssh servers do not support an @code{fsync}-style operation.
1135The ssh driver cannot guarantee that disk flush requests are
1136obeyed, and this causes a risk of disk corruption if the remote
1137server or network goes down during writes. The driver will
1138print a warning when @code{fsync} is not supported:
1139
1140warning: ssh server @code{ssh.example.com:22} does not support fsync
1141
1142With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
1143supported.
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001144
bellarddebc7062006-04-30 21:58:41 +00001145@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001146@section Network emulation
1147
ths4be456f2007-06-03 13:41:28 +00001148QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001149target) and can connect them to an arbitrary number of Virtual Local
1150Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1151VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001152simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001153network stack can replace the TAP device to have a basic network
1154connection.
bellard9d4fb822004-04-26 20:55:38 +00001155
bellard41d03942005-11-15 23:02:53 +00001156@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001157
bellard41d03942005-11-15 23:02:53 +00001158QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1159connection between several network devices. These devices can be for
1160example QEMU virtual Ethernet cards or virtual Host ethernet devices
1161(TAP devices).
1162
1163@subsection Using TAP network interfaces
1164
1165This is the standard way to connect QEMU to a real network. QEMU adds
1166a virtual network device on your host (called @code{tapN}), and you
1167can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001168
bellard8f40c382006-09-20 20:28:05 +00001169@subsubsection Linux host
1170
bellard9d4fb822004-04-26 20:55:38 +00001171As an example, you can download the @file{linux-test-xxx.tar.gz}
1172archive and copy the script @file{qemu-ifup} in @file{/etc} and
1173configure properly @code{sudo} so that the command @code{ifconfig}
1174contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001175that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001176device @file{/dev/net/tun} must be present.
1177
bellardee0f4752006-08-19 16:56:18 +00001178See @ref{sec_invocation} to have examples of command lines using the
1179TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001180
bellard8f40c382006-09-20 20:28:05 +00001181@subsubsection Windows host
1182
1183There is a virtual ethernet driver for Windows 2000/XP systems, called
1184TAP-Win32. But it is not included in standard QEMU for Windows,
1185so you will need to get it separately. It is part of OpenVPN package,
1186so download OpenVPN from : @url{http://openvpn.net/}.
1187
bellard9d4fb822004-04-26 20:55:38 +00001188@subsection Using the user mode network stack
1189
bellard41d03942005-11-15 23:02:53 +00001190By using the option @option{-net user} (default configuration if no
1191@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001192network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001193network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001194
1195@example
1196
bellard41d03942005-11-15 23:02:53 +00001197 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1198 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001199 |
bellard2518bd02004-09-30 22:35:13 +00001200 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001201 |
bellard2518bd02004-09-30 22:35:13 +00001202 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001203@end example
1204
1205The QEMU VM behaves as if it was behind a firewall which blocks all
1206incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001207configure the network in the QEMU VM. The DHCP server assign addresses
1208to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001209
1210In order to check that the user mode network is working, you can ping
1211the address 10.0.2.2 and verify that you got an address in the range
121210.0.2.x from the QEMU virtual DHCP server.
1213
Gernot Hillier37cbfcc2014-07-10 16:01:25 +02001214Note that ICMP traffic in general does not work with user mode networking.
1215@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
1216however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
1217ping sockets to allow @code{ping} to the Internet. The host admin has to set
1218the ping_group_range in order to grant access to those sockets. To allow ping
1219for GID 100 (usually users group):
1220
1221@example
1222echo 100 100 > /proc/sys/net/ipv4/ping_group_range
1223@end example
bellardb415a402004-05-23 21:04:06 +00001224
bellard9bf05442004-08-25 22:12:49 +00001225When using the built-in TFTP server, the router is also the TFTP
1226server.
1227
1228When using the @option{-redir} option, TCP or UDP connections can be
1229redirected from the host to the guest. It allows for example to
1230redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001231
bellard41d03942005-11-15 23:02:53 +00001232@subsection Connecting VLANs between QEMU instances
1233
1234Using the @option{-net socket} option, it is possible to make VLANs
1235that span several QEMU instances. See @ref{sec_invocation} to have a
1236basic example.
1237
Stefan Weil576fd0a2011-01-07 18:59:14 +01001238@node pcsys_other_devs
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001239@section Other Devices
1240
1241@subsection Inter-VM Shared Memory device
1242
1243With KVM enabled on a Linux host, a shared memory device is available. Guests
1244map a POSIX shared memory region into the guest as a PCI device that enables
1245zero-copy communication to the application level of the guests. The basic
1246syntax is:
1247
1248@example
Stefan Weil3804da92012-05-11 22:21:50 +02001249qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001250@end example
1251
1252If desired, interrupts can be sent between guest VMs accessing the same shared
1253memory region. Interrupt support requires using a shared memory server and
1254using a chardev socket to connect to it. The code for the shared memory server
1255is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
1256memory server is:
1257
1258@example
Stefan Weil3804da92012-05-11 22:21:50 +02001259qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
1260 [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
1261qemu-system-i386 -chardev socket,path=<path>,id=<id>
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001262@end example
1263
1264When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1265using the same server to communicate via interrupts. Guests can read their
1266VM ID from a device register (see example code). Since receiving the shared
1267memory region from the server is asynchronous, there is a (small) chance the
1268guest may boot before the shared memory is attached. To allow an application
1269to ensure shared memory is attached, the VM ID register will return -1 (an
1270invalid VM ID) until the memory is attached. Once the shared memory is
1271attached, the VM ID will return the guest's valid VM ID. With these semantics,
1272the guest application can check to ensure the shared memory is attached to the
1273guest before proceeding.
1274
1275The @option{role} argument can be set to either master or peer and will affect
1276how the shared memory is migrated. With @option{role=master}, the guest will
1277copy the shared memory on migration to the destination host. With
1278@option{role=peer}, the guest will not be able to migrate with the device attached.
1279With the @option{peer} case, the device should be detached and then reattached
1280after migration using the PCI hotplug support.
1281
bellard9d4fb822004-04-26 20:55:38 +00001282@node direct_linux_boot
1283@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001284
1285This section explains how to launch a Linux kernel inside QEMU without
1286having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001287kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001288
bellardee0f4752006-08-19 16:56:18 +00001289The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001290@example
Stefan Weil3804da92012-05-11 22:21:50 +02001291qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001292@end example
1293
bellardee0f4752006-08-19 16:56:18 +00001294Use @option{-kernel} to provide the Linux kernel image and
1295@option{-append} to give the kernel command line arguments. The
1296@option{-initrd} option can be used to provide an INITRD image.
1297
1298When using the direct Linux boot, a disk image for the first hard disk
1299@file{hda} is required because its boot sector is used to launch the
1300Linux kernel.
1301
1302If you do not need graphical output, you can disable it and redirect
1303the virtual serial port and the QEMU monitor to the console with the
1304@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001305@example
Stefan Weil3804da92012-05-11 22:21:50 +02001306qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1307 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001308@end example
1309
bellardee0f4752006-08-19 16:56:18 +00001310Use @key{Ctrl-a c} to switch between the serial console and the
1311monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001312
bellarddebc7062006-04-30 21:58:41 +00001313@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001314@section USB emulation
1315
pbrook0aff66b2006-05-26 00:49:52 +00001316QEMU emulates a PCI UHCI USB controller. You can virtually plug
1317virtual USB devices or real host USB devices (experimental, works only
Stefan Weil071c9392012-04-07 09:23:36 +02001318on Linux hosts). QEMU will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001319as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001320
pbrook0aff66b2006-05-26 00:49:52 +00001321@menu
1322* usb_devices::
1323* host_usb_devices::
1324@end menu
1325@node usb_devices
1326@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001327
pbrook0aff66b2006-05-26 00:49:52 +00001328USB devices can be connected with the @option{-usbdevice} commandline option
1329or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001330
balrogdb380c02008-01-17 22:22:45 +00001331@table @code
1332@item mouse
pbrook0aff66b2006-05-26 00:49:52 +00001333Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001334@item tablet
bellardc6d46c22006-09-03 17:10:41 +00001335Pointer device that uses absolute coordinates (like a touchscreen).
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001336This means QEMU is able to report the mouse position without having
pbrook0aff66b2006-05-26 00:49:52 +00001337to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001338@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +00001339Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +00001340@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +00001341Pass through the host device identified by @var{bus.addr}
1342(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001343@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +00001344Pass through the host device identified by @var{vendor_id:product_id}
1345(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001346@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +00001347Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1348above but it can be used with the tslib library because in addition to touch
1349coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +00001350@item keyboard
balrog47b2d332007-06-22 08:16:00 +00001351Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +00001352@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1353Serial converter. This emulates an FTDI FT232BM chip connected to host character
1354device @var{dev}. The available character devices are the same as for the
1355@code{-serial} option. The @code{vendorid} and @code{productid} options can be
Stefan Weil0d6753e2011-01-07 18:59:13 +01001356used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +00001357@example
1358usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1359@end example
1360will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1361serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +00001362@item braille
1363Braille device. This will use BrlAPI to display the braille output on a real
1364or fake device.
balrog9ad97e62008-07-29 13:16:31 +00001365@item net:@var{options}
1366Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1367specifies NIC options as with @code{-net nic,}@var{options} (see description).
1368For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +00001369@example
Stefan Weil3804da92012-05-11 22:21:50 +02001370qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +00001371@end example
1372Currently this cannot be used in machines that support PCI NICs.
balrog2d564692008-11-09 02:24:54 +00001373@item bt[:@var{hci-type}]
1374Bluetooth dongle whose type is specified in the same format as with
1375the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
1376no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1377This USB device implements the USB Transport Layer of HCI. Example
1378usage:
1379@example
Stefan Weil3804da92012-05-11 22:21:50 +02001380qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
balrog2d564692008-11-09 02:24:54 +00001381@end example
pbrook0aff66b2006-05-26 00:49:52 +00001382@end table
bellardb389dbf2005-11-06 16:49:55 +00001383
pbrook0aff66b2006-05-26 00:49:52 +00001384@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001385@subsection Using host USB devices on a Linux host
1386
1387WARNING: this is an experimental feature. QEMU will slow down when
1388using it. USB devices requiring real time streaming (i.e. USB Video
1389Cameras) are not supported yet.
1390
1391@enumerate
ths5fafdf22007-09-16 21:08:06 +00001392@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001393is actually using the USB device. A simple way to do that is simply to
1394disable the corresponding kernel module by renaming it from @file{mydriver.o}
1395to @file{mydriver.o.disabled}.
1396
1397@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1398@example
1399ls /proc/bus/usb
1400001 devices drivers
1401@end example
1402
1403@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:
1404@example
1405chown -R myuid /proc/bus/usb
1406@end example
1407
1408@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001409@example
bellardb389dbf2005-11-06 16:49:55 +00001410info usbhost
1411 Device 1.2, speed 480 Mb/s
1412 Class 00: USB device 1234:5678, USB DISK
1413@end example
1414You should see the list of the devices you can use (Never try to use
1415hubs, it won't work).
1416
1417@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001418@example
bellardb389dbf2005-11-06 16:49:55 +00001419usb_add host:1234:5678
1420@end example
1421
1422Normally the guest OS should report that a new USB device is
1423plugged. You can use the option @option{-usbdevice} to do the same.
1424
1425@item Now you can try to use the host USB device in QEMU.
1426
1427@end enumerate
1428
1429When relaunching QEMU, you may have to unplug and plug again the USB
1430device to make it work again (this is a bug).
1431
thsf858dca2007-08-25 01:40:37 +00001432@node vnc_security
1433@section VNC security
1434
1435The VNC server capability provides access to the graphical console
1436of the guest VM across the network. This has a number of security
1437considerations depending on the deployment scenarios.
1438
1439@menu
1440* vnc_sec_none::
1441* vnc_sec_password::
1442* vnc_sec_certificate::
1443* vnc_sec_certificate_verify::
1444* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +00001445* vnc_sec_sasl::
1446* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +00001447* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +00001448* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +00001449@end menu
1450@node vnc_sec_none
1451@subsection Without passwords
1452
1453The simplest VNC server setup does not include any form of authentication.
1454For this setup it is recommended to restrict it to listen on a UNIX domain
1455socket only. For example
1456
1457@example
Stefan Weil3804da92012-05-11 22:21:50 +02001458qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
thsf858dca2007-08-25 01:40:37 +00001459@end example
1460
1461This ensures that only users on local box with read/write access to that
1462path can access the VNC server. To securely access the VNC server from a
1463remote machine, a combination of netcat+ssh can be used to provide a secure
1464tunnel.
1465
1466@node vnc_sec_password
1467@subsection With passwords
1468
1469The VNC protocol has limited support for password based authentication. Since
1470the protocol limits passwords to 8 characters it should not be considered
1471to provide high security. The password can be fairly easily brute-forced by
1472a client making repeat connections. For this reason, a VNC server using password
1473authentication should be restricted to only listen on the loopback interface
Paul Moore0f669982012-08-03 14:39:21 -04001474or UNIX domain sockets. Password authentication is not supported when operating
1475in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1476authentication is requested with the @code{password} option, and then once QEMU
1477is running the password is set with the monitor. Until the monitor is used to
1478set the password all clients will be rejected.
thsf858dca2007-08-25 01:40:37 +00001479
1480@example
Stefan Weil3804da92012-05-11 22:21:50 +02001481qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001482(qemu) change vnc password
1483Password: ********
1484(qemu)
1485@end example
1486
1487@node vnc_sec_certificate
1488@subsection With x509 certificates
1489
1490The QEMU VNC server also implements the VeNCrypt extension allowing use of
1491TLS for encryption of the session, and x509 certificates for authentication.
1492The use of x509 certificates is strongly recommended, because TLS on its
1493own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1494support provides a secure session, but no authentication. This allows any
1495client to connect, and provides an encrypted session.
1496
1497@example
Stefan Weil3804da92012-05-11 22:21:50 +02001498qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001499@end example
1500
1501In the above example @code{/etc/pki/qemu} should contain at least three files,
1502@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1503users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1504NB the @code{server-key.pem} file should be protected with file mode 0600 to
1505only be readable by the user owning it.
1506
1507@node vnc_sec_certificate_verify
1508@subsection With x509 certificates and client verification
1509
1510Certificates can also provide a means to authenticate the client connecting.
1511The server will request that the client provide a certificate, which it will
1512then validate against the CA certificate. This is a good choice if deploying
1513in an environment with a private internal certificate authority.
1514
1515@example
Stefan Weil3804da92012-05-11 22:21:50 +02001516qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001517@end example
1518
1519
1520@node vnc_sec_certificate_pw
1521@subsection With x509 certificates, client verification and passwords
1522
1523Finally, the previous method can be combined with VNC password authentication
1524to provide two layers of authentication for clients.
1525
1526@example
Stefan Weil3804da92012-05-11 22:21:50 +02001527qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001528(qemu) change vnc password
1529Password: ********
1530(qemu)
1531@end example
1532
aliguori2f9606b2009-03-06 20:27:28 +00001533
1534@node vnc_sec_sasl
1535@subsection With SASL authentication
1536
1537The SASL authentication method is a VNC extension, that provides an
1538easily extendable, pluggable authentication method. This allows for
1539integration with a wide range of authentication mechanisms, such as
1540PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1541The strength of the authentication depends on the exact mechanism
1542configured. If the chosen mechanism also provides a SSF layer, then
1543it will encrypt the datastream as well.
1544
1545Refer to the later docs on how to choose the exact SASL mechanism
1546used for authentication, but assuming use of one supporting SSF,
1547then QEMU can be launched with:
1548
1549@example
Stefan Weil3804da92012-05-11 22:21:50 +02001550qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001551@end example
1552
1553@node vnc_sec_certificate_sasl
1554@subsection With x509 certificates and SASL authentication
1555
1556If the desired SASL authentication mechanism does not supported
1557SSF layers, then it is strongly advised to run it in combination
1558with TLS and x509 certificates. This provides securely encrypted
1559data stream, avoiding risk of compromising of the security
1560credentials. This can be enabled, by combining the 'sasl' option
1561with the aforementioned TLS + x509 options:
1562
1563@example
Stefan Weil3804da92012-05-11 22:21:50 +02001564qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001565@end example
1566
1567
thsf858dca2007-08-25 01:40:37 +00001568@node vnc_generate_cert
1569@subsection Generating certificates for VNC
1570
1571The GNU TLS packages provides a command called @code{certtool} which can
1572be used to generate certificates and keys in PEM format. At a minimum it
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001573is necessary to setup a certificate authority, and issue certificates to
thsf858dca2007-08-25 01:40:37 +00001574each server. If using certificates for authentication, then each client
1575will also need to be issued a certificate. The recommendation is for the
1576server to keep its certificates in either @code{/etc/pki/qemu} or for
1577unprivileged users in @code{$HOME/.pki/qemu}.
1578
1579@menu
1580* vnc_generate_ca::
1581* vnc_generate_server::
1582* vnc_generate_client::
1583@end menu
1584@node vnc_generate_ca
1585@subsubsection Setup the Certificate Authority
1586
1587This step only needs to be performed once per organization / organizational
1588unit. First the CA needs a private key. This key must be kept VERY secret
1589and secure. If this key is compromised the entire trust chain of the certificates
1590issued with it is lost.
1591
1592@example
1593# certtool --generate-privkey > ca-key.pem
1594@end example
1595
1596A CA needs to have a public certificate. For simplicity it can be a self-signed
1597certificate, or one issue by a commercial certificate issuing authority. To
1598generate a self-signed certificate requires one core piece of information, the
1599name of the organization.
1600
1601@example
1602# cat > ca.info <<EOF
1603cn = Name of your organization
1604ca
1605cert_signing_key
1606EOF
1607# certtool --generate-self-signed \
1608 --load-privkey ca-key.pem
1609 --template ca.info \
1610 --outfile ca-cert.pem
1611@end example
1612
1613The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1614TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1615
1616@node vnc_generate_server
1617@subsubsection Issuing server certificates
1618
1619Each server (or host) needs to be issued with a key and certificate. When connecting
1620the certificate is sent to the client which validates it against the CA certificate.
1621The core piece of information for a server certificate is the hostname. This should
1622be the fully qualified hostname that the client will connect with, since the client
1623will typically also verify the hostname in the certificate. On the host holding the
1624secure CA private key:
1625
1626@example
1627# cat > server.info <<EOF
1628organization = Name of your organization
1629cn = server.foo.example.com
1630tls_www_server
1631encryption_key
1632signing_key
1633EOF
1634# certtool --generate-privkey > server-key.pem
1635# certtool --generate-certificate \
1636 --load-ca-certificate ca-cert.pem \
1637 --load-ca-privkey ca-key.pem \
Gonglei63c693f2014-11-03 20:48:30 +08001638 --load-privkey server-key.pem \
thsf858dca2007-08-25 01:40:37 +00001639 --template server.info \
1640 --outfile server-cert.pem
1641@end example
1642
1643The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1644to the server for which they were generated. The @code{server-key.pem} is security
1645sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1646
1647@node vnc_generate_client
1648@subsubsection Issuing client certificates
1649
1650If the QEMU VNC server is to use the @code{x509verify} option to validate client
1651certificates as its authentication mechanism, each client also needs to be issued
1652a certificate. The client certificate contains enough metadata to uniquely identify
1653the client, typically organization, state, city, building, etc. On the host holding
1654the secure CA private key:
1655
1656@example
1657# cat > client.info <<EOF
1658country = GB
1659state = London
1660locality = London
Gonglei63c693f2014-11-03 20:48:30 +08001661organization = Name of your organization
thsf858dca2007-08-25 01:40:37 +00001662cn = client.foo.example.com
1663tls_www_client
1664encryption_key
1665signing_key
1666EOF
1667# certtool --generate-privkey > client-key.pem
1668# certtool --generate-certificate \
1669 --load-ca-certificate ca-cert.pem \
1670 --load-ca-privkey ca-key.pem \
1671 --load-privkey client-key.pem \
1672 --template client.info \
1673 --outfile client-cert.pem
1674@end example
1675
1676The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1677copied to the client for which they were generated.
1678
aliguori2f9606b2009-03-06 20:27:28 +00001679
1680@node vnc_setup_sasl
1681
1682@subsection Configuring SASL mechanisms
1683
1684The following documentation assumes use of the Cyrus SASL implementation on a
1685Linux host, but the principals should apply to any other SASL impl. When SASL
1686is enabled, the mechanism configuration will be loaded from system default
1687SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1688unprivileged user, an environment variable SASL_CONF_PATH can be used
1689to make it search alternate locations for the service config.
1690
1691The default configuration might contain
1692
1693@example
1694mech_list: digest-md5
1695sasldb_path: /etc/qemu/passwd.db
1696@end example
1697
1698This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1699Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1700in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1701command. While this mechanism is easy to configure and use, it is not
1702considered secure by modern standards, so only suitable for developers /
1703ad-hoc testing.
1704
1705A more serious deployment might use Kerberos, which is done with the 'gssapi'
1706mechanism
1707
1708@example
1709mech_list: gssapi
1710keytab: /etc/qemu/krb5.tab
1711@end example
1712
1713For this to work the administrator of your KDC must generate a Kerberos
1714principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
1715replacing 'somehost.example.com' with the fully qualified host name of the
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001716machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
aliguori2f9606b2009-03-06 20:27:28 +00001717
1718Other configurations will be left as an exercise for the reader. It should
1719be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1720encryption. For all other mechanisms, VNC should always be configured to
1721use TLS and x509 certificates to protect security credentials from snooping.
1722
bellard0806e3f2003-10-01 00:15:32 +00001723@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001724@section GDB usage
1725
1726QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001727'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001728
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001729In order to use gdb, launch QEMU with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001730gdb connection:
1731@example
Stefan Weil3804da92012-05-11 22:21:50 +02001732qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1733 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001734Connected to host network interface: tun0
1735Waiting gdb connection on port 1234
1736@end example
1737
1738Then launch gdb on the 'vmlinux' executable:
1739@example
1740> gdb vmlinux
1741@end example
1742
1743In gdb, connect to QEMU:
1744@example
bellard6c9bf892004-01-24 13:46:56 +00001745(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001746@end example
1747
1748Then you can use gdb normally. For example, type 'c' to launch the kernel:
1749@example
1750(gdb) c
1751@end example
1752
bellard0806e3f2003-10-01 00:15:32 +00001753Here are some useful tips in order to use gdb on system code:
1754
1755@enumerate
1756@item
1757Use @code{info reg} to display all the CPU registers.
1758@item
1759Use @code{x/10i $eip} to display the code at the PC position.
1760@item
1761Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001762@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001763@end enumerate
1764
edgar_igl60897d32008-05-09 08:25:14 +00001765Advanced debugging options:
1766
1767The 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 +00001768@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001769@item maintenance packet qqemu.sstepbits
1770
1771This will display the MASK bits used to control the single stepping IE:
1772@example
1773(gdb) maintenance packet qqemu.sstepbits
1774sending: "qqemu.sstepbits"
1775received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1776@end example
1777@item maintenance packet qqemu.sstep
1778
1779This will display the current value of the mask used when single stepping IE:
1780@example
1781(gdb) maintenance packet qqemu.sstep
1782sending: "qqemu.sstep"
1783received: "0x7"
1784@end example
1785@item maintenance packet Qqemu.sstep=HEX_VALUE
1786
1787This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1788@example
1789(gdb) maintenance packet Qqemu.sstep=0x5
1790sending: "qemu.sstep=0x5"
1791received: "OK"
1792@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001793@end table
edgar_igl60897d32008-05-09 08:25:14 +00001794
bellarddebc7062006-04-30 21:58:41 +00001795@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001796@section Target OS specific information
1797
1798@subsection Linux
1799
bellard15a34c62004-07-08 21:26:26 +00001800To have access to SVGA graphic modes under X11, use the @code{vesa} or
1801the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1802color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001803
bellarde3371e62004-07-10 16:26:02 +00001804When using a 2.6 guest Linux kernel, you should add the option
1805@code{clock=pit} on the kernel command line because the 2.6 Linux
1806kernels make very strict real time clock checks by default that QEMU
1807cannot simulate exactly.
1808
bellard7c3fc842005-02-10 21:46:47 +00001809When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1810not activated because QEMU is slower with this patch. The QEMU
1811Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001812Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001813patch by default. Newer kernels don't have it.
1814
bellard1a084f32004-05-13 22:34:49 +00001815@subsection Windows
1816
1817If you have a slow host, using Windows 95 is better as it gives the
1818best speed. Windows 2000 is also a good choice.
1819
bellarde3371e62004-07-10 16:26:02 +00001820@subsubsection SVGA graphic modes support
1821
1822QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001823card. All Windows versions starting from Windows 95 should recognize
1824and use this graphic card. For optimal performances, use 16 bit color
1825depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001826
bellard3cb08532006-06-21 21:19:50 +00001827If you are using Windows XP as guest OS and if you want to use high
1828resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
18291280x1024x16), then you should use the VESA VBE virtual graphic card
1830(option @option{-std-vga}).
1831
bellarde3371e62004-07-10 16:26:02 +00001832@subsubsection CPU usage reduction
1833
1834Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001835instruction. The result is that it takes host CPU cycles even when
1836idle. You can install the utility from
1837@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1838problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001839
bellard9d0a8e62005-07-03 17:34:05 +00001840@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001841
bellard9d0a8e62005-07-03 17:34:05 +00001842Windows 2000 has a bug which gives a disk full problem during its
1843installation. When installing it, use the @option{-win2k-hack} QEMU
1844option to enable a specific workaround. After Windows 2000 is
1845installed, you no longer need this option (this option slows down the
1846IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001847
bellard6cc721c2005-07-28 22:27:28 +00001848@subsubsection Windows 2000 shutdown
1849
1850Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1851can. It comes from the fact that Windows 2000 does not automatically
1852use the APM driver provided by the BIOS.
1853
1854In order to correct that, do the following (thanks to Struan
1855Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1856Add/Troubleshoot a device => Add a new device & Next => No, select the
1857hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1858(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001859correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001860
1861@subsubsection Share a directory between Unix and Windows
1862
1863See @ref{sec_invocation} about the help of the option @option{-smb}.
1864
bellard2192c332006-08-21 20:28:18 +00001865@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001866
1867Some releases of Windows XP install correctly but give a security
1868error when booting:
1869@example
1870A problem is preventing Windows from accurately checking the
1871license for this computer. Error code: 0x800703e6.
1872@end example
bellarde3371e62004-07-10 16:26:02 +00001873
bellard2192c332006-08-21 20:28:18 +00001874The workaround is to install a service pack for XP after a boot in safe
1875mode. Then reboot, and the problem should go away. Since there is no
1876network while in safe mode, its recommended to download the full
1877installation of SP1 or SP2 and transfer that via an ISO or using the
1878vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001879
bellarda0a821a2004-07-14 17:38:57 +00001880@subsection MS-DOS and FreeDOS
1881
1882@subsubsection CPU usage reduction
1883
1884DOS does not correctly use the CPU HLT instruction. The result is that
1885it takes host CPU cycles even when idle. You can install the utility
1886from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1887problem.
1888
bellarddebc7062006-04-30 21:58:41 +00001889@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001890@chapter QEMU System emulator for non PC targets
1891
1892QEMU is a generic emulator and it emulates many non PC
1893machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001894differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001895
bellarddebc7062006-04-30 21:58:41 +00001896@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001897* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001898* Sparc32 System emulator::
1899* Sparc64 System emulator::
1900* MIPS System emulator::
1901* ARM System emulator::
1902* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001903* Cris System emulator::
1904* Microblaze System emulator::
1905* SH4 System emulator::
Max Filippov3aeaea62011-10-10 14:48:23 +04001906* Xtensa System emulator::
bellarddebc7062006-04-30 21:58:41 +00001907@end menu
1908
Stefan Weil7544a042010-02-05 23:52:03 +01001909@node PowerPC System emulator
1910@section PowerPC System emulator
1911@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001912
1913Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001914or PowerMac PowerPC system.
1915
bellardb671f9e2005-04-30 15:08:33 +00001916QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001917
1918@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001919@item
blueswir1006f3a42009-02-08 15:59:36 +00001920UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001921@item
1922PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001923@item
bellard15a34c62004-07-08 21:26:26 +000019242 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001925@item
bellard15a34c62004-07-08 21:26:26 +00001926NE2000 PCI adapters
1927@item
1928Non Volatile RAM
1929@item
1930VIA-CUDA with ADB keyboard and mouse.
1931@end itemize
bellard52c00a52004-04-25 21:27:03 +00001932
bellardb671f9e2005-04-30 15:08:33 +00001933QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001934
1935@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001936@item
bellard15a34c62004-07-08 21:26:26 +00001937PCI Bridge
1938@item
1939PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001940@item
bellard52c00a52004-04-25 21:27:03 +000019412 IDE interfaces with hard disk and CD-ROM support
1942@item
1943Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001944@item
bellard15a34c62004-07-08 21:26:26 +00001945NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001946@item
1947Serial port
1948@item
1949PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001950@item
1951PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001952@end itemize
1953
bellard15a34c62004-07-08 21:26:26 +00001954QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001955@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001956
blueswir1992e5ac2008-12-24 20:23:51 +00001957Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00001958for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1959v2) portable firmware implementation. The goal is to implement a 100%
1960IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00001961
bellard15a34c62004-07-08 21:26:26 +00001962@c man begin OPTIONS
1963
1964The following options are specific to the PowerPC emulation:
1965
1966@table @option
1967
Kevin Wolf4e257e52009-10-09 10:58:36 +02001968@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00001969
Mark Cave-Ayland340fb412014-03-17 21:46:26 +00001970Set the initial VGA graphic mode. The default is 800x600x32.
bellard15a34c62004-07-08 21:26:26 +00001971
Kevin Wolf4e257e52009-10-09 10:58:36 +02001972@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00001973
1974Set OpenBIOS variables in NVRAM, for example:
1975
1976@example
1977qemu-system-ppc -prom-env 'auto-boot?=false' \
1978 -prom-env 'boot-device=hd:2,\yaboot' \
1979 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1980@end example
1981
1982These variables are not used by Open Hack'Ware.
1983
bellard15a34c62004-07-08 21:26:26 +00001984@end table
1985
ths5fafdf22007-09-16 21:08:06 +00001986@c man end
bellard15a34c62004-07-08 21:26:26 +00001987
1988
bellard52c00a52004-04-25 21:27:03 +00001989More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00001990@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00001991
ths24d4de42007-07-11 10:24:28 +00001992@node Sparc32 System emulator
1993@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01001994@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00001995
blueswir134a3d232008-10-04 20:43:39 +00001996Use the executable @file{qemu-system-sparc} to simulate the following
1997Sun4m architecture machines:
1998@itemize @minus
1999@item
2000SPARCstation 4
2001@item
2002SPARCstation 5
2003@item
2004SPARCstation 10
2005@item
2006SPARCstation 20
2007@item
2008SPARCserver 600MP
2009@item
2010SPARCstation LX
2011@item
2012SPARCstation Voyager
2013@item
2014SPARCclassic
2015@item
2016SPARCbook
2017@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00002018
blueswir134a3d232008-10-04 20:43:39 +00002019The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2020but Linux limits the number of usable CPUs to 4.
2021
Blue Swirl6a4e1772013-04-14 18:10:28 +00002022QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00002023
2024@itemize @minus
bellard34751872005-07-02 14:31:34 +00002025@item
Blue Swirl6a4e1772013-04-14 18:10:28 +00002026IOMMU
bellarde80cfcf2004-12-19 23:18:01 +00002027@item
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002028TCX or cgthree Frame buffer
ths5fafdf22007-09-16 21:08:06 +00002029@item
bellarde80cfcf2004-12-19 23:18:01 +00002030Lance (Am7990) Ethernet
2031@item
blueswir134a3d232008-10-04 20:43:39 +00002032Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00002033@item
bellard34751872005-07-02 14:31:34 +00002034Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2035and power/reset logic
2036@item
2037ESP SCSI controller with hard disk and CD-ROM support
2038@item
blueswir16a3b9cc2007-11-11 17:56:38 +00002039Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00002040@item
2041CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00002042@end itemize
2043
blueswir16a3b9cc2007-11-11 17:56:38 +00002044The number of peripherals is fixed in the architecture. Maximum
2045memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00002046others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00002047
bellard30a604f2006-06-14 18:35:18 +00002048Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00002049@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2050firmware implementation. The goal is to implement a 100% IEEE
20511275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00002052
2053A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00002054the QEMU web site. There are still issues with NetBSD and OpenBSD, but
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002055some kernel versions work. Please note that currently older Solaris kernels
blueswir134a3d232008-10-04 20:43:39 +00002056don't work probably due to interface issues between OpenBIOS and
2057Solaris.
bellard34751872005-07-02 14:31:34 +00002058
2059@c man begin OPTIONS
2060
blueswir1a2502b52007-06-10 17:01:00 +00002061The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00002062
2063@table @option
2064
Kevin Wolf4e257e52009-10-09 10:58:36 +02002065@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00002066
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002067Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
2068option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
2069of 1152x900x8 for people who wish to use OBP.
bellard34751872005-07-02 14:31:34 +00002070
Kevin Wolf4e257e52009-10-09 10:58:36 +02002071@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00002072
2073Set OpenBIOS variables in NVRAM, for example:
2074
2075@example
2076qemu-system-sparc -prom-env 'auto-boot?=false' \
2077 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2078@end example
2079
Blue Swirl6a4e1772013-04-14 18:10:28 +00002080@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
blueswir1a2502b52007-06-10 17:01:00 +00002081
2082Set the emulated machine type. Default is SS-5.
2083
bellard34751872005-07-02 14:31:34 +00002084@end table
2085
ths5fafdf22007-09-16 21:08:06 +00002086@c man end
bellard34751872005-07-02 14:31:34 +00002087
ths24d4de42007-07-11 10:24:28 +00002088@node Sparc64 System emulator
2089@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002090@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00002091
blueswir134a3d232008-10-04 20:43:39 +00002092Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2093(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2094Niagara (T1) machine. The emulator is not usable for anything yet, but
2095it can launch some kernels.
bellardb7569212005-03-13 09:43:05 +00002096
blueswir1c7ba2182008-07-22 07:07:34 +00002097QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00002098
2099@itemize @minus
2100@item
ths5fafdf22007-09-16 21:08:06 +00002101UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00002102@item
2103PCI VGA compatible card with VESA Bochs Extensions
2104@item
blueswir134a3d232008-10-04 20:43:39 +00002105PS/2 mouse and keyboard
2106@item
bellard83469012005-07-23 14:27:54 +00002107Non Volatile RAM M48T59
2108@item
2109PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00002110@item
21112 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00002112@item
2113Floppy disk
bellard83469012005-07-23 14:27:54 +00002114@end itemize
2115
blueswir1c7ba2182008-07-22 07:07:34 +00002116@c man begin OPTIONS
2117
2118The following options are specific to the Sparc64 emulation:
2119
2120@table @option
2121
Kevin Wolf4e257e52009-10-09 10:58:36 +02002122@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00002123
2124Set OpenBIOS variables in NVRAM, for example:
2125
2126@example
2127qemu-system-sparc64 -prom-env 'auto-boot?=false'
2128@end example
2129
2130@item -M [sun4u|sun4v|Niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00002131
2132Set the emulated machine type. The default is sun4u.
2133
2134@end table
2135
2136@c man end
2137
ths24d4de42007-07-11 10:24:28 +00002138@node MIPS System emulator
2139@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002140@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00002141
thsd9aedc32007-12-17 03:47:55 +00002142Four executables cover simulation of 32 and 64-bit MIPS systems in
2143both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2144@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00002145Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002146
2147@itemize @minus
2148@item
2149A generic ISA PC-like machine "mips"
2150@item
2151The MIPS Malta prototype board "malta"
2152@item
thsd9aedc32007-12-17 03:47:55 +00002153An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002154@item
thsf0fc6f82007-10-17 13:39:42 +00002155MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00002156@item
2157A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00002158@end itemize
2159
2160The generic emulation is supported by Debian 'Etch' and is able to
2161install Debian into a virtual disk image. The following devices are
2162emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002163
bellard3f9f3aa2005-12-18 20:11:37 +00002164@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002165@item
ths6bf5b4e2007-10-17 13:08:32 +00002166A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002167@item
2168PC style serial port
2169@item
ths24d4de42007-07-11 10:24:28 +00002170PC style IDE disk
2171@item
bellard3f9f3aa2005-12-18 20:11:37 +00002172NE2000 network card
2173@end itemize
2174
ths24d4de42007-07-11 10:24:28 +00002175The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002176
ths24d4de42007-07-11 10:24:28 +00002177@itemize @minus
2178@item
ths0b64d002007-07-11 21:43:14 +00002179Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002180@item
2181PIIX4 PCI/USB/SMbus controller
2182@item
2183The Multi-I/O chip's serial device
2184@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02002185PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00002186@item
2187Malta FPGA serial device
2188@item
aurel321f605a72009-02-08 14:51:19 +00002189Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00002190@end itemize
2191
2192The ACER Pica emulation supports:
2193
2194@itemize @minus
2195@item
2196MIPS R4000 CPU
2197@item
2198PC-style IRQ and DMA controllers
2199@item
2200PC Keyboard
2201@item
2202IDE controller
2203@end itemize
2204
Stefan Weilb5e49462011-11-13 22:24:26 +01002205The mipssim pseudo board emulation provides an environment similar
thsf0fc6f82007-10-17 13:39:42 +00002206to what the proprietary MIPS emulator uses for running Linux.
2207It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002208
2209@itemize @minus
2210@item
2211A range of MIPS CPUs, default is the 24Kf
2212@item
2213PC style serial port
2214@item
2215MIPSnet network emulation
2216@end itemize
2217
aurel3288cb0a02008-04-08 05:57:37 +00002218The MIPS Magnum R4000 emulation supports:
2219
2220@itemize @minus
2221@item
2222MIPS R4000 CPU
2223@item
2224PC-style IRQ controller
2225@item
2226PC Keyboard
2227@item
2228SCSI controller
2229@item
2230G364 framebuffer
2231@end itemize
2232
2233
ths24d4de42007-07-11 10:24:28 +00002234@node ARM System emulator
2235@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002236@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00002237
2238Use the executable @file{qemu-system-arm} to simulate a ARM
2239machine. The ARM Integrator/CP board is emulated with the following
2240devices:
2241
2242@itemize @minus
2243@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002244ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002245@item
2246Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002247@item
bellard3f9f3aa2005-12-18 20:11:37 +00002248SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002249@item
2250PL110 LCD controller
2251@item
2252PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002253@item
2254PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002255@end itemize
2256
2257The ARM Versatile baseboard is emulated with the following devices:
2258
2259@itemize @minus
2260@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002261ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002262@item
2263PL190 Vectored Interrupt Controller
2264@item
2265Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002266@item
pbrook00a9bf12006-05-13 16:55:46 +00002267SMC 91c111 Ethernet adapter
2268@item
2269PL110 LCD controller
2270@item
2271PL050 KMI with PS/2 keyboard and mouse.
2272@item
2273PCI host bridge. Note the emulated PCI bridge only provides access to
2274PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002275This means some devices (eg. ne2k_pci NIC) are not usable, and others
2276(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002277mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002278@item
2279PCI OHCI USB controller.
2280@item
2281LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002282@item
2283PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002284@end itemize
2285
Paul Brook21a88942009-12-21 20:19:12 +00002286Several variants of the ARM RealView baseboard are emulated,
2287including the EB, PB-A8 and PBX-A9. Due to interactions with the
2288bootloader, only certain Linux kernel configurations work out
2289of the box on these boards.
2290
2291Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2292enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
2293should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2294disabled and expect 1024M RAM.
2295
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002296The following devices are emulated:
pbrookd7739d72007-02-28 16:25:17 +00002297
2298@itemize @minus
2299@item
Paul Brookf7c70322009-11-19 16:45:21 +00002300ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00002301@item
2302ARM AMBA Generic/Distributed Interrupt Controller
2303@item
2304Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002305@item
Paul Brook0ef849d2009-11-16 17:06:43 +00002306SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00002307@item
2308PL110 LCD controller
2309@item
2310PL050 KMI with PS/2 keyboard and mouse
2311@item
2312PCI host bridge
2313@item
2314PCI OHCI USB controller
2315@item
2316LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002317@item
2318PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002319@end itemize
2320
balrogb00052e2007-04-30 02:22:06 +00002321The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2322and "Terrier") emulation includes the following peripherals:
2323
2324@itemize @minus
2325@item
2326Intel PXA270 System-on-chip (ARM V5TE core)
2327@item
2328NAND Flash memory
2329@item
2330IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2331@item
2332On-chip OHCI USB controller
2333@item
2334On-chip LCD controller
2335@item
2336On-chip Real Time Clock
2337@item
2338TI ADS7846 touchscreen controller on SSP bus
2339@item
2340Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2341@item
2342GPIO-connected keyboard controller and LEDs
2343@item
balrog549444e2007-05-01 17:53:37 +00002344Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002345@item
2346Three on-chip UARTs
2347@item
2348WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2349@end itemize
2350
balrog02645922007-11-03 12:50:46 +00002351The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2352following elements:
2353
2354@itemize @minus
2355@item
2356Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2357@item
2358ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2359@item
2360On-chip LCD controller
2361@item
2362On-chip Real Time Clock
2363@item
2364TI TSC2102i touchscreen controller / analog-digital converter / Audio
2365CODEC, connected through MicroWire and I@math{^2}S busses
2366@item
2367GPIO-connected matrix keypad
2368@item
2369Secure Digital card connected to OMAP MMC/SD host
2370@item
2371Three on-chip UARTs
2372@end itemize
2373
balrogc30bb262008-05-18 13:01:40 +00002374Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2375emulation supports the following elements:
2376
2377@itemize @minus
2378@item
2379Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2380@item
2381RAM and non-volatile OneNAND Flash memories
2382@item
2383Display connected to EPSON remote framebuffer chip and OMAP on-chip
2384display controller and a LS041y3 MIPI DBI-C controller
2385@item
2386TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2387driven through SPI bus
2388@item
2389National Semiconductor LM8323-controlled qwerty keyboard driven
2390through I@math{^2}C bus
2391@item
2392Secure Digital card connected to OMAP MMC/SD host
2393@item
2394Three OMAP on-chip UARTs and on-chip STI debugging console
2395@item
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002396A Bluetooth(R) transceiver and HCI connected to an UART
balrog2d564692008-11-09 02:24:54 +00002397@item
balrogc30bb262008-05-18 13:01:40 +00002398Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2399TUSB6010 chip - only USB host mode is supported
2400@item
2401TI TMP105 temperature sensor driven through I@math{^2}C bus
2402@item
2403TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2404@item
2405Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2406through CBUS
2407@end itemize
2408
pbrook9ee6e8b2007-11-11 00:04:49 +00002409The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2410devices:
2411
2412@itemize @minus
2413@item
2414Cortex-M3 CPU core.
2415@item
241664k Flash and 8k SRAM.
2417@item
2418Timers, UARTs, ADC and I@math{^2}C interface.
2419@item
2420OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2421@end itemize
2422
2423The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2424devices:
2425
2426@itemize @minus
2427@item
2428Cortex-M3 CPU core.
2429@item
2430256k Flash and 64k SRAM.
2431@item
2432Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2433@item
2434OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2435@end itemize
2436
balrog57cd6e92008-05-07 12:23:32 +00002437The Freecom MusicPal internet radio emulation includes the following
2438elements:
2439
2440@itemize @minus
2441@item
2442Marvell MV88W8618 ARM core.
2443@item
244432 MB RAM, 256 KB SRAM, 8 MB flash.
2445@item
2446Up to 2 16550 UARTs
2447@item
2448MV88W8xx8 Ethernet controller
2449@item
2450MV88W8618 audio controller, WM8750 CODEC and mixer
2451@item
Stefan Weile080e782010-02-05 23:52:00 +01002452128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00002453@item
24542 buttons, 2 navigation wheels with button function
2455@end itemize
2456
balrog997641a2008-12-15 02:05:00 +00002457The Siemens SX1 models v1 and v2 (default) basic emulation.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002458The emulation includes the following elements:
balrog997641a2008-12-15 02:05:00 +00002459
2460@itemize @minus
2461@item
2462Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2463@item
2464ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2465V1
24661 Flash of 16MB and 1 Flash of 8MB
2467V2
24681 Flash of 32MB
2469@item
2470On-chip LCD controller
2471@item
2472On-chip Real Time Clock
2473@item
2474Secure Digital card connected to OMAP MMC/SD host
2475@item
2476Three on-chip UARTs
2477@end itemize
2478
bellard3f9f3aa2005-12-18 20:11:37 +00002479A Linux 2.6 test image is available on the QEMU web site. More
2480information is available in the QEMU mailing-list archive.
2481
blueswir1d2c639d2009-01-24 18:19:25 +00002482@c man begin OPTIONS
2483
2484The following options are specific to the ARM emulation:
2485
2486@table @option
2487
2488@item -semihosting
2489Enable semihosting syscall emulation.
2490
2491On ARM this implements the "Angel" interface.
2492
2493Note that this allows guest direct access to the host filesystem,
2494so should only be used with trusted guest OS.
2495
2496@end table
2497
ths24d4de42007-07-11 10:24:28 +00002498@node ColdFire System emulator
2499@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002500@cindex system emulation (ColdFire)
2501@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002502
2503Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2504The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002505
2506The M5208EVB emulation includes the following devices:
2507
2508@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002509@item
pbrook707e0112007-06-04 00:50:06 +00002510MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2511@item
2512Three Two on-chip UARTs.
2513@item
2514Fast Ethernet Controller (FEC)
2515@end itemize
2516
2517The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002518
2519@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002520@item
pbrook209a4e62007-05-23 20:16:15 +00002521MCF5206 ColdFire V2 Microprocessor.
2522@item
2523Two on-chip UARTs.
2524@end itemize
2525
blueswir1d2c639d2009-01-24 18:19:25 +00002526@c man begin OPTIONS
2527
Stefan Weil7544a042010-02-05 23:52:03 +01002528The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002529
2530@table @option
2531
2532@item -semihosting
2533Enable semihosting syscall emulation.
2534
2535On M68K this implements the "ColdFire GDB" interface used by libgloss.
2536
2537Note that this allows guest direct access to the host filesystem,
2538so should only be used with trusted guest OS.
2539
2540@end table
2541
Stefan Weil7544a042010-02-05 23:52:03 +01002542@node Cris System emulator
2543@section Cris System emulator
2544@cindex system emulation (Cris)
2545
2546TODO
2547
2548@node Microblaze System emulator
2549@section Microblaze System emulator
2550@cindex system emulation (Microblaze)
2551
2552TODO
2553
2554@node SH4 System emulator
2555@section SH4 System emulator
2556@cindex system emulation (SH4)
2557
2558TODO
2559
Max Filippov3aeaea62011-10-10 14:48:23 +04002560@node Xtensa System emulator
2561@section Xtensa System emulator
2562@cindex system emulation (Xtensa)
2563
2564Two executables cover simulation of both Xtensa endian options,
2565@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2566Two different machine types are emulated:
2567
2568@itemize @minus
2569@item
2570Xtensa emulator pseudo board "sim"
2571@item
2572Avnet LX60/LX110/LX200 board
2573@end itemize
2574
Stefan Weilb5e49462011-11-13 22:24:26 +01002575The sim pseudo board emulation provides an environment similar
Max Filippov3aeaea62011-10-10 14:48:23 +04002576to one provided by the proprietary Tensilica ISS.
2577It supports:
2578
2579@itemize @minus
2580@item
2581A range of Xtensa CPUs, default is the DC232B
2582@item
2583Console and filesystem access via semihosting calls
2584@end itemize
2585
2586The Avnet LX60/LX110/LX200 emulation supports:
2587
2588@itemize @minus
2589@item
2590A range of Xtensa CPUs, default is the DC232B
2591@item
259216550 UART
2593@item
2594OpenCores 10/100 Mbps Ethernet MAC
2595@end itemize
2596
2597@c man begin OPTIONS
2598
2599The following options are specific to the Xtensa emulation:
2600
2601@table @option
2602
2603@item -semihosting
2604Enable semihosting syscall emulation.
2605
2606Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2607Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2608
2609Note that this allows guest direct access to the host filesystem,
2610so should only be used with trusted guest OS.
2611
2612@end table
ths5fafdf22007-09-16 21:08:06 +00002613@node QEMU User space emulator
2614@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002615
2616@menu
2617* Supported Operating Systems ::
2618* Linux User space emulator::
blueswir184778502008-10-26 20:33:16 +00002619* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002620@end menu
2621
2622@node Supported Operating Systems
2623@section Supported Operating Systems
2624
2625The following OS are supported in user space emulation:
2626
2627@itemize @minus
2628@item
ths4be456f2007-06-03 13:41:28 +00002629Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002630@item
blueswir184778502008-10-26 20:33:16 +00002631BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002632@end itemize
2633
2634@node Linux User space emulator
2635@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002636
bellarddebc7062006-04-30 21:58:41 +00002637@menu
2638* Quick Start::
2639* Wine launch::
2640* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002641* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002642@end menu
2643
2644@node Quick Start
bellard83195232007-02-05 19:42:07 +00002645@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002646
bellard1f673132004-04-04 15:21:17 +00002647In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002648itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002649
bellard1f673132004-04-04 15:21:17 +00002650@itemize
bellard386405f2003-03-23 21:28:45 +00002651
bellard1f673132004-04-04 15:21:17 +00002652@item On x86, you can just try to launch any process by using the native
2653libraries:
bellard386405f2003-03-23 21:28:45 +00002654
ths5fafdf22007-09-16 21:08:06 +00002655@example
bellard1f673132004-04-04 15:21:17 +00002656qemu-i386 -L / /bin/ls
2657@end example
bellardfd429f22003-03-30 20:59:46 +00002658
bellard1f673132004-04-04 15:21:17 +00002659@code{-L /} tells that the x86 dynamic linker must be searched with a
2660@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002661
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002662@item Since QEMU is also a linux process, you can launch QEMU with
2663QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002664
ths5fafdf22007-09-16 21:08:06 +00002665@example
bellard1f673132004-04-04 15:21:17 +00002666qemu-i386 -L / qemu-i386 -L / /bin/ls
2667@end example
bellard386405f2003-03-23 21:28:45 +00002668
bellard1f673132004-04-04 15:21:17 +00002669@item On non x86 CPUs, you need first to download at least an x86 glibc
2670(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2671@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002672
bellard1f673132004-04-04 15:21:17 +00002673@example
ths5fafdf22007-09-16 21:08:06 +00002674unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002675@end example
bellard386405f2003-03-23 21:28:45 +00002676
bellard1f673132004-04-04 15:21:17 +00002677Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002678
bellard1f673132004-04-04 15:21:17 +00002679@example
2680qemu-i386 tests/i386/ls
2681@end example
Blue Swirl4c3b5a42011-01-20 20:54:21 +00002682You can look at @file{scripts/qemu-binfmt-conf.sh} so that
bellard1f673132004-04-04 15:21:17 +00002683QEMU is automatically launched by the Linux kernel when you try to
2684launch x86 executables. It requires the @code{binfmt_misc} module in the
2685Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002686
bellard1f673132004-04-04 15:21:17 +00002687@item The x86 version of QEMU is also included. You can try weird things such as:
2688@example
bellarddebc7062006-04-30 21:58:41 +00002689qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2690 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002691@end example
bellard386405f2003-03-23 21:28:45 +00002692
bellard1f673132004-04-04 15:21:17 +00002693@end itemize
bellard386405f2003-03-23 21:28:45 +00002694
bellarddebc7062006-04-30 21:58:41 +00002695@node Wine launch
bellard83195232007-02-05 19:42:07 +00002696@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002697
bellard1f673132004-04-04 15:21:17 +00002698@itemize
bellard386405f2003-03-23 21:28:45 +00002699
bellard1f673132004-04-04 15:21:17 +00002700@item Ensure that you have a working QEMU with the x86 glibc
2701distribution (see previous section). In order to verify it, you must be
2702able to do:
bellard386405f2003-03-23 21:28:45 +00002703
bellard1f673132004-04-04 15:21:17 +00002704@example
2705qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2706@end example
bellard386405f2003-03-23 21:28:45 +00002707
bellard1f673132004-04-04 15:21:17 +00002708@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002709(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002710
bellard1f673132004-04-04 15:21:17 +00002711@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002712@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002713@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002714
bellard1f673132004-04-04 15:21:17 +00002715@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002716
bellard1f673132004-04-04 15:21:17 +00002717@example
bellarddebc7062006-04-30 21:58:41 +00002718qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2719 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002720@end example
bellard386405f2003-03-23 21:28:45 +00002721
bellard1f673132004-04-04 15:21:17 +00002722@end itemize
bellard386405f2003-03-23 21:28:45 +00002723
bellarddebc7062006-04-30 21:58:41 +00002724@node Command line options
bellard83195232007-02-05 19:42:07 +00002725@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002726
bellard1f673132004-04-04 15:21:17 +00002727@example
Paul Brook68a1c812010-05-29 02:27:35 +01002728usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
bellard1f673132004-04-04 15:21:17 +00002729@end example
bellard386405f2003-03-23 21:28:45 +00002730
bellard1f673132004-04-04 15:21:17 +00002731@table @option
2732@item -h
2733Print the help
ths3b46e622007-09-17 08:09:54 +00002734@item -L path
bellard1f673132004-04-04 15:21:17 +00002735Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2736@item -s size
2737Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002738@item -cpu model
Peter Maydellc8057f92012-08-02 13:45:54 +01002739Select CPU model (-cpu help for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002740@item -E @var{var}=@var{value}
2741Set environment @var{var} to @var{value}.
2742@item -U @var{var}
2743Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002744@item -B offset
2745Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002746the address region required by guest applications is reserved on the host.
2747This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002748@item -R size
2749Pre-allocate a guest virtual address space of the given size (in bytes).
Stefan Weil0d6753e2011-01-07 18:59:13 +01002750"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002751@end table
2752
bellard1f673132004-04-04 15:21:17 +00002753Debug options:
bellard386405f2003-03-23 21:28:45 +00002754
bellard1f673132004-04-04 15:21:17 +00002755@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00002756@item -d item1,...
2757Activate logging of the specified items (use '-d help' for a list of log items)
bellard1f673132004-04-04 15:21:17 +00002758@item -p pagesize
2759Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002760@item -g port
2761Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002762@item -singlestep
2763Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002764@end table
bellard386405f2003-03-23 21:28:45 +00002765
balrogb01bcae2007-12-16 13:05:59 +00002766Environment variables:
2767
2768@table @env
2769@item QEMU_STRACE
2770Print system calls and arguments similar to the 'strace' program
2771(NOTE: the actual 'strace' program will not work because the user
2772space emulator hasn't implemented ptrace). At the moment this is
2773incomplete. All system calls that don't have a specific argument
2774format are printed with information for six arguments. Many
2775flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002776@end table
balrogb01bcae2007-12-16 13:05:59 +00002777
pbrook79737e42006-06-11 16:28:41 +00002778@node Other binaries
bellard83195232007-02-05 19:42:07 +00002779@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002780
Stefan Weil7544a042010-02-05 23:52:03 +01002781@cindex user mode (Alpha)
2782@command{qemu-alpha} TODO.
2783
2784@cindex user mode (ARM)
2785@command{qemu-armeb} TODO.
2786
2787@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002788@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2789binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2790configurations), and arm-uclinux bFLT format binaries.
2791
Stefan Weil7544a042010-02-05 23:52:03 +01002792@cindex user mode (ColdFire)
2793@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002794@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2795(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2796coldfire uClinux bFLT format binaries.
2797
pbrook79737e42006-06-11 16:28:41 +00002798The binary format is detected automatically.
2799
Stefan Weil7544a042010-02-05 23:52:03 +01002800@cindex user mode (Cris)
2801@command{qemu-cris} TODO.
2802
2803@cindex user mode (i386)
2804@command{qemu-i386} TODO.
2805@command{qemu-x86_64} TODO.
2806
2807@cindex user mode (Microblaze)
2808@command{qemu-microblaze} TODO.
2809
2810@cindex user mode (MIPS)
2811@command{qemu-mips} TODO.
2812@command{qemu-mipsel} TODO.
2813
2814@cindex user mode (PowerPC)
2815@command{qemu-ppc64abi32} TODO.
2816@command{qemu-ppc64} TODO.
2817@command{qemu-ppc} TODO.
2818
2819@cindex user mode (SH4)
2820@command{qemu-sh4eb} TODO.
2821@command{qemu-sh4} TODO.
2822
2823@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002824@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2825
blueswir1a785e422007-10-20 08:09:05 +00002826@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2827(Sparc64 CPU, 32 bit ABI).
2828
2829@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2830SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2831
blueswir184778502008-10-26 20:33:16 +00002832@node BSD User space emulator
2833@section BSD User space emulator
2834
2835@menu
2836* BSD Status::
2837* BSD Quick Start::
2838* BSD Command line options::
2839@end menu
2840
2841@node BSD Status
2842@subsection BSD Status
2843
2844@itemize @minus
2845@item
2846target Sparc64 on Sparc64: Some trivial programs work.
2847@end itemize
2848
2849@node BSD Quick Start
2850@subsection Quick Start
2851
2852In order to launch a BSD process, QEMU needs the process executable
2853itself and all the target dynamic libraries used by it.
2854
2855@itemize
2856
2857@item On Sparc64, you can just try to launch any process by using the native
2858libraries:
2859
2860@example
2861qemu-sparc64 /bin/ls
2862@end example
2863
2864@end itemize
2865
2866@node BSD Command line options
2867@subsection Command line options
2868
2869@example
2870usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2871@end example
2872
2873@table @option
2874@item -h
2875Print the help
2876@item -L path
2877Set the library root path (default=/)
2878@item -s size
2879Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002880@item -ignore-environment
2881Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002882the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002883@item -E @var{var}=@var{value}
2884Set environment @var{var} to @var{value}.
2885@item -U @var{var}
2886Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00002887@item -bsd type
2888Set the type of the emulated BSD Operating system. Valid values are
2889FreeBSD, NetBSD and OpenBSD (default).
2890@end table
2891
2892Debug options:
2893
2894@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00002895@item -d item1,...
2896Activate logging of the specified items (use '-d help' for a list of log items)
blueswir184778502008-10-26 20:33:16 +00002897@item -p pagesize
2898Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002899@item -singlestep
2900Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00002901@end table
2902
bellard15a34c62004-07-08 21:26:26 +00002903@node compilation
2904@chapter Compilation from the sources
2905
bellarddebc7062006-04-30 21:58:41 +00002906@menu
2907* Linux/Unix::
2908* Windows::
2909* Cross compilation for Windows with Linux::
2910* Mac OS X::
Stefan Weil47eacb42010-02-05 23:52:01 +01002911* Make targets::
bellarddebc7062006-04-30 21:58:41 +00002912@end menu
2913
2914@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002915@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002916
bellard7c3fc842005-02-10 21:46:47 +00002917@subsection Compilation
2918
2919First you must decompress the sources:
2920@example
2921cd /tmp
2922tar zxvf qemu-x.y.z.tar.gz
2923cd qemu-x.y.z
2924@end example
2925
2926Then you configure QEMU and build it (usually no options are needed):
2927@example
2928./configure
2929make
2930@end example
2931
2932Then type as root user:
2933@example
2934make install
2935@end example
2936to install QEMU in @file{/usr/local}.
2937
bellarddebc7062006-04-30 21:58:41 +00002938@node Windows
bellard15a34c62004-07-08 21:26:26 +00002939@section Windows
2940
2941@itemize
2942@item Install the current versions of MSYS and MinGW from
2943@url{http://www.mingw.org/}. You can find detailed installation
2944instructions in the download section and the FAQ.
2945
ths5fafdf22007-09-16 21:08:06 +00002946@item Download
bellard15a34c62004-07-08 21:26:26 +00002947the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002948(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
Scott Tsaid0a96f32010-01-30 03:28:58 +08002949@url{http://www.libsdl.org}. Unpack it in a temporary place and
2950edit the @file{sdl-config} script so that it gives the
bellard15a34c62004-07-08 21:26:26 +00002951correct SDL directory when invoked.
2952
Scott Tsaid0a96f32010-01-30 03:28:58 +08002953@item Install the MinGW version of zlib and make sure
2954@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002955MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002956
bellard15a34c62004-07-08 21:26:26 +00002957@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002958
bellard15a34c62004-07-08 21:26:26 +00002959@item Start the MSYS shell (file @file{msys.bat}).
2960
ths5fafdf22007-09-16 21:08:06 +00002961@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00002962@file{make}. If you have problems using SDL, verify that
2963@file{sdl-config} can be launched from the MSYS command line.
2964
Stefan Weilc5ec15e2012-04-07 09:23:38 +02002965@item You can install QEMU in @file{Program Files/QEMU} by typing
bellard15a34c62004-07-08 21:26:26 +00002966@file{make install}. Don't forget to copy @file{SDL.dll} in
Stefan Weilc5ec15e2012-04-07 09:23:38 +02002967@file{Program Files/QEMU}.
bellard15a34c62004-07-08 21:26:26 +00002968
2969@end itemize
2970
bellarddebc7062006-04-30 21:58:41 +00002971@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00002972@section Cross compilation for Windows with Linux
2973
2974@itemize
2975@item
2976Install the MinGW cross compilation tools available at
2977@url{http://www.mingw.org/}.
2978
Scott Tsaid0a96f32010-01-30 03:28:58 +08002979@item Download
2980the MinGW development library of SDL 1.2.x
2981(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2982@url{http://www.libsdl.org}. Unpack it in a temporary place and
2983edit the @file{sdl-config} script so that it gives the
2984correct SDL directory when invoked. Set up the @code{PATH} environment
2985variable so that @file{sdl-config} can be launched by
bellard15a34c62004-07-08 21:26:26 +00002986the QEMU configuration script.
2987
Scott Tsaid0a96f32010-01-30 03:28:58 +08002988@item Install the MinGW version of zlib and make sure
2989@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002990MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002991
ths5fafdf22007-09-16 21:08:06 +00002992@item
bellard15a34c62004-07-08 21:26:26 +00002993Configure QEMU for Windows cross compilation:
2994@example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002995PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
bellard15a34c62004-07-08 21:26:26 +00002996@end example
Scott Tsaid0a96f32010-01-30 03:28:58 +08002997The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
2998MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002999We 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 +08003000use --cross-prefix to specify the name of the cross compiler.
Stefan Weilc5ec15e2012-04-07 09:23:38 +02003001You 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 +08003002
3003Under Fedora Linux, you can run:
3004@example
3005yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
3006@end example
3007to get a suitable cross compilation environment.
bellard15a34c62004-07-08 21:26:26 +00003008
ths5fafdf22007-09-16 21:08:06 +00003009@item You can install QEMU in the installation directory by typing
Scott Tsaid0a96f32010-01-30 03:28:58 +08003010@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
ths5fafdf22007-09-16 21:08:06 +00003011installation directory.
bellard15a34c62004-07-08 21:26:26 +00003012
3013@end itemize
3014
Stefan Weil3804da92012-05-11 22:21:50 +02003015Wine can be used to launch the resulting qemu-system-i386.exe
3016and all other qemu-system-@var{target}.exe compiled for Win32.
bellard15a34c62004-07-08 21:26:26 +00003017
bellarddebc7062006-04-30 21:58:41 +00003018@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00003019@section Mac OS X
3020
3021The Mac OS X patches are not fully merged in QEMU, so you should look
3022at the QEMU mailing list archive to have all the necessary
3023information.
3024
Stefan Weil47eacb42010-02-05 23:52:01 +01003025@node Make targets
3026@section Make targets
3027
3028@table @code
3029
3030@item make
3031@item make all
3032Make everything which is typically needed.
3033
3034@item install
3035TODO
3036
3037@item install-doc
3038TODO
3039
3040@item make clean
3041Remove most files which were built during make.
3042
3043@item make distclean
3044Remove everything which was built during make.
3045
3046@item make dvi
3047@item make html
3048@item make info
3049@item make pdf
3050Create documentation in dvi, html, info or pdf format.
3051
3052@item make cscope
3053TODO
3054
3055@item make defconfig
3056(Re-)create some build configuration files.
3057User made changes will be overwritten.
3058
3059@item tar
3060@item tarbin
3061TODO
3062
3063@end table
3064
Stefan Weil7544a042010-02-05 23:52:03 +01003065@node License
3066@appendix License
3067
3068QEMU is a trademark of Fabrice Bellard.
3069
3070QEMU is released under the GNU General Public License (TODO: add link).
3071Parts of QEMU have specific licenses, see file LICENSE.
3072
3073TODO (refer to file LICENSE, include it, include the GPL?)
3074
bellarddebc7062006-04-30 21:58:41 +00003075@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01003076@appendix Index
3077@menu
3078* Concept Index::
3079* Function Index::
3080* Keystroke Index::
3081* Program Index::
3082* Data Type Index::
3083* Variable Index::
3084@end menu
3085
3086@node Concept Index
3087@section Concept Index
3088This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00003089@printindex cp
3090
Stefan Weil7544a042010-02-05 23:52:03 +01003091@node Function Index
3092@section Function Index
3093This index could be used for command line options and monitor functions.
3094@printindex fn
3095
3096@node Keystroke Index
3097@section Keystroke Index
3098
3099This is a list of all keystrokes which have a special function
3100in system emulation.
3101
3102@printindex ky
3103
3104@node Program Index
3105@section Program Index
3106@printindex pg
3107
3108@node Data Type Index
3109@section Data Type Index
3110
3111This index could be used for qdev device names and options.
3112
3113@printindex tp
3114
3115@node Variable Index
3116@section Variable Index
3117@printindex vr
3118
bellarddebc7062006-04-30 21:58:41 +00003119@bye