blob: 965ba5929eb3683f249401d8e3dd617125fd8ebb [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::
bellarddebc7062006-04-30 21:58:41 +000035* QEMU PC System emulator::
36* QEMU System emulator for non PC targets::
Thomas Huth3f2ce722017-05-22 22:53:29 +020037* QEMU Guest Agent::
bellard83195232007-02-05 19:42:07 +000038* QEMU User space emulator::
Paolo Bonzini78e87792016-10-06 16:12:11 +020039* Implementation notes::
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
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020060@cindex operating modes
bellard1eb20522003-06-25 16:21:49 +000061QEMU has two operating modes:
bellard0806e3f2003-10-01 00:15:32 +000062
Stefan Weild7e5edc2010-02-05 23:52:02 +010063@itemize
Stefan Weil7544a042010-02-05 23:52:03 +010064@cindex system emulation
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020065@item Full system emulation. In this mode, QEMU emulates a full system (for
bellard3f9f3aa2005-12-18 20:11:37 +000066example a PC), including one or several processors and various
67peripherals. It can be used to launch different Operating Systems
68without rebooting the PC or to debug system code.
bellard1eb20522003-06-25 16:21:49 +000069
Stefan Weil7544a042010-02-05 23:52:03 +010070@cindex user mode emulation
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020071@item User mode emulation. In this mode, QEMU can launch
bellard83195232007-02-05 19:42:07 +000072processes compiled for one CPU on another CPU. It can be used to
bellard1f673132004-04-04 15:21:17 +000073launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
74to ease cross-compilation and cross-debugging.
bellard1eb20522003-06-25 16:21:49 +000075
76@end itemize
77
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020078QEMU has the following features:
bellard322d0c62003-06-15 23:29:28 +000079
bellard52c00a52004-04-25 21:27:03 +000080@itemize
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020081@item QEMU can run without a host kernel driver and yet gives acceptable
82performance. It uses dynamic translation to native code for reasonable speed,
83with support for self-modifying code and precise exceptions.
84
85@item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
86Windows) and architectures.
87
88@item It performs accurate software emulation of the FPU.
bellard52c00a52004-04-25 21:27:03 +000089@end itemize
bellard386405f2003-03-23 21:28:45 +000090
Paolo Bonzini1f3e7e42016-10-06 14:59:26 +020091QEMU user mode emulation has the following features:
92@itemize
93@item Generic Linux system call converter, including most ioctls.
94
95@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
96
97@item Accurate signal handling by remapping host signals to target signals.
98@end itemize
99
100QEMU full system emulation has the following features:
101@itemize
102@item
103QEMU uses a full software MMU for maximum portability.
104
105@item
106QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators
107execute most of the guest code natively, while
108continuing to emulate the rest of the machine.
109
110@item
111Various hardware devices can be emulated and in some cases, host
112devices (e.g. serial and parallel ports, USB, drives) can be used
113transparently by the guest Operating System. Host device passthrough
114can be used for talking to external physical peripherals (e.g. a
115webcam, modem or tape drive).
116
117@item
118Symmetric multiprocessing (SMP) support. Currently, an in-kernel
119accelerator is required to use more than one host CPU for emulation.
120
121@end itemize
122
bellard0806e3f2003-10-01 00:15:32 +0000123
bellarddebc7062006-04-30 21:58:41 +0000124@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000125@chapter QEMU PC System emulator
Stefan Weil7544a042010-02-05 23:52:03 +0100126@cindex system emulation (PC)
bellard1eb20522003-06-25 16:21:49 +0000127
bellarddebc7062006-04-30 21:58:41 +0000128@menu
129* pcsys_introduction:: Introduction
130* pcsys_quickstart:: Quick Start
131* sec_invocation:: Invocation
Peter Maydella40db1b2016-02-16 17:28:58 +0000132* pcsys_keys:: Keys in the graphical frontends
133* mux_keys:: Keys in the character backend multiplexer
bellarddebc7062006-04-30 21:58:41 +0000134* pcsys_monitor:: QEMU Monitor
135* disk_images:: Disk Images
136* pcsys_network:: Network emulation
Stefan Weil576fd0a2011-01-07 18:59:14 +0100137* pcsys_other_devs:: Other Devices
bellarddebc7062006-04-30 21:58:41 +0000138* direct_linux_boot:: Direct Linux Boot
139* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000140* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000141* gdb_usage:: GDB usage
142* pcsys_os_specific:: Target OS specific information
143@end menu
144
145@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000146@section Introduction
147
148@c man begin DESCRIPTION
149
bellard3f9f3aa2005-12-18 20:11:37 +0000150The QEMU PC System emulator simulates the
151following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000152
153@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000154@item
bellard15a34c62004-07-08 21:26:26 +0000155i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000156@item
bellard15a34c62004-07-08 21:26:26 +0000157Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
158extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000159@item
160PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000161@item
bellard15a34c62004-07-08 21:26:26 +00001622 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000163@item
164Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000165@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +0200166PCI and ISA network adapters
bellard0806e3f2003-10-01 00:15:32 +0000167@item
bellard05d58182004-08-24 21:12:04 +0000168Serial ports
169@item
Corey Minyard23076bb2015-12-17 12:50:04 -0600170IPMI BMC, either and internal or external one
171@item
bellardc0fe3822005-11-05 18:55:28 +0000172Creative SoundBlaster 16 sound card
173@item
174ENSONIQ AudioPCI ES1370 sound card
175@item
balroge5c9a132008-01-14 04:27:55 +0000176Intel 82801AA AC97 Audio compatible sound card
177@item
Gerd Hoffmann7d72e762010-11-01 16:57:48 +0100178Intel HD Audio Controller and HDA codec
179@item
Stefan Weil2d983442011-01-07 18:59:15 +0100180Adlib (OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000181@item
balrog26463db2008-01-17 21:47:25 +0000182Gravis Ultrasound GF1 sound card
183@item
malccc53d262008-06-13 10:48:22 +0000184CS4231A compatible sound card
185@item
Thomas Hutha92ff8c2017-05-08 17:13:49 +0200186PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
bellard0806e3f2003-10-01 00:15:32 +0000187@end itemize
188
bellard3f9f3aa2005-12-18 20:11:37 +0000189SMP is supported with up to 255 CPUs.
190
Michael Tokareva8ad4152013-06-28 10:08:16 +0400191QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
bellard15a34c62004-07-08 21:26:26 +0000192VGA BIOS.
193
bellardc0fe3822005-11-05 18:55:28 +0000194QEMU uses YM3812 emulation by Tatsuyuki Satoh.
195
Stefan Weil2d983442011-01-07 18:59:15 +0100196QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
balrog26463db2008-01-17 21:47:25 +0000197by Tibor "TS" Schütz.
balrog423d65f2008-01-14 22:09:11 +0000198
Bernhard Reutner-Fischer1a1a0e22011-10-25 10:22:18 +0200199Note that, by default, GUS shares IRQ(7) with parallel ports and so
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200200QEMU must be told to not have parallel ports to have working GUS.
malc720036a2009-09-10 20:05:59 +0400201
202@example
Stefan Weil3804da92012-05-11 22:21:50 +0200203qemu-system-i386 dos.img -soundhw gus -parallel none
malc720036a2009-09-10 20:05:59 +0400204@end example
205
206Alternatively:
207@example
Stefan Weil3804da92012-05-11 22:21:50 +0200208qemu-system-i386 dos.img -device gus,irq=5
malc720036a2009-09-10 20:05:59 +0400209@end example
210
211Or some other unclaimed IRQ.
212
malccc53d262008-06-13 10:48:22 +0000213CS4231A is the chip used in Windows Sound System and GUSMAX products
214
bellard0806e3f2003-10-01 00:15:32 +0000215@c man end
216
bellarddebc7062006-04-30 21:58:41 +0000217@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000218@section Quick Start
Stefan Weil7544a042010-02-05 23:52:03 +0100219@cindex quick start
bellard1eb20522003-06-25 16:21:49 +0000220
bellard285dc332003-10-27 23:58:04 +0000221Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000222
223@example
Stefan Weil3804da92012-05-11 22:21:50 +0200224qemu-system-i386 linux.img
bellard0806e3f2003-10-01 00:15:32 +0000225@end example
226
227Linux should boot and give you a prompt.
228
bellard6cc721c2005-07-28 22:27:28 +0000229@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000230@section Invocation
231
232@example
233@c man begin SYNOPSIS
Sitsofe Wheeler84851402016-01-13 20:50:26 +0000234@command{qemu-system-i386} [@var{options}] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000235@c man end
236@end example
237
238@c man begin OPTIONS
blueswir1d2c639d2009-01-24 18:19:25 +0000239@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
240targets do not need a disk image.
bellard1f673132004-04-04 15:21:17 +0000241
blueswir15824d652009-03-28 06:44:27 +0000242@include qemu-options.texi
bellard1f673132004-04-04 15:21:17 +0000243
bellard3e11db92004-07-14 17:47:14 +0000244@c man end
245
bellarddebc7062006-04-30 21:58:41 +0000246@node pcsys_keys
Peter Maydella40db1b2016-02-16 17:28:58 +0000247@section Keys in the graphical frontends
bellard3e11db92004-07-14 17:47:14 +0000248
249@c man begin OPTIONS
250
Brad Hardsde1db2a2011-04-29 21:46:12 +1000251During the graphical emulation, you can use special key combinations to change
252modes. The default key mappings are shown below, but if you use @code{-alt-grab}
253then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
254@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
255
bellarda1b74fe2004-05-08 13:26:35 +0000256@table @key
bellardf9859312004-10-03 14:33:10 +0000257@item Ctrl-Alt-f
Stefan Weil7544a042010-02-05 23:52:03 +0100258@kindex Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000259Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000260
Jan Kiszkad6a65ba2011-07-30 11:39:16 +0200261@item Ctrl-Alt-+
262@kindex Ctrl-Alt-+
263Enlarge the screen
264
265@item Ctrl-Alt--
266@kindex Ctrl-Alt--
267Shrink the screen
268
malcc4a735f2009-09-10 05:15:07 +0400269@item Ctrl-Alt-u
Stefan Weil7544a042010-02-05 23:52:03 +0100270@kindex Ctrl-Alt-u
malcc4a735f2009-09-10 05:15:07 +0400271Restore the screen's un-scaled dimensions
272
bellardf9859312004-10-03 14:33:10 +0000273@item Ctrl-Alt-n
Stefan Weil7544a042010-02-05 23:52:03 +0100274@kindex Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000275Switch to virtual console 'n'. Standard console mappings are:
276@table @emph
277@item 1
278Target system display
279@item 2
280Monitor
281@item 3
282Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000283@end table
284
bellardf9859312004-10-03 14:33:10 +0000285@item Ctrl-Alt
Stefan Weil7544a042010-02-05 23:52:03 +0100286@kindex Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000287Toggle mouse and keyboard grab.
288@end table
289
Stefan Weil7544a042010-02-05 23:52:03 +0100290@kindex Ctrl-Up
291@kindex Ctrl-Down
292@kindex Ctrl-PageUp
293@kindex Ctrl-PageDown
bellard3e11db92004-07-14 17:47:14 +0000294In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
295@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
296
Peter Maydella40db1b2016-02-16 17:28:58 +0000297@c man end
298
299@node mux_keys
300@section Keys in the character backend multiplexer
301
302@c man begin OPTIONS
303
304During emulation, if you are using a character backend multiplexer
305(which is the default if you are using @option{-nographic}) then
306several commands are available via an escape sequence. These
307key sequences all start with an escape character, which is @key{Ctrl-a}
308by default, but can be changed with @option{-echr}. The list below assumes
309you're using the default.
bellard1f673132004-04-04 15:21:17 +0000310
311@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000312@item Ctrl-a h
Stefan Weil7544a042010-02-05 23:52:03 +0100313@kindex Ctrl-a h
bellard1f673132004-04-04 15:21:17 +0000314Print this help
ths3b46e622007-09-17 08:09:54 +0000315@item Ctrl-a x
Stefan Weil7544a042010-02-05 23:52:03 +0100316@kindex Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000317Exit emulator
ths3b46e622007-09-17 08:09:54 +0000318@item Ctrl-a s
Stefan Weil7544a042010-02-05 23:52:03 +0100319@kindex Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000320Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000321@item Ctrl-a t
Stefan Weil7544a042010-02-05 23:52:03 +0100322@kindex Ctrl-a t
blueswir1d2c639d2009-01-24 18:19:25 +0000323Toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000324@item Ctrl-a b
Stefan Weil7544a042010-02-05 23:52:03 +0100325@kindex Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000326Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000327@item Ctrl-a c
Stefan Weil7544a042010-02-05 23:52:03 +0100328@kindex Ctrl-a c
Peter Maydella40db1b2016-02-16 17:28:58 +0000329Rotate between the frontends connected to the multiplexer (usually
330this switches between the monitor and the console)
bellarda1b74fe2004-05-08 13:26:35 +0000331@item Ctrl-a Ctrl-a
Peter Maydella40db1b2016-02-16 17:28:58 +0000332@kindex Ctrl-a Ctrl-a
333Send the escape character to the frontend
bellard1f673132004-04-04 15:21:17 +0000334@end table
335@c man end
336
337@ignore
338
bellard1f673132004-04-04 15:21:17 +0000339@c man begin SEEALSO
340The HTML documentation of QEMU for more precise information and Linux
341user mode emulator invocation.
342@c man end
343
344@c man begin AUTHOR
345Fabrice Bellard
346@c man end
347
348@end ignore
349
bellarddebc7062006-04-30 21:58:41 +0000350@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000351@section QEMU Monitor
Stefan Weil7544a042010-02-05 23:52:03 +0100352@cindex QEMU monitor
bellard1f673132004-04-04 15:21:17 +0000353
354The QEMU monitor is used to give complex commands to the QEMU
355emulator. You can use it to:
356
357@itemize @minus
358
359@item
thse5987522007-03-30 18:58:01 +0000360Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000361(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000362
ths5fafdf22007-09-16 21:08:06 +0000363@item
bellard1f673132004-04-04 15:21:17 +0000364Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
365from a disk file.
366
367@item Inspect the VM state without an external debugger.
368
369@end itemize
370
371@subsection Commands
372
373The following commands are available:
374
Blue Swirl23130862009-06-06 08:22:04 +0000375@include qemu-monitor.texi
bellard1f673132004-04-04 15:21:17 +0000376
Pavel Butsykin2cd8af22015-09-10 18:39:01 +0300377@include qemu-monitor-info.texi
378
bellard1f673132004-04-04 15:21:17 +0000379@subsection Integer expressions
380
381The monitor understands integers expressions for every integer
382argument. You can use register names to get the value of specifics
383CPU registers by prefixing them with @emph{$}.
384
385@node disk_images
386@section Disk Images
387
bellardacd935e2004-11-15 22:57:26 +0000388Since version 0.6.1, QEMU supports many disk image formats, including
389growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000390written), compressed and encrypted disk images. Version 0.8.3 added
391the new qcow2 disk image format which is essential to support VM
392snapshots.
bellard1f673132004-04-04 15:21:17 +0000393
bellarddebc7062006-04-30 21:58:41 +0000394@menu
395* disk_images_quickstart:: Quick start for disk image creation
396* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000397* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000398* qemu_img_invocation:: qemu-img Invocation
ths975b0922008-07-02 21:18:00 +0000399* qemu_nbd_invocation:: qemu-nbd Invocation
Kevin Wolfd3067b02012-11-21 14:21:47 +0100400* disk_images_formats:: Disk image file formats
bellard19cb3732006-08-19 11:45:59 +0000401* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000402* disk_images_fat_images:: Virtual FAT disk images
ths75818252008-07-03 13:41:03 +0000403* disk_images_nbd:: NBD access
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900404* disk_images_sheepdog:: Sheepdog disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100405* disk_images_iscsi:: iSCSI LUNs
Bharata B Rao8809e282012-10-24 17:17:53 +0530406* disk_images_gluster:: GlusterFS disk images
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +0100407* disk_images_ssh:: Secure Shell (ssh) disk images
bellarddebc7062006-04-30 21:58:41 +0000408@end menu
409
410@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000411@subsection Quick start for disk image creation
412
413You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000414@example
bellardacd935e2004-11-15 22:57:26 +0000415qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000416@end example
bellardacd935e2004-11-15 22:57:26 +0000417where @var{myimage.img} is the disk image filename and @var{mysize} is its
418size in kilobytes. You can add an @code{M} suffix to give the size in
419megabytes and a @code{G} suffix for gigabytes.
420
bellarddebc7062006-04-30 21:58:41 +0000421See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000422
bellarddebc7062006-04-30 21:58:41 +0000423@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000424@subsection Snapshot mode
425
426If you use the option @option{-snapshot}, all disk images are
427considered as read only. When sectors in written, they are written in
428a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000429write back to the raw disk images by using the @code{commit} monitor
430command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000431
bellard13a2e802006-08-06 14:50:31 +0000432@node vm_snapshots
433@subsection VM snapshots
434
435VM snapshots are snapshots of the complete virtual machine including
436CPU state, RAM, device state and the content of all the writable
437disks. In order to use VM snapshots, you must have at least one non
438removable and writable block device using the @code{qcow2} disk image
439format. Normally this device is the first virtual hard drive.
440
441Use the monitor command @code{savevm} to create a new VM snapshot or
442replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +0000443snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +0000444
445Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
446a VM snapshot. @code{info snapshots} lists the available snapshots
447with their associated information:
448
449@example
450(qemu) info snapshots
451Snapshot devices: hda
452Snapshot list (from hda):
453ID TAG VM SIZE DATE VM CLOCK
4541 start 41M 2006-08-06 12:38:02 00:00:14.954
4552 40M 2006-08-06 12:43:29 00:00:18.633
4563 msys 40M 2006-08-06 12:44:04 00:00:23.514
457@end example
458
459A VM snapshot is made of a VM state info (its size is shown in
460@code{info snapshots}) and a snapshot of every writable disk image.
461The VM state info is stored in the first @code{qcow2} non removable
462and writable block device. The disk image snapshots are stored in
463every disk image. The size of a snapshot in a disk image is difficult
464to evaluate and is not shown by @code{info snapshots} because the
465associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +0000466disk space (otherwise each snapshot would need a full copy of all the
467disk images).
bellard13a2e802006-08-06 14:50:31 +0000468
469When using the (unrelated) @code{-snapshot} option
470(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
471but they are deleted as soon as you exit QEMU.
472
473VM snapshots currently have the following known limitations:
474@itemize
ths5fafdf22007-09-16 21:08:06 +0000475@item
bellard13a2e802006-08-06 14:50:31 +0000476They cannot cope with removable devices if they are removed or
477inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +0000478@item
bellard13a2e802006-08-06 14:50:31 +0000479A few device drivers still have incomplete snapshot support so their
480state is not saved or restored properly (in particular USB).
481@end itemize
482
bellardacd935e2004-11-15 22:57:26 +0000483@node qemu_img_invocation
484@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000485
bellardacd935e2004-11-15 22:57:26 +0000486@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000487
ths975b0922008-07-02 21:18:00 +0000488@node qemu_nbd_invocation
489@subsection @code{qemu-nbd} Invocation
490
491@include qemu-nbd.texi
492
Kevin Wolfd3067b02012-11-21 14:21:47 +0100493@node disk_images_formats
494@subsection Disk image file formats
495
496QEMU supports many image file formats that can be used with VMs as well as with
497any of the tools (like @code{qemu-img}). This includes the preferred formats
498raw and qcow2 as well as formats that are supported for compatibility with
499older QEMU versions or other hypervisors.
500
501Depending on the image format, different options can be passed to
502@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
503This section describes each format and the options that are supported for it.
504
505@table @option
506@item raw
507
508Raw disk image format. This format has the advantage of
509being simple and easily exportable to all other emulators. If your
510file system supports @emph{holes} (for example in ext2 or ext3 on
511Linux or NTFS on Windows), then only the written sectors will reserve
512space. Use @code{qemu-img info} to know the real size used by the
513image or @code{ls -ls} on Unix/Linux.
514
Hu Tao06247422014-09-10 17:05:48 +0800515Supported options:
516@table @code
517@item preallocation
518Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
519@code{falloc} mode preallocates space for image by calling posix_fallocate().
520@code{full} mode preallocates space for image by writing zeros to underlying
521storage.
522@end table
523
Kevin Wolfd3067b02012-11-21 14:21:47 +0100524@item qcow2
525QEMU image format, the most versatile format. Use it to have smaller
526images (useful if your filesystem does not supports holes, for example
Markus Armbrustera1f688f2015-03-13 21:09:40 +0100527on Windows), zlib based compression and support of multiple VM
528snapshots.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100529
530Supported options:
531@table @code
532@item compat
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800533Determines the qcow2 version to use. @code{compat=0.10} uses the
534traditional image format that can be read by any QEMU since 0.10.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100535@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
Stefan Hajnoczi7fa9e1f2014-01-06 12:39:01 +0800536newer understand (this is the default). Amongst others, this includes
537zero clusters, which allow efficient copy-on-read for sparse images.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100538
539@item backing_file
540File name of a base image (see @option{create} subcommand)
541@item backing_fmt
542Image format of the base image
543@item encryption
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000544If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100545
Daniel P. Berrange136cd192014-01-22 15:47:10 +0000546The use of encryption in qcow and qcow2 images is considered to be flawed by
547modern cryptography standards, suffering from a number of design problems:
548
549@itemize @minus
550@item The AES-CBC cipher is used with predictable initialization vectors based
551on the sector number. This makes it vulnerable to chosen plaintext attacks
552which can reveal the existence of encrypted data.
553@item The user passphrase is directly used as the encryption key. A poorly
554chosen or short passphrase will compromise the security of the encryption.
555@item In the event of the passphrase being compromised there is no way to
556change the passphrase to protect data in any qcow images. The files must
557be cloned, using a different encryption passphrase in the new file. The
558original file must then be securely erased using a program like shred,
559though even this is ineffective with many modern storage technologies.
560@end itemize
561
Markus Armbrustera1f688f2015-03-13 21:09:40 +0100562Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
563it will go away in a future release. Users are recommended to use an
564alternative encryption technology such as the Linux dm-crypt / LUKS
565system.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100566
567@item cluster_size
568Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
569sizes can improve the image file size whereas larger cluster sizes generally
570provide better performance.
571
572@item preallocation
Hu Tao0e4271b2014-09-10 17:05:49 +0800573Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
574@code{full}). An image with preallocated metadata is initially larger but can
575improve performance when the image needs to grow. @code{falloc} and @code{full}
576preallocations are like the same options of @code{raw} format, but sets up
577metadata also.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100578
579@item lazy_refcounts
580If this option is set to @code{on}, reference count updates are postponed with
581the goal of avoiding metadata I/O and improving performance. This is
582particularly interesting with @option{cache=writethrough} which doesn't batch
583metadata updates. The tradeoff is that after a host crash, the reference count
584tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
585check -r all} is required, which may take some time.
586
587This option can only be enabled if @code{compat=1.1} is specified.
588
Chunyan Liu4ab15592014-06-30 14:29:58 +0800589@item nocow
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800590If 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 +0800591valid on btrfs, no effect on other file systems.
592
593Btrfs has low performance when hosting a VM image file, even more when the guest
594on the VM also using btrfs as file system. Turning off COW is a way to mitigate
595this bad performance. Generally there are two ways to turn off COW on btrfs:
596a) Disable it by mounting with nodatacow, then all newly created files will be
597NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
598does.
599
600Note: this option is only valid to new or empty files. If there is an existing
601file which is COW and has data blocks already, it couldn't be changed to NOCOW
602by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
Chunyan Liubc3a7f92014-07-02 12:27:29 +0800603the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
Chunyan Liu4ab15592014-06-30 14:29:58 +0800604
Kevin Wolfd3067b02012-11-21 14:21:47 +0100605@end table
606
607@item qed
608Old QEMU image format with support for backing files and compact image files
609(when your filesystem or transport medium does not support holes).
610
611When converting QED images to qcow2, you might want to consider using the
612@code{lazy_refcounts=on} option to get a more QED-like behaviour.
613
614Supported options:
615@table @code
616@item backing_file
617File name of a base image (see @option{create} subcommand).
618@item backing_fmt
619Image file format of backing file (optional). Useful if the format cannot be
620autodetected because it has no header, like some vhd/vpc files.
621@item cluster_size
622Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
623cluster sizes can improve the image file size whereas larger cluster sizes
624generally provide better performance.
625@item table_size
626Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
627and 16). There is normally no need to change this value but this option can be
628used for performance benchmarking.
629@end table
630
631@item qcow
632Old QEMU image format with support for backing files, compact image files,
633encryption and compression.
634
635Supported options:
636@table @code
637@item backing_file
638File name of a base image (see @option{create} subcommand)
639@item encryption
640If this option is set to @code{on}, the image is encrypted.
641@end table
642
Kevin Wolfd3067b02012-11-21 14:21:47 +0100643@item vdi
644VirtualBox 1.1 compatible image format.
645Supported options:
646@table @code
647@item static
648If this option is set to @code{on}, the image is created with metadata
649preallocation.
650@end table
651
652@item vmdk
653VMware 3 and 4 compatible image format.
654
655Supported options:
656@table @code
657@item backing_file
658File name of a base image (see @option{create} subcommand).
659@item compat6
660Create a VMDK version 6 image (instead of version 4)
Janne Karhunenf2499242016-05-03 02:43:30 -0700661@item hwversion
662Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
663if hwversion is specified.
Kevin Wolfd3067b02012-11-21 14:21:47 +0100664@item subformat
665Specifies which VMDK subformat to use. Valid options are
666@code{monolithicSparse} (default),
667@code{monolithicFlat},
668@code{twoGbMaxExtentSparse},
669@code{twoGbMaxExtentFlat} and
670@code{streamOptimized}.
671@end table
672
673@item vpc
674VirtualPC compatible image format (VHD).
675Supported options:
676@table @code
677@item subformat
678Specifies which VHD subformat to use. Valid options are
679@code{dynamic} (default) and @code{fixed}.
680@end table
Jeff Cody8282db12013-12-17 13:56:06 -0500681
682@item VHDX
683Hyper-V compatible image format (VHDX).
684Supported options:
685@table @code
686@item subformat
687Specifies which VHDX subformat to use. Valid options are
688@code{dynamic} (default) and @code{fixed}.
689@item block_state_zero
Jeff Cody30af51c2014-12-08 01:07:44 -0500690Force use of payload blocks of type 'ZERO'. Can be set to @code{on} (default)
691or @code{off}. When set to @code{off}, new blocks will be created as
692@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
693arbitrary data for those blocks. Do not set to @code{off} when using
694@code{qemu-img convert} with @code{subformat=dynamic}.
Jeff Cody8282db12013-12-17 13:56:06 -0500695@item block_size
696Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
697@item log_size
698Log size; min 1 MB.
699@end table
Kevin Wolfd3067b02012-11-21 14:21:47 +0100700@end table
701
702@subsubsection Read-only formats
703More disk image file formats are supported in a read-only mode.
704@table @option
705@item bochs
706Bochs images of @code{growing} type.
707@item cloop
708Linux Compressed Loop image, useful only to reuse directly compressed
709CD-ROM images present for example in the Knoppix CD-ROMs.
710@item dmg
711Apple disk image.
712@item parallels
713Parallels disk image format.
714@end table
715
716
bellard19cb3732006-08-19 11:45:59 +0000717@node host_drives
718@subsection Using host drives
719
720In addition to disk image files, QEMU can directly access host
721devices. We describe here the usage for QEMU version >= 0.8.3.
722
723@subsubsection Linux
724
725On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +0000726disk image filename provided you have enough privileges to access
Markus Armbruster92a539d2015-03-17 17:02:20 +0100727it. For example, use @file{/dev/cdrom} to access to the CDROM.
bellard19cb3732006-08-19 11:45:59 +0000728
bellardf5420862006-08-21 20:26:44 +0000729@table @code
bellard19cb3732006-08-19 11:45:59 +0000730@item CD
731You can specify a CDROM device even if no CDROM is loaded. QEMU has
732specific code to detect CDROM insertion or removal. CDROM ejection by
733the guest OS is supported. Currently only data CDs are supported.
734@item Floppy
735You can specify a floppy device even if no floppy is loaded. Floppy
736removal is currently not detected accurately (if you change floppy
737without doing floppy access while the floppy is not loaded, the guest
738OS will think that the same floppy is loaded).
Markus Armbruster92a539d2015-03-17 17:02:20 +0100739Use of the host's floppy device is deprecated, and support for it will
740be removed in a future release.
bellard19cb3732006-08-19 11:45:59 +0000741@item Hard disks
742Hard disks can be used. Normally you must specify the whole disk
743(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
744see it as a partitioned disk. WARNING: unless you know what you do, it
745is better to only make READ-ONLY accesses to the hard disk otherwise
746you may corrupt your host data (use the @option{-snapshot} command
747line option or modify the device permissions accordingly).
748@end table
749
750@subsubsection Windows
751
bellard01781962007-01-07 22:43:30 +0000752@table @code
753@item CD
ths4be456f2007-06-03 13:41:28 +0000754The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +0000755alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
756supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +0000757
thse5987522007-03-30 18:58:01 +0000758Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000759is better to use the @code{change} or @code{eject} monitor commands to
760change or eject media.
bellard01781962007-01-07 22:43:30 +0000761@item Hard disks
ths89dfe892007-11-21 22:38:37 +0000762Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +0000763where @var{N} is the drive number (0 is the first hard disk).
764
765WARNING: unless you know what you do, it is better to only make
766READ-ONLY accesses to the hard disk otherwise you may corrupt your
767host data (use the @option{-snapshot} command line so that the
768modifications are written in a temporary file).
769@end table
770
bellard19cb3732006-08-19 11:45:59 +0000771
772@subsubsection Mac OS X
773
ths5fafdf22007-09-16 21:08:06 +0000774@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +0000775
thse5987522007-03-30 18:58:01 +0000776Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +0000777is better to use the @code{change} or @code{eject} monitor commands to
778change or eject media.
779
bellarddebc7062006-04-30 21:58:41 +0000780@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +0000781@subsection Virtual FAT disk images
782
783QEMU can automatically create a virtual FAT disk image from a
784directory tree. In order to use it, just type:
785
ths5fafdf22007-09-16 21:08:06 +0000786@example
Stefan Weil3804da92012-05-11 22:21:50 +0200787qemu-system-i386 linux.img -hdb fat:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000788@end example
789
790Then you access access to all the files in the @file{/my_directory}
791directory without having to copy them in a disk image or to export
792them via SAMBA or NFS. The default access is @emph{read-only}.
793
794Floppies can be emulated with the @code{:floppy:} option:
795
ths5fafdf22007-09-16 21:08:06 +0000796@example
Stefan Weil3804da92012-05-11 22:21:50 +0200797qemu-system-i386 linux.img -fda fat:floppy:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000798@end example
799
800A read/write support is available for testing (beta stage) with the
801@code{:rw:} option:
802
ths5fafdf22007-09-16 21:08:06 +0000803@example
Stefan Weil3804da92012-05-11 22:21:50 +0200804qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
bellard2c6cadd2005-12-18 18:31:45 +0000805@end example
806
807What you should @emph{never} do:
808@itemize
809@item use non-ASCII filenames ;
810@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +0000811@item expect it to work when loadvm'ing ;
812@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +0000813@end itemize
814
ths75818252008-07-03 13:41:03 +0000815@node disk_images_nbd
816@subsection NBD access
817
818QEMU can access directly to block device exported using the Network Block Device
819protocol.
820
821@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100822qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
ths75818252008-07-03 13:41:03 +0000823@end example
824
825If the NBD server is located on the same host, you can use an unix socket instead
826of an inet socket:
827
828@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100829qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000830@end example
831
832In this case, the block device must be exported using qemu-nbd:
833
834@example
835qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
836@end example
837
Michael Tokarev9d85d552014-04-07 13:34:58 +0400838The use of qemu-nbd allows sharing of a disk between several guests:
ths75818252008-07-03 13:41:03 +0000839@example
840qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
841@end example
842
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100843@noindent
ths75818252008-07-03 13:41:03 +0000844and then you can use it with two guests:
845@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100846qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
847qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
ths75818252008-07-03 13:41:03 +0000848@end example
849
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100850If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
851own embedded NBD server), you must specify an export name in the URI:
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200852@example
Paolo Bonzini1d7d2a92012-11-04 13:04:24 +0100853qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
854qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
855@end example
856
857The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
858also available. Here are some example of the older syntax:
859@example
860qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
861qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
862qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
Laurent Vivier1d45f8b2010-08-25 22:48:33 +0200863@end example
864
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900865@node disk_images_sheepdog
866@subsection Sheepdog disk images
867
868Sheepdog is a distributed storage system for QEMU. It provides highly
869available block level storage volumes that can be attached to
870QEMU-based virtual machines.
871
872You can create a Sheepdog disk image with the command:
873@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900874qemu-img create sheepdog:///@var{image} @var{size}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900875@end example
876where @var{image} is the Sheepdog image name and @var{size} is its
877size.
878
879To import the existing @var{filename} to Sheepdog, you can use a
880convert command.
881@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900882qemu-img convert @var{filename} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900883@end example
884
885You can boot from the Sheepdog disk image with the command:
886@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900887qemu-system-i386 sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900888@end example
889
890You can also create a snapshot of the Sheepdog image like qcow2.
891@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900892qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900893@end example
894where @var{tag} is a tag name of the newly created snapshot.
895
896To boot from the Sheepdog snapshot, specify the tag name of the
897snapshot.
898@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900899qemu-system-i386 sheepdog:///@var{image}#@var{tag}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900900@end example
901
902You can create a cloned image from the existing snapshot.
903@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900904qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900905@end example
906where @var{base} is a image name of the source snapshot and @var{tag}
907is its tag name.
908
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +0900909You can use an unix socket instead of an inet socket:
910
911@example
912qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
913@end example
914
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900915If the Sheepdog daemon doesn't run on the local host, you need to
916specify one of the Sheepdog servers to connect to.
917@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +0900918qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
919qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
MORITA Kazutaka42af9c32011-02-07 16:04:04 +0900920@end example
921
Ronnie Sahlberg00984e32011-11-12 11:06:30 +1100922@node disk_images_iscsi
923@subsection iSCSI LUNs
924
925iSCSI is a popular protocol used to access SCSI devices across a computer
926network.
927
928There are two different ways iSCSI devices can be used by QEMU.
929
930The first method is to mount the iSCSI LUN on the host, and make it appear as
931any other ordinary SCSI device on the host and then to access this device as a
932/dev/sd device from QEMU. How to do this differs between host OSes.
933
934The second method involves using the iSCSI initiator that is built into
935QEMU. This provides a mechanism that works the same way regardless of which
936host OS you are running QEMU on. This section will describe this second method
937of using iSCSI together with QEMU.
938
939In QEMU, iSCSI devices are described using special iSCSI URLs
940
941@example
942URL syntax:
943iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
944@end example
945
946Username and password are optional and only used if your target is set up
947using CHAP authentication for access control.
948Alternatively the username and password can also be set via environment
949variables to have these not show up in the process list
950
951@example
952export LIBISCSI_CHAP_USERNAME=<username>
953export LIBISCSI_CHAP_PASSWORD=<password>
954iscsi://<host>/<target-iqn-name>/<lun>
955@end example
956
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100957Various session related parameters can be set via special options, either
958in a configuration file provided via '-readconfig' or directly on the
959command line.
960
Ronnie Sahlberg31459f42012-08-06 18:24:55 +1000961If the initiator-name is not specified qemu will use a default name
962of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
963virtual machine.
964
965
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +1100966@example
967Setting a specific initiator name to use when logging in to the target
968-iscsi initiator-name=iqn.qemu.test:my-initiator
969@end example
970
971@example
972Controlling which type of header digest to negotiate with the target
973-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
974@end example
975
976These can also be set via a configuration file
977@example
978[iscsi]
979 user = "CHAP username"
980 password = "CHAP password"
981 initiator-name = "iqn.qemu.test:my-initiator"
982 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
983 header-digest = "CRC32C"
984@end example
985
986
987Setting the target name allows different options for different targets
988@example
989[iscsi "iqn.target.name"]
990 user = "CHAP username"
991 password = "CHAP password"
992 initiator-name = "iqn.qemu.test:my-initiator"
993 # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
994 header-digest = "CRC32C"
995@end example
996
997
998Howto use a configuration file to set iSCSI configuration options:
999@example
1000cat >iscsi.conf <<EOF
1001[iscsi]
1002 user = "me"
1003 password = "my password"
1004 initiator-name = "iqn.qemu.test:my-initiator"
1005 header-digest = "CRC32C"
1006EOF
1007
1008qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1009 -readconfig iscsi.conf
1010@end example
1011
1012
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001013Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
1014@example
1015This example shows how to set up an iSCSI target with one CDROM and one DISK
1016using the Linux STGT software target. This target is available on Red Hat based
1017systems as the package 'scsi-target-utils'.
1018
1019tgtd --iscsi portal=127.0.0.1:3260
1020tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
1021tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
1022 -b /IMAGES/disk.img --device-type=disk
1023tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
1024 -b /IMAGES/cd.iso --device-type=cd
1025tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
1026
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11001027qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
1028 -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001029 -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
1030@end example
1031
Bharata B Rao8809e282012-10-24 17:17:53 +05301032@node disk_images_gluster
1033@subsection GlusterFS disk images
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001034
Stefan Weil736a83f2016-11-19 20:22:07 +01001035GlusterFS is a user space distributed file system.
Bharata B Rao8809e282012-10-24 17:17:53 +05301036
1037You can boot from the GlusterFS disk image with the command:
1038@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301039URI:
1040qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path}
1041 [?socket=...][,file.debug=9][,file.logfile=...]
1042
1043JSON:
1044qemu-system-x86_64 'json:@{"driver":"qcow2",
1045 "file":@{"driver":"gluster",
1046 "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
1047 "server":[@{"type":"tcp","host":"...","port":"..."@},
1048 @{"type":"unix","socket":"..."@}]@}@}'
Bharata B Rao8809e282012-10-24 17:17:53 +05301049@end example
1050
1051@var{gluster} is the protocol.
1052
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301053@var{type} specifies the transport type used to connect to gluster
Bharata B Rao8809e282012-10-24 17:17:53 +05301054management daemon (glusterd). Valid transport types are
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301055tcp and unix. In the URI form, if a transport type isn't specified,
1056then tcp type is assumed.
Bharata B Rao8809e282012-10-24 17:17:53 +05301057
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301058@var{host} specifies the server where the volume file specification for
1059the given volume resides. This can be either a hostname or an ipv4 address.
1060If transport type is unix, then @var{host} field should not be specified.
Bharata B Rao8809e282012-10-24 17:17:53 +05301061Instead @var{socket} field needs to be populated with the path to unix domain
1062socket.
1063
1064@var{port} is the port number on which glusterd is listening. This is optional
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301065and if not specified, it defaults to port 24007. If the transport type is unix,
1066then @var{port} should not be specified.
Bharata B Rao8809e282012-10-24 17:17:53 +05301067
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301068@var{volume} is the name of the gluster volume which contains the disk image.
Bharata B Rao8809e282012-10-24 17:17:53 +05301069
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301070@var{path} is the path to the actual disk image that resides on gluster volume.
1071
1072@var{debug} is the logging level of the gluster protocol driver. Debug levels
1073are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
1074The default level is 4. The current logging levels defined in the gluster source
1075are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
10766 - Notice, 7 - Info, 8 - Debug, 9 - Trace
1077
1078@var{logfile} is a commandline option to mention log file path which helps in
1079logging to the specified file and also help in persisting the gfapi logs. The
1080default is stderr.
1081
1082
1083
Bharata B Rao8809e282012-10-24 17:17:53 +05301084
1085You can create a GlusterFS disk image with the command:
1086@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301087qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
Bharata B Rao8809e282012-10-24 17:17:53 +05301088@end example
1089
1090Examples
1091@example
1092qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1093qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1094qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1095qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1096qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1097qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1098qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1099qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05301100qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
1101qemu-system-x86_64 'json:@{"driver":"qcow2",
1102 "file":@{"driver":"gluster",
1103 "volume":"testvol","path":"a.img",
1104 "debug":9,"logfile":"/var/log/qemu-gluster.log",
1105 "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
1106 @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
1107qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
1108 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
1109 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
1110 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
Bharata B Rao8809e282012-10-24 17:17:53 +05301111@end example
Ronnie Sahlberg00984e32011-11-12 11:06:30 +11001112
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001113@node disk_images_ssh
1114@subsection Secure Shell (ssh) disk images
1115
1116You can access disk images located on a remote ssh server
1117by using the ssh protocol:
1118
1119@example
1120qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
1121@end example
1122
1123Alternative syntax using properties:
1124
1125@example
1126qemu-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}]
1127@end example
1128
1129@var{ssh} is the protocol.
1130
1131@var{user} is the remote user. If not specified, then the local
1132username is tried.
1133
1134@var{server} specifies the remote ssh server. Any ssh server can be
1135used, but it must implement the sftp-server protocol. Most Unix/Linux
1136systems should work without requiring any extra configuration.
1137
1138@var{port} is the port number on which sshd is listening. By default
1139the standard ssh port (22) is used.
1140
1141@var{path} is the path to the disk image.
1142
1143The optional @var{host_key_check} parameter controls how the remote
1144host's key is checked. The default is @code{yes} which means to use
1145the local @file{.ssh/known_hosts} file. Setting this to @code{no}
1146turns off known-hosts checking. Or you can check that the host key
1147matches a specific fingerprint:
1148@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
1149(@code{sha1:} can also be used as a prefix, but note that OpenSSH
1150tools only use MD5 to print fingerprints).
1151
1152Currently authentication must be done using ssh-agent. Other
1153authentication methods may be supported in future.
1154
Richard W.M. Jones9a2d4622013-04-09 15:30:54 +01001155Note: Many ssh servers do not support an @code{fsync}-style operation.
1156The ssh driver cannot guarantee that disk flush requests are
1157obeyed, and this causes a risk of disk corruption if the remote
1158server or network goes down during writes. The driver will
1159print a warning when @code{fsync} is not supported:
1160
1161warning: ssh server @code{ssh.example.com:22} does not support fsync
1162
1163With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
1164supported.
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01001165
bellarddebc7062006-04-30 21:58:41 +00001166@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001167@section Network emulation
1168
ths4be456f2007-06-03 13:41:28 +00001169QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001170target) and can connect them to an arbitrary number of Virtual Local
1171Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1172VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001173simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001174network stack can replace the TAP device to have a basic network
1175connection.
bellard9d4fb822004-04-26 20:55:38 +00001176
bellard41d03942005-11-15 23:02:53 +00001177@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001178
bellard41d03942005-11-15 23:02:53 +00001179QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1180connection between several network devices. These devices can be for
1181example QEMU virtual Ethernet cards or virtual Host ethernet devices
1182(TAP devices).
1183
1184@subsection Using TAP network interfaces
1185
1186This is the standard way to connect QEMU to a real network. QEMU adds
1187a virtual network device on your host (called @code{tapN}), and you
1188can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001189
bellard8f40c382006-09-20 20:28:05 +00001190@subsubsection Linux host
1191
bellard9d4fb822004-04-26 20:55:38 +00001192As an example, you can download the @file{linux-test-xxx.tar.gz}
1193archive and copy the script @file{qemu-ifup} in @file{/etc} and
1194configure properly @code{sudo} so that the command @code{ifconfig}
1195contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001196that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001197device @file{/dev/net/tun} must be present.
1198
bellardee0f4752006-08-19 16:56:18 +00001199See @ref{sec_invocation} to have examples of command lines using the
1200TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001201
bellard8f40c382006-09-20 20:28:05 +00001202@subsubsection Windows host
1203
1204There is a virtual ethernet driver for Windows 2000/XP systems, called
1205TAP-Win32. But it is not included in standard QEMU for Windows,
1206so you will need to get it separately. It is part of OpenVPN package,
1207so download OpenVPN from : @url{http://openvpn.net/}.
1208
bellard9d4fb822004-04-26 20:55:38 +00001209@subsection Using the user mode network stack
1210
bellard41d03942005-11-15 23:02:53 +00001211By using the option @option{-net user} (default configuration if no
1212@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001213network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001214network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001215
1216@example
1217
bellard41d03942005-11-15 23:02:53 +00001218 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1219 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001220 |
bellard2518bd02004-09-30 22:35:13 +00001221 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001222 |
bellard2518bd02004-09-30 22:35:13 +00001223 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001224@end example
1225
1226The QEMU VM behaves as if it was behind a firewall which blocks all
1227incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001228configure the network in the QEMU VM. The DHCP server assign addresses
1229to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001230
1231In order to check that the user mode network is working, you can ping
1232the address 10.0.2.2 and verify that you got an address in the range
123310.0.2.x from the QEMU virtual DHCP server.
1234
Gernot Hillier37cbfcc2014-07-10 16:01:25 +02001235Note that ICMP traffic in general does not work with user mode networking.
1236@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
1237however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
1238ping sockets to allow @code{ping} to the Internet. The host admin has to set
1239the ping_group_range in order to grant access to those sockets. To allow ping
1240for GID 100 (usually users group):
1241
1242@example
1243echo 100 100 > /proc/sys/net/ipv4/ping_group_range
1244@end example
bellardb415a402004-05-23 21:04:06 +00001245
bellard9bf05442004-08-25 22:12:49 +00001246When using the built-in TFTP server, the router is also the TFTP
1247server.
1248
Thomas Huthc8c6afa2016-01-13 09:21:02 +01001249When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
1250connections can be redirected from the host to the guest. It allows for
1251example to redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001252
bellard41d03942005-11-15 23:02:53 +00001253@subsection Connecting VLANs between QEMU instances
1254
1255Using the @option{-net socket} option, it is possible to make VLANs
1256that span several QEMU instances. See @ref{sec_invocation} to have a
1257basic example.
1258
Stefan Weil576fd0a2011-01-07 18:59:14 +01001259@node pcsys_other_devs
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001260@section Other Devices
1261
1262@subsection Inter-VM Shared Memory device
1263
Markus Armbruster5400c022016-03-15 19:34:51 +01001264On Linux hosts, a shared memory device is available. The basic syntax
1265is:
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001266
1267@example
Markus Armbruster5400c022016-03-15 19:34:51 +01001268qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
1269@end example
1270
1271where @var{hostmem} names a host memory backend. For a POSIX shared
1272memory backend, use something like
1273
1274@example
1275-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001276@end example
1277
1278If desired, interrupts can be sent between guest VMs accessing the same shared
1279memory region. Interrupt support requires using a shared memory server and
1280using a chardev socket to connect to it. The code for the shared memory server
1281is qemu.git/contrib/ivshmem-server. An example syntax when using the shared
1282memory server is:
1283
1284@example
David Marchanda75eb032014-09-08 11:17:48 +02001285# First start the ivshmem server once and for all
Markus Armbruster50d34c42015-11-24 18:06:25 +01001286ivshmem-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 +02001287
1288# Then start your qemu instances with matching arguments
Markus Armbruster5400c022016-03-15 19:34:51 +01001289qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
Markus Armbruster50d34c42015-11-24 18:06:25 +01001290 -chardev socket,path=@var{path},id=@var{id}
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001291@end example
1292
1293When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1294using the same server to communicate via interrupts. Guests can read their
Markus Armbruster1309cf42016-03-15 19:34:41 +01001295VM ID from a device register (see ivshmem-spec.txt).
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001296
Markus Armbruster62a830b2016-03-15 19:34:54 +01001297@subsubsection Migration with ivshmem
1298
Markus Armbruster5400c022016-03-15 19:34:51 +01001299With device property @option{master=on}, the guest will copy the shared
1300memory on migration to the destination host. With @option{master=off},
1301the guest will not be able to migrate with the device attached. In the
1302latter case, the device should be detached and then reattached after
1303migration using the PCI hotplug support.
Cam Macdonell6cbf4c82010-07-27 10:54:13 -06001304
Markus Armbruster62a830b2016-03-15 19:34:54 +01001305At most one of the devices sharing the same memory can be master. The
1306master must complete migration before you plug back the other devices.
1307
Marc-André Lureau7d4f4bd2015-10-07 16:31:47 +02001308@subsubsection ivshmem and hugepages
1309
1310Instead of specifying the <shm size> using POSIX shm, you may specify
1311a memory backend that has hugepage support:
1312
1313@example
Markus Armbruster5400c022016-03-15 19:34:51 +01001314qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
1315 -device ivshmem-plain,memdev=mb1
Marc-André Lureau7d4f4bd2015-10-07 16:31:47 +02001316@end example
1317
1318ivshmem-server also supports hugepages mount points with the
1319@option{-m} memory path argument.
1320
bellard9d4fb822004-04-26 20:55:38 +00001321@node direct_linux_boot
1322@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001323
1324This section explains how to launch a Linux kernel inside QEMU without
1325having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001326kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001327
bellardee0f4752006-08-19 16:56:18 +00001328The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001329@example
Stefan Weil3804da92012-05-11 22:21:50 +02001330qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001331@end example
1332
bellardee0f4752006-08-19 16:56:18 +00001333Use @option{-kernel} to provide the Linux kernel image and
1334@option{-append} to give the kernel command line arguments. The
1335@option{-initrd} option can be used to provide an INITRD image.
1336
1337When using the direct Linux boot, a disk image for the first hard disk
1338@file{hda} is required because its boot sector is used to launch the
1339Linux kernel.
1340
1341If you do not need graphical output, you can disable it and redirect
1342the virtual serial port and the QEMU monitor to the console with the
1343@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001344@example
Stefan Weil3804da92012-05-11 22:21:50 +02001345qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1346 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001347@end example
1348
bellardee0f4752006-08-19 16:56:18 +00001349Use @key{Ctrl-a c} to switch between the serial console and the
1350monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001351
bellarddebc7062006-04-30 21:58:41 +00001352@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001353@section USB emulation
1354
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001355QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
1356plug virtual USB devices or real host USB devices (only works with certain
1357host operating systems). QEMU will automatically create and connect virtual
1358USB hubs as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001359
pbrook0aff66b2006-05-26 00:49:52 +00001360@menu
1361* usb_devices::
1362* host_usb_devices::
1363@end menu
1364@node usb_devices
1365@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001366
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001367USB devices can be connected with the @option{-device usb-...} command line
1368option or the @code{device_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001369
balrogdb380c02008-01-17 22:22:45 +00001370@table @code
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001371@item usb-mouse
pbrook0aff66b2006-05-26 00:49:52 +00001372Virtual Mouse. This will override the PS/2 mouse emulation when activated.
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001373@item usb-tablet
bellardc6d46c22006-09-03 17:10:41 +00001374Pointer device that uses absolute coordinates (like a touchscreen).
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001375This means QEMU is able to report the mouse position without having
pbrook0aff66b2006-05-26 00:49:52 +00001376to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001377@item usb-storage,drive=@var{drive_id}
1378Mass storage device backed by @var{drive_id} (@pxref{disk_images})
1379@item usb-uas
1380USB attached SCSI device, see
1381@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
1382for details
1383@item usb-bot
1384Bulk-only transport storage device, see
1385@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
1386for details here, too
1387@item usb-mtp,x-root=@var{dir}
1388Media transfer protocol device, using @var{dir} as root of the file tree
1389that is presented to the guest.
1390@item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
1391Pass through the host device identified by @var{bus} and @var{addr}
1392@item usb-host,vendorid=@var{vendor},productid=@var{product}
1393Pass through the host device identified by @var{vendor} and @var{product} ID
1394@item usb-wacom-tablet
balrogf6d2a312007-06-10 19:21:04 +00001395Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1396above but it can be used with the tslib library because in addition to touch
1397coordinates it reports touch pressure.
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001398@item usb-kbd
balrog47b2d332007-06-22 08:16:00 +00001399Standard USB keyboard. Will override the PS/2 keyboard (if present).
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001400@item usb-serial,chardev=@var{id}
balrogdb380c02008-01-17 22:22:45 +00001401Serial converter. This emulates an FTDI FT232BM chip connected to host character
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001402device @var{id}.
1403@item usb-braille,chardev=@var{id}
aurel322e4d9fb2008-04-08 06:01:02 +00001404Braille device. This will use BrlAPI to display the braille output on a real
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001405or fake device referenced by @var{id}.
1406@item usb-net[,netdev=@var{id}]
1407Network adapter that supports CDC ethernet and RNDIS protocols. @var{id}
1408specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
balrog9ad97e62008-07-29 13:16:31 +00001409For instance, user-mode networking can be used with
balrog6c9f8862008-07-17 20:47:13 +00001410@example
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001411qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
balrog6c9f8862008-07-17 20:47:13 +00001412@end example
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001413@item usb-ccid
1414Smartcard reader device
1415@item usb-audio
1416USB audio device
1417@item usb-bt-dongle
1418Bluetooth dongle for the transport layer of HCI. It is connected to HCI
1419scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
1420Note that the syntax for the @code{-device usb-bt-dongle} option is not as
1421useful yet as it was with the legacy @code{-usbdevice} option. So to
1422configure an USB bluetooth device, you might need to use
1423"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
1424bluetooth dongle whose type is specified in the same format as with
balrog2d564692008-11-09 02:24:54 +00001425the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
1426no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1427This USB device implements the USB Transport Layer of HCI. Example
1428usage:
1429@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00001430@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
balrog2d564692008-11-09 02:24:54 +00001431@end example
pbrook0aff66b2006-05-26 00:49:52 +00001432@end table
bellardb389dbf2005-11-06 16:49:55 +00001433
pbrook0aff66b2006-05-26 00:49:52 +00001434@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001435@subsection Using host USB devices on a Linux host
1436
1437WARNING: this is an experimental feature. QEMU will slow down when
1438using it. USB devices requiring real time streaming (i.e. USB Video
1439Cameras) are not supported yet.
1440
1441@enumerate
ths5fafdf22007-09-16 21:08:06 +00001442@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001443is actually using the USB device. A simple way to do that is simply to
1444disable the corresponding kernel module by renaming it from @file{mydriver.o}
1445to @file{mydriver.o.disabled}.
1446
1447@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1448@example
1449ls /proc/bus/usb
1450001 devices drivers
1451@end example
1452
1453@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:
1454@example
1455chown -R myuid /proc/bus/usb
1456@end example
1457
1458@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001459@example
bellardb389dbf2005-11-06 16:49:55 +00001460info usbhost
1461 Device 1.2, speed 480 Mb/s
1462 Class 00: USB device 1234:5678, USB DISK
1463@end example
1464You should see the list of the devices you can use (Never try to use
1465hubs, it won't work).
1466
1467@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001468@example
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001469device_add usb-host,vendorid=0x1234,productid=0x5678
bellardb389dbf2005-11-06 16:49:55 +00001470@end example
1471
Thomas Hutha92ff8c2017-05-08 17:13:49 +02001472Normally the guest OS should report that a new USB device is plugged.
1473You can use the option @option{-device usb-host,...} to do the same.
bellardb389dbf2005-11-06 16:49:55 +00001474
1475@item Now you can try to use the host USB device in QEMU.
1476
1477@end enumerate
1478
1479When relaunching QEMU, you may have to unplug and plug again the USB
1480device to make it work again (this is a bug).
1481
thsf858dca2007-08-25 01:40:37 +00001482@node vnc_security
1483@section VNC security
1484
1485The VNC server capability provides access to the graphical console
1486of the guest VM across the network. This has a number of security
1487considerations depending on the deployment scenarios.
1488
1489@menu
1490* vnc_sec_none::
1491* vnc_sec_password::
1492* vnc_sec_certificate::
1493* vnc_sec_certificate_verify::
1494* vnc_sec_certificate_pw::
aliguori2f9606b2009-03-06 20:27:28 +00001495* vnc_sec_sasl::
1496* vnc_sec_certificate_sasl::
thsf858dca2007-08-25 01:40:37 +00001497* vnc_generate_cert::
aliguori2f9606b2009-03-06 20:27:28 +00001498* vnc_setup_sasl::
thsf858dca2007-08-25 01:40:37 +00001499@end menu
1500@node vnc_sec_none
1501@subsection Without passwords
1502
1503The simplest VNC server setup does not include any form of authentication.
1504For this setup it is recommended to restrict it to listen on a UNIX domain
1505socket only. For example
1506
1507@example
Stefan Weil3804da92012-05-11 22:21:50 +02001508qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
thsf858dca2007-08-25 01:40:37 +00001509@end example
1510
1511This ensures that only users on local box with read/write access to that
1512path can access the VNC server. To securely access the VNC server from a
1513remote machine, a combination of netcat+ssh can be used to provide a secure
1514tunnel.
1515
1516@node vnc_sec_password
1517@subsection With passwords
1518
1519The VNC protocol has limited support for password based authentication. Since
1520the protocol limits passwords to 8 characters it should not be considered
1521to provide high security. The password can be fairly easily brute-forced by
1522a client making repeat connections. For this reason, a VNC server using password
1523authentication should be restricted to only listen on the loopback interface
Paul Moore0f669982012-08-03 14:39:21 -04001524or UNIX domain sockets. Password authentication is not supported when operating
1525in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1526authentication is requested with the @code{password} option, and then once QEMU
1527is running the password is set with the monitor. Until the monitor is used to
1528set the password all clients will be rejected.
thsf858dca2007-08-25 01:40:37 +00001529
1530@example
Stefan Weil3804da92012-05-11 22:21:50 +02001531qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001532(qemu) change vnc password
1533Password: ********
1534(qemu)
1535@end example
1536
1537@node vnc_sec_certificate
1538@subsection With x509 certificates
1539
1540The QEMU VNC server also implements the VeNCrypt extension allowing use of
1541TLS for encryption of the session, and x509 certificates for authentication.
1542The use of x509 certificates is strongly recommended, because TLS on its
1543own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1544support provides a secure session, but no authentication. This allows any
1545client to connect, and provides an encrypted session.
1546
1547@example
Stefan Weil3804da92012-05-11 22:21:50 +02001548qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001549@end example
1550
1551In the above example @code{/etc/pki/qemu} should contain at least three files,
1552@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1553users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1554NB the @code{server-key.pem} file should be protected with file mode 0600 to
1555only be readable by the user owning it.
1556
1557@node vnc_sec_certificate_verify
1558@subsection With x509 certificates and client verification
1559
1560Certificates can also provide a means to authenticate the client connecting.
1561The server will request that the client provide a certificate, which it will
1562then validate against the CA certificate. This is a good choice if deploying
1563in an environment with a private internal certificate authority.
1564
1565@example
Stefan Weil3804da92012-05-11 22:21:50 +02001566qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001567@end example
1568
1569
1570@node vnc_sec_certificate_pw
1571@subsection With x509 certificates, client verification and passwords
1572
1573Finally, the previous method can be combined with VNC password authentication
1574to provide two layers of authentication for clients.
1575
1576@example
Stefan Weil3804da92012-05-11 22:21:50 +02001577qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
thsf858dca2007-08-25 01:40:37 +00001578(qemu) change vnc password
1579Password: ********
1580(qemu)
1581@end example
1582
aliguori2f9606b2009-03-06 20:27:28 +00001583
1584@node vnc_sec_sasl
1585@subsection With SASL authentication
1586
1587The SASL authentication method is a VNC extension, that provides an
1588easily extendable, pluggable authentication method. This allows for
1589integration with a wide range of authentication mechanisms, such as
1590PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1591The strength of the authentication depends on the exact mechanism
1592configured. If the chosen mechanism also provides a SSF layer, then
1593it will encrypt the datastream as well.
1594
1595Refer to the later docs on how to choose the exact SASL mechanism
1596used for authentication, but assuming use of one supporting SSF,
1597then QEMU can be launched with:
1598
1599@example
Stefan Weil3804da92012-05-11 22:21:50 +02001600qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001601@end example
1602
1603@node vnc_sec_certificate_sasl
1604@subsection With x509 certificates and SASL authentication
1605
1606If the desired SASL authentication mechanism does not supported
1607SSF layers, then it is strongly advised to run it in combination
1608with TLS and x509 certificates. This provides securely encrypted
1609data stream, avoiding risk of compromising of the security
1610credentials. This can be enabled, by combining the 'sasl' option
1611with the aforementioned TLS + x509 options:
1612
1613@example
Stefan Weil3804da92012-05-11 22:21:50 +02001614qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
aliguori2f9606b2009-03-06 20:27:28 +00001615@end example
1616
1617
thsf858dca2007-08-25 01:40:37 +00001618@node vnc_generate_cert
1619@subsection Generating certificates for VNC
1620
1621The GNU TLS packages provides a command called @code{certtool} which can
1622be used to generate certificates and keys in PEM format. At a minimum it
Stefan Weil40c5c6c2011-01-07 18:59:16 +01001623is necessary to setup a certificate authority, and issue certificates to
thsf858dca2007-08-25 01:40:37 +00001624each server. If using certificates for authentication, then each client
1625will also need to be issued a certificate. The recommendation is for the
1626server to keep its certificates in either @code{/etc/pki/qemu} or for
1627unprivileged users in @code{$HOME/.pki/qemu}.
1628
1629@menu
1630* vnc_generate_ca::
1631* vnc_generate_server::
1632* vnc_generate_client::
1633@end menu
1634@node vnc_generate_ca
1635@subsubsection Setup the Certificate Authority
1636
1637This step only needs to be performed once per organization / organizational
1638unit. First the CA needs a private key. This key must be kept VERY secret
1639and secure. If this key is compromised the entire trust chain of the certificates
1640issued with it is lost.
1641
1642@example
1643# certtool --generate-privkey > ca-key.pem
1644@end example
1645
1646A CA needs to have a public certificate. For simplicity it can be a self-signed
1647certificate, or one issue by a commercial certificate issuing authority. To
1648generate a self-signed certificate requires one core piece of information, the
1649name of the organization.
1650
1651@example
1652# cat > ca.info <<EOF
1653cn = Name of your organization
1654ca
1655cert_signing_key
1656EOF
1657# certtool --generate-self-signed \
1658 --load-privkey ca-key.pem
1659 --template ca.info \
1660 --outfile ca-cert.pem
1661@end example
1662
1663The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1664TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1665
1666@node vnc_generate_server
1667@subsubsection Issuing server certificates
1668
1669Each server (or host) needs to be issued with a key and certificate. When connecting
1670the certificate is sent to the client which validates it against the CA certificate.
1671The core piece of information for a server certificate is the hostname. This should
1672be the fully qualified hostname that the client will connect with, since the client
1673will typically also verify the hostname in the certificate. On the host holding the
1674secure CA private key:
1675
1676@example
1677# cat > server.info <<EOF
1678organization = Name of your organization
1679cn = server.foo.example.com
1680tls_www_server
1681encryption_key
1682signing_key
1683EOF
1684# certtool --generate-privkey > server-key.pem
1685# certtool --generate-certificate \
1686 --load-ca-certificate ca-cert.pem \
1687 --load-ca-privkey ca-key.pem \
Gonglei63c693f2014-11-03 20:48:30 +08001688 --load-privkey server-key.pem \
thsf858dca2007-08-25 01:40:37 +00001689 --template server.info \
1690 --outfile server-cert.pem
1691@end example
1692
1693The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1694to the server for which they were generated. The @code{server-key.pem} is security
1695sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1696
1697@node vnc_generate_client
1698@subsubsection Issuing client certificates
1699
1700If the QEMU VNC server is to use the @code{x509verify} option to validate client
1701certificates as its authentication mechanism, each client also needs to be issued
1702a certificate. The client certificate contains enough metadata to uniquely identify
1703the client, typically organization, state, city, building, etc. On the host holding
1704the secure CA private key:
1705
1706@example
1707# cat > client.info <<EOF
1708country = GB
1709state = London
1710locality = London
Gonglei63c693f2014-11-03 20:48:30 +08001711organization = Name of your organization
thsf858dca2007-08-25 01:40:37 +00001712cn = client.foo.example.com
1713tls_www_client
1714encryption_key
1715signing_key
1716EOF
1717# certtool --generate-privkey > client-key.pem
1718# certtool --generate-certificate \
1719 --load-ca-certificate ca-cert.pem \
1720 --load-ca-privkey ca-key.pem \
1721 --load-privkey client-key.pem \
1722 --template client.info \
1723 --outfile client-cert.pem
1724@end example
1725
1726The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1727copied to the client for which they were generated.
1728
aliguori2f9606b2009-03-06 20:27:28 +00001729
1730@node vnc_setup_sasl
1731
1732@subsection Configuring SASL mechanisms
1733
1734The following documentation assumes use of the Cyrus SASL implementation on a
1735Linux host, but the principals should apply to any other SASL impl. When SASL
1736is enabled, the mechanism configuration will be loaded from system default
1737SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1738unprivileged user, an environment variable SASL_CONF_PATH can be used
1739to make it search alternate locations for the service config.
1740
Daniel P. Berrangec6a9a9f2017-03-15 11:53:22 +00001741If the TLS option is enabled for VNC, then it will provide session encryption,
1742otherwise the SASL mechanism will have to provide encryption. In the latter
1743case the list of possible plugins that can be used is drastically reduced. In
1744fact only the GSSAPI SASL mechanism provides an acceptable level of security
1745by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1746mechanism, however, it has multiple serious flaws described in detail in
1747RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1748provides a simple username/password auth facility similar to DIGEST-MD5, but
1749does not support session encryption, so can only be used in combination with
1750TLS.
aliguori2f9606b2009-03-06 20:27:28 +00001751
Daniel P. Berrangec6a9a9f2017-03-15 11:53:22 +00001752When not using TLS the recommended configuration is
aliguori2f9606b2009-03-06 20:27:28 +00001753
1754@example
1755mech_list: gssapi
1756keytab: /etc/qemu/krb5.tab
1757@end example
1758
Daniel P. Berrangec6a9a9f2017-03-15 11:53:22 +00001759This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1760the server principal stored in /etc/qemu/krb5.tab. For this to work the
1761administrator of your KDC must generate a Kerberos principal for the server,
1762with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1763'somehost.example.com' with the fully qualified host name of the machine
1764running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
aliguori2f9606b2009-03-06 20:27:28 +00001765
Daniel P. Berrangec6a9a9f2017-03-15 11:53:22 +00001766When using TLS, if username+password authentication is desired, then a
1767reasonable configuration is
1768
1769@example
1770mech_list: scram-sha-1
1771sasldb_path: /etc/qemu/passwd.db
1772@end example
1773
1774The saslpasswd2 program can be used to populate the passwd.db file with
1775accounts.
1776
1777Other SASL configurations will be left as an exercise for the reader. Note that
1778all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
1779secure data channel.
aliguori2f9606b2009-03-06 20:27:28 +00001780
bellard0806e3f2003-10-01 00:15:32 +00001781@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001782@section GDB usage
1783
1784QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001785'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001786
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001787In order to use gdb, launch QEMU with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001788gdb connection:
1789@example
Stefan Weil3804da92012-05-11 22:21:50 +02001790qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1791 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001792Connected to host network interface: tun0
1793Waiting gdb connection on port 1234
1794@end example
1795
1796Then launch gdb on the 'vmlinux' executable:
1797@example
1798> gdb vmlinux
1799@end example
1800
1801In gdb, connect to QEMU:
1802@example
bellard6c9bf892004-01-24 13:46:56 +00001803(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001804@end example
1805
1806Then you can use gdb normally. For example, type 'c' to launch the kernel:
1807@example
1808(gdb) c
1809@end example
1810
bellard0806e3f2003-10-01 00:15:32 +00001811Here are some useful tips in order to use gdb on system code:
1812
1813@enumerate
1814@item
1815Use @code{info reg} to display all the CPU registers.
1816@item
1817Use @code{x/10i $eip} to display the code at the PC position.
1818@item
1819Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001820@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001821@end enumerate
1822
edgar_igl60897d32008-05-09 08:25:14 +00001823Advanced debugging options:
1824
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01001825The 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 +00001826@table @code
edgar_igl60897d32008-05-09 08:25:14 +00001827@item maintenance packet qqemu.sstepbits
1828
1829This will display the MASK bits used to control the single stepping IE:
1830@example
1831(gdb) maintenance packet qqemu.sstepbits
1832sending: "qqemu.sstepbits"
1833received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1834@end example
1835@item maintenance packet qqemu.sstep
1836
1837This will display the current value of the mask used when single stepping IE:
1838@example
1839(gdb) maintenance packet qqemu.sstep
1840sending: "qqemu.sstep"
1841received: "0x7"
1842@end example
1843@item maintenance packet Qqemu.sstep=HEX_VALUE
1844
1845This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1846@example
1847(gdb) maintenance packet Qqemu.sstep=0x5
1848sending: "qemu.sstep=0x5"
1849received: "OK"
1850@end example
edgar_igl94d45e42008-05-10 19:37:44 +00001851@end table
edgar_igl60897d32008-05-09 08:25:14 +00001852
bellarddebc7062006-04-30 21:58:41 +00001853@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001854@section Target OS specific information
1855
1856@subsection Linux
1857
bellard15a34c62004-07-08 21:26:26 +00001858To have access to SVGA graphic modes under X11, use the @code{vesa} or
1859the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1860color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001861
bellarde3371e62004-07-10 16:26:02 +00001862When using a 2.6 guest Linux kernel, you should add the option
1863@code{clock=pit} on the kernel command line because the 2.6 Linux
1864kernels make very strict real time clock checks by default that QEMU
1865cannot simulate exactly.
1866
bellard7c3fc842005-02-10 21:46:47 +00001867When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1868not activated because QEMU is slower with this patch. The QEMU
1869Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001870Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001871patch by default. Newer kernels don't have it.
1872
bellard1a084f32004-05-13 22:34:49 +00001873@subsection Windows
1874
1875If you have a slow host, using Windows 95 is better as it gives the
1876best speed. Windows 2000 is also a good choice.
1877
bellarde3371e62004-07-10 16:26:02 +00001878@subsubsection SVGA graphic modes support
1879
1880QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001881card. All Windows versions starting from Windows 95 should recognize
1882and use this graphic card. For optimal performances, use 16 bit color
1883depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001884
bellard3cb08532006-06-21 21:19:50 +00001885If you are using Windows XP as guest OS and if you want to use high
1886resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
18871280x1024x16), then you should use the VESA VBE virtual graphic card
1888(option @option{-std-vga}).
1889
bellarde3371e62004-07-10 16:26:02 +00001890@subsubsection CPU usage reduction
1891
1892Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001893instruction. The result is that it takes host CPU cycles even when
1894idle. You can install the utility from
Thomas Huth3ba34a72017-03-08 13:13:25 +01001895@url{http://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1896to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001897
bellard9d0a8e62005-07-03 17:34:05 +00001898@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001899
bellard9d0a8e62005-07-03 17:34:05 +00001900Windows 2000 has a bug which gives a disk full problem during its
1901installation. When installing it, use the @option{-win2k-hack} QEMU
1902option to enable a specific workaround. After Windows 2000 is
1903installed, you no longer need this option (this option slows down the
1904IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001905
bellard6cc721c2005-07-28 22:27:28 +00001906@subsubsection Windows 2000 shutdown
1907
1908Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1909can. It comes from the fact that Windows 2000 does not automatically
1910use the APM driver provided by the BIOS.
1911
1912In order to correct that, do the following (thanks to Struan
1913Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1914Add/Troubleshoot a device => Add a new device & Next => No, select the
1915hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1916(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001917correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001918
1919@subsubsection Share a directory between Unix and Windows
1920
Thomas Huthc8c6afa2016-01-13 09:21:02 +01001921See @ref{sec_invocation} about the help of the option
1922@option{'-netdev user,smb=...'}.
bellard6cc721c2005-07-28 22:27:28 +00001923
bellard2192c332006-08-21 20:28:18 +00001924@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001925
1926Some releases of Windows XP install correctly but give a security
1927error when booting:
1928@example
1929A problem is preventing Windows from accurately checking the
1930license for this computer. Error code: 0x800703e6.
1931@end example
bellarde3371e62004-07-10 16:26:02 +00001932
bellard2192c332006-08-21 20:28:18 +00001933The workaround is to install a service pack for XP after a boot in safe
1934mode. Then reboot, and the problem should go away. Since there is no
1935network while in safe mode, its recommended to download the full
1936installation of SP1 or SP2 and transfer that via an ISO or using the
1937vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001938
bellarda0a821a2004-07-14 17:38:57 +00001939@subsection MS-DOS and FreeDOS
1940
1941@subsubsection CPU usage reduction
1942
1943DOS does not correctly use the CPU HLT instruction. The result is that
Thomas Huth3ba34a72017-03-08 13:13:25 +01001944it takes host CPU cycles even when idle. You can install the utility from
1945@url{http://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1946to solve this problem.
bellarda0a821a2004-07-14 17:38:57 +00001947
bellarddebc7062006-04-30 21:58:41 +00001948@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001949@chapter QEMU System emulator for non PC targets
1950
1951QEMU is a generic emulator and it emulates many non PC
1952machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001953differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001954
bellarddebc7062006-04-30 21:58:41 +00001955@menu
Stefan Weil7544a042010-02-05 23:52:03 +01001956* PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001957* Sparc32 System emulator::
1958* Sparc64 System emulator::
1959* MIPS System emulator::
1960* ARM System emulator::
1961* ColdFire System emulator::
Stefan Weil7544a042010-02-05 23:52:03 +01001962* Cris System emulator::
1963* Microblaze System emulator::
1964* SH4 System emulator::
Max Filippov3aeaea62011-10-10 14:48:23 +04001965* Xtensa System emulator::
bellarddebc7062006-04-30 21:58:41 +00001966@end menu
1967
Stefan Weil7544a042010-02-05 23:52:03 +01001968@node PowerPC System emulator
1969@section PowerPC System emulator
1970@cindex system emulation (PowerPC)
bellard52c00a52004-04-25 21:27:03 +00001971
1972Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001973or PowerMac PowerPC system.
1974
bellardb671f9e2005-04-30 15:08:33 +00001975QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001976
1977@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001978@item
blueswir1006f3a42009-02-08 15:59:36 +00001979UniNorth or Grackle PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001980@item
1981PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001982@item
bellard15a34c62004-07-08 21:26:26 +000019832 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001984@item
bellard15a34c62004-07-08 21:26:26 +00001985NE2000 PCI adapters
1986@item
1987Non Volatile RAM
1988@item
1989VIA-CUDA with ADB keyboard and mouse.
1990@end itemize
bellard52c00a52004-04-25 21:27:03 +00001991
bellardb671f9e2005-04-30 15:08:33 +00001992QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001993
1994@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001995@item
bellard15a34c62004-07-08 21:26:26 +00001996PCI Bridge
1997@item
1998PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001999@item
bellard52c00a52004-04-25 21:27:03 +000020002 IDE interfaces with hard disk and CD-ROM support
2001@item
2002Floppy disk
ths5fafdf22007-09-16 21:08:06 +00002003@item
bellard15a34c62004-07-08 21:26:26 +00002004NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00002005@item
2006Serial port
2007@item
2008PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00002009@item
2010PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00002011@end itemize
2012
bellard15a34c62004-07-08 21:26:26 +00002013QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00002014@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00002015
blueswir1992e5ac2008-12-24 20:23:51 +00002016Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
blueswir1006f3a42009-02-08 15:59:36 +00002017for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
2018v2) portable firmware implementation. The goal is to implement a 100%
2019IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
blueswir1992e5ac2008-12-24 20:23:51 +00002020
bellard15a34c62004-07-08 21:26:26 +00002021@c man begin OPTIONS
2022
2023The following options are specific to the PowerPC emulation:
2024
2025@table @option
2026
Kevin Wolf4e257e52009-10-09 10:58:36 +02002027@item -g @var{W}x@var{H}[x@var{DEPTH}]
bellard15a34c62004-07-08 21:26:26 +00002028
Mark Cave-Ayland340fb412014-03-17 21:46:26 +00002029Set the initial VGA graphic mode. The default is 800x600x32.
bellard15a34c62004-07-08 21:26:26 +00002030
Kevin Wolf4e257e52009-10-09 10:58:36 +02002031@item -prom-env @var{string}
blueswir195efd112008-12-24 20:26:14 +00002032
2033Set OpenBIOS variables in NVRAM, for example:
2034
2035@example
2036qemu-system-ppc -prom-env 'auto-boot?=false' \
2037 -prom-env 'boot-device=hd:2,\yaboot' \
2038 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
2039@end example
2040
2041These variables are not used by Open Hack'Ware.
2042
bellard15a34c62004-07-08 21:26:26 +00002043@end table
2044
ths5fafdf22007-09-16 21:08:06 +00002045@c man end
bellard15a34c62004-07-08 21:26:26 +00002046
2047
bellard52c00a52004-04-25 21:27:03 +00002048More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00002049@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00002050
ths24d4de42007-07-11 10:24:28 +00002051@node Sparc32 System emulator
2052@section Sparc32 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002053@cindex system emulation (Sparc32)
bellarde80cfcf2004-12-19 23:18:01 +00002054
blueswir134a3d232008-10-04 20:43:39 +00002055Use the executable @file{qemu-system-sparc} to simulate the following
2056Sun4m architecture machines:
2057@itemize @minus
2058@item
2059SPARCstation 4
2060@item
2061SPARCstation 5
2062@item
2063SPARCstation 10
2064@item
2065SPARCstation 20
2066@item
2067SPARCserver 600MP
2068@item
2069SPARCstation LX
2070@item
2071SPARCstation Voyager
2072@item
2073SPARCclassic
2074@item
2075SPARCbook
2076@end itemize
bellarde80cfcf2004-12-19 23:18:01 +00002077
blueswir134a3d232008-10-04 20:43:39 +00002078The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2079but Linux limits the number of usable CPUs to 4.
2080
Blue Swirl6a4e1772013-04-14 18:10:28 +00002081QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00002082
2083@itemize @minus
bellard34751872005-07-02 14:31:34 +00002084@item
Blue Swirl6a4e1772013-04-14 18:10:28 +00002085IOMMU
bellarde80cfcf2004-12-19 23:18:01 +00002086@item
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002087TCX or cgthree Frame buffer
ths5fafdf22007-09-16 21:08:06 +00002088@item
bellarde80cfcf2004-12-19 23:18:01 +00002089Lance (Am7990) Ethernet
2090@item
blueswir134a3d232008-10-04 20:43:39 +00002091Non Volatile RAM M48T02/M48T08
bellarde80cfcf2004-12-19 23:18:01 +00002092@item
bellard34751872005-07-02 14:31:34 +00002093Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2094and power/reset logic
2095@item
2096ESP SCSI controller with hard disk and CD-ROM support
2097@item
blueswir16a3b9cc2007-11-11 17:56:38 +00002098Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00002099@item
2100CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00002101@end itemize
2102
blueswir16a3b9cc2007-11-11 17:56:38 +00002103The number of peripherals is fixed in the architecture. Maximum
2104memory size depends on the machine type, for SS-5 it is 256MB and for
blueswir17d858922007-12-28 20:57:43 +00002105others 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00002106
bellard30a604f2006-06-14 18:35:18 +00002107Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00002108@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2109firmware implementation. The goal is to implement a 100% IEEE
21101275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00002111
2112A sample Linux 2.6 series kernel and ram disk image are available on
blueswir134a3d232008-10-04 20:43:39 +00002113the QEMU web site. There are still issues with NetBSD and OpenBSD, but
Mark Cave-Ayland9bb9f212015-03-02 22:23:27 +00002114most kernel versions work. Please note that currently older Solaris kernels
blueswir134a3d232008-10-04 20:43:39 +00002115don't work probably due to interface issues between OpenBIOS and
2116Solaris.
bellard34751872005-07-02 14:31:34 +00002117
2118@c man begin OPTIONS
2119
blueswir1a2502b52007-06-10 17:01:00 +00002120The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00002121
2122@table @option
2123
Kevin Wolf4e257e52009-10-09 10:58:36 +02002124@item -g @var{W}x@var{H}x[x@var{DEPTH}]
bellard34751872005-07-02 14:31:34 +00002125
Mark Cave-Ayland33632782014-03-17 21:46:25 +00002126Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
2127option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
2128of 1152x900x8 for people who wish to use OBP.
bellard34751872005-07-02 14:31:34 +00002129
Kevin Wolf4e257e52009-10-09 10:58:36 +02002130@item -prom-env @var{string}
blueswir166508602007-05-01 14:16:52 +00002131
2132Set OpenBIOS variables in NVRAM, for example:
2133
2134@example
2135qemu-system-sparc -prom-env 'auto-boot?=false' \
2136 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2137@end example
2138
Blue Swirl6a4e1772013-04-14 18:10:28 +00002139@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
blueswir1a2502b52007-06-10 17:01:00 +00002140
2141Set the emulated machine type. Default is SS-5.
2142
bellard34751872005-07-02 14:31:34 +00002143@end table
2144
ths5fafdf22007-09-16 21:08:06 +00002145@c man end
bellard34751872005-07-02 14:31:34 +00002146
ths24d4de42007-07-11 10:24:28 +00002147@node Sparc64 System emulator
2148@section Sparc64 System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002149@cindex system emulation (Sparc64)
bellard34751872005-07-02 14:31:34 +00002150
blueswir134a3d232008-10-04 20:43:39 +00002151Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2152(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
Mark Cave-Ayland9bb9f212015-03-02 22:23:27 +00002153Niagara (T1) machine. The Sun4u emulator is mostly complete, being
2154able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
Artyom Tarasenkoa2664ca2016-09-29 14:46:45 +02002155Sun4v emulator is still a work in progress.
2156
2157The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
2158of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
2159and is able to boot the disk.s10hw2 Solaris image.
2160@example
2161qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
2162 -nographic -m 256 \
2163 -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
2164@end example
2165
bellardb7569212005-03-13 09:43:05 +00002166
blueswir1c7ba2182008-07-22 07:07:34 +00002167QEMU emulates the following peripherals:
bellard83469012005-07-23 14:27:54 +00002168
2169@itemize @minus
2170@item
ths5fafdf22007-09-16 21:08:06 +00002171UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00002172@item
2173PCI VGA compatible card with VESA Bochs Extensions
2174@item
blueswir134a3d232008-10-04 20:43:39 +00002175PS/2 mouse and keyboard
2176@item
bellard83469012005-07-23 14:27:54 +00002177Non Volatile RAM M48T59
2178@item
2179PC-compatible serial ports
blueswir1c7ba2182008-07-22 07:07:34 +00002180@item
21812 PCI IDE interfaces with hard disk and CD-ROM support
blueswir134a3d232008-10-04 20:43:39 +00002182@item
2183Floppy disk
bellard83469012005-07-23 14:27:54 +00002184@end itemize
2185
blueswir1c7ba2182008-07-22 07:07:34 +00002186@c man begin OPTIONS
2187
2188The following options are specific to the Sparc64 emulation:
2189
2190@table @option
2191
Kevin Wolf4e257e52009-10-09 10:58:36 +02002192@item -prom-env @var{string}
blueswir134a3d232008-10-04 20:43:39 +00002193
2194Set OpenBIOS variables in NVRAM, for example:
2195
2196@example
2197qemu-system-sparc64 -prom-env 'auto-boot?=false'
2198@end example
2199
Artyom Tarasenkoa2664ca2016-09-29 14:46:45 +02002200@item -M [sun4u|sun4v|niagara]
blueswir1c7ba2182008-07-22 07:07:34 +00002201
2202Set the emulated machine type. The default is sun4u.
2203
2204@end table
2205
2206@c man end
2207
ths24d4de42007-07-11 10:24:28 +00002208@node MIPS System emulator
2209@section MIPS System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002210@cindex system emulation (MIPS)
bellard9d0a8e62005-07-03 17:34:05 +00002211
thsd9aedc32007-12-17 03:47:55 +00002212Four executables cover simulation of 32 and 64-bit MIPS systems in
2213both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2214@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
aurel3288cb0a02008-04-08 05:57:37 +00002215Five different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002216
2217@itemize @minus
2218@item
2219A generic ISA PC-like machine "mips"
2220@item
2221The MIPS Malta prototype board "malta"
2222@item
thsd9aedc32007-12-17 03:47:55 +00002223An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002224@item
thsf0fc6f82007-10-17 13:39:42 +00002225MIPS emulator pseudo board "mipssim"
aurel3288cb0a02008-04-08 05:57:37 +00002226@item
2227A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
ths24d4de42007-07-11 10:24:28 +00002228@end itemize
2229
2230The generic emulation is supported by Debian 'Etch' and is able to
2231install Debian into a virtual disk image. The following devices are
2232emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002233
bellard3f9f3aa2005-12-18 20:11:37 +00002234@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002235@item
ths6bf5b4e2007-10-17 13:08:32 +00002236A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002237@item
2238PC style serial port
2239@item
ths24d4de42007-07-11 10:24:28 +00002240PC style IDE disk
2241@item
bellard3f9f3aa2005-12-18 20:11:37 +00002242NE2000 network card
2243@end itemize
2244
ths24d4de42007-07-11 10:24:28 +00002245The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002246
ths24d4de42007-07-11 10:24:28 +00002247@itemize @minus
2248@item
ths0b64d002007-07-11 21:43:14 +00002249Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002250@item
2251PIIX4 PCI/USB/SMbus controller
2252@item
2253The Multi-I/O chip's serial device
2254@item
Stefan Weil3a2eeac2009-06-06 18:05:58 +02002255PCI network cards (PCnet32 and others)
ths24d4de42007-07-11 10:24:28 +00002256@item
2257Malta FPGA serial device
2258@item
aurel321f605a72009-02-08 14:51:19 +00002259Cirrus (default) or any other PCI VGA graphics card
ths24d4de42007-07-11 10:24:28 +00002260@end itemize
2261
2262The ACER Pica emulation supports:
2263
2264@itemize @minus
2265@item
2266MIPS R4000 CPU
2267@item
2268PC-style IRQ and DMA controllers
2269@item
2270PC Keyboard
2271@item
2272IDE controller
2273@end itemize
2274
Stefan Weilb5e49462011-11-13 22:24:26 +01002275The mipssim pseudo board emulation provides an environment similar
thsf0fc6f82007-10-17 13:39:42 +00002276to what the proprietary MIPS emulator uses for running Linux.
2277It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002278
2279@itemize @minus
2280@item
2281A range of MIPS CPUs, default is the 24Kf
2282@item
2283PC style serial port
2284@item
2285MIPSnet network emulation
2286@end itemize
2287
aurel3288cb0a02008-04-08 05:57:37 +00002288The MIPS Magnum R4000 emulation supports:
2289
2290@itemize @minus
2291@item
2292MIPS R4000 CPU
2293@item
2294PC-style IRQ controller
2295@item
2296PC Keyboard
2297@item
2298SCSI controller
2299@item
2300G364 framebuffer
2301@end itemize
2302
2303
ths24d4de42007-07-11 10:24:28 +00002304@node ARM System emulator
2305@section ARM System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002306@cindex system emulation (ARM)
bellard3f9f3aa2005-12-18 20:11:37 +00002307
2308Use the executable @file{qemu-system-arm} to simulate a ARM
2309machine. The ARM Integrator/CP board is emulated with the following
2310devices:
2311
2312@itemize @minus
2313@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002314ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002315@item
2316Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002317@item
bellard3f9f3aa2005-12-18 20:11:37 +00002318SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002319@item
2320PL110 LCD controller
2321@item
2322PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002323@item
2324PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002325@end itemize
2326
2327The ARM Versatile baseboard is emulated with the following devices:
2328
2329@itemize @minus
2330@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002331ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002332@item
2333PL190 Vectored Interrupt Controller
2334@item
2335Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002336@item
pbrook00a9bf12006-05-13 16:55:46 +00002337SMC 91c111 Ethernet adapter
2338@item
2339PL110 LCD controller
2340@item
2341PL050 KMI with PS/2 keyboard and mouse.
2342@item
2343PCI host bridge. Note the emulated PCI bridge only provides access to
2344PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002345This means some devices (eg. ne2k_pci NIC) are not usable, and others
2346(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002347mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002348@item
2349PCI OHCI USB controller.
2350@item
2351LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002352@item
2353PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002354@end itemize
2355
Paul Brook21a88942009-12-21 20:19:12 +00002356Several variants of the ARM RealView baseboard are emulated,
2357including the EB, PB-A8 and PBX-A9. Due to interactions with the
2358bootloader, only certain Linux kernel configurations work out
2359of the box on these boards.
2360
2361Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2362enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
2363should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2364disabled and expect 1024M RAM.
2365
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002366The following devices are emulated:
pbrookd7739d72007-02-28 16:25:17 +00002367
2368@itemize @minus
2369@item
Paul Brookf7c70322009-11-19 16:45:21 +00002370ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
pbrookd7739d72007-02-28 16:25:17 +00002371@item
2372ARM AMBA Generic/Distributed Interrupt Controller
2373@item
2374Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002375@item
Paul Brook0ef849d2009-11-16 17:06:43 +00002376SMC 91c111 or SMSC LAN9118 Ethernet adapter
pbrookd7739d72007-02-28 16:25:17 +00002377@item
2378PL110 LCD controller
2379@item
2380PL050 KMI with PS/2 keyboard and mouse
2381@item
2382PCI host bridge
2383@item
2384PCI OHCI USB controller
2385@item
2386LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002387@item
2388PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002389@end itemize
2390
balrogb00052e2007-04-30 02:22:06 +00002391The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2392and "Terrier") emulation includes the following peripherals:
2393
2394@itemize @minus
2395@item
2396Intel PXA270 System-on-chip (ARM V5TE core)
2397@item
2398NAND Flash memory
2399@item
2400IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2401@item
2402On-chip OHCI USB controller
2403@item
2404On-chip LCD controller
2405@item
2406On-chip Real Time Clock
2407@item
2408TI ADS7846 touchscreen controller on SSP bus
2409@item
2410Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2411@item
2412GPIO-connected keyboard controller and LEDs
2413@item
balrog549444e2007-05-01 17:53:37 +00002414Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002415@item
2416Three on-chip UARTs
2417@item
2418WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2419@end itemize
2420
balrog02645922007-11-03 12:50:46 +00002421The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2422following elements:
2423
2424@itemize @minus
2425@item
2426Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2427@item
2428ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2429@item
2430On-chip LCD controller
2431@item
2432On-chip Real Time Clock
2433@item
2434TI TSC2102i touchscreen controller / analog-digital converter / Audio
2435CODEC, connected through MicroWire and I@math{^2}S busses
2436@item
2437GPIO-connected matrix keypad
2438@item
2439Secure Digital card connected to OMAP MMC/SD host
2440@item
2441Three on-chip UARTs
2442@end itemize
2443
balrogc30bb262008-05-18 13:01:40 +00002444Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2445emulation supports the following elements:
2446
2447@itemize @minus
2448@item
2449Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2450@item
2451RAM and non-volatile OneNAND Flash memories
2452@item
2453Display connected to EPSON remote framebuffer chip and OMAP on-chip
2454display controller and a LS041y3 MIPI DBI-C controller
2455@item
2456TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2457driven through SPI bus
2458@item
2459National Semiconductor LM8323-controlled qwerty keyboard driven
2460through I@math{^2}C bus
2461@item
2462Secure Digital card connected to OMAP MMC/SD host
2463@item
2464Three OMAP on-chip UARTs and on-chip STI debugging console
2465@item
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002466A Bluetooth(R) transceiver and HCI connected to an UART
balrog2d564692008-11-09 02:24:54 +00002467@item
balrogc30bb262008-05-18 13:01:40 +00002468Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2469TUSB6010 chip - only USB host mode is supported
2470@item
2471TI TMP105 temperature sensor driven through I@math{^2}C bus
2472@item
2473TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2474@item
2475Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2476through CBUS
2477@end itemize
2478
pbrook9ee6e8b2007-11-11 00:04:49 +00002479The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2480devices:
2481
2482@itemize @minus
2483@item
2484Cortex-M3 CPU core.
2485@item
248664k Flash and 8k SRAM.
2487@item
2488Timers, UARTs, ADC and I@math{^2}C interface.
2489@item
2490OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2491@end itemize
2492
2493The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2494devices:
2495
2496@itemize @minus
2497@item
2498Cortex-M3 CPU core.
2499@item
2500256k Flash and 64k SRAM.
2501@item
2502Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2503@item
2504OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2505@end itemize
2506
balrog57cd6e92008-05-07 12:23:32 +00002507The Freecom MusicPal internet radio emulation includes the following
2508elements:
2509
2510@itemize @minus
2511@item
2512Marvell MV88W8618 ARM core.
2513@item
251432 MB RAM, 256 KB SRAM, 8 MB flash.
2515@item
2516Up to 2 16550 UARTs
2517@item
2518MV88W8xx8 Ethernet controller
2519@item
2520MV88W8618 audio controller, WM8750 CODEC and mixer
2521@item
Stefan Weile080e782010-02-05 23:52:00 +01002522128×64 display with brightness control
balrog57cd6e92008-05-07 12:23:32 +00002523@item
25242 buttons, 2 navigation wheels with button function
2525@end itemize
2526
balrog997641a2008-12-15 02:05:00 +00002527The Siemens SX1 models v1 and v2 (default) basic emulation.
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002528The emulation includes the following elements:
balrog997641a2008-12-15 02:05:00 +00002529
2530@itemize @minus
2531@item
2532Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2533@item
2534ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2535V1
25361 Flash of 16MB and 1 Flash of 8MB
2537V2
25381 Flash of 32MB
2539@item
2540On-chip LCD controller
2541@item
2542On-chip Real Time Clock
2543@item
2544Secure Digital card connected to OMAP MMC/SD host
2545@item
2546Three on-chip UARTs
2547@end itemize
2548
bellard3f9f3aa2005-12-18 20:11:37 +00002549A Linux 2.6 test image is available on the QEMU web site. More
2550information is available in the QEMU mailing-list archive.
2551
blueswir1d2c639d2009-01-24 18:19:25 +00002552@c man begin OPTIONS
2553
2554The following options are specific to the ARM emulation:
2555
2556@table @option
2557
2558@item -semihosting
2559Enable semihosting syscall emulation.
2560
2561On ARM this implements the "Angel" interface.
2562
2563Note that this allows guest direct access to the host filesystem,
2564so should only be used with trusted guest OS.
2565
2566@end table
2567
ths24d4de42007-07-11 10:24:28 +00002568@node ColdFire System emulator
2569@section ColdFire System emulator
Stefan Weil7544a042010-02-05 23:52:03 +01002570@cindex system emulation (ColdFire)
2571@cindex system emulation (M68K)
pbrook209a4e62007-05-23 20:16:15 +00002572
2573Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2574The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002575
2576The M5208EVB emulation includes the following devices:
2577
2578@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002579@item
pbrook707e0112007-06-04 00:50:06 +00002580MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2581@item
2582Three Two on-chip UARTs.
2583@item
2584Fast Ethernet Controller (FEC)
2585@end itemize
2586
2587The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002588
2589@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002590@item
pbrook209a4e62007-05-23 20:16:15 +00002591MCF5206 ColdFire V2 Microprocessor.
2592@item
2593Two on-chip UARTs.
2594@end itemize
2595
blueswir1d2c639d2009-01-24 18:19:25 +00002596@c man begin OPTIONS
2597
Stefan Weil7544a042010-02-05 23:52:03 +01002598The following options are specific to the ColdFire emulation:
blueswir1d2c639d2009-01-24 18:19:25 +00002599
2600@table @option
2601
2602@item -semihosting
2603Enable semihosting syscall emulation.
2604
2605On M68K this implements the "ColdFire GDB" interface used by libgloss.
2606
2607Note that this allows guest direct access to the host filesystem,
2608so should only be used with trusted guest OS.
2609
2610@end table
2611
Stefan Weil7544a042010-02-05 23:52:03 +01002612@node Cris System emulator
2613@section Cris System emulator
2614@cindex system emulation (Cris)
2615
2616TODO
2617
2618@node Microblaze System emulator
2619@section Microblaze System emulator
2620@cindex system emulation (Microblaze)
2621
2622TODO
2623
2624@node SH4 System emulator
2625@section SH4 System emulator
2626@cindex system emulation (SH4)
2627
2628TODO
2629
Max Filippov3aeaea62011-10-10 14:48:23 +04002630@node Xtensa System emulator
2631@section Xtensa System emulator
2632@cindex system emulation (Xtensa)
2633
2634Two executables cover simulation of both Xtensa endian options,
2635@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2636Two different machine types are emulated:
2637
2638@itemize @minus
2639@item
2640Xtensa emulator pseudo board "sim"
2641@item
2642Avnet LX60/LX110/LX200 board
2643@end itemize
2644
Stefan Weilb5e49462011-11-13 22:24:26 +01002645The sim pseudo board emulation provides an environment similar
Max Filippov3aeaea62011-10-10 14:48:23 +04002646to one provided by the proprietary Tensilica ISS.
2647It supports:
2648
2649@itemize @minus
2650@item
2651A range of Xtensa CPUs, default is the DC232B
2652@item
2653Console and filesystem access via semihosting calls
2654@end itemize
2655
2656The Avnet LX60/LX110/LX200 emulation supports:
2657
2658@itemize @minus
2659@item
2660A range of Xtensa CPUs, default is the DC232B
2661@item
266216550 UART
2663@item
2664OpenCores 10/100 Mbps Ethernet MAC
2665@end itemize
2666
2667@c man begin OPTIONS
2668
2669The following options are specific to the Xtensa emulation:
2670
2671@table @option
2672
2673@item -semihosting
2674Enable semihosting syscall emulation.
2675
2676Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2677Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2678
2679Note that this allows guest direct access to the host filesystem,
2680so should only be used with trusted guest OS.
2681
2682@end table
Thomas Huth3f2ce722017-05-22 22:53:29 +02002683
2684@node QEMU Guest Agent
2685@chapter QEMU Guest Agent invocation
2686
2687@include qemu-ga.texi
2688
ths5fafdf22007-09-16 21:08:06 +00002689@node QEMU User space emulator
2690@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002691
2692@menu
2693* Supported Operating Systems ::
Paolo Bonzini0722cc42016-10-06 15:22:05 +02002694* Features::
bellard83195232007-02-05 19:42:07 +00002695* Linux User space emulator::
blueswir184778502008-10-26 20:33:16 +00002696* BSD User space emulator ::
bellard83195232007-02-05 19:42:07 +00002697@end menu
2698
2699@node Supported Operating Systems
2700@section Supported Operating Systems
2701
2702The following OS are supported in user space emulation:
2703
2704@itemize @minus
2705@item
ths4be456f2007-06-03 13:41:28 +00002706Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002707@item
blueswir184778502008-10-26 20:33:16 +00002708BSD (referred as qemu-bsd-user)
bellard83195232007-02-05 19:42:07 +00002709@end itemize
2710
Paolo Bonzini0722cc42016-10-06 15:22:05 +02002711@node Features
2712@section Features
2713
2714QEMU user space emulation has the following notable features:
2715
2716@table @strong
2717@item System call translation:
2718QEMU includes a generic system call translator. This means that
2719the parameters of the system calls can be converted to fix
2720endianness and 32/64-bit mismatches between hosts and targets.
2721IOCTLs can be converted too.
2722
2723@item POSIX signal handling:
2724QEMU can redirect to the running program all signals coming from
2725the host (such as @code{SIGALRM}), as well as synthesize signals from
2726virtual CPU exceptions (for example @code{SIGFPE} when the program
2727executes a division by zero).
2728
2729QEMU relies on the host kernel to emulate most signal system
2730calls, for example to emulate the signal mask. On Linux, QEMU
2731supports both normal and real-time signals.
2732
2733@item Threading:
2734On Linux, QEMU can emulate the @code{clone} syscall and create a real
2735host thread (with a separate virtual CPU) for each emulated thread.
2736Note that not all targets currently emulate atomic operations correctly.
2737x86 and ARM use a global lock in order to preserve their semantics.
2738@end table
2739
2740QEMU was conceived so that ultimately it can emulate itself. Although
2741it is not very useful, it is an important test to show the power of the
2742emulator.
2743
bellard83195232007-02-05 19:42:07 +00002744@node Linux User space emulator
2745@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002746
bellarddebc7062006-04-30 21:58:41 +00002747@menu
2748* Quick Start::
2749* Wine launch::
2750* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002751* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002752@end menu
2753
2754@node Quick Start
bellard83195232007-02-05 19:42:07 +00002755@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002756
bellard1f673132004-04-04 15:21:17 +00002757In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002758itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002759
bellard1f673132004-04-04 15:21:17 +00002760@itemize
bellard386405f2003-03-23 21:28:45 +00002761
bellard1f673132004-04-04 15:21:17 +00002762@item On x86, you can just try to launch any process by using the native
2763libraries:
bellard386405f2003-03-23 21:28:45 +00002764
ths5fafdf22007-09-16 21:08:06 +00002765@example
bellard1f673132004-04-04 15:21:17 +00002766qemu-i386 -L / /bin/ls
2767@end example
bellardfd429f22003-03-30 20:59:46 +00002768
bellard1f673132004-04-04 15:21:17 +00002769@code{-L /} tells that the x86 dynamic linker must be searched with a
2770@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002771
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002772@item Since QEMU is also a linux process, you can launch QEMU with
2773QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002774
ths5fafdf22007-09-16 21:08:06 +00002775@example
bellard1f673132004-04-04 15:21:17 +00002776qemu-i386 -L / qemu-i386 -L / /bin/ls
2777@end example
bellard386405f2003-03-23 21:28:45 +00002778
bellard1f673132004-04-04 15:21:17 +00002779@item On non x86 CPUs, you need first to download at least an x86 glibc
2780(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2781@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002782
bellard1f673132004-04-04 15:21:17 +00002783@example
ths5fafdf22007-09-16 21:08:06 +00002784unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002785@end example
bellard386405f2003-03-23 21:28:45 +00002786
bellard1f673132004-04-04 15:21:17 +00002787Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002788
bellard1f673132004-04-04 15:21:17 +00002789@example
2790qemu-i386 tests/i386/ls
2791@end example
Blue Swirl4c3b5a42011-01-20 20:54:21 +00002792You can look at @file{scripts/qemu-binfmt-conf.sh} so that
bellard1f673132004-04-04 15:21:17 +00002793QEMU is automatically launched by the Linux kernel when you try to
2794launch x86 executables. It requires the @code{binfmt_misc} module in the
2795Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002796
bellard1f673132004-04-04 15:21:17 +00002797@item The x86 version of QEMU is also included. You can try weird things such as:
2798@example
bellarddebc7062006-04-30 21:58:41 +00002799qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2800 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002801@end example
bellard386405f2003-03-23 21:28:45 +00002802
bellard1f673132004-04-04 15:21:17 +00002803@end itemize
bellard386405f2003-03-23 21:28:45 +00002804
bellarddebc7062006-04-30 21:58:41 +00002805@node Wine launch
bellard83195232007-02-05 19:42:07 +00002806@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002807
bellard1f673132004-04-04 15:21:17 +00002808@itemize
bellard386405f2003-03-23 21:28:45 +00002809
bellard1f673132004-04-04 15:21:17 +00002810@item Ensure that you have a working QEMU with the x86 glibc
2811distribution (see previous section). In order to verify it, you must be
2812able to do:
bellard386405f2003-03-23 21:28:45 +00002813
bellard1f673132004-04-04 15:21:17 +00002814@example
2815qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2816@end example
bellard386405f2003-03-23 21:28:45 +00002817
bellard1f673132004-04-04 15:21:17 +00002818@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002819(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002820
bellard1f673132004-04-04 15:21:17 +00002821@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002822@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002823@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002824
bellard1f673132004-04-04 15:21:17 +00002825@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002826
bellard1f673132004-04-04 15:21:17 +00002827@example
bellarddebc7062006-04-30 21:58:41 +00002828qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2829 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002830@end example
bellard386405f2003-03-23 21:28:45 +00002831
bellard1f673132004-04-04 15:21:17 +00002832@end itemize
bellard386405f2003-03-23 21:28:45 +00002833
bellarddebc7062006-04-30 21:58:41 +00002834@node Command line options
bellard83195232007-02-05 19:42:07 +00002835@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002836
bellard1f673132004-04-04 15:21:17 +00002837@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00002838@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 +00002839@end example
bellard386405f2003-03-23 21:28:45 +00002840
bellard1f673132004-04-04 15:21:17 +00002841@table @option
2842@item -h
2843Print the help
ths3b46e622007-09-17 08:09:54 +00002844@item -L path
bellard1f673132004-04-04 15:21:17 +00002845Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2846@item -s size
2847Set the x86 stack size in bytes (default=524288)
blueswir134a3d232008-10-04 20:43:39 +00002848@item -cpu model
Peter Maydellc8057f92012-08-02 13:45:54 +01002849Select CPU model (-cpu help for list and additional feature selection)
Stefan Weilf66724c2010-07-15 22:28:02 +02002850@item -E @var{var}=@var{value}
2851Set environment @var{var} to @var{value}.
2852@item -U @var{var}
2853Remove @var{var} from the environment.
Paul Brook379f6692009-07-17 12:48:08 +01002854@item -B offset
2855Offset guest address by the specified number of bytes. This is useful when
Stefan Weil1f5c3f82010-07-11 18:34:28 +02002856the address region required by guest applications is reserved on the host.
2857This option is currently only supported on some hosts.
Paul Brook68a1c812010-05-29 02:27:35 +01002858@item -R size
2859Pre-allocate a guest virtual address space of the given size (in bytes).
Stefan Weil0d6753e2011-01-07 18:59:13 +01002860"G", "M", and "k" suffixes may be used when specifying the size.
bellard386405f2003-03-23 21:28:45 +00002861@end table
2862
bellard1f673132004-04-04 15:21:17 +00002863Debug options:
bellard386405f2003-03-23 21:28:45 +00002864
bellard1f673132004-04-04 15:21:17 +00002865@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00002866@item -d item1,...
2867Activate logging of the specified items (use '-d help' for a list of log items)
bellard1f673132004-04-04 15:21:17 +00002868@item -p pagesize
2869Act as if the host page size was 'pagesize' bytes
blueswir134a3d232008-10-04 20:43:39 +00002870@item -g port
2871Wait gdb connection to port
aurel321b530a62009-04-05 20:08:59 +00002872@item -singlestep
2873Run the emulation in single step mode.
bellard1f673132004-04-04 15:21:17 +00002874@end table
bellard386405f2003-03-23 21:28:45 +00002875
balrogb01bcae2007-12-16 13:05:59 +00002876Environment variables:
2877
2878@table @env
2879@item QEMU_STRACE
2880Print system calls and arguments similar to the 'strace' program
2881(NOTE: the actual 'strace' program will not work because the user
2882space emulator hasn't implemented ptrace). At the moment this is
2883incomplete. All system calls that don't have a specific argument
2884format are printed with information for six arguments. Many
2885flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002886@end table
balrogb01bcae2007-12-16 13:05:59 +00002887
pbrook79737e42006-06-11 16:28:41 +00002888@node Other binaries
bellard83195232007-02-05 19:42:07 +00002889@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002890
Stefan Weil7544a042010-02-05 23:52:03 +01002891@cindex user mode (Alpha)
2892@command{qemu-alpha} TODO.
2893
2894@cindex user mode (ARM)
2895@command{qemu-armeb} TODO.
2896
2897@cindex user mode (ARM)
pbrook79737e42006-06-11 16:28:41 +00002898@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2899binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2900configurations), and arm-uclinux bFLT format binaries.
2901
Stefan Weil7544a042010-02-05 23:52:03 +01002902@cindex user mode (ColdFire)
2903@cindex user mode (M68K)
pbrooke6e59062006-10-22 00:18:54 +00002904@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2905(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2906coldfire uClinux bFLT format binaries.
2907
pbrook79737e42006-06-11 16:28:41 +00002908The binary format is detected automatically.
2909
Stefan Weil7544a042010-02-05 23:52:03 +01002910@cindex user mode (Cris)
2911@command{qemu-cris} TODO.
2912
2913@cindex user mode (i386)
2914@command{qemu-i386} TODO.
2915@command{qemu-x86_64} TODO.
2916
2917@cindex user mode (Microblaze)
2918@command{qemu-microblaze} TODO.
2919
2920@cindex user mode (MIPS)
2921@command{qemu-mips} TODO.
2922@command{qemu-mipsel} TODO.
2923
Marek Vasute6717112017-01-18 23:01:46 +01002924@cindex user mode (NiosII)
2925@command{qemu-nios2} TODO.
2926
Stefan Weil7544a042010-02-05 23:52:03 +01002927@cindex user mode (PowerPC)
2928@command{qemu-ppc64abi32} TODO.
2929@command{qemu-ppc64} TODO.
2930@command{qemu-ppc} TODO.
2931
2932@cindex user mode (SH4)
2933@command{qemu-sh4eb} TODO.
2934@command{qemu-sh4} TODO.
2935
2936@cindex user mode (SPARC)
blueswir134a3d232008-10-04 20:43:39 +00002937@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2938
blueswir1a785e422007-10-20 08:09:05 +00002939@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2940(Sparc64 CPU, 32 bit ABI).
2941
2942@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2943SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2944
blueswir184778502008-10-26 20:33:16 +00002945@node BSD User space emulator
2946@section BSD User space emulator
2947
2948@menu
2949* BSD Status::
2950* BSD Quick Start::
2951* BSD Command line options::
2952@end menu
2953
2954@node BSD Status
2955@subsection BSD Status
2956
2957@itemize @minus
2958@item
2959target Sparc64 on Sparc64: Some trivial programs work.
2960@end itemize
2961
2962@node BSD Quick Start
2963@subsection Quick Start
2964
2965In order to launch a BSD process, QEMU needs the process executable
2966itself and all the target dynamic libraries used by it.
2967
2968@itemize
2969
2970@item On Sparc64, you can just try to launch any process by using the native
2971libraries:
2972
2973@example
2974qemu-sparc64 /bin/ls
2975@end example
2976
2977@end itemize
2978
2979@node BSD Command line options
2980@subsection Command line options
2981
2982@example
Sitsofe Wheeler84851402016-01-13 20:50:26 +00002983@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 +00002984@end example
2985
2986@table @option
2987@item -h
2988Print the help
2989@item -L path
2990Set the library root path (default=/)
2991@item -s size
2992Set the stack size in bytes (default=524288)
Stefan Weilf66724c2010-07-15 22:28:02 +02002993@item -ignore-environment
2994Start with an empty environment. Without this option,
Stefan Weil40c5c6c2011-01-07 18:59:16 +01002995the initial environment is a copy of the caller's environment.
Stefan Weilf66724c2010-07-15 22:28:02 +02002996@item -E @var{var}=@var{value}
2997Set environment @var{var} to @var{value}.
2998@item -U @var{var}
2999Remove @var{var} from the environment.
blueswir184778502008-10-26 20:33:16 +00003000@item -bsd type
3001Set the type of the emulated BSD Operating system. Valid values are
3002FreeBSD, NetBSD and OpenBSD (default).
3003@end table
3004
3005Debug options:
3006
3007@table @option
Peter Maydell989b6972013-02-26 17:52:40 +00003008@item -d item1,...
3009Activate logging of the specified items (use '-d help' for a list of log items)
blueswir184778502008-10-26 20:33:16 +00003010@item -p pagesize
3011Act as if the host page size was 'pagesize' bytes
aurel321b530a62009-04-05 20:08:59 +00003012@item -singlestep
3013Run the emulation in single step mode.
blueswir184778502008-10-26 20:33:16 +00003014@end table
3015
Stefan Weil47eacb42010-02-05 23:52:01 +01003016
Paolo Bonzini78e87792016-10-06 16:12:11 +02003017@include qemu-tech.texi
3018
Stefan Weil7544a042010-02-05 23:52:03 +01003019@node License
3020@appendix License
3021
3022QEMU is a trademark of Fabrice Bellard.
3023
Thomas Huth2f8d8f02017-05-22 22:26:45 +02003024QEMU is released under the
3025@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
3026version 2. Parts of QEMU have specific licenses, see file
3027@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
Stefan Weil7544a042010-02-05 23:52:03 +01003028
bellarddebc7062006-04-30 21:58:41 +00003029@node Index
Stefan Weil7544a042010-02-05 23:52:03 +01003030@appendix Index
3031@menu
3032* Concept Index::
3033* Function Index::
3034* Keystroke Index::
3035* Program Index::
3036* Data Type Index::
3037* Variable Index::
3038@end menu
3039
3040@node Concept Index
3041@section Concept Index
3042This is the main index. Should we combine all keywords in one index? TODO
bellarddebc7062006-04-30 21:58:41 +00003043@printindex cp
3044
Stefan Weil7544a042010-02-05 23:52:03 +01003045@node Function Index
3046@section Function Index
3047This index could be used for command line options and monitor functions.
3048@printindex fn
3049
3050@node Keystroke Index
3051@section Keystroke Index
3052
3053This is a list of all keystrokes which have a special function
3054in system emulation.
3055
3056@printindex ky
3057
3058@node Program Index
3059@section Program Index
3060@printindex pg
3061
3062@node Data Type Index
3063@section Data Type Index
3064
3065This index could be used for qdev device names and options.
3066
3067@printindex tp
3068
3069@node Variable Index
3070@section Variable Index
3071@printindex vr
3072
bellarddebc7062006-04-30 21:58:41 +00003073@bye