blob: 79141d3582a424050601c5b291fe7d36b2292eee [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
Peter Maydella40db1b2016-02-16 17:28:58 +0000161* pcsys_keys:: Keys in the graphical frontends
162* mux_keys:: Keys in the character backend multiplexer
bellarddebc7062006-04-30 21:58:41 +0000163* pcsys_monitor:: QEMU Monitor
164* disk_images:: Disk Images
165* pcsys_network:: Network emulation
Stefan Weil576fd0a2011-01-07 18:59:14 +0100166* pcsys_other_devs:: Other Devices
bellarddebc7062006-04-30 21:58:41 +0000167* direct_linux_boot:: Direct Linux Boot
168* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000169* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000170* gdb_usage:: GDB usage
171* pcsys_os_specific:: Target OS specific information
172@end menu
173
174@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000175@section Introduction
176
177@c man begin DESCRIPTION
178
bellard3f9f3aa2005-12-18 20:11:37 +0000179The QEMU PC System emulator simulates the
180following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000181
182@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000183@item
bellard15a34c62004-07-08 21:26:26 +0000184i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000185@item
bellard15a34c62004-07-08 21:26:26 +0000186Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
187extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000188@item
189PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000190@item
bellard15a34c62004-07-08 21:26:26 +00001912 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000192@item
193Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000194@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +0200195PCI and ISA network adapters
bellard0806e3f2003-10-01 00:15:32 +0000196@item
bellard05d58182004-08-24 21:12:04 +0000197Serial ports
198@item
Corey Minyard23076bb2015-12-17 12:50:04 -0600199IPMI BMC, either and internal or external one
200@item
bellardc0fe3822005-11-05 18:55:28 +0000201Creative SoundBlaster 16 sound card
202@item
203ENSONIQ AudioPCI ES1370 sound card
204@item
balroge5c9a132008-01-14 04:27:55 +0000205Intel 82801AA AC97 Audio compatible sound card
206@item
Gerd Hoffmann7d72e762010-11-01 16:57:48 +0100207Intel HD Audio Controller and HDA codec
208@item
Stefan Weil2d983442011-01-07 18:59:15 +0100209Adlib (OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000210@item
balrog26463db2008-01-17 21:47:25 +0000211Gravis Ultrasound GF1 sound card
212@item
malccc53d262008-06-13 10:48:22 +0000213CS4231A compatible sound card
214@item
bellardb389dbf2005-11-06 16:49:55 +0000215PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000216@end itemize
217
bellard3f9f3aa2005-12-18 20:11:37 +0000218SMP is supported with up to 255 CPUs.
219
Michael Tokareva8ad4152013-06-28 10:08:16 +0400220QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
bellard15a34c62004-07-08 21:26:26 +0000221VGA BIOS.
222
bellardc0fe3822005-11-05 18:55:28 +0000223QEMU uses YM3812 emulation by Tatsuyuki Satoh.
224
Stefan Weil2d983442011-01-07 18:59:15 +0100225QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
balrog26463db2008-01-17 21:47:25 +0000226by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000227
Bernhard Reutner-Fischer1a1a0e22011-10-25 10:22:18 +0200228Note that, by default, GUS shares IRQ(7) with parallel ports and so
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200229QEMU must be told to not have parallel ports to have working GUS.
malc720036a2009-09-10 20:05:59 +0400230
231@example
Stefan Weil3804da92012-05-11 22:21:50 +0200232qemu-system-i386 dos.img -soundhw gus -parallel none
malc720036a2009-09-10 20:05:59 +0400233@end example
234
235Alternatively:
236@example
Stefan Weil3804da92012-05-11 22:21:50 +0200237qemu-system-i386 dos.img -device gus,irq=5
malc720036a2009-09-10 20:05:59 +0400238@end example
239
240Or some other unclaimed IRQ.
241
malccc53d262008-06-13 10:48:22 +0000242CS4231A is the chip used in Windows Sound System and GUSMAX products
243
bellard0806e3f2003-10-01 00:15:32 +0000244@c man end
245
bellarddebc7062006-04-30 21:58:41 +0000246@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000247@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100248@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000249
bellard285dc332003-10-27 23:58:04 +0000250Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000251
252@example
Stefan Weil3804da92012-05-11 22:21:50 +0200253qemu-system-i386 linux.img
bellard0806e3f2003-10-01 00:15:32 +0000254@end example
255
256Linux should boot and give you a prompt.
257
bellard6cc721c2005-07-28 22:27:28 +0000258@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000259@section Invocation
260
261@example
262@c man begin SYNOPSIS
Sitsofe Wheeler84851402016-01-13 20:50:26 +0000263@command{qemu-system-i386} [@var{options}] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000264@c man end
265@end example
266
267@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000268@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
269targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000270
blueswir15824d652009-03-28 06:44:27 +0000271@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000272
bellard3e11db92004-07-14 17:47:14 +0000273@c man end
274
bellarddebc7062006-04-30 21:58:41 +0000275@node pcsys_keys
Peter Maydella40db1b2016-02-16 17:28:58 +0000276@section Keys in the graphical frontends
bellard3e11db92004-07-14 17:47:14 +0000277
278@c man begin OPTIONS
279
Brad Hardsde1db2a2011-04-29 21:46:12 +1000280During the graphical emulation, you can use special key combinations to change
281modes. The default key mappings are shown below, but if you use @code{-alt-grab}
282then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
283@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
284
bellarda1b74fe2004-05-08 13:26:35 +0000285@table @key
bellardf9859312004-10-03 14:33:10 +0000286@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100287@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000288Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000289
Jan Kiszkad6a65ba2011-07-30 11:39:16 +0200290@item Ctrl-Alt-+
291@kindex Ctrl-Alt-+
292Enlarge the screen
293
294@item Ctrl-Alt--
295@kindex Ctrl-Alt--
296Shrink the screen
297
malcc4a735f2009-09-10 05:15:07 +0400298@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100299@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400300Restore the screen's un-scaled dimensions
301
bellardf9859312004-10-03 14:33:10 +0000302@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100303@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000304Switch to virtual console 'n'. Standard console mappings are:
305@table @emph
306@item 1
307Target system display
308@item 2
309Monitor
310@item 3
311Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000312@end table
313
bellardf9859312004-10-03 14:33:10 +0000314@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100315@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000316Toggle mouse and keyboard grab.
317@end table
318
Stefan Weil7544a042010-02-05 23:52:03 +0100319@kindex Ctrl-Up
320@kindex Ctrl-Down
321@kindex Ctrl-PageUp
322@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000323In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
324@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
325
Peter Maydella40db1b2016-02-16 17:28:58 +0000326@c man end
327
328@node mux_keys
329@section Keys in the character backend multiplexer
330
331@c man begin OPTIONS
332
333During emulation, if you are using a character backend multiplexer
334(which is the default if you are using @option{-nographic}) then
335several commands are available via an escape sequence. These
336key sequences all start with an escape character, which is @key{Ctrl-a}
337by default, but can be changed with @option{-echr}. The list below assumes
338you're using the default.
bellard1f673132004-04-04 15:21:17 +0000339
340@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000341@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100342@kindex Ctrl-a h
bellard1f673132004-04-04 15:21:17 +0000343Print this help
ths3b46e622007-09-17 08:09:54 +0000344@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100345@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000346Exit emulator
ths3b46e622007-09-17 08:09:54 +0000347@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100348@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000349Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000350@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100351@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000352Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000353@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100354@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000355Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000356@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100357@kindex Ctrl-a c
Peter Maydella40db1b2016-02-16 17:28:58 +0000358Rotate between the frontends connected to the multiplexer (usually
359this switches between the monitor and the console)
bellarda1b74fe2004-05-08 13:26:35 +0000360@item Ctrl-a Ctrl-a
Peter Maydella40db1b2016-02-16 17:28:58 +0000361@kindex Ctrl-a Ctrl-a
362Send the escape character to the frontend
bellard1f673132004-04-04 15:21:17 +0000363@end table
364@c man end
365
366@ignore
367
bellard1f673132004-04-04 15:21:17 +0000368@c man begin SEEALSO
369The HTML documentation of QEMU for more precise information and Linux
370user mode emulator invocation.
371@c man end
372
373@c man begin AUTHOR
374Fabrice Bellard
375@c man end
376
377@end ignore
378
bellarddebc7062006-04-30 21:58:41 +0000379@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000380@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100381@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000382
383The QEMU monitor is used to give complex commands to the QEMU
384emulator. You can use it to:
385
386@itemize @minus
387
388@item
thse5987522007-03-30 18:58:01 +0000389Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000390(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000391
ths5fafdf22007-09-16 21:08:06 +0000392@item
bellard1f673132004-04-04 15:21:17 +0000393Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
394from a disk file.
395
396@item Inspect the VM state without an external debugger.
397
398@end itemize
399
400@subsection Commands
401
402The following commands are available:
403
Blue Swirl23130862009-06-06 08:22:04 +0000404@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000405
Pavel Butsykin2cd8af22015-09-10 18:39:01 +0300406@include qemu-monitor-info.texi
407
bellard1f673132004-04-04 15:21:17 +0000408@subsection Integer expressions
409
410The monitor understands integers expressions for every integer
411argument. You can use register names to get the value of specifics
412CPU registers by prefixing them with @emph{$}.
413
414@node disk_images
415@section Disk Images
416
bellardacd935e2004-11-15 22:57:26 +0000417Since version 0.6.1, QEMU supports many disk image formats, including
418growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000419written), compressed and encrypted disk images. Version 0.8.3 added
420the new qcow2 disk image format which is essential to support VM
421snapshots.
bellard1f673132004-04-04 15:21:17 +0000422
bellarddebc7062006-04-30 21:58:41 +0000423@menu
424* disk_images_quickstart:: Quick start for disk image creation
425* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000426* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000427* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000428* qemu_nbd_invocation:: qemu-nbd Invocation
Marc-André Lureau665b5d02015-08-27 01:34:59 +0200429* qemu_ga_invocation:: qemu-ga Invocation
Kevin Wolfd3067b02012-11-21 14:21:47 +0100430* disk_images_formats:: Disk image file formats
bellard19cb3732006-08-19 11:45:59 +0000431* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000432* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +0000433* disk_images_nbd:: NBD access
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900434* disk_images_sheepdog:: Sheepdog disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100435* disk_images_iscsi:: iSCSI LUNs
Bharata B Rao8809e282012-10-24 17:17:53 +0530436* disk_images_gluster:: GlusterFS disk images
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +0100437* disk_images_ssh:: Secure Shell (ssh) disk images
bellarddebc7062006-04-30 21:58:41 +0000438@end menu
439
440@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000441@subsection Quick start for disk image creation
442
443You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000444@example
bellardacd935e2004-11-15 22:57:26 +0000445qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000446@end example
bellardacd935e2004-11-15 22:57:26 +0000447where @var{myimage.img} is the disk image filename and @var{mysize} is its
448size in kilobytes. You can add an @code{M} suffix to give the size in
449megabytes and a @code{G} suffix for gigabytes.
450
bellarddebc7062006-04-30 21:58:41 +0000451See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000452
bellarddebc7062006-04-30 21:58:41 +0000453@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000454@subsection Snapshot mode
455
456If you use the option @option{-snapshot}, all disk images are
457considered as read only. When sectors in written, they are written in
458a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000459write back to the raw disk images by using the @code{commit} monitor
460command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000461
bellard13a2e802006-08-06 14:50:31 +0000462@node vm_snapshots
463@subsection VM snapshots
464
465VM snapshots are snapshots of the complete virtual machine including
466CPU state, RAM, device state and the content of all the writable
467disks. In order to use VM snapshots, you must have at least one non
468removable and writable block device using the @code{qcow2} disk image
469format. Normally this device is the first virtual hard drive.
470
471Use the monitor command @code{savevm} to create a new VM snapshot or
472replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000473snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000474
475Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
476a VM snapshot. @code{info snapshots} lists the available snapshots
477with their associated information:
478
479@example
480(qemu) info snapshots
481Snapshot devices: hda
482Snapshot list (from hda):
483ID TAG VM SIZE DATE VM CLOCK
4841 start 41M 2006-08-06 12:38:02 00:00:14.954
4852 40M 2006-08-06 12:43:29 00:00:18.633
4863 msys 40M 2006-08-06 12:44:04 00:00:23.514
487@end example
488
489A VM snapshot is made of a VM state info (its size is shown in
490@code{info snapshots}) and a snapshot of every writable disk image.
491The VM state info is stored in the first @code{qcow2} non removable
492and writable block device. The disk image snapshots are stored in
493every disk image. The size of a snapshot in a disk image is difficult
494to evaluate and is not shown by @code{info snapshots} because the
495associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000496disk space (otherwise each snapshot would need a full copy of all the
497disk images).
bellard13a2e802006-08-06 14:50:31 +0000498
499When using the (unrelated) @code{-snapshot} option
500(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
501but they are deleted as soon as you exit QEMU.
502
503VM snapshots currently have the following known limitations:
504@itemize
ths5fafdf22007-09-16 21:08:06 +0000505@item
bellard13a2e802006-08-06 14:50:31 +0000506They cannot cope with removable devices if they are removed or
507inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000508@item
bellard13a2e802006-08-06 14:50:31 +0000509A few device drivers still have incomplete snapshot support so their
510state is not saved or restored properly (in particular USB).
511@end itemize
512
bellardacd935e2004-11-15 22:57:26 +0000513@node qemu_img_invocation
514@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000515
bellardacd935e2004-11-15 22:57:26 +0000516@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000517
ths975b0922008-07-02 21:18:00 +0000518@node qemu_nbd_invocation
519@subsection @code{qemu-nbd} Invocation
520
521@include qemu-nbd.texi
522
Marc-André Lureau665b5d02015-08-27 01:34:59 +0200523@node qemu_ga_invocation
524@subsection @code{qemu-ga} Invocation
525
526@include qemu-ga.texi
527
Kevin Wolfd3067b02012-11-21 14:21:47 +0100528@node disk_images_formats
529@subsection Disk image file formats
530
531QEMU supports many image file formats that can be used with VMs as well as with
532any of the tools (like @code{qemu-img}). This includes the preferred formats
533raw and qcow2 as well as formats that are supported for compatibility with
534older QEMU versions or other hypervisors.
535
536Depending on the image format, different options can be passed to
537@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
538This section describes each format and the options that are supported for it.
539
540@table @option
541@item raw
542
543Raw disk image format. This format has the advantage of
544being simple and easily exportable to all other emulators. If your
545file system supports @emph{holes} (for example in ext2 or ext3 on
546Linux or NTFS on Windows), then only the written sectors will reserve
547space. Use @code{qemu-img info} to know the real size used by the
548image or @code{ls -ls} on Unix/Linux.
549
Hu Tao06247422014-09-10 17:05:48 +0800550Supported options:
551@table @code
552@item preallocation
553Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
554@code{falloc} mode preallocates space for image by calling posix_fallocate().
555@code{full} mode preallocates space for image by writing zeros to underlying
556storage.
557@end table
558
Kevin Wolfd3067b02012-11-21 14:21:47 +0100559@item qcow2
560QEMU image format, the most versatile format. Use it to have smaller
561images (useful if your filesystem does not supports holes, for example
Markus Armbrustera1f688f2015-03-13 21:09:40 +0100562on Windows), zlib based compression and support of multiple VM
563snapshots.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100564
565Supported options:
566@table @code
567@item compat
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800568Determines the qcow2 version to use. @code{compat=0.10} uses the
569traditional image format that can be read by any QEMU since 0.10.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100570@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800571newer understand (this is the default). Amongst others, this includes
572zero clusters, which allow efficient copy-on-read for sparse images.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100573
574@item backing_file
575File name of a base image (see @option{create} subcommand)
576@item backing_fmt
577Image format of the base image
578@item encryption
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000579If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100580
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000581The use of encryption in qcow and qcow2 images is considered to be flawed by
582modern cryptography standards, suffering from a number of design problems:
583
584@itemize @minus
585@item The AES-CBC cipher is used with predictable initialization vectors based
586on the sector number. This makes it vulnerable to chosen plaintext attacks
587which can reveal the existence of encrypted data.
588@item The user passphrase is directly used as the encryption key. A poorly
589chosen or short passphrase will compromise the security of the encryption.
590@item In the event of the passphrase being compromised there is no way to
591change the passphrase to protect data in any qcow images. The files must
592be cloned, using a different encryption passphrase in the new file. The
593original file must then be securely erased using a program like shred,
594though even this is ineffective with many modern storage technologies.
595@end itemize
596
Markus Armbrustera1f688f2015-03-13 21:09:40 +0100597Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
598it will go away in a future release. Users are recommended to use an
599alternative encryption technology such as the Linux dm-crypt / LUKS
600system.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100601
602@item cluster_size
603Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
604sizes can improve the image file size whereas larger cluster sizes generally
605provide better performance.
606
607@item preallocation
Hu Tao0e4271b2014-09-10 17:05:49 +0800608Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
609@code{full}). An image with preallocated metadata is initially larger but can
610improve performance when the image needs to grow. @code{falloc} and @code{full}
611preallocations are like the same options of @code{raw} format, but sets up
612metadata also.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100613
614@item lazy_refcounts
615If this option is set to @code{on}, reference count updates are postponed with
616the goal of avoiding metadata I/O and improving performance. This is
617particularly interesting with @option{cache=writethrough} which doesn't batch
618metadata updates. The tradeoff is that after a host crash, the reference count
619tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
620check -r all} is required, which may take some time.
621
622This option can only be enabled if @code{compat=1.1} is specified.
623
Chunyan Liu4ab15592014-06-30 14:29:58 +0800624@item nocow
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800625If 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 +0800626valid on btrfs, no effect on other file systems.
627
628Btrfs has low performance when hosting a VM image file, even more when the guest
629on the VM also using btrfs as file system. Turning off COW is a way to mitigate
630this bad performance. Generally there are two ways to turn off COW on btrfs:
631a) Disable it by mounting with nodatacow, then all newly created files will be
632NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
633does.
634
635Note: this option is only valid to new or empty files. If there is an existing
636file which is COW and has data blocks already, it couldn't be changed to NOCOW
637by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800638the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
Chunyan Liu4ab15592014-06-30 14:29:58 +0800639
Kevin Wolfd3067b02012-11-21 14:21:47 +0100640@end table
641
642@item qed
643Old QEMU image format with support for backing files and compact image files
644(when your filesystem or transport medium does not support holes).
645
646When converting QED images to qcow2, you might want to consider using the
647@code{lazy_refcounts=on} option to get a more QED-like behaviour.
648
649Supported options:
650@table @code
651@item backing_file
652File name of a base image (see @option{create} subcommand).
653@item backing_fmt
654Image file format of backing file (optional). Useful if the format cannot be
655autodetected because it has no header, like some vhd/vpc files.
656@item cluster_size
657Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
658cluster sizes can improve the image file size whereas larger cluster sizes
659generally provide better performance.
660@item table_size
661Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
662and 16). There is normally no need to change this value but this option can be
663used for performance benchmarking.
664@end table
665
666@item qcow
667Old QEMU image format with support for backing files, compact image files,
668encryption and compression.
669
670Supported options:
671@table @code
672@item backing_file
673File name of a base image (see @option{create} subcommand)
674@item encryption
675If this option is set to @code{on}, the image is encrypted.
676@end table
677
Kevin Wolfd3067b02012-11-21 14:21:47 +0100678@item vdi
679VirtualBox 1.1 compatible image format.
680Supported options:
681@table @code
682@item static
683If this option is set to @code{on}, the image is created with metadata
684preallocation.
685@end table
686
687@item vmdk
688VMware 3 and 4 compatible image format.
689
690Supported options:
691@table @code
692@item backing_file
693File name of a base image (see @option{create} subcommand).
694@item compat6
695Create a VMDK version 6 image (instead of version 4)
696@item subformat
697Specifies which VMDK subformat to use. Valid options are
698@code{monolithicSparse} (default),
699@code{monolithicFlat},
700@code{twoGbMaxExtentSparse},
701@code{twoGbMaxExtentFlat} and
702@code{streamOptimized}.
703@end table
704
705@item vpc
706VirtualPC compatible image format (VHD).
707Supported options:
708@table @code
709@item subformat
710Specifies which VHD subformat to use. Valid options are
711@code{dynamic} (default) and @code{fixed}.
712@end table
Jeff Cody8282db12013-12-17 13:56:06 -0500713
714@item VHDX
715Hyper-V compatible image format (VHDX).
716Supported options:
717@table @code
718@item subformat
719Specifies which VHDX subformat to use. Valid options are
720@code{dynamic} (default) and @code{fixed}.
721@item block_state_zero
Jeff Cody30af51c2014-12-08 01:07:44 -0500722Force use of payload blocks of type 'ZERO'. Can be set to @code{on} (default)
723or @code{off}. When set to @code{off}, new blocks will be created as
724@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
725arbitrary data for those blocks. Do not set to @code{off} when using
726@code{qemu-img convert} with @code{subformat=dynamic}.
Jeff Cody8282db12013-12-17 13:56:06 -0500727@item block_size
728Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
729@item log_size
730Log size; min 1 MB.
731@end table
Kevin Wolfd3067b02012-11-21 14:21:47 +0100732@end table
733
734@subsubsection Read-only formats
735More disk image file formats are supported in a read-only mode.
736@table @option
737@item bochs
738Bochs images of @code{growing} type.
739@item cloop
740Linux Compressed Loop image, useful only to reuse directly compressed
741CD-ROM images present for example in the Knoppix CD-ROMs.
742@item dmg
743Apple disk image.
744@item parallels
745Parallels disk image format.
746@end table
747
748
bellard19cb3732006-08-19 11:45:59 +0000749@node host_drives
750@subsection Using host drives
751
752In addition to disk image files, QEMU can directly access host
753devices. We describe here the usage for QEMU version >= 0.8.3.
754
755@subsubsection Linux
756
757On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000758disk image filename provided you have enough privileges to access
Markus Armbruster92a539d2015-03-17 17:02:20 +0100759it. For example, use @file{/dev/cdrom} to access to the CDROM.
bellard19cb3732006-08-19 11:45:59 +0000760
bellardf5420862006-08-21 20:26:44 +0000761@table @code
bellard19cb3732006-08-19 11:45:59 +0000762@item CD
763You can specify a CDROM device even if no CDROM is loaded. QEMU has
764specific code to detect CDROM insertion or removal. CDROM ejection by
765the guest OS is supported. Currently only data CDs are supported.
766@item Floppy
767You can specify a floppy device even if no floppy is loaded. Floppy
768removal is currently not detected accurately (if you change floppy
769without doing floppy access while the floppy is not loaded, the guest
770OS will think that the same floppy is loaded).
Markus Armbruster92a539d2015-03-17 17:02:20 +0100771Use of the host's floppy device is deprecated, and support for it will
772be removed in a future release.
bellard19cb3732006-08-19 11:45:59 +0000773@item Hard disks
774Hard disks can be used. Normally you must specify the whole disk
775(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
776see it as a partitioned disk. WARNING: unless you know what you do, it
777is better to only make READ-ONLY accesses to the hard disk otherwise
778you may corrupt your host data (use the @option{-snapshot} command
779line option or modify the device permissions accordingly).
780@end table
781
782@subsubsection Windows
783
bellard01781962007-01-07 22:43:30 +0000784@table @code
785@item CD
ths4be456f2007-06-03 13:41:28 +0000786The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000787alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
788supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000789
thse5987522007-03-30 18:58:01 +0000790Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000791is better to use the @code{change} or @code{eject} monitor commands to
792change or eject media.
bellard01781962007-01-07 22:43:30 +0000793@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000794Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000795where @var{N} is the drive number (0 is the first hard disk).
796
797WARNING: unless you know what you do, it is better to only make
798READ-ONLY accesses to the hard disk otherwise you may corrupt your
799host data (use the @option{-snapshot} command line so that the
800modifications are written in a temporary file).
801@end table
802
bellard19cb3732006-08-19 11:45:59 +0000803
804@subsubsection Mac OS X
805
ths5fafdf22007-09-16 21:08:06 +0000806@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000807
thse5987522007-03-30 18:58:01 +0000808Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000809is better to use the @code{change} or @code{eject} monitor commands to
810change or eject media.
811
bellarddebc7062006-04-30 21:58:41 +0000812@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000813@subsection Virtual FAT disk images
814
815QEMU can automatically create a virtual FAT disk image from a
816directory tree. In order to use it, just type:
817
ths5fafdf22007-09-16 21:08:06 +0000818@example
Stefan Weil3804da92012-05-11 22:21:50 +0200819qemu-system-i386 linux.img -hdb fat:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000820@end example
821
822Then you access access to all the files in the @file{/my_directory}
823directory without having to copy them in a disk image or to export
824them via SAMBA or NFS. The default access is @emph{read-only}.
825
826Floppies can be emulated with the @code{:floppy:} option:
827
ths5fafdf22007-09-16 21:08:06 +0000828@example
Stefan Weil3804da92012-05-11 22:21:50 +0200829qemu-system-i386 linux.img -fda fat:floppy:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000830@end example
831
832A read/write support is available for testing (beta stage) with the
833@code{:rw:} option:
834
ths5fafdf22007-09-16 21:08:06 +0000835@example
Stefan Weil3804da92012-05-11 22:21:50 +0200836qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000837@end example
838
839What you should @emph{never} do:
840@itemize
841@item use non-ASCII filenames ;
842@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000843@item expect it to work when loadvm'ing ;
844@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000845@end itemize
846
ths75818252008-07-03 13:41:03 +0000847@node disk_images_nbd
848@subsection NBD access
849
850QEMU can access directly to block device exported using the Network Block Device
851protocol.
852
853@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100854qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
ths75818252008-07-03 13:41:03 +0000855@end example
856
857If the NBD server is located on the same host, you can use an unix socket instead
858of an inet socket:
859
860@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100861qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000862@end example
863
864In this case, the block device must be exported using qemu-nbd:
865
866@example
867qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
868@end example
869
Michael Tokarev9d85d552014-04-07 13:34:58 +0400870The use of qemu-nbd allows sharing of a disk between several guests:
ths75818252008-07-03 13:41:03 +0000871@example
872qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
873@end example
874
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100875@noindent
ths75818252008-07-03 13:41:03 +0000876and then you can use it with two guests:
877@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100878qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
879qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000880@end example
881
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100882If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
883own embedded NBD server), you must specify an export name in the URI:
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200884@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100885qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
886qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
887@end example
888
889The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
890also available. Here are some example of the older syntax:
891@example
892qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
893qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
894qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200895@end example
896
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900897@node disk_images_sheepdog
898@subsection Sheepdog disk images
899
900Sheepdog is a distributed storage system for QEMU. It provides highly
901available block level storage volumes that can be attached to
902QEMU-based virtual machines.
903
904You can create a Sheepdog disk image with the command:
905@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900906qemu-img create sheepdog:///@var{image} @var{size}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900907@end example
908where @var{image} is the Sheepdog image name and @var{size} is its
909size.
910
911To import the existing @var{filename} to Sheepdog, you can use a
912convert command.
913@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900914qemu-img convert @var{filename} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900915@end example
916
917You can boot from the Sheepdog disk image with the command:
918@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900919qemu-system-i386 sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900920@end example
921
922You can also create a snapshot of the Sheepdog image like qcow2.
923@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900924qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900925@end example
926where @var{tag} is a tag name of the newly created snapshot.
927
928To boot from the Sheepdog snapshot, specify the tag name of the
929snapshot.
930@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900931qemu-system-i386 sheepdog:///@var{image}#@var{tag}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900932@end example
933
934You can create a cloned image from the existing snapshot.
935@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900936qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900937@end example
938where @var{base} is a image name of the source snapshot and @var{tag}
939is its tag name.
940
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +0900941You can use an unix socket instead of an inet socket:
942
943@example
944qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
945@end example
946
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900947If the Sheepdog daemon doesn't run on the local host, you need to
948specify one of the Sheepdog servers to connect to.
949@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900950qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
951qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900952@end example
953
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100954@node disk_images_iscsi
955@subsection iSCSI LUNs
956
957iSCSI is a popular protocol used to access SCSI devices across a computer
958network.
959
960There are two different ways iSCSI devices can be used by QEMU.
961
962The first method is to mount the iSCSI LUN on the host, and make it appear as
963any other ordinary SCSI device on the host and then to access this device as a
964/dev/sd device from QEMU. How to do this differs between host OSes.
965
966The second method involves using the iSCSI initiator that is built into
967QEMU. This provides a mechanism that works the same way regardless of which
968host OS you are running QEMU on. This section will describe this second method
969of using iSCSI together with QEMU.
970
971In QEMU, iSCSI devices are described using special iSCSI URLs
972
973@example
974URL syntax:
975iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
976@end example
977
978Username and password are optional and only used if your target is set up
979using CHAP authentication for access control.
980Alternatively the username and password can also be set via environment
981variables to have these not show up in the process list
982
983@example
984export LIBISCSI_CHAP_USERNAME=<username>
985export LIBISCSI_CHAP_PASSWORD=<password>
986iscsi://<host>/<target-iqn-name>/<lun>
987@end example
988
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100989Various session related parameters can be set via special options, either
990in a configuration file provided via '-readconfig' or directly on the
991command line.
992
Ronnie Sahlberg31459f42012-08-06 18:24:55 +1000993If the initiator-name is not specified qemu will use a default name
994of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
995virtual machine.
996
997
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100998@example
999Setting a specific initiator name to use when logging in to the target
1000-iscsi initiator-name=iqn.qemu.test:my-initiator
1001@end example
1002
1003@example
1004Controlling which type of header digest to negotiate with the target
1005-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1006@end example
1007
1008These can also be set via a configuration file
1009@example
1010[iscsi]
1011 user = "CHAP username"
1012 password = "CHAP password"
1013 initiator-name = "iqn.qemu.test:my-initiator"
1014 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1015 header-digest = "CRC32C"
1016@end example
1017
1018
1019Setting the target name allows different options for different targets
1020@example
1021[iscsi "iqn.target.name"]
1022 user = "CHAP username"
1023 password = "CHAP password"
1024 initiator-name = "iqn.qemu.test:my-initiator"
1025 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1026 header-digest = "CRC32C"
1027@end example
1028
1029
1030Howto use a configuration file to set iSCSI configuration options:
1031@example
1032cat >iscsi.conf <<EOF
1033[iscsi]
1034 user = "me"
1035 password = "my password"
1036 initiator-name = "iqn.qemu.test:my-initiator"
1037 header-digest = "CRC32C"
1038EOF
1039
1040qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1041 -readconfig iscsi.conf
1042@end example
1043
1044
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001045Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
1046@example
1047This example shows how to set up an iSCSI target with one CDROM and one DISK
1048using the Linux STGT software target. This target is available on Red Hat based
1049systems as the package 'scsi-target-utils'.
1050
1051tgtd --iscsi portal=127.0.0.1:3260
1052tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
1053tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
1054 -b /IMAGES/disk.img --device-type=disk
1055tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
1056 -b /IMAGES/cd.iso --device-type=cd
1057tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
1058
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11001059qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
1060 -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001061 -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
1062@end example
1063
Bharata B Rao8809e282012-10-24 17:17:53 +05301064@node disk_images_gluster
1065@subsection GlusterFS disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001066
Bharata B Rao8809e282012-10-24 17:17:53 +05301067GlusterFS is an user space distributed file system.
1068
1069You can boot from the GlusterFS disk image with the command:
1070@example
1071qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
1072@end example
1073
1074@var{gluster} is the protocol.
1075
1076@var{transport} specifies the transport type used to connect to gluster
1077management daemon (glusterd). Valid transport types are
1078tcp, unix and rdma. If a transport type isn't specified, then tcp
1079type is assumed.
1080
1081@var{server} specifies the server where the volume file specification for
1082the given volume resides. This can be either hostname, ipv4 address
1083or ipv6 address. ipv6 address needs to be within square brackets [ ].
Gongleid274e072015-07-03 17:50:57 +08001084If transport type is unix, then @var{server} field should not be specified.
Bharata B Rao8809e282012-10-24 17:17:53 +05301085Instead @var{socket} field needs to be populated with the path to unix domain
1086socket.
1087
1088@var{port} is the port number on which glusterd is listening. This is optional
1089and if not specified, QEMU will send 0 which will make gluster to use the
1090default port. If the transport type is unix, then @var{port} should not be
1091specified.
1092
1093@var{volname} is the name of the gluster volume which contains the disk image.
1094
1095@var{image} is the path to the actual disk image that resides on gluster volume.
1096
1097You can create a GlusterFS disk image with the command:
1098@example
1099qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
1100@end example
1101
1102Examples
1103@example
1104qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1105qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1106qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1107qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1108qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1109qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1110qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1111qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
1112@end example
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001113
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001114@node disk_images_ssh
1115@subsection Secure Shell (ssh) disk images
1116
1117You can access disk images located on a remote ssh server
1118by using the ssh protocol:
1119
1120@example
1121qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
1122@end example
1123
1124Alternative syntax using properties:
1125
1126@example
1127qemu-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}]
1128@end example
1129
1130@var{ssh} is the protocol.
1131
1132@var{user} is the remote user. If not specified, then the local
1133username is tried.
1134
1135@var{server} specifies the remote ssh server. Any ssh server can be
1136used, but it must implement the sftp-server protocol. Most Unix/Linux
1137systems should work without requiring any extra configuration.
1138
1139@var{port} is the port number on which sshd is listening. By default
1140the standard ssh port (22) is used.
1141
1142@var{path} is the path to the disk image.
1143
1144The optional @var{host_key_check} parameter controls how the remote
1145host's key is checked. The default is @code{yes} which means to use
1146the local @file{.ssh/known_hosts} file. Setting this to @code{no}
1147turns off known-hosts checking. Or you can check that the host key
1148matches a specific fingerprint:
1149@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
1150(@code{sha1:} can also be used as a prefix, but note that OpenSSH
1151tools only use MD5 to print fingerprints).
1152
1153Currently authentication must be done using ssh-agent. Other
1154authentication methods may be supported in future.
1155
Richard W.M. Jones9a2d4622013-04-09 15:30:54 +01001156Note: Many ssh servers do not support an @code{fsync}-style operation.
1157The ssh driver cannot guarantee that disk flush requests are
1158obeyed, and this causes a risk of disk corruption if the remote
1159server or network goes down during writes. The driver will
1160print a warning when @code{fsync} is not supported:
1161
1162warning: ssh server @code{ssh.example.com:22} does not support fsync
1163
1164With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
1165supported.
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001166
bellarddebc7062006-04-30 21:58:41 +00001167@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001168@section Network emulation
1169
ths4be456f2007-06-03 13:41:28 +00001170QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001171target) and can connect them to an arbitrary number of Virtual Local
1172Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1173VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001174simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001175network stack can replace the TAP device to have a basic network
1176connection.
bellard9d4fb822004-04-26 20:55:38 +00001177
bellard41d03942005-11-15 23:02:53 +00001178@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001179
bellard41d03942005-11-15 23:02:53 +00001180QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1181connection between several network devices. These devices can be for
1182example QEMU virtual Ethernet cards or virtual Host ethernet devices
1183(TAP devices).
1184
1185@subsection Using TAP network interfaces
1186
1187This is the standard way to connect QEMU to a real network. QEMU adds
1188a virtual network device on your host (called @code{tapN}), and you
1189can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001190
bellard8f40c382006-09-20 20:28:05 +00001191@subsubsection Linux host
1192
bellard9d4fb822004-04-26 20:55:38 +00001193As an example, you can download the @file{linux-test-xxx.tar.gz}
1194archive and copy the script @file{qemu-ifup} in @file{/etc} and
1195configure properly @code{sudo} so that the command @code{ifconfig}
1196contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001197that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001198device @file{/dev/net/tun} must be present.
1199
bellardee0f4752006-08-19 16:56:18 +00001200See @ref{sec_invocation} to have examples of command lines using the
1201TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001202
bellard8f40c382006-09-20 20:28:05 +00001203@subsubsection Windows host
1204
1205There is a virtual ethernet driver for Windows 2000/XP systems, called
1206TAP-Win32. But it is not included in standard QEMU for Windows,
1207so you will need to get it separately. It is part of OpenVPN package,
1208so download OpenVPN from : @url{http://openvpn.net/}.
1209
bellard9d4fb822004-04-26 20:55:38 +00001210@subsection Using the user mode network stack
1211
bellard41d03942005-11-15 23:02:53 +00001212By using the option @option{-net user} (default configuration if no
1213@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001214network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001215network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001216
1217@example
1218
bellard41d03942005-11-15 23:02:53 +00001219 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1220 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001221 |
bellard2518bd02004-09-30 22:35:13 +00001222 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001223 |
bellard2518bd02004-09-30 22:35:13 +00001224 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001225@end example
1226
1227The QEMU VM behaves as if it was behind a firewall which blocks all
1228incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001229configure the network in the QEMU VM. The DHCP server assign addresses
1230to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001231
1232In order to check that the user mode network is working, you can ping
1233the address 10.0.2.2 and verify that you got an address in the range
123410.0.2.x from the QEMU virtual DHCP server.
1235
Gernot Hillier37cbfcc2014-07-10 16:01:25 +02001236Note that ICMP traffic in general does not work with user mode networking.
1237@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
1238however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
1239ping sockets to allow @code{ping} to the Internet. The host admin has to set
1240the ping_group_range in order to grant access to those sockets. To allow ping
1241for GID 100 (usually users group):
1242
1243@example
1244echo 100 100 > /proc/sys/net/ipv4/ping_group_range
1245@end example
bellardb415a402004-05-23 21:04:06 +00001246
bellard9bf05442004-08-25 22:12:49 +00001247When using the built-in TFTP server, the router is also the TFTP
1248server.
1249
Thomas Huthc8c6afa2016-01-13 09:21:02 +01001250When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
1251connections can be redirected from the host to the guest. It allows for
1252example to redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001253
bellard41d03942005-11-15 23:02:53 +00001254@subsection Connecting VLANs between QEMU instances
1255
1256Using the @option{-net socket} option, it is possible to make VLANs
1257that span several QEMU instances. See @ref{sec_invocation} to have a
1258basic example.
1259
Stefan Weil576fd0a2011-01-07 18:59:14 +01001260@node pcsys_other_devs
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001261@section Other Devices
1262
1263@subsection Inter-VM Shared Memory device
1264
Markus Armbruster5400c022016-03-15 19:34:51 +01001265On Linux hosts, a shared memory device is available. The basic syntax
1266is:
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001267
1268@example
Markus Armbruster5400c022016-03-15 19:34:51 +01001269qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
1270@end example
1271
1272where @var{hostmem} names a host memory backend. For a POSIX shared
1273memory backend, use something like
1274
1275@example
1276-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001277@end example
1278
1279If desired, interrupts can be sent between guest VMs accessing the same shared
1280memory region. Interrupt support requires using a shared memory server and
1281using a chardev socket to connect to it. The code for the shared memory server
1282is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
1283memory server is:
1284
1285@example
David Marchanda75eb032014-09-08 11:17:48 +02001286# First start the ivshmem server once and for all
Markus Armbruster50d34c42015-11-24 18:06:25 +01001287ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
David Marchanda75eb032014-09-08 11:17:48 +02001288
1289# Then start your qemu instances with matching arguments
Markus Armbruster5400c022016-03-15 19:34:51 +01001290qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
Markus Armbruster50d34c42015-11-24 18:06:25 +01001291 -chardev socket,path=@var{path},id=@var{id}
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001292@end example
1293
1294When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1295using the same server to communicate via interrupts. Guests can read their
Markus Armbruster1309cf42016-03-15 19:34:41 +01001296VM ID from a device register (see ivshmem-spec.txt).
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001297
Markus Armbruster62a830b2016-03-15 19:34:54 +01001298@subsubsection Migration with ivshmem
1299
Markus Armbruster5400c022016-03-15 19:34:51 +01001300With device property @option{master=on}, the guest will copy the shared
1301memory on migration to the destination host. With @option{master=off},
1302the guest will not be able to migrate with the device attached. In the
1303latter case, the device should be detached and then reattached after
1304migration using the PCI hotplug support.
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001305
Markus Armbruster62a830b2016-03-15 19:34:54 +01001306At most one of the devices sharing the same memory can be master. The
1307master must complete migration before you plug back the other devices.
1308
Marc-André Lureau7d4f4bd2015-10-07 16:31:47 +02001309@subsubsection ivshmem and hugepages
1310
1311Instead of specifying the <shm size> using POSIX shm, you may specify
1312a memory backend that has hugepage support:
1313
1314@example
Markus Armbruster5400c022016-03-15 19:34:51 +01001315qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
1316 -device ivshmem-plain,memdev=mb1
Marc-André Lureau7d4f4bd2015-10-07 16:31:47 +02001317@end example
1318
1319ivshmem-server also supports hugepages mount points with the
1320@option{-m} memory path argument.
1321
bellard9d4fb822004-04-26 20:55:38 +00001322@node direct_linux_boot
1323@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001324
1325This section explains how to launch a Linux kernel inside QEMU without
1326having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001327kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001328
bellardee0f4752006-08-19 16:56:18 +00001329The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001330@example
Stefan Weil3804da92012-05-11 22:21:50 +02001331qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001332@end example
1333
bellardee0f4752006-08-19 16:56:18 +00001334Use @option{-kernel} to provide the Linux kernel image and
1335@option{-append} to give the kernel command line arguments. The
1336@option{-initrd} option can be used to provide an INITRD image.
1337
1338When using the direct Linux boot, a disk image for the first hard disk
1339@file{hda} is required because its boot sector is used to launch the
1340Linux kernel.
1341
1342If you do not need graphical output, you can disable it and redirect
1343the virtual serial port and the QEMU monitor to the console with the
1344@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001345@example
Stefan Weil3804da92012-05-11 22:21:50 +02001346qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1347 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001348@end example
1349
bellardee0f4752006-08-19 16:56:18 +00001350Use @key{Ctrl-a c} to switch between the serial console and the
1351monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001352
bellarddebc7062006-04-30 21:58:41 +00001353@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001354@section USB emulation
1355
pbrook0aff66b2006-05-26 00:49:52 +00001356QEMU emulates a PCI UHCI USB controller. You can virtually plug
1357virtual USB devices or real host USB devices (experimental, works only
Stefan Weil071c9392012-04-07 09:23:36 +02001358on Linux hosts). QEMU will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001359as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001360
pbrook0aff66b2006-05-26 00:49:52 +00001361@menu
1362* usb_devices::
1363* host_usb_devices::
1364@end menu
1365@node usb_devices
1366@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001367
pbrook0aff66b2006-05-26 00:49:52 +00001368USB devices can be connected with the @option{-usbdevice} commandline option
1369or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001370
balrogdb380c02008-01-17 22:22:45 +00001371@table @code
1372@item mouse
pbrook0aff66b2006-05-26 00:49:52 +00001373Virtual Mouse. This will override the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001374@item tablet
bellardc6d46c22006-09-03 17:10:41 +00001375Pointer device that uses absolute coordinates (like a touchscreen).
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001376This means QEMU is able to report the mouse position without having
pbrook0aff66b2006-05-26 00:49:52 +00001377to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
balrogdb380c02008-01-17 22:22:45 +00001378@item disk:@var{file}
pbrook0aff66b2006-05-26 00:49:52 +00001379Mass storage device based on @var{file} (@pxref{disk_images})
balrogdb380c02008-01-17 22:22:45 +00001380@item host:@var{bus.addr}
pbrook0aff66b2006-05-26 00:49:52 +00001381Pass through the host device identified by @var{bus.addr}
1382(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001383@item host:@var{vendor_id:product_id}
pbrook0aff66b2006-05-26 00:49:52 +00001384Pass through the host device identified by @var{vendor_id:product_id}
1385(Linux only)
balrogdb380c02008-01-17 22:22:45 +00001386@item wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +00001387Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1388above but it can be used with the tslib library because in addition to touch
1389coordinates it reports touch pressure.
balrogdb380c02008-01-17 22:22:45 +00001390@item keyboard
balrog47b2d332007-06-22 08:16:00 +00001391Standard USB keyboard. Will override the PS/2 keyboard (if present).
balrogdb380c02008-01-17 22:22:45 +00001392@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1393Serial converter. This emulates an FTDI FT232BM chip connected to host character
1394device @var{dev}. The available character devices are the same as for the
1395@code{-serial} option. The @code{vendorid} and @code{productid} options can be
Stefan Weil0d6753e2011-01-07 18:59:13 +01001396used to override the default 0403:6001. For instance,
balrogdb380c02008-01-17 22:22:45 +00001397@example
1398usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1399@end example
1400will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1401serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
aurel322e4d9fb2008-04-08 06:01:02 +00001402@item braille
1403Braille device. This will use BrlAPI to display the braille output on a real
1404or fake device.
balrog9ad97e62008-07-29 13:16:31 +00001405@item net:@var{options}
1406Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1407specifies NIC options as with @code{-net nic,}@var{options} (see description).
1408For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +00001409@example
Stefan Weil3804da92012-05-11 22:21:50 +02001410qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
balrog6c9f8862008-07-17 20:47:13 +00001411@end example
1412Currently this cannot be used in machines that support PCI NICs.
balrog2d564692008-11-09 02:24:54 +00001413@item bt[:@var{hci-type}]
1414Bluetooth dongle whose type is specified in the same format as with
1415the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
1416no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1417This USB device implements the USB Transport Layer of HCI. Example
1418usage:
1419@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00001420@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
balrog2d564692008-11-09 02:24:54 +00001421@end example
pbrook0aff66b2006-05-26 00:49:52 +00001422@end table
bellardb389dbf2005-11-06 16:49:55 +00001423
pbrook0aff66b2006-05-26 00:49:52 +00001424@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001425@subsection Using host USB devices on a Linux host
1426
1427WARNING: this is an experimental feature. QEMU will slow down when
1428using it. USB devices requiring real time streaming (i.e. USB Video
1429Cameras) are not supported yet.
1430
1431@enumerate
ths5fafdf22007-09-16 21:08:06 +00001432@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001433is actually using the USB device. A simple way to do that is simply to
1434disable the corresponding kernel module by renaming it from @file{mydriver.o}
1435to @file{mydriver.o.disabled}.
1436
1437@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1438@example
1439ls /proc/bus/usb
1440001 devices drivers
1441@end example
1442
1443@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:
1444@example
1445chown -R myuid /proc/bus/usb
1446@end example
1447
1448@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001449@example
bellardb389dbf2005-11-06 16:49:55 +00001450info usbhost
1451 Device 1.2, speed 480 Mb/s
1452 Class 00: USB device 1234:5678, USB DISK
1453@end example
1454You should see the list of the devices you can use (Never try to use
1455hubs, it won't work).
1456
1457@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001458@example
bellardb389dbf2005-11-06 16:49:55 +00001459usb_add host:1234:5678
1460@end example
1461
1462Normally the guest OS should report that a new USB device is
1463plugged. You can use the option @option{-usbdevice} to do the same.
1464
1465@item Now you can try to use the host USB device in QEMU.
1466
1467@end enumerate
1468
1469When relaunching QEMU, you may have to unplug and plug again the USB
1470device to make it work again (this is a bug).
1471
thsf858dca2007-08-25 01:40:37 +00001472@node vnc_security
1473@section VNC security
1474
1475The VNC server capability provides access to the graphical console
1476of the guest VM across the network. This has a number of security
1477considerations depending on the deployment scenarios.
1478
1479@menu
1480* vnc_sec_none::
1481* vnc_sec_password::
1482* vnc_sec_certificate::
1483* vnc_sec_certificate_verify::
1484* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +00001485* vnc_sec_sasl::
1486* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +00001487* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +00001488* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +00001489@end menu
1490@node vnc_sec_none
1491@subsection Without passwords
1492
1493The simplest VNC server setup does not include any form of authentication.
1494For this setup it is recommended to restrict it to listen on a UNIX domain
1495socket only. For example
1496
1497@example
Stefan Weil3804da92012-05-11 22:21:50 +02001498qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
thsf858dca2007-08-25 01:40:37 +00001499@end example
1500
1501This ensures that only users on local box with read/write access to that
1502path can access the VNC server. To securely access the VNC server from a
1503remote machine, a combination of netcat+ssh can be used to provide a secure
1504tunnel.
1505
1506@node vnc_sec_password
1507@subsection With passwords
1508
1509The VNC protocol has limited support for password based authentication. Since
1510the protocol limits passwords to 8 characters it should not be considered
1511to provide high security. The password can be fairly easily brute-forced by
1512a client making repeat connections. For this reason, a VNC server using password
1513authentication should be restricted to only listen on the loopback interface
Paul Moore0f669982012-08-03 14:39:21 -04001514or UNIX domain sockets. Password authentication is not supported when operating
1515in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1516authentication is requested with the @code{password} option, and then once QEMU
1517is running the password is set with the monitor. Until the monitor is used to
1518set the password all clients will be rejected.
thsf858dca2007-08-25 01:40:37 +00001519
1520@example
Stefan Weil3804da92012-05-11 22:21:50 +02001521qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001522(qemu) change vnc password
1523Password: ********
1524(qemu)
1525@end example
1526
1527@node vnc_sec_certificate
1528@subsection With x509 certificates
1529
1530The QEMU VNC server also implements the VeNCrypt extension allowing use of
1531TLS for encryption of the session, and x509 certificates for authentication.
1532The use of x509 certificates is strongly recommended, because TLS on its
1533own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1534support provides a secure session, but no authentication. This allows any
1535client to connect, and provides an encrypted session.
1536
1537@example
Stefan Weil3804da92012-05-11 22:21:50 +02001538qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001539@end example
1540
1541In the above example @code{/etc/pki/qemu} should contain at least three files,
1542@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1543users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1544NB the @code{server-key.pem} file should be protected with file mode 0600 to
1545only be readable by the user owning it.
1546
1547@node vnc_sec_certificate_verify
1548@subsection With x509 certificates and client verification
1549
1550Certificates can also provide a means to authenticate the client connecting.
1551The server will request that the client provide a certificate, which it will
1552then validate against the CA certificate. This is a good choice if deploying
1553in an environment with a private internal certificate authority.
1554
1555@example
Stefan Weil3804da92012-05-11 22:21:50 +02001556qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001557@end example
1558
1559
1560@node vnc_sec_certificate_pw
1561@subsection With x509 certificates, client verification and passwords
1562
1563Finally, the previous method can be combined with VNC password authentication
1564to provide two layers of authentication for clients.
1565
1566@example
Stefan Weil3804da92012-05-11 22:21:50 +02001567qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001568(qemu) change vnc password
1569Password: ********
1570(qemu)
1571@end example
1572
aliguori2f9606b2009-03-06 20:27:28 +00001573
1574@node vnc_sec_sasl
1575@subsection With SASL authentication
1576
1577The SASL authentication method is a VNC extension, that provides an
1578easily extendable, pluggable authentication method. This allows for
1579integration with a wide range of authentication mechanisms, such as
1580PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1581The strength of the authentication depends on the exact mechanism
1582configured. If the chosen mechanism also provides a SSF layer, then
1583it will encrypt the datastream as well.
1584
1585Refer to the later docs on how to choose the exact SASL mechanism
1586used for authentication, but assuming use of one supporting SSF,
1587then QEMU can be launched with:
1588
1589@example
Stefan Weil3804da92012-05-11 22:21:50 +02001590qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001591@end example
1592
1593@node vnc_sec_certificate_sasl
1594@subsection With x509 certificates and SASL authentication
1595
1596If the desired SASL authentication mechanism does not supported
1597SSF layers, then it is strongly advised to run it in combination
1598with TLS and x509 certificates. This provides securely encrypted
1599data stream, avoiding risk of compromising of the security
1600credentials. This can be enabled, by combining the 'sasl' option
1601with the aforementioned TLS + x509 options:
1602
1603@example
Stefan Weil3804da92012-05-11 22:21:50 +02001604qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001605@end example
1606
1607
thsf858dca2007-08-25 01:40:37 +00001608@node vnc_generate_cert
1609@subsection Generating certificates for VNC
1610
1611The GNU TLS packages provides a command called @code{certtool} which can
1612be used to generate certificates and keys in PEM format. At a minimum it
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001613is necessary to setup a certificate authority, and issue certificates to
thsf858dca2007-08-25 01:40:37 +00001614each server. If using certificates for authentication, then each client
1615will also need to be issued a certificate. The recommendation is for the
1616server to keep its certificates in either @code{/etc/pki/qemu} or for
1617unprivileged users in @code{$HOME/.pki/qemu}.
1618
1619@menu
1620* vnc_generate_ca::
1621* vnc_generate_server::
1622* vnc_generate_client::
1623@end menu
1624@node vnc_generate_ca
1625@subsubsection Setup the Certificate Authority
1626
1627This step only needs to be performed once per organization / organizational
1628unit. First the CA needs a private key. This key must be kept VERY secret
1629and secure. If this key is compromised the entire trust chain of the certificates
1630issued with it is lost.
1631
1632@example
1633# certtool --generate-privkey > ca-key.pem
1634@end example
1635
1636A CA needs to have a public certificate. For simplicity it can be a self-signed
1637certificate, or one issue by a commercial certificate issuing authority. To
1638generate a self-signed certificate requires one core piece of information, the
1639name of the organization.
1640
1641@example
1642# cat > ca.info <<EOF
1643cn = Name of your organization
1644ca
1645cert_signing_key
1646EOF
1647# certtool --generate-self-signed \
1648 --load-privkey ca-key.pem
1649 --template ca.info \
1650 --outfile ca-cert.pem
1651@end example
1652
1653The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1654TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1655
1656@node vnc_generate_server
1657@subsubsection Issuing server certificates
1658
1659Each server (or host) needs to be issued with a key and certificate. When connecting
1660the certificate is sent to the client which validates it against the CA certificate.
1661The core piece of information for a server certificate is the hostname. This should
1662be the fully qualified hostname that the client will connect with, since the client
1663will typically also verify the hostname in the certificate. On the host holding the
1664secure CA private key:
1665
1666@example
1667# cat > server.info <<EOF
1668organization = Name of your organization
1669cn = server.foo.example.com
1670tls_www_server
1671encryption_key
1672signing_key
1673EOF
1674# certtool --generate-privkey > server-key.pem
1675# certtool --generate-certificate \
1676 --load-ca-certificate ca-cert.pem \
1677 --load-ca-privkey ca-key.pem \
Gonglei63c693f2014-11-03 20:48:30 +08001678 --load-privkey server-key.pem \
thsf858dca2007-08-25 01:40:37 +00001679 --template server.info \
1680 --outfile server-cert.pem
1681@end example
1682
1683The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1684to the server for which they were generated. The @code{server-key.pem} is security
1685sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1686
1687@node vnc_generate_client
1688@subsubsection Issuing client certificates
1689
1690If the QEMU VNC server is to use the @code{x509verify} option to validate client
1691certificates as its authentication mechanism, each client also needs to be issued
1692a certificate. The client certificate contains enough metadata to uniquely identify
1693the client, typically organization, state, city, building, etc. On the host holding
1694the secure CA private key:
1695
1696@example
1697# cat > client.info <<EOF
1698country = GB
1699state = London
1700locality = London
Gonglei63c693f2014-11-03 20:48:30 +08001701organization = Name of your organization
thsf858dca2007-08-25 01:40:37 +00001702cn = client.foo.example.com
1703tls_www_client
1704encryption_key
1705signing_key
1706EOF
1707# certtool --generate-privkey > client-key.pem
1708# certtool --generate-certificate \
1709 --load-ca-certificate ca-cert.pem \
1710 --load-ca-privkey ca-key.pem \
1711 --load-privkey client-key.pem \
1712 --template client.info \
1713 --outfile client-cert.pem
1714@end example
1715
1716The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1717copied to the client for which they were generated.
1718
aliguori2f9606b2009-03-06 20:27:28 +00001719
1720@node vnc_setup_sasl
1721
1722@subsection Configuring SASL mechanisms
1723
1724The following documentation assumes use of the Cyrus SASL implementation on a
1725Linux host, but the principals should apply to any other SASL impl. When SASL
1726is enabled, the mechanism configuration will be loaded from system default
1727SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1728unprivileged user, an environment variable SASL_CONF_PATH can be used
1729to make it search alternate locations for the service config.
1730
1731The default configuration might contain
1732
1733@example
1734mech_list: digest-md5
1735sasldb_path: /etc/qemu/passwd.db
1736@end example
1737
1738This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1739Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1740in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1741command. While this mechanism is easy to configure and use, it is not
1742considered secure by modern standards, so only suitable for developers /
1743ad-hoc testing.
1744
1745A more serious deployment might use Kerberos, which is done with the 'gssapi'
1746mechanism
1747
1748@example
1749mech_list: gssapi
1750keytab: /etc/qemu/krb5.tab
1751@end example
1752
1753For this to work the administrator of your KDC must generate a Kerberos
1754principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
1755replacing 'somehost.example.com' with the fully qualified host name of the
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001756machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
aliguori2f9606b2009-03-06 20:27:28 +00001757
1758Other configurations will be left as an exercise for the reader. It should
1759be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1760encryption. For all other mechanisms, VNC should always be configured to
1761use TLS and x509 certificates to protect security credentials from snooping.
1762
bellard0806e3f2003-10-01 00:15:32 +00001763@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001764@section GDB usage
1765
1766QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001767'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001768
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001769In order to use gdb, launch QEMU with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001770gdb connection:
1771@example
Stefan Weil3804da92012-05-11 22:21:50 +02001772qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1773 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001774Connected to host network interface: tun0
1775Waiting gdb connection on port 1234
1776@end example
1777
1778Then launch gdb on the 'vmlinux' executable:
1779@example
1780> gdb vmlinux
1781@end example
1782
1783In gdb, connect to QEMU:
1784@example
bellard6c9bf892004-01-24 13:46:56 +00001785(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001786@end example
1787
1788Then you can use gdb normally. For example, type 'c' to launch the kernel:
1789@example
1790(gdb) c
1791@end example
1792
bellard0806e3f2003-10-01 00:15:32 +00001793Here are some useful tips in order to use gdb on system code:
1794
1795@enumerate
1796@item
1797Use @code{info reg} to display all the CPU registers.
1798@item
1799Use @code{x/10i $eip} to display the code at the PC position.
1800@item
1801Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001802@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001803@end enumerate
1804
edgar_igl60897d32008-05-09 08:25:14 +00001805Advanced debugging options:
1806
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01001807The 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 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 +00001808@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001809@item maintenance packet qqemu.sstepbits
1810
1811This will display the MASK bits used to control the single stepping IE:
1812@example
1813(gdb) maintenance packet qqemu.sstepbits
1814sending: "qqemu.sstepbits"
1815received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1816@end example
1817@item maintenance packet qqemu.sstep
1818
1819This will display the current value of the mask used when single stepping IE:
1820@example
1821(gdb) maintenance packet qqemu.sstep
1822sending: "qqemu.sstep"
1823received: "0x7"
1824@end example
1825@item maintenance packet Qqemu.sstep=HEX_VALUE
1826
1827This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1828@example
1829(gdb) maintenance packet Qqemu.sstep=0x5
1830sending: "qemu.sstep=0x5"
1831received: "OK"
1832@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001833@end table
edgar_igl60897d32008-05-09 08:25:14 +00001834
bellarddebc7062006-04-30 21:58:41 +00001835@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001836@section Target OS specific information
1837
1838@subsection Linux
1839
bellard15a34c62004-07-08 21:26:26 +00001840To have access to SVGA graphic modes under X11, use the @code{vesa} or
1841the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1842color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001843
bellarde3371e62004-07-10 16:26:02 +00001844When using a 2.6 guest Linux kernel, you should add the option
1845@code{clock=pit} on the kernel command line because the 2.6 Linux
1846kernels make very strict real time clock checks by default that QEMU
1847cannot simulate exactly.
1848
bellard7c3fc842005-02-10 21:46:47 +00001849When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1850not activated because QEMU is slower with this patch. The QEMU
1851Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001852Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001853patch by default. Newer kernels don't have it.
1854
bellard1a084f32004-05-13 22:34:49 +00001855@subsection Windows
1856
1857If you have a slow host, using Windows 95 is better as it gives the
1858best speed. Windows 2000 is also a good choice.
1859
bellarde3371e62004-07-10 16:26:02 +00001860@subsubsection SVGA graphic modes support
1861
1862QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001863card. All Windows versions starting from Windows 95 should recognize
1864and use this graphic card. For optimal performances, use 16 bit color
1865depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001866
bellard3cb08532006-06-21 21:19:50 +00001867If you are using Windows XP as guest OS and if you want to use high
1868resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
18691280x1024x16), then you should use the VESA VBE virtual graphic card
1870(option @option{-std-vga}).
1871
bellarde3371e62004-07-10 16:26:02 +00001872@subsubsection CPU usage reduction
1873
1874Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001875instruction. The result is that it takes host CPU cycles even when
1876idle. You can install the utility from
1877@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1878problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001879
bellard9d0a8e62005-07-03 17:34:05 +00001880@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001881
bellard9d0a8e62005-07-03 17:34:05 +00001882Windows 2000 has a bug which gives a disk full problem during its
1883installation. When installing it, use the @option{-win2k-hack} QEMU
1884option to enable a specific workaround. After Windows 2000 is
1885installed, you no longer need this option (this option slows down the
1886IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001887
bellard6cc721c2005-07-28 22:27:28 +00001888@subsubsection Windows 2000 shutdown
1889
1890Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1891can. It comes from the fact that Windows 2000 does not automatically
1892use the APM driver provided by the BIOS.
1893
1894In order to correct that, do the following (thanks to Struan
1895Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1896Add/Troubleshoot a device => Add a new device & Next => No, select the
1897hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1898(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001899correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001900
1901@subsubsection Share a directory between Unix and Windows
1902
Thomas Huthc8c6afa2016-01-13 09:21:02 +01001903See @ref{sec_invocation} about the help of the option
1904@option{'-netdev user,smb=...'}.
bellard6cc721c2005-07-28 22:27:28 +00001905
bellard2192c332006-08-21 20:28:18 +00001906@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001907
1908Some releases of Windows XP install correctly but give a security
1909error when booting:
1910@example
1911A problem is preventing Windows from accurately checking the
1912license for this computer. Error code: 0x800703e6.
1913@end example
bellarde3371e62004-07-10 16:26:02 +00001914
bellard2192c332006-08-21 20:28:18 +00001915The workaround is to install a service pack for XP after a boot in safe
1916mode. Then reboot, and the problem should go away. Since there is no
1917network while in safe mode, its recommended to download the full
1918installation of SP1 or SP2 and transfer that via an ISO or using the
1919vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001920
bellarda0a821a2004-07-14 17:38:57 +00001921@subsection MS-DOS and FreeDOS
1922
1923@subsubsection CPU usage reduction
1924
1925DOS does not correctly use the CPU HLT instruction. The result is that
1926it takes host CPU cycles even when idle. You can install the utility
1927from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1928problem.
1929
bellarddebc7062006-04-30 21:58:41 +00001930@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001931@chapter QEMU System emulator for non PC targets
1932
1933QEMU is a generic emulator and it emulates many non PC
1934machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001935differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001936
bellarddebc7062006-04-30 21:58:41 +00001937@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001938* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001939* Sparc32 System emulator::
1940* Sparc64 System emulator::
1941* MIPS System emulator::
1942* ARM System emulator::
1943* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001944* Cris System emulator::
1945* Microblaze System emulator::
1946* SH4 System emulator::
Max Filippov3aeaea62011-10-10 14:48:23 +04001947* Xtensa System emulator::
bellarddebc7062006-04-30 21:58:41 +00001948@end menu
1949
Stefan Weil7544a042010-02-05 23:52:03 +01001950@node PowerPC System emulator
1951@section PowerPC System emulator
1952@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001953
1954Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001955or PowerMac PowerPC system.
1956
bellardb671f9e2005-04-30 15:08:33 +00001957QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001958
1959@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001960@item
blueswir1006f3a42009-02-08 15:59:36 +00001961UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001962@item
1963PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001964@item
bellard15a34c62004-07-08 21:26:26 +000019652 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001966@item
bellard15a34c62004-07-08 21:26:26 +00001967NE2000 PCI adapters
1968@item
1969Non Volatile RAM
1970@item
1971VIA-CUDA with ADB keyboard and mouse.
1972@end itemize
bellard52c00a52004-04-25 21:27:03 +00001973
bellardb671f9e2005-04-30 15:08:33 +00001974QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001975
1976@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001977@item
bellard15a34c62004-07-08 21:26:26 +00001978PCI Bridge
1979@item
1980PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001981@item
bellard52c00a52004-04-25 21:27:03 +000019822 IDE interfaces with hard disk and CD-ROM support
1983@item
1984Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001985@item
bellard15a34c62004-07-08 21:26:26 +00001986NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001987@item
1988Serial port
1989@item
1990PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001991@item
1992PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001993@end itemize
1994
bellard15a34c62004-07-08 21:26:26 +00001995QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001996@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001997
blueswir1992e5ac2008-12-24 20:23:51 +00001998Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00001999for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
2000v2) portable firmware implementation. The goal is to implement a 100%
2001IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00002002
bellard15a34c62004-07-08 21:26:26 +00002003@c man begin OPTIONS
2004
2005The following options are specific to the PowerPC emulation:
2006
2007@table @option
2008
Kevin Wolf4e257e52009-10-09 10:58:36 +02002009@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00002010
Mark Cave-Ayland340fb412014-03-17 21:46:26 +00002011Set the initial VGA graphic mode. The default is 800x600x32.
bellard15a34c62004-07-08 21:26:26 +00002012
Kevin Wolf4e257e52009-10-09 10:58:36 +02002013@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00002014
2015Set OpenBIOS variables in NVRAM, for example:
2016
2017@example
2018qemu-system-ppc -prom-env 'auto-boot?=false' \
2019 -prom-env 'boot-device=hd:2,\yaboot' \
2020 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
2021@end example
2022
2023These variables are not used by Open Hack'Ware.
2024
bellard15a34c62004-07-08 21:26:26 +00002025@end table
2026
ths5fafdf22007-09-16 21:08:06 +00002027@c man end
bellard15a34c62004-07-08 21:26:26 +00002028
2029
bellard52c00a52004-04-25 21:27:03 +00002030More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00002031@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00002032
ths24d4de42007-07-11 10:24:28 +00002033@node Sparc32 System emulator
2034@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002035@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00002036
blueswir134a3d232008-10-04 20:43:39 +00002037Use the executable @file{qemu-system-sparc} to simulate the following
2038Sun4m architecture machines:
2039@itemize @minus
2040@item
2041SPARCstation 4
2042@item
2043SPARCstation 5
2044@item
2045SPARCstation 10
2046@item
2047SPARCstation 20
2048@item
2049SPARCserver 600MP
2050@item
2051SPARCstation LX
2052@item
2053SPARCstation Voyager
2054@item
2055SPARCclassic
2056@item
2057SPARCbook
2058@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00002059
blueswir134a3d232008-10-04 20:43:39 +00002060The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2061but Linux limits the number of usable CPUs to 4.
2062
Blue Swirl6a4e1772013-04-14 18:10:28 +00002063QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00002064
2065@itemize @minus
bellard34751872005-07-02 14:31:34 +00002066@item
Blue Swirl6a4e1772013-04-14 18:10:28 +00002067IOMMU
bellarde80cfcf2004-12-19 23:18:01 +00002068@item
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002069TCX or cgthree Frame buffer
ths5fafdf22007-09-16 21:08:06 +00002070@item
bellarde80cfcf2004-12-19 23:18:01 +00002071Lance (Am7990) Ethernet
2072@item
blueswir134a3d232008-10-04 20:43:39 +00002073Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00002074@item
bellard34751872005-07-02 14:31:34 +00002075Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2076and power/reset logic
2077@item
2078ESP SCSI controller with hard disk and CD-ROM support
2079@item
blueswir16a3b9cc2007-11-11 17:56:38 +00002080Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00002081@item
2082CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00002083@end itemize
2084
blueswir16a3b9cc2007-11-11 17:56:38 +00002085The number of peripherals is fixed in the architecture. Maximum
2086memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00002087others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00002088
bellard30a604f2006-06-14 18:35:18 +00002089Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00002090@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2091firmware implementation. The goal is to implement a 100% IEEE
20921275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00002093
2094A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00002095the QEMU web site. There are still issues with NetBSD and OpenBSD, but
Mark Cave-Ayland9bb9f212015-03-02 22:23:27 +00002096most kernel versions work. Please note that currently older Solaris kernels
blueswir134a3d232008-10-04 20:43:39 +00002097don't work probably due to interface issues between OpenBIOS and
2098Solaris.
bellard34751872005-07-02 14:31:34 +00002099
2100@c man begin OPTIONS
2101
blueswir1a2502b52007-06-10 17:01:00 +00002102The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00002103
2104@table @option
2105
Kevin Wolf4e257e52009-10-09 10:58:36 +02002106@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00002107
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002108Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
2109option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
2110of 1152x900x8 for people who wish to use OBP.
bellard34751872005-07-02 14:31:34 +00002111
Kevin Wolf4e257e52009-10-09 10:58:36 +02002112@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00002113
2114Set OpenBIOS variables in NVRAM, for example:
2115
2116@example
2117qemu-system-sparc -prom-env 'auto-boot?=false' \
2118 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2119@end example
2120
Blue Swirl6a4e1772013-04-14 18:10:28 +00002121@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
blueswir1a2502b52007-06-10 17:01:00 +00002122
2123Set the emulated machine type. Default is SS-5.
2124
bellard34751872005-07-02 14:31:34 +00002125@end table
2126
ths5fafdf22007-09-16 21:08:06 +00002127@c man end
bellard34751872005-07-02 14:31:34 +00002128
ths24d4de42007-07-11 10:24:28 +00002129@node Sparc64 System emulator
2130@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002131@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00002132
blueswir134a3d232008-10-04 20:43:39 +00002133Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2134(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
Mark Cave-Ayland9bb9f212015-03-02 22:23:27 +00002135Niagara (T1) machine. The Sun4u emulator is mostly complete, being
2136able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
2137Sun4v and Niagara emulators are still a work in progress.
bellardb7569212005-03-13 09:43:05 +00002138
blueswir1c7ba2182008-07-22 07:07:34 +00002139QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00002140
2141@itemize @minus
2142@item
ths5fafdf22007-09-16 21:08:06 +00002143UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00002144@item
2145PCI VGA compatible card with VESA Bochs Extensions
2146@item
blueswir134a3d232008-10-04 20:43:39 +00002147PS/2 mouse and keyboard
2148@item
bellard83469012005-07-23 14:27:54 +00002149Non Volatile RAM M48T59
2150@item
2151PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00002152@item
21532 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00002154@item
2155Floppy disk
bellard83469012005-07-23 14:27:54 +00002156@end itemize
2157
blueswir1c7ba2182008-07-22 07:07:34 +00002158@c man begin OPTIONS
2159
2160The following options are specific to the Sparc64 emulation:
2161
2162@table @option
2163
Kevin Wolf4e257e52009-10-09 10:58:36 +02002164@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00002165
2166Set OpenBIOS variables in NVRAM, for example:
2167
2168@example
2169qemu-system-sparc64 -prom-env 'auto-boot?=false'
2170@end example
2171
2172@item -M [sun4u|sun4v|Niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00002173
2174Set the emulated machine type. The default is sun4u.
2175
2176@end table
2177
2178@c man end
2179
ths24d4de42007-07-11 10:24:28 +00002180@node MIPS System emulator
2181@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002182@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00002183
thsd9aedc32007-12-17 03:47:55 +00002184Four executables cover simulation of 32 and 64-bit MIPS systems in
2185both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2186@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00002187Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002188
2189@itemize @minus
2190@item
2191A generic ISA PC-like machine "mips"
2192@item
2193The MIPS Malta prototype board "malta"
2194@item
thsd9aedc32007-12-17 03:47:55 +00002195An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002196@item
thsf0fc6f82007-10-17 13:39:42 +00002197MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00002198@item
2199A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00002200@end itemize
2201
2202The generic emulation is supported by Debian 'Etch' and is able to
2203install Debian into a virtual disk image. The following devices are
2204emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002205
bellard3f9f3aa2005-12-18 20:11:37 +00002206@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002207@item
ths6bf5b4e2007-10-17 13:08:32 +00002208A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002209@item
2210PC style serial port
2211@item
ths24d4de42007-07-11 10:24:28 +00002212PC style IDE disk
2213@item
bellard3f9f3aa2005-12-18 20:11:37 +00002214NE2000 network card
2215@end itemize
2216
ths24d4de42007-07-11 10:24:28 +00002217The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002218
ths24d4de42007-07-11 10:24:28 +00002219@itemize @minus
2220@item
ths0b64d002007-07-11 21:43:14 +00002221Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002222@item
2223PIIX4 PCI/USB/SMbus controller
2224@item
2225The Multi-I/O chip's serial device
2226@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02002227PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00002228@item
2229Malta FPGA serial device
2230@item
aurel321f605a72009-02-08 14:51:19 +00002231Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00002232@end itemize
2233
2234The ACER Pica emulation supports:
2235
2236@itemize @minus
2237@item
2238MIPS R4000 CPU
2239@item
2240PC-style IRQ and DMA controllers
2241@item
2242PC Keyboard
2243@item
2244IDE controller
2245@end itemize
2246
Stefan Weilb5e49462011-11-13 22:24:26 +01002247The mipssim pseudo board emulation provides an environment similar
thsf0fc6f82007-10-17 13:39:42 +00002248to what the proprietary MIPS emulator uses for running Linux.
2249It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002250
2251@itemize @minus
2252@item
2253A range of MIPS CPUs, default is the 24Kf
2254@item
2255PC style serial port
2256@item
2257MIPSnet network emulation
2258@end itemize
2259
aurel3288cb0a02008-04-08 05:57:37 +00002260The MIPS Magnum R4000 emulation supports:
2261
2262@itemize @minus
2263@item
2264MIPS R4000 CPU
2265@item
2266PC-style IRQ controller
2267@item
2268PC Keyboard
2269@item
2270SCSI controller
2271@item
2272G364 framebuffer
2273@end itemize
2274
2275
ths24d4de42007-07-11 10:24:28 +00002276@node ARM System emulator
2277@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002278@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00002279
2280Use the executable @file{qemu-system-arm} to simulate a ARM
2281machine. The ARM Integrator/CP board is emulated with the following
2282devices:
2283
2284@itemize @minus
2285@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002286ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002287@item
2288Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002289@item
bellard3f9f3aa2005-12-18 20:11:37 +00002290SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002291@item
2292PL110 LCD controller
2293@item
2294PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002295@item
2296PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002297@end itemize
2298
2299The ARM Versatile baseboard is emulated with the following devices:
2300
2301@itemize @minus
2302@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002303ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002304@item
2305PL190 Vectored Interrupt Controller
2306@item
2307Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002308@item
pbrook00a9bf12006-05-13 16:55:46 +00002309SMC 91c111 Ethernet adapter
2310@item
2311PL110 LCD controller
2312@item
2313PL050 KMI with PS/2 keyboard and mouse.
2314@item
2315PCI host bridge. Note the emulated PCI bridge only provides access to
2316PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002317This means some devices (eg. ne2k_pci NIC) are not usable, and others
2318(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002319mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002320@item
2321PCI OHCI USB controller.
2322@item
2323LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002324@item
2325PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002326@end itemize
2327
Paul Brook21a88942009-12-21 20:19:12 +00002328Several variants of the ARM RealView baseboard are emulated,
2329including the EB, PB-A8 and PBX-A9. Due to interactions with the
2330bootloader, only certain Linux kernel configurations work out
2331of the box on these boards.
2332
2333Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2334enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
2335should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2336disabled and expect 1024M RAM.
2337
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002338The following devices are emulated:
pbrookd7739d72007-02-28 16:25:17 +00002339
2340@itemize @minus
2341@item
Paul Brookf7c70322009-11-19 16:45:21 +00002342ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00002343@item
2344ARM AMBA Generic/Distributed Interrupt Controller
2345@item
2346Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002347@item
Paul Brook0ef849d2009-11-16 17:06:43 +00002348SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00002349@item
2350PL110 LCD controller
2351@item
2352PL050 KMI with PS/2 keyboard and mouse
2353@item
2354PCI host bridge
2355@item
2356PCI OHCI USB controller
2357@item
2358LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002359@item
2360PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002361@end itemize
2362
balrogb00052e2007-04-30 02:22:06 +00002363The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2364and "Terrier") emulation includes the following peripherals:
2365
2366@itemize @minus
2367@item
2368Intel PXA270 System-on-chip (ARM V5TE core)
2369@item
2370NAND Flash memory
2371@item
2372IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2373@item
2374On-chip OHCI USB controller
2375@item
2376On-chip LCD controller
2377@item
2378On-chip Real Time Clock
2379@item
2380TI ADS7846 touchscreen controller on SSP bus
2381@item
2382Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2383@item
2384GPIO-connected keyboard controller and LEDs
2385@item
balrog549444e2007-05-01 17:53:37 +00002386Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002387@item
2388Three on-chip UARTs
2389@item
2390WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2391@end itemize
2392
balrog02645922007-11-03 12:50:46 +00002393The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2394following elements:
2395
2396@itemize @minus
2397@item
2398Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2399@item
2400ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2401@item
2402On-chip LCD controller
2403@item
2404On-chip Real Time Clock
2405@item
2406TI TSC2102i touchscreen controller / analog-digital converter / Audio
2407CODEC, connected through MicroWire and I@math{^2}S busses
2408@item
2409GPIO-connected matrix keypad
2410@item
2411Secure Digital card connected to OMAP MMC/SD host
2412@item
2413Three on-chip UARTs
2414@end itemize
2415
balrogc30bb262008-05-18 13:01:40 +00002416Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2417emulation supports the following elements:
2418
2419@itemize @minus
2420@item
2421Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2422@item
2423RAM and non-volatile OneNAND Flash memories
2424@item
2425Display connected to EPSON remote framebuffer chip and OMAP on-chip
2426display controller and a LS041y3 MIPI DBI-C controller
2427@item
2428TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2429driven through SPI bus
2430@item
2431National Semiconductor LM8323-controlled qwerty keyboard driven
2432through I@math{^2}C bus
2433@item
2434Secure Digital card connected to OMAP MMC/SD host
2435@item
2436Three OMAP on-chip UARTs and on-chip STI debugging console
2437@item
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002438A Bluetooth(R) transceiver and HCI connected to an UART
balrog2d564692008-11-09 02:24:54 +00002439@item
balrogc30bb262008-05-18 13:01:40 +00002440Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2441TUSB6010 chip - only USB host mode is supported
2442@item
2443TI TMP105 temperature sensor driven through I@math{^2}C bus
2444@item
2445TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2446@item
2447Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2448through CBUS
2449@end itemize
2450
pbrook9ee6e8b2007-11-11 00:04:49 +00002451The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2452devices:
2453
2454@itemize @minus
2455@item
2456Cortex-M3 CPU core.
2457@item
245864k Flash and 8k SRAM.
2459@item
2460Timers, UARTs, ADC and I@math{^2}C interface.
2461@item
2462OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2463@end itemize
2464
2465The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2466devices:
2467
2468@itemize @minus
2469@item
2470Cortex-M3 CPU core.
2471@item
2472256k Flash and 64k SRAM.
2473@item
2474Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2475@item
2476OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2477@end itemize
2478
balrog57cd6e92008-05-07 12:23:32 +00002479The Freecom MusicPal internet radio emulation includes the following
2480elements:
2481
2482@itemize @minus
2483@item
2484Marvell MV88W8618 ARM core.
2485@item
248632 MB RAM, 256 KB SRAM, 8 MB flash.
2487@item
2488Up to 2 16550 UARTs
2489@item
2490MV88W8xx8 Ethernet controller
2491@item
2492MV88W8618 audio controller, WM8750 CODEC and mixer
2493@item
Stefan Weile080e782010-02-05 23:52:00 +01002494128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00002495@item
24962 buttons, 2 navigation wheels with button function
2497@end itemize
2498
balrog997641a2008-12-15 02:05:00 +00002499The Siemens SX1 models v1 and v2 (default) basic emulation.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002500The emulation includes the following elements:
balrog997641a2008-12-15 02:05:00 +00002501
2502@itemize @minus
2503@item
2504Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2505@item
2506ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2507V1
25081 Flash of 16MB and 1 Flash of 8MB
2509V2
25101 Flash of 32MB
2511@item
2512On-chip LCD controller
2513@item
2514On-chip Real Time Clock
2515@item
2516Secure Digital card connected to OMAP MMC/SD host
2517@item
2518Three on-chip UARTs
2519@end itemize
2520
bellard3f9f3aa2005-12-18 20:11:37 +00002521A Linux 2.6 test image is available on the QEMU web site. More
2522information is available in the QEMU mailing-list archive.
2523
blueswir1d2c639d2009-01-24 18:19:25 +00002524@c man begin OPTIONS
2525
2526The following options are specific to the ARM emulation:
2527
2528@table @option
2529
2530@item -semihosting
2531Enable semihosting syscall emulation.
2532
2533On ARM this implements the "Angel" interface.
2534
2535Note that this allows guest direct access to the host filesystem,
2536so should only be used with trusted guest OS.
2537
2538@end table
2539
ths24d4de42007-07-11 10:24:28 +00002540@node ColdFire System emulator
2541@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002542@cindex system emulation (ColdFire)
2543@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002544
2545Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2546The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002547
2548The M5208EVB emulation includes the following devices:
2549
2550@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002551@item
pbrook707e0112007-06-04 00:50:06 +00002552MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2553@item
2554Three Two on-chip UARTs.
2555@item
2556Fast Ethernet Controller (FEC)
2557@end itemize
2558
2559The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002560
2561@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002562@item
pbrook209a4e62007-05-23 20:16:15 +00002563MCF5206 ColdFire V2 Microprocessor.
2564@item
2565Two on-chip UARTs.
2566@end itemize
2567
blueswir1d2c639d2009-01-24 18:19:25 +00002568@c man begin OPTIONS
2569
Stefan Weil7544a042010-02-05 23:52:03 +01002570The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002571
2572@table @option
2573
2574@item -semihosting
2575Enable semihosting syscall emulation.
2576
2577On M68K this implements the "ColdFire GDB" interface used by libgloss.
2578
2579Note that this allows guest direct access to the host filesystem,
2580so should only be used with trusted guest OS.
2581
2582@end table
2583
Stefan Weil7544a042010-02-05 23:52:03 +01002584@node Cris System emulator
2585@section Cris System emulator
2586@cindex system emulation (Cris)
2587
2588TODO
2589
2590@node Microblaze System emulator
2591@section Microblaze System emulator
2592@cindex system emulation (Microblaze)
2593
2594TODO
2595
2596@node SH4 System emulator
2597@section SH4 System emulator
2598@cindex system emulation (SH4)
2599
2600TODO
2601
Max Filippov3aeaea62011-10-10 14:48:23 +04002602@node Xtensa System emulator
2603@section Xtensa System emulator
2604@cindex system emulation (Xtensa)
2605
2606Two executables cover simulation of both Xtensa endian options,
2607@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2608Two different machine types are emulated:
2609
2610@itemize @minus
2611@item
2612Xtensa emulator pseudo board "sim"
2613@item
2614Avnet LX60/LX110/LX200 board
2615@end itemize
2616
Stefan Weilb5e49462011-11-13 22:24:26 +01002617The sim pseudo board emulation provides an environment similar
Max Filippov3aeaea62011-10-10 14:48:23 +04002618to one provided by the proprietary Tensilica ISS.
2619It supports:
2620
2621@itemize @minus
2622@item
2623A range of Xtensa CPUs, default is the DC232B
2624@item
2625Console and filesystem access via semihosting calls
2626@end itemize
2627
2628The Avnet LX60/LX110/LX200 emulation supports:
2629
2630@itemize @minus
2631@item
2632A range of Xtensa CPUs, default is the DC232B
2633@item
263416550 UART
2635@item
2636OpenCores 10/100 Mbps Ethernet MAC
2637@end itemize
2638
2639@c man begin OPTIONS
2640
2641The following options are specific to the Xtensa emulation:
2642
2643@table @option
2644
2645@item -semihosting
2646Enable semihosting syscall emulation.
2647
2648Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2649Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2650
2651Note that this allows guest direct access to the host filesystem,
2652so should only be used with trusted guest OS.
2653
2654@end table
ths5fafdf22007-09-16 21:08:06 +00002655@node QEMU User space emulator
2656@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002657
2658@menu
2659* Supported Operating Systems ::
2660* Linux User space emulator::
blueswir184778502008-10-26 20:33:16 +00002661* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002662@end menu
2663
2664@node Supported Operating Systems
2665@section Supported Operating Systems
2666
2667The following OS are supported in user space emulation:
2668
2669@itemize @minus
2670@item
ths4be456f2007-06-03 13:41:28 +00002671Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002672@item
blueswir184778502008-10-26 20:33:16 +00002673BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002674@end itemize
2675
2676@node Linux User space emulator
2677@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002678
bellarddebc7062006-04-30 21:58:41 +00002679@menu
2680* Quick Start::
2681* Wine launch::
2682* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002683* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002684@end menu
2685
2686@node Quick Start
bellard83195232007-02-05 19:42:07 +00002687@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002688
bellard1f673132004-04-04 15:21:17 +00002689In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002690itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002691
bellard1f673132004-04-04 15:21:17 +00002692@itemize
bellard386405f2003-03-23 21:28:45 +00002693
bellard1f673132004-04-04 15:21:17 +00002694@item On x86, you can just try to launch any process by using the native
2695libraries:
bellard386405f2003-03-23 21:28:45 +00002696
ths5fafdf22007-09-16 21:08:06 +00002697@example
bellard1f673132004-04-04 15:21:17 +00002698qemu-i386 -L / /bin/ls
2699@end example
bellardfd429f22003-03-30 20:59:46 +00002700
bellard1f673132004-04-04 15:21:17 +00002701@code{-L /} tells that the x86 dynamic linker must be searched with a
2702@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002703
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002704@item Since QEMU is also a linux process, you can launch QEMU with
2705QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002706
ths5fafdf22007-09-16 21:08:06 +00002707@example
bellard1f673132004-04-04 15:21:17 +00002708qemu-i386 -L / qemu-i386 -L / /bin/ls
2709@end example
bellard386405f2003-03-23 21:28:45 +00002710
bellard1f673132004-04-04 15:21:17 +00002711@item On non x86 CPUs, you need first to download at least an x86 glibc
2712(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2713@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002714
bellard1f673132004-04-04 15:21:17 +00002715@example
ths5fafdf22007-09-16 21:08:06 +00002716unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002717@end example
bellard386405f2003-03-23 21:28:45 +00002718
bellard1f673132004-04-04 15:21:17 +00002719Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002720
bellard1f673132004-04-04 15:21:17 +00002721@example
2722qemu-i386 tests/i386/ls
2723@end example
Blue Swirl4c3b5a42011-01-20 20:54:21 +00002724You can look at @file{scripts/qemu-binfmt-conf.sh} so that
bellard1f673132004-04-04 15:21:17 +00002725QEMU is automatically launched by the Linux kernel when you try to
2726launch x86 executables. It requires the @code{binfmt_misc} module in the
2727Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002728
bellard1f673132004-04-04 15:21:17 +00002729@item The x86 version of QEMU is also included. You can try weird things such as:
2730@example
bellarddebc7062006-04-30 21:58:41 +00002731qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2732 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002733@end example
bellard386405f2003-03-23 21:28:45 +00002734
bellard1f673132004-04-04 15:21:17 +00002735@end itemize
bellard386405f2003-03-23 21:28:45 +00002736
bellarddebc7062006-04-30 21:58:41 +00002737@node Wine launch
bellard83195232007-02-05 19:42:07 +00002738@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002739
bellard1f673132004-04-04 15:21:17 +00002740@itemize
bellard386405f2003-03-23 21:28:45 +00002741
bellard1f673132004-04-04 15:21:17 +00002742@item Ensure that you have a working QEMU with the x86 glibc
2743distribution (see previous section). In order to verify it, you must be
2744able to do:
bellard386405f2003-03-23 21:28:45 +00002745
bellard1f673132004-04-04 15:21:17 +00002746@example
2747qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2748@end example
bellard386405f2003-03-23 21:28:45 +00002749
bellard1f673132004-04-04 15:21:17 +00002750@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002751(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002752
bellard1f673132004-04-04 15:21:17 +00002753@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002754@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002755@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002756
bellard1f673132004-04-04 15:21:17 +00002757@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002758
bellard1f673132004-04-04 15:21:17 +00002759@example
bellarddebc7062006-04-30 21:58:41 +00002760qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2761 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002762@end example
bellard386405f2003-03-23 21:28:45 +00002763
bellard1f673132004-04-04 15:21:17 +00002764@end itemize
bellard386405f2003-03-23 21:28:45 +00002765
bellarddebc7062006-04-30 21:58:41 +00002766@node Command line options
bellard83195232007-02-05 19:42:07 +00002767@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002768
bellard1f673132004-04-04 15:21:17 +00002769@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00002770@command{qemu-i386} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-cpu} @var{model}] [@option{-g} @var{port}] [@option{-B} @var{offset}] [@option{-R} @var{size}] @var{program} [@var{arguments}...]
bellard1f673132004-04-04 15:21:17 +00002771@end example
bellard386405f2003-03-23 21:28:45 +00002772
bellard1f673132004-04-04 15:21:17 +00002773@table @option
2774@item -h
2775Print the help
ths3b46e622007-09-17 08:09:54 +00002776@item -L path
bellard1f673132004-04-04 15:21:17 +00002777Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2778@item -s size
2779Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002780@item -cpu model
Peter Maydellc8057f92012-08-02 13:45:54 +01002781Select CPU model (-cpu help for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002782@item -E @var{var}=@var{value}
2783Set environment @var{var} to @var{value}.
2784@item -U @var{var}
2785Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002786@item -B offset
2787Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002788the address region required by guest applications is reserved on the host.
2789This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002790@item -R size
2791Pre-allocate a guest virtual address space of the given size (in bytes).
Stefan Weil0d6753e2011-01-07 18:59:13 +01002792"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002793@end table
2794
bellard1f673132004-04-04 15:21:17 +00002795Debug options:
bellard386405f2003-03-23 21:28:45 +00002796
bellard1f673132004-04-04 15:21:17 +00002797@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00002798@item -d item1,...
2799Activate logging of the specified items (use '-d help' for a list of log items)
bellard1f673132004-04-04 15:21:17 +00002800@item -p pagesize
2801Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002802@item -g port
2803Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002804@item -singlestep
2805Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002806@end table
bellard386405f2003-03-23 21:28:45 +00002807
balrogb01bcae2007-12-16 13:05:59 +00002808Environment variables:
2809
2810@table @env
2811@item QEMU_STRACE
2812Print system calls and arguments similar to the 'strace' program
2813(NOTE: the actual 'strace' program will not work because the user
2814space emulator hasn't implemented ptrace). At the moment this is
2815incomplete. All system calls that don't have a specific argument
2816format are printed with information for six arguments. Many
2817flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002818@end table
balrogb01bcae2007-12-16 13:05:59 +00002819
pbrook79737e42006-06-11 16:28:41 +00002820@node Other binaries
bellard83195232007-02-05 19:42:07 +00002821@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002822
Stefan Weil7544a042010-02-05 23:52:03 +01002823@cindex user mode (Alpha)
2824@command{qemu-alpha} TODO.
2825
2826@cindex user mode (ARM)
2827@command{qemu-armeb} TODO.
2828
2829@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002830@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2831binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2832configurations), and arm-uclinux bFLT format binaries.
2833
Stefan Weil7544a042010-02-05 23:52:03 +01002834@cindex user mode (ColdFire)
2835@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002836@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2837(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2838coldfire uClinux bFLT format binaries.
2839
pbrook79737e42006-06-11 16:28:41 +00002840The binary format is detected automatically.
2841
Stefan Weil7544a042010-02-05 23:52:03 +01002842@cindex user mode (Cris)
2843@command{qemu-cris} TODO.
2844
2845@cindex user mode (i386)
2846@command{qemu-i386} TODO.
2847@command{qemu-x86_64} TODO.
2848
2849@cindex user mode (Microblaze)
2850@command{qemu-microblaze} TODO.
2851
2852@cindex user mode (MIPS)
2853@command{qemu-mips} TODO.
2854@command{qemu-mipsel} TODO.
2855
2856@cindex user mode (PowerPC)
2857@command{qemu-ppc64abi32} TODO.
2858@command{qemu-ppc64} TODO.
2859@command{qemu-ppc} TODO.
2860
2861@cindex user mode (SH4)
2862@command{qemu-sh4eb} TODO.
2863@command{qemu-sh4} TODO.
2864
2865@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002866@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2867
blueswir1a785e422007-10-20 08:09:05 +00002868@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2869(Sparc64 CPU, 32 bit ABI).
2870
2871@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2872SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2873
blueswir184778502008-10-26 20:33:16 +00002874@node BSD User space emulator
2875@section BSD User space emulator
2876
2877@menu
2878* BSD Status::
2879* BSD Quick Start::
2880* BSD Command line options::
2881@end menu
2882
2883@node BSD Status
2884@subsection BSD Status
2885
2886@itemize @minus
2887@item
2888target Sparc64 on Sparc64: Some trivial programs work.
2889@end itemize
2890
2891@node BSD Quick Start
2892@subsection Quick Start
2893
2894In order to launch a BSD process, QEMU needs the process executable
2895itself and all the target dynamic libraries used by it.
2896
2897@itemize
2898
2899@item On Sparc64, you can just try to launch any process by using the native
2900libraries:
2901
2902@example
2903qemu-sparc64 /bin/ls
2904@end example
2905
2906@end itemize
2907
2908@node BSD Command line options
2909@subsection Command line options
2910
2911@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00002912@command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
blueswir184778502008-10-26 20:33:16 +00002913@end example
2914
2915@table @option
2916@item -h
2917Print the help
2918@item -L path
2919Set the library root path (default=/)
2920@item -s size
2921Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002922@item -ignore-environment
2923Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002924the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002925@item -E @var{var}=@var{value}
2926Set environment @var{var} to @var{value}.
2927@item -U @var{var}
2928Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00002929@item -bsd type
2930Set the type of the emulated BSD Operating system. Valid values are
2931FreeBSD, NetBSD and OpenBSD (default).
2932@end table
2933
2934Debug options:
2935
2936@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00002937@item -d item1,...
2938Activate logging of the specified items (use '-d help' for a list of log items)
blueswir184778502008-10-26 20:33:16 +00002939@item -p pagesize
2940Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00002941@item -singlestep
2942Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00002943@end table
2944
bellard15a34c62004-07-08 21:26:26 +00002945@node compilation
2946@chapter Compilation from the sources
2947
bellarddebc7062006-04-30 21:58:41 +00002948@menu
2949* Linux/Unix::
2950* Windows::
2951* Cross compilation for Windows with Linux::
2952* Mac OS X::
Stefan Weil47eacb42010-02-05 23:52:01 +01002953* Make targets::
bellarddebc7062006-04-30 21:58:41 +00002954@end menu
2955
2956@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002957@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002958
bellard7c3fc842005-02-10 21:46:47 +00002959@subsection Compilation
2960
2961First you must decompress the sources:
2962@example
2963cd /tmp
2964tar zxvf qemu-x.y.z.tar.gz
2965cd qemu-x.y.z
2966@end example
2967
2968Then you configure QEMU and build it (usually no options are needed):
2969@example
2970./configure
2971make
2972@end example
2973
2974Then type as root user:
2975@example
2976make install
2977@end example
2978to install QEMU in @file{/usr/local}.
2979
bellarddebc7062006-04-30 21:58:41 +00002980@node Windows
bellard15a34c62004-07-08 21:26:26 +00002981@section Windows
2982
2983@itemize
2984@item Install the current versions of MSYS and MinGW from
2985@url{http://www.mingw.org/}. You can find detailed installation
2986instructions in the download section and the FAQ.
2987
ths5fafdf22007-09-16 21:08:06 +00002988@item Download
bellard15a34c62004-07-08 21:26:26 +00002989the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002990(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
Scott Tsaid0a96f32010-01-30 03:28:58 +08002991@url{http://www.libsdl.org}. Unpack it in a temporary place and
2992edit the @file{sdl-config} script so that it gives the
bellard15a34c62004-07-08 21:26:26 +00002993correct SDL directory when invoked.
2994
Scott Tsaid0a96f32010-01-30 03:28:58 +08002995@item Install the MinGW version of zlib and make sure
2996@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002997MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08002998
bellard15a34c62004-07-08 21:26:26 +00002999@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00003000
bellard15a34c62004-07-08 21:26:26 +00003001@item Start the MSYS shell (file @file{msys.bat}).
3002
ths5fafdf22007-09-16 21:08:06 +00003003@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00003004@file{make}. If you have problems using SDL, verify that
3005@file{sdl-config} can be launched from the MSYS command line.
3006
Stefan Weilc5ec15e2012-04-07 09:23:38 +02003007@item You can install QEMU in @file{Program Files/QEMU} by typing
bellard15a34c62004-07-08 21:26:26 +00003008@file{make install}. Don't forget to copy @file{SDL.dll} in
Stefan Weilc5ec15e2012-04-07 09:23:38 +02003009@file{Program Files/QEMU}.
bellard15a34c62004-07-08 21:26:26 +00003010
3011@end itemize
3012
bellarddebc7062006-04-30 21:58:41 +00003013@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00003014@section Cross compilation for Windows with Linux
3015
3016@itemize
3017@item
3018Install the MinGW cross compilation tools available at
3019@url{http://www.mingw.org/}.
3020
Scott Tsaid0a96f32010-01-30 03:28:58 +08003021@item Download
3022the MinGW development library of SDL 1.2.x
3023(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
3024@url{http://www.libsdl.org}. Unpack it in a temporary place and
3025edit the @file{sdl-config} script so that it gives the
3026correct SDL directory when invoked. Set up the @code{PATH} environment
3027variable so that @file{sdl-config} can be launched by
bellard15a34c62004-07-08 21:26:26 +00003028the QEMU configuration script.
3029
Scott Tsaid0a96f32010-01-30 03:28:58 +08003030@item Install the MinGW version of zlib and make sure
3031@file{zlib.h} and @file{libz.dll.a} are in
Stefan Weil40c5c6c2011-01-07 18:59:16 +01003032MinGW's default header and linker search paths.
Scott Tsaid0a96f32010-01-30 03:28:58 +08003033
ths5fafdf22007-09-16 21:08:06 +00003034@item
bellard15a34c62004-07-08 21:26:26 +00003035Configure QEMU for Windows cross compilation:
3036@example
Scott Tsaid0a96f32010-01-30 03:28:58 +08003037PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
bellard15a34c62004-07-08 21:26:26 +00003038@end example
Scott Tsaid0a96f32010-01-30 03:28:58 +08003039The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
3040MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01003041We 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 +08003042use --cross-prefix to specify the name of the cross compiler.
Stefan Weilc5ec15e2012-04-07 09:23:38 +02003043You 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 +08003044
3045Under Fedora Linux, you can run:
3046@example
3047yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
3048@end example
3049to get a suitable cross compilation environment.
bellard15a34c62004-07-08 21:26:26 +00003050
ths5fafdf22007-09-16 21:08:06 +00003051@item You can install QEMU in the installation directory by typing
Scott Tsaid0a96f32010-01-30 03:28:58 +08003052@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
ths5fafdf22007-09-16 21:08:06 +00003053installation directory.
bellard15a34c62004-07-08 21:26:26 +00003054
3055@end itemize
3056
Stefan Weil3804da92012-05-11 22:21:50 +02003057Wine can be used to launch the resulting qemu-system-i386.exe
3058and all other qemu-system-@var{target}.exe compiled for Win32.
bellard15a34c62004-07-08 21:26:26 +00003059
bellarddebc7062006-04-30 21:58:41 +00003060@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00003061@section Mac OS X
3062
G 3b3521532015-08-14 13:54:25 -04003063System Requirements:
3064@itemize
3065@item Mac OS 10.5 or higher
3066@item The clang compiler shipped with Xcode 4.2 or higher,
3067or GCC 4.3 or higher
3068@end itemize
3069
3070Additional Requirements (install in order):
3071@enumerate
3072@item libffi: @uref{https://sourceware.org/libffi/}
3073@item gettext: @uref{http://www.gnu.org/software/gettext/}
3074@item glib: @uref{http://ftp.gnome.org/pub/GNOME/sources/glib/}
3075@item pkg-config: @uref{http://www.freedesktop.org/wiki/Software/pkg-config/}
3076@item autoconf: @uref{http://www.gnu.org/software/autoconf/autoconf.html}
3077@item automake: @uref{http://www.gnu.org/software/automake/}
G 3b3521532015-08-14 13:54:25 -04003078@item pixman: @uref{http://www.pixman.org/}
3079@end enumerate
3080
3081* You may find it easiest to get these from a third-party packager
3082such as Homebrew, Macports, or Fink.
3083
3084After downloading the QEMU source code, double-click it to expand it.
3085
3086Then configure and make QEMU:
3087@example
3088./configure
3089make
3090@end example
3091
3092If you have a recent version of Mac OS X (OSX 10.7 or better
3093with Xcode 4.2 or better) we recommend building QEMU with the
3094default compiler provided by Apple, for your version of Mac OS X
3095(which will be 'clang'). The configure script will
3096automatically pick this.
3097
3098Note: If after the configure step you see a message like this:
3099@example
3100ERROR: Your compiler does not support the __thread specifier for
3101 Thread-Local Storage (TLS). Please upgrade to a version that does.
3102@end example
Peter Maydell6c76ec62015-08-28 11:42:53 +01003103you may have to build your own version of gcc from source. Expect that to take
G 3b3521532015-08-14 13:54:25 -04003104several hours. More information can be found here:
3105@uref{https://gcc.gnu.org/install/} @*
3106
3107These are some of the third party binaries of gcc available for download:
3108@itemize
3109@item Homebrew: @uref{http://brew.sh/}
3110@item @uref{https://www.litebeam.net/gcc/gcc_472.pkg}
3111@item @uref{http://www.macports.org/ports.php?by=name&substr=gcc}
3112@end itemize
3113
3114You can have several versions of GCC on your system. To specify a certain version,
3115use the --cc and --cxx options.
3116@example
3117./configure --cxx=<path of your c++ compiler> --cc=<path of your c compiler> <other options>
3118@end example
bellard15a34c62004-07-08 21:26:26 +00003119
Stefan Weil47eacb42010-02-05 23:52:01 +01003120@node Make targets
3121@section Make targets
3122
3123@table @code
3124
3125@item make
3126@item make all
3127Make everything which is typically needed.
3128
3129@item install
3130TODO
3131
3132@item install-doc
3133TODO
3134
3135@item make clean
3136Remove most files which were built during make.
3137
3138@item make distclean
3139Remove everything which was built during make.
3140
3141@item make dvi
3142@item make html
3143@item make info
3144@item make pdf
3145Create documentation in dvi, html, info or pdf format.
3146
3147@item make cscope
3148TODO
3149
3150@item make defconfig
3151(Re-)create some build configuration files.
3152User made changes will be overwritten.
3153
3154@item tar
3155@item tarbin
3156TODO
3157
3158@end table
3159
Stefan Weil7544a042010-02-05 23:52:03 +01003160@node License
3161@appendix License
3162
3163QEMU is a trademark of Fabrice Bellard.
3164
3165QEMU is released under the GNU General Public License (TODO: add link).
3166Parts of QEMU have specific licenses, see file LICENSE.
3167
3168TODO (refer to file LICENSE, include it, include the GPL?)
3169
bellarddebc7062006-04-30 21:58:41 +00003170@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01003171@appendix Index
3172@menu
3173* Concept Index::
3174* Function Index::
3175* Keystroke Index::
3176* Program Index::
3177* Data Type Index::
3178* Variable Index::
3179@end menu
3180
3181@node Concept Index
3182@section Concept Index
3183This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00003184@printindex cp
3185
Stefan Weil7544a042010-02-05 23:52:03 +01003186@node Function Index
3187@section Function Index
3188This index could be used for command line options and monitor functions.
3189@printindex fn
3190
3191@node Keystroke Index
3192@section Keystroke Index
3193
3194This is a list of all keystrokes which have a special function
3195in system emulation.
3196
3197@printindex ky
3198
3199@node Program Index
3200@section Program Index
3201@printindex pg
3202
3203@node Data Type Index
3204@section Data Type Index
3205
3206This index could be used for qdev device names and options.
3207
3208@printindex tp
3209
3210@node Variable Index
3211@section Variable Index
3212@printindex vr
3213
bellarddebc7062006-04-30 21:58:41 +00003214@bye