blob: ffa957eef1feec5b42f39b4e7c300ed44e2e821f [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
bellard8f40c382006-09-20 20:28:05 +00004@settitle QEMU Emulator User Documentation
bellarddebc7062006-04-30 21:58:41 +00005@exampleindent 0
6@paragraphindent 0
7@c %**end of header
bellard386405f2003-03-23 21:28:45 +00008
bellard0806e3f2003-10-01 00:15:32 +00009@iftex
bellard386405f2003-03-23 21:28:45 +000010@titlepage
11@sp 7
bellard8f40c382006-09-20 20:28:05 +000012@center @titlefont{QEMU Emulator}
bellarddebc7062006-04-30 21:58:41 +000013@sp 1
14@center @titlefont{User Documentation}
bellard386405f2003-03-23 21:28:45 +000015@sp 3
16@end titlepage
bellard0806e3f2003-10-01 00:15:32 +000017@end iftex
bellard386405f2003-03-23 21:28:45 +000018
bellarddebc7062006-04-30 21:58:41 +000019@ifnottex
20@node Top
21@top
22
23@menu
24* Introduction::
25* Installation::
26* QEMU PC System emulator::
27* QEMU System emulator for non PC targets::
bellard83195232007-02-05 19:42:07 +000028* QEMU User space emulator::
bellarddebc7062006-04-30 21:58:41 +000029* compilation:: Compilation from the sources
30* Index::
31@end menu
32@end ifnottex
33
34@contents
35
36@node Introduction
bellard386405f2003-03-23 21:28:45 +000037@chapter Introduction
38
bellarddebc7062006-04-30 21:58:41 +000039@menu
40* intro_features:: Features
41@end menu
42
43@node intro_features
bellard322d0c62003-06-15 23:29:28 +000044@section Features
bellard386405f2003-03-23 21:28:45 +000045
bellard1f673132004-04-04 15:21:17 +000046QEMU is a FAST! processor emulator using dynamic translation to
47achieve good emulation speed.
bellard1eb20522003-06-25 16:21:49 +000048
49QEMU has two operating modes:
bellard0806e3f2003-10-01 00:15:32 +000050
51@itemize @minus
52
ths5fafdf22007-09-16 21:08:06 +000053@item
bellard1f673132004-04-04 15:21:17 +000054Full system emulation. In this mode, QEMU emulates a full system (for
bellard3f9f3aa2005-12-18 20:11:37 +000055example a PC), including one or several processors and various
56peripherals. It can be used to launch different Operating Systems
57without rebooting the PC or to debug system code.
bellard1eb20522003-06-25 16:21:49 +000058
ths5fafdf22007-09-16 21:08:06 +000059@item
bellard83195232007-02-05 19:42:07 +000060User mode emulation. In this mode, QEMU can launch
61processes compiled for one CPU on another CPU. It can be used to
bellard1f673132004-04-04 15:21:17 +000062launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63to ease cross-compilation and cross-debugging.
bellard1eb20522003-06-25 16:21:49 +000064
65@end itemize
66
bellard7c3fc842005-02-10 21:46:47 +000067QEMU can run without an host kernel driver and yet gives acceptable
ths5fafdf22007-09-16 21:08:06 +000068performance.
bellard322d0c62003-06-15 23:29:28 +000069
bellard52c00a52004-04-25 21:27:03 +000070For system emulation, the following hardware targets are supported:
71@itemize
bellard9d0a8e62005-07-03 17:34:05 +000072@item PC (x86 or x86_64 processor)
bellard3f9f3aa2005-12-18 20:11:37 +000073@item ISA PC (old style PC without PCI bus)
bellard52c00a52004-04-25 21:27:03 +000074@item PREP (PowerPC processor)
bellard9d0a8e62005-07-03 17:34:05 +000075@item G3 BW PowerMac (PowerPC processor)
76@item Mac99 PowerMac (PowerPC processor, in progress)
bellard34751872005-07-02 14:31:34 +000077@item Sun4m (32-bit Sparc processor)
78@item Sun4u (64-bit Sparc processor, in progress)
thsd9aedc32007-12-17 03:47:55 +000079@item Malta board (32-bit and 64-bit MIPS processors)
pbrook9ee6e8b2007-11-11 00:04:49 +000080@item ARM Integrator/CP (ARM)
81@item ARM Versatile baseboard (ARM)
82@item ARM RealView Emulation baseboard (ARM)
balrogb00052e2007-04-30 02:22:06 +000083@item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
pbrook9ee6e8b2007-11-11 00:04:49 +000084@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
85@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
pbrook707e0112007-06-04 00:50:06 +000086@item Freescale MCF5208EVB (ColdFire V2).
pbrook209a4e62007-05-23 20:16:15 +000087@item Arnewsh MCF5206 evaluation board (ColdFire V2).
balrog02645922007-11-03 12:50:46 +000088@item Palm Tungsten|E PDA (OMAP310 processor)
bellard52c00a52004-04-25 21:27:03 +000089@end itemize
bellard386405f2003-03-23 21:28:45 +000090
thsd9aedc32007-12-17 03:47:55 +000091For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +000092
bellarddebc7062006-04-30 21:58:41 +000093@node Installation
bellard5b9f4572003-10-28 00:49:54 +000094@chapter Installation
95
bellard15a34c62004-07-08 21:26:26 +000096If you want to compile QEMU yourself, see @ref{compilation}.
97
bellarddebc7062006-04-30 21:58:41 +000098@menu
99* install_linux:: Linux
100* install_windows:: Windows
101* install_mac:: Macintosh
102@end menu
103
104@node install_linux
bellard1f673132004-04-04 15:21:17 +0000105@section Linux
106
bellard7c3fc842005-02-10 21:46:47 +0000107If a precompiled package is available for your distribution - you just
108have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000109
bellarddebc7062006-04-30 21:58:41 +0000110@node install_windows
bellard1f673132004-04-04 15:21:17 +0000111@section Windows
bellard8cd0ac22004-05-12 19:09:16 +0000112
bellard15a34c62004-07-08 21:26:26 +0000113Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000114@url{http://www.free.oszoo.org/@/download.html}.
bellardd691f662003-03-24 21:58:34 +0000115
bellarddebc7062006-04-30 21:58:41 +0000116@node install_mac
bellard1f673132004-04-04 15:21:17 +0000117@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000118
bellard15a34c62004-07-08 21:26:26 +0000119Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000120@url{http://www.free.oszoo.org/@/download.html}.
bellarddf0f11a2003-05-28 00:27:57 +0000121
bellarddebc7062006-04-30 21:58:41 +0000122@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000123@chapter QEMU PC System emulator
bellard1eb20522003-06-25 16:21:49 +0000124
bellarddebc7062006-04-30 21:58:41 +0000125@menu
126* pcsys_introduction:: Introduction
127* pcsys_quickstart:: Quick Start
128* sec_invocation:: Invocation
129* pcsys_keys:: Keys
130* pcsys_monitor:: QEMU Monitor
131* disk_images:: Disk Images
132* pcsys_network:: Network emulation
133* direct_linux_boot:: Direct Linux Boot
134* pcsys_usb:: USB emulation
thsf858dca2007-08-25 01:40:37 +0000135* vnc_security:: VNC security
bellarddebc7062006-04-30 21:58:41 +0000136* gdb_usage:: GDB usage
137* pcsys_os_specific:: Target OS specific information
138@end menu
139
140@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000141@section Introduction
142
143@c man begin DESCRIPTION
144
bellard3f9f3aa2005-12-18 20:11:37 +0000145The QEMU PC System emulator simulates the
146following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000147
148@itemize @minus
ths5fafdf22007-09-16 21:08:06 +0000149@item
bellard15a34c62004-07-08 21:26:26 +0000150i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000151@item
bellard15a34c62004-07-08 21:26:26 +0000152Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
153extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000154@item
155PS/2 mouse and keyboard
ths5fafdf22007-09-16 21:08:06 +0000156@item
bellard15a34c62004-07-08 21:26:26 +00001572 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000158@item
159Floppy disk
ths5fafdf22007-09-16 21:08:06 +0000160@item
blueswir1c4a70602007-05-27 19:41:17 +0000161PCI/ISA PCI network adapters
bellard0806e3f2003-10-01 00:15:32 +0000162@item
bellard05d58182004-08-24 21:12:04 +0000163Serial ports
164@item
bellardc0fe3822005-11-05 18:55:28 +0000165Creative SoundBlaster 16 sound card
166@item
167ENSONIQ AudioPCI ES1370 sound card
168@item
169Adlib(OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000170@item
171PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000172@end itemize
173
bellard3f9f3aa2005-12-18 20:11:37 +0000174SMP is supported with up to 255 CPUs.
175
bellardc0fe3822005-11-05 18:55:28 +0000176Note that adlib is only available when QEMU was configured with
177-enable-adlib
178
bellard15a34c62004-07-08 21:26:26 +0000179QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
180VGA BIOS.
181
bellardc0fe3822005-11-05 18:55:28 +0000182QEMU uses YM3812 emulation by Tatsuyuki Satoh.
183
bellard0806e3f2003-10-01 00:15:32 +0000184@c man end
185
bellarddebc7062006-04-30 21:58:41 +0000186@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000187@section Quick Start
188
bellard285dc332003-10-27 23:58:04 +0000189Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000190
191@example
bellard285dc332003-10-27 23:58:04 +0000192qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000193@end example
194
195Linux should boot and give you a prompt.
196
bellard6cc721c2005-07-28 22:27:28 +0000197@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000198@section Invocation
199
200@example
201@c man begin SYNOPSIS
ths89dfe892007-11-21 22:38:37 +0000202usage: qemu [options] [@var{disk_image}]
bellard1f673132004-04-04 15:21:17 +0000203@c man end
204@end example
205
206@c man begin OPTIONS
207@var{disk_image} is a raw hard disk image for IDE hard disk 0.
208
209General options:
210@table @option
ths89dfe892007-11-21 22:38:37 +0000211@item -M @var{machine}
212Select the emulated @var{machine} (@code{-M ?} for list)
bellard3dbbdc22005-11-06 18:20:37 +0000213
ths89dfe892007-11-21 22:38:37 +0000214@item -fda @var{file}
215@item -fdb @var{file}
bellarddebc7062006-04-30 21:58:41 +0000216Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
bellard19cb3732006-08-19 11:45:59 +0000217use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000218
ths89dfe892007-11-21 22:38:37 +0000219@item -hda @var{file}
220@item -hdb @var{file}
221@item -hdc @var{file}
222@item -hdd @var{file}
bellarddebc7062006-04-30 21:58:41 +0000223Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000224
ths89dfe892007-11-21 22:38:37 +0000225@item -cdrom @var{file}
226Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
bellardbe3edd92004-06-03 12:48:45 +0000227@option{-cdrom} at the same time). You can use the host CD-ROM by
bellard19cb3732006-08-19 11:45:59 +0000228using @file{/dev/cdrom} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000229
balroge0e7ada2007-12-11 21:56:43 +0000230@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
231
232Define a new drive. Valid options are:
233
234@table @code
235@item file=@var{file}
236This option defines which disk image (@pxref{disk_images}) to use with
237this drive.
238@item if=@var{interface}
239This option defines on which type on interface the drive is connected.
240Available types are: ide, scsi, sd, mtd, floppy, pflash.
241@item bus=@var{bus},unit=@var{unit}
242These options define where is connected the drive by defining the bus number and
243the unit id.
244@item index=@var{index}
245This option defines where is connected the drive by using an index in the list
246of available connectors of a given interface type.
247@item media=@var{media}
248This option defines the type of the media: disk or cdrom.
249@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
250These options have the same definition as they have in @option{-hdachs}.
251@item snapshot=@var{snapshot}
252@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
253@end table
254
255Instead of @option{-cdrom} you can use:
256@example
257qemu -drive file=file,index=2,media=cdrom
258@end example
259
260Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
261use:
262@example
263qemu -drive file=file,index=0,media=disk
264qemu -drive file=file,index=1,media=disk
265qemu -drive file=file,index=2,media=disk
266qemu -drive file=file,index=3,media=disk
267@end example
268
269You can connect a CDROM to the slave of ide0:
270@example
271qemu -drive file=file,if=ide,index=1,media=cdrom
272@end example
273
274If you don't specify the "file=" argument, you define an empty drive:
275@example
276qemu -drive if=ide,index=1,media=cdrom
277@end example
278
279You can connect a SCSI disk with unit ID 6 on the bus #0:
280@example
281qemu -drive file=file,if=scsi,bus=0,unit=6
282@end example
283
284Instead of @option{-fda}, @option{-fdb}, you can use:
285@example
286qemu -drive file=file,index=0,if=floppy
287qemu -drive file=file,index=1,if=floppy
288@end example
289
290By default, @var{interface} is "ide" and @var{index} is automatically
291incremented:
292@example
293qemu -drive file=a -drive file=b"
294@end example
295is interpreted like:
296@example
297qemu -hda a -hdb b
298@end example
299
thseec85c22007-01-05 17:41:07 +0000300@item -boot [a|c|d|n]
301Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
302is the default.
bellard1f673132004-04-04 15:21:17 +0000303
304@item -snapshot
305Write to temporary files instead of disk image files. In this case,
306the raw disk image you use is not written back. You can however force
ths42550fd2006-12-22 16:34:12 +0000307the write back by pressing @key{C-a s} (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000308
bellard52ca8d62006-06-14 16:03:05 +0000309@item -no-fd-bootchk
310Disable boot signature checking for floppy disks in Bochs BIOS. It may
311be needed to boot from old floppy disks.
312
ths89dfe892007-11-21 22:38:37 +0000313@item -m @var{megs}
314Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.
bellard1f673132004-04-04 15:21:17 +0000315
ths89dfe892007-11-21 22:38:37 +0000316@item -smp @var{n}
bellard3f9f3aa2005-12-18 20:11:37 +0000317Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
blueswir1a785e422007-10-20 08:09:05 +0000318CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
319to 4.
bellard3f9f3aa2005-12-18 20:11:37 +0000320
bellard1d14ffa2005-10-30 18:58:22 +0000321@item -audio-help
322
323Will show the audio subsystem help: list of drivers, tunable
324parameters.
325
ths89dfe892007-11-21 22:38:37 +0000326@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
bellard1d14ffa2005-10-30 18:58:22 +0000327
328Enable audio and selected sound hardware. Use ? to print all
329available sound hardware.
330
331@example
332qemu -soundhw sb16,adlib hda
333qemu -soundhw es1370 hda
bellard6a36d842005-12-18 20:34:32 +0000334qemu -soundhw all hda
bellard1d14ffa2005-10-30 18:58:22 +0000335qemu -soundhw ?
336@end example
bellarda8c490c2004-04-26 20:59:17 +0000337
bellard15a34c62004-07-08 21:26:26 +0000338@item -localtime
339Set the real time clock to local time (the default is to UTC
340time). This option is needed to have correct date in MS-DOS or
341Windows.
342
ths89dfe892007-11-21 22:38:37 +0000343@item -startdate @var{date}
bellard7e0af5d02007-11-07 16:24:33 +0000344Set the initial date of the real time clock. Valid format for
345@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
346@code{2006-06-17}. The default value is @code{now}.
347
ths89dfe892007-11-21 22:38:37 +0000348@item -pidfile @var{file}
bellardf7cce892004-12-08 22:21:25 +0000349Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
350from a script.
351
ths71e3ceb2006-12-22 02:11:31 +0000352@item -daemonize
353Daemonize the QEMU process after initialization. QEMU will not detach from
354standard IO until it is ready to receive connections on any of its devices.
355This option is a useful way for external programs to launch QEMU without having
356to cope with initialization race conditions.
357
bellard9d0a8e62005-07-03 17:34:05 +0000358@item -win2k-hack
359Use it when installing Windows 2000 to avoid a disk full bug. After
360Windows 2000 is installed, you no longer need this option (this option
361slows down the IDE transfers).
362
ths89dfe892007-11-21 22:38:37 +0000363@item -option-rom @var{file}
364Load the contents of @var{file} as an option ROM.
365This option is useful to load things like EtherBoot.
ths9ae02552007-01-05 17:39:04 +0000366
ths89dfe892007-11-21 22:38:37 +0000367@item -name @var{name}
368Sets the @var{name} of the guest.
369This name will be display in the SDL window caption.
370The @var{name} will also be used for the VNC server.
thsc35734b2007-03-19 15:17:08 +0000371
bellard1f673132004-04-04 15:21:17 +0000372@end table
373
thsf858dca2007-08-25 01:40:37 +0000374Display options:
375@table @option
376
377@item -nographic
378
379Normally, QEMU uses SDL to display the VGA output. With this option,
380you can totally disable graphical output so that QEMU is a simple
381command line application. The emulated serial port is redirected on
382the console. Therefore, you can still use QEMU to debug a Linux kernel
383with a serial console.
384
385@item -no-frame
386
387Do not use decorations for SDL windows and start them using the whole
388available screen space. This makes the using QEMU in a dedicated desktop
389workspace more convenient.
390
391@item -full-screen
392Start in full screen.
393
ths89dfe892007-11-21 22:38:37 +0000394@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
thsf858dca2007-08-25 01:40:37 +0000395
396Normally, QEMU uses SDL to display the VGA output. With this option,
397you can have QEMU listen on VNC display @var{display} and redirect the VGA
398display over the VNC session. It is very useful to enable the usb
399tablet device when using this option (option @option{-usbdevice
400tablet}). When using the VNC display, you must use the @option{-k}
401parameter to set the keyboard layout if you are not using en-us. Valid
402syntax for the @var{display} is
403
404@table @code
405
ths89dfe892007-11-21 22:38:37 +0000406@item @var{interface}:@var{d}
thsf858dca2007-08-25 01:40:37 +0000407
408TCP connections will only be allowed from @var{interface} on display @var{d}.
409By convention the TCP port is 5900+@var{d}. Optionally, @var{interface} can
410be omitted in which case the server will bind to all interfaces.
411
ths89dfe892007-11-21 22:38:37 +0000412@item @var{unix}:@var{path}
thsf858dca2007-08-25 01:40:37 +0000413
414Connections will be allowed over UNIX domain sockets where @var{path} is the
415location of a unix socket to listen for connections on.
416
ths89dfe892007-11-21 22:38:37 +0000417@item none
thsf858dca2007-08-25 01:40:37 +0000418
419VNC is initialized by not started. The monitor @code{change} command can be used
420to later start the VNC server.
421
422@end table
423
424Following the @var{display} value there may be one or more @var{option} flags
425separated by commas. Valid options are
426
427@table @code
428
ths89dfe892007-11-21 22:38:37 +0000429@item password
thsf858dca2007-08-25 01:40:37 +0000430
431Require that password based authentication is used for client connections.
432The password must be set separately using the @code{change} command in the
433@ref{pcsys_monitor}
434
ths89dfe892007-11-21 22:38:37 +0000435@item tls
thsf858dca2007-08-25 01:40:37 +0000436
437Require that client use TLS when communicating with the VNC server. This
438uses anonymous TLS credentials so is susceptible to a man-in-the-middle
439attack. It is recommended that this option be combined with either the
440@var{x509} or @var{x509verify} options.
441
ths89dfe892007-11-21 22:38:37 +0000442@item x509=@var{/path/to/certificate/dir}
thsf858dca2007-08-25 01:40:37 +0000443
ths89dfe892007-11-21 22:38:37 +0000444Valid if @option{tls} is specified. Require that x509 credentials are used
thsf858dca2007-08-25 01:40:37 +0000445for negotiating the TLS session. The server will send its x509 certificate
446to the client. It is recommended that a password be set on the VNC server
447to provide authentication of the client when this is used. The path following
448this option specifies where the x509 certificates are to be loaded from.
449See the @ref{vnc_security} section for details on generating certificates.
450
ths89dfe892007-11-21 22:38:37 +0000451@item x509verify=@var{/path/to/certificate/dir}
thsf858dca2007-08-25 01:40:37 +0000452
ths89dfe892007-11-21 22:38:37 +0000453Valid if @option{tls} is specified. Require that x509 credentials are used
thsf858dca2007-08-25 01:40:37 +0000454for negotiating the TLS session. The server will send its x509 certificate
455to the client, and request that the client send its own x509 certificate.
456The server will validate the client's certificate against the CA certificate,
457and reject clients when validation fails. If the certificate authority is
458trusted, this is a sufficient authentication mechanism. You may still wish
459to set a password on the VNC server as a second authentication layer. The
460path following this option specifies where the x509 certificates are to
461be loaded from. See the @ref{vnc_security} section for details on generating
462certificates.
463
464@end table
465
ths89dfe892007-11-21 22:38:37 +0000466@item -k @var{language}
thsf858dca2007-08-25 01:40:37 +0000467
468Use keyboard layout @var{language} (for example @code{fr} for
469French). This option is only needed where it is not easy to get raw PC
470keycodes (e.g. on Macs, with some X11 servers or with a VNC
471display). You don't normally need to use it on PC/Linux or PC/Windows
472hosts.
473
474The available layouts are:
475@example
476ar de-ch es fo fr-ca hu ja mk no pt-br sv
477da en-gb et fr fr-ch is lt nl pl ru th
478de en-us fi fr-be hr it lv nl-be pt sl tr
479@end example
480
481The default is @code{en-us}.
482
483@end table
484
bellardb389dbf2005-11-06 16:49:55 +0000485USB options:
486@table @option
487
488@item -usb
489Enable the USB driver (will be the default soon)
490
ths89dfe892007-11-21 22:38:37 +0000491@item -usbdevice @var{devname}
pbrook0aff66b2006-05-26 00:49:52 +0000492Add the USB device @var{devname}. @xref{usb_devices}.
bellardb389dbf2005-11-06 16:49:55 +0000493@end table
494
bellard1f673132004-04-04 15:21:17 +0000495Network options:
496
497@table @option
498
ths89dfe892007-11-21 22:38:37 +0000499@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
bellard41d03942005-11-15 23:02:53 +0000500Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
blueswir1c4a70602007-05-27 19:41:17 +0000501= 0 is the default). The NIC is an ne2k_pci by default on the PC
bellard41d03942005-11-15 23:02:53 +0000502target. Optionally, the MAC address can be changed. If no
503@option{-net} option is specified, a single NIC is created.
balrog549444e2007-05-01 17:53:37 +0000504Qemu can emulate several different models of network card.
505Valid values for @var{type} are
506@code{i82551}, @code{i82557b}, @code{i82559er},
507@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
pbrook7e049b82007-06-04 00:31:01 +0000508@code{smc91c111}, @code{lance} and @code{mcf_fec}.
blueswir1c4a70602007-05-27 19:41:17 +0000509Not all devices are supported on all targets. Use -net nic,model=?
510for a list of available devices for your target.
bellard1f673132004-04-04 15:21:17 +0000511
ths89dfe892007-11-21 22:38:37 +0000512@item -net user[,vlan=@var{n}][,hostname=@var{name}]
bellard7e894632005-11-19 17:42:52 +0000513Use the user mode network stack which requires no administrator
ths4be456f2007-06-03 13:41:28 +0000514privilege to run. @option{hostname=name} can be used to specify the client
pbrook115defd2006-04-16 11:06:58 +0000515hostname reported by the builtin DHCP server.
bellard3f1a88f2005-06-05 16:48:41 +0000516
ths89dfe892007-11-21 22:38:37 +0000517@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}]
bellard41d03942005-11-15 23:02:53 +0000518Connect the host TAP network interface @var{name} to VLAN @var{n} and
519use the network script @var{file} to configure it. The default
ths6a1cbf62007-02-02 00:37:56 +0000520network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
521disable script execution. If @var{name} is not
ths89dfe892007-11-21 22:38:37 +0000522provided, the OS automatically provides one. @option{fd}=@var{h} can be
bellard41d03942005-11-15 23:02:53 +0000523used to specify the handle of an already opened host TAP interface. Example:
bellard3f1a88f2005-06-05 16:48:41 +0000524
bellard41d03942005-11-15 23:02:53 +0000525@example
526qemu linux.img -net nic -net tap
527@end example
bellard1f673132004-04-04 15:21:17 +0000528
bellard41d03942005-11-15 23:02:53 +0000529More complicated example (two NICs, each one connected to a TAP device)
530@example
531qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
532 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
533@end example
bellard1f673132004-04-04 15:21:17 +0000534
bellard52c00a52004-04-25 21:27:03 +0000535
ths89dfe892007-11-21 22:38:37 +0000536@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
bellard41d03942005-11-15 23:02:53 +0000537
538Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
539machine using a TCP socket connection. If @option{listen} is
540specified, QEMU waits for incoming connections on @var{port}
541(@var{host} is optional). @option{connect} is used to connect to
ths89dfe892007-11-21 22:38:37 +0000542another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
bellard3d830452005-12-18 16:36:49 +0000543specifies an already opened TCP socket.
bellard41d03942005-11-15 23:02:53 +0000544
545Example:
546@example
547# launch a first QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000548qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
549 -net socket,listen=:1234
550# connect the VLAN 0 of this instance to the VLAN 0
551# of the first instance
552qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
553 -net socket,connect=127.0.0.1:1234
bellard41d03942005-11-15 23:02:53 +0000554@end example
555
ths89dfe892007-11-21 22:38:37 +0000556@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
bellard3d830452005-12-18 16:36:49 +0000557
558Create a VLAN @var{n} shared with another QEMU virtual
ths5fafdf22007-09-16 21:08:06 +0000559machines using a UDP multicast socket, effectively making a bus for
bellard3d830452005-12-18 16:36:49 +0000560every QEMU with same multicast address @var{maddr} and @var{port}.
561NOTES:
562@enumerate
ths5fafdf22007-09-16 21:08:06 +0000563@item
564Several QEMU can be running on different hosts and share same bus (assuming
bellard3d830452005-12-18 16:36:49 +0000565correct multicast setup for these hosts).
566@item
567mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
568@url{http://user-mode-linux.sf.net}.
ths4be456f2007-06-03 13:41:28 +0000569@item
570Use @option{fd=h} to specify an already opened UDP multicast socket.
bellard3d830452005-12-18 16:36:49 +0000571@end enumerate
572
573Example:
574@example
575# launch one QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000576qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
577 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000578# launch another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000579qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
580 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000581# launch yet another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000582qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
583 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000584@end example
585
586Example (User Mode Linux compat.):
587@example
bellarddebc7062006-04-30 21:58:41 +0000588# launch QEMU instance (note mcast address selected
589# is UML's default)
590qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
591 -net socket,mcast=239.192.168.1:1102
bellard3d830452005-12-18 16:36:49 +0000592# launch UML
593/path/to/linux ubd0=/path/to/root_fs eth0=mcast
594@end example
595
bellard41d03942005-11-15 23:02:53 +0000596@item -net none
597Indicate that no network devices should be configured. It is used to
bellard039af322006-02-01 21:30:55 +0000598override the default configuration (@option{-net nic -net user}) which
599is activated if no @option{-net} options are provided.
bellard52c00a52004-04-25 21:27:03 +0000600
ths89dfe892007-11-21 22:38:37 +0000601@item -tftp @var{dir}
bellard9bf05442004-08-25 22:12:49 +0000602When using the user mode network stack, activate a built-in TFTP
ths0db11372007-02-20 00:12:07 +0000603server. The files in @var{dir} will be exposed as the root of a TFTP server.
604The TFTP client on the guest must be configured in binary mode (use the command
605@code{bin} of the Unix TFTP client). The host IP address on the guest is as
606usual 10.0.2.2.
bellard9bf05442004-08-25 22:12:49 +0000607
ths89dfe892007-11-21 22:38:37 +0000608@item -bootp @var{file}
ths47d5d012007-02-20 00:05:08 +0000609When using the user mode network stack, broadcast @var{file} as the BOOTP
610filename. In conjunction with @option{-tftp}, this can be used to network boot
611a guest from a local directory.
612
613Example (using pxelinux):
614@example
615qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
616@end example
617
ths89dfe892007-11-21 22:38:37 +0000618@item -smb @var{dir}
bellard2518bd02004-09-30 22:35:13 +0000619When using the user mode network stack, activate a built-in SMB
ths89dfe892007-11-21 22:38:37 +0000620server so that Windows OSes can access to the host files in @file{@var{dir}}
bellard2518bd02004-09-30 22:35:13 +0000621transparently.
622
623In the guest Windows OS, the line:
624@example
62510.0.2.4 smbserver
626@end example
627must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
628or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
629
ths89dfe892007-11-21 22:38:37 +0000630Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
bellard2518bd02004-09-30 22:35:13 +0000631
632Note that a SAMBA server must be installed on the host OS in
ths366dfc52006-12-11 18:35:08 +0000633@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
bellard6cc721c2005-07-28 22:27:28 +00006342.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
bellard2518bd02004-09-30 22:35:13 +0000635
ths89dfe892007-11-21 22:38:37 +0000636@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
bellard9bf05442004-08-25 22:12:49 +0000637
638When using the user mode network stack, redirect incoming TCP or UDP
639connections to the host port @var{host-port} to the guest
640@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
641is not specified, its value is 10.0.2.15 (default address given by the
642built-in DHCP server).
643
644For example, to redirect host X11 connection from screen 1 to guest
645screen 0, use the following:
646
647@example
648# on the host
649qemu -redir tcp:6001::6000 [...]
650# this host xterm should open in the guest X11 server
651xterm -display :1
652@end example
653
654To redirect telnet connections from host port 5555 to telnet port on
655the guest, use the following:
656
657@example
658# on the host
659qemu -redir tcp:5555::23 [...]
660telnet localhost 5555
661@end example
662
663Then when you use on the host @code{telnet localhost 5555}, you
664connect to the guest telnet server.
665
bellard1f673132004-04-04 15:21:17 +0000666@end table
667
bellard41d03942005-11-15 23:02:53 +0000668Linux boot specific: When using these options, you can use a given
bellard1f673132004-04-04 15:21:17 +0000669Linux kernel without installing it in the disk image. It can be useful
670for easier testing of various kernels.
671
672@table @option
673
ths89dfe892007-11-21 22:38:37 +0000674@item -kernel @var{bzImage}
bellard1f673132004-04-04 15:21:17 +0000675Use @var{bzImage} as kernel image.
676
ths89dfe892007-11-21 22:38:37 +0000677@item -append @var{cmdline}
bellard1f673132004-04-04 15:21:17 +0000678Use @var{cmdline} as kernel command line
679
ths89dfe892007-11-21 22:38:37 +0000680@item -initrd @var{file}
bellard1f673132004-04-04 15:21:17 +0000681Use @var{file} as initial ram disk.
682
683@end table
684
bellard15a34c62004-07-08 21:26:26 +0000685Debug/Expert options:
bellard1f673132004-04-04 15:21:17 +0000686@table @option
bellarda0a821a2004-07-14 17:38:57 +0000687
ths89dfe892007-11-21 22:38:37 +0000688@item -serial @var{dev}
bellard0bab00f2006-06-25 14:49:44 +0000689Redirect the virtual serial port to host character device
690@var{dev}. The default device is @code{vc} in graphical mode and
691@code{stdio} in non graphical mode.
692
693This option can be used several times to simulate up to 4 serials
694ports.
695
bellardc03b0f02006-09-03 14:10:53 +0000696Use @code{-serial none} to disable all serial ports.
697
bellard0bab00f2006-06-25 14:49:44 +0000698Available character devices are:
bellarda0a821a2004-07-14 17:38:57 +0000699@table @code
thsaf3a9032007-07-11 23:14:59 +0000700@item vc[:WxH]
701Virtual console. Optionally, a width and height can be given in pixel with
702@example
703vc:800x600
704@end example
705It is also possible to specify width or height in characters:
706@example
707vc:80Cx24C
708@end example
bellarda0a821a2004-07-14 17:38:57 +0000709@item pty
710[Linux only] Pseudo TTY (a new PTY is automatically allocated)
bellardc03b0f02006-09-03 14:10:53 +0000711@item none
712No device is allocated.
bellarda0a821a2004-07-14 17:38:57 +0000713@item null
714void device
bellardf8d179e2005-11-08 22:30:36 +0000715@item /dev/XXX
bellarde57a8c02005-11-10 23:58:52 +0000716[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
bellardf8d179e2005-11-08 22:30:36 +0000717parameters are set according to the emulated ones.
ths89dfe892007-11-21 22:38:37 +0000718@item /dev/parport@var{N}
bellarde57a8c02005-11-10 23:58:52 +0000719[Linux only, parallel port only] Use host parallel port
ths5867c882007-02-17 23:44:43 +0000720@var{N}. Currently SPP and EPP parallel port features can be used.
ths89dfe892007-11-21 22:38:37 +0000721@item file:@var{filename}
722Write output to @var{filename}. No character can be read.
bellarda0a821a2004-07-14 17:38:57 +0000723@item stdio
724[Unix only] standard input/output
ths89dfe892007-11-21 22:38:37 +0000725@item pipe:@var{filename}
bellard0bab00f2006-06-25 14:49:44 +0000726name pipe @var{filename}
ths89dfe892007-11-21 22:38:37 +0000727@item COM@var{n}
bellard0bab00f2006-06-25 14:49:44 +0000728[Windows only] Use host serial port @var{n}
ths89dfe892007-11-21 22:38:37 +0000729@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
730This implements UDP Net Console.
731When @var{remote_host} or @var{src_ip} are not specified
732they default to @code{0.0.0.0}.
733When not using a specified @var{src_port} a random port is automatically chosen.
bellarda0a821a2004-07-14 17:38:57 +0000734
bellard951f1352006-06-27 21:02:43 +0000735If you just want a simple readonly console you can use @code{netcat} or
736@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
737@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
738will appear in the netconsole session.
bellard0bab00f2006-06-25 14:49:44 +0000739
740If you plan to send characters back via netconsole or you want to stop
741and start qemu a lot of times, you should have qemu use the same
742source port each time by using something like @code{-serial
bellard951f1352006-06-27 21:02:43 +0000743udp::4555@@:4556} to qemu. Another approach is to use a patched
bellard0bab00f2006-06-25 14:49:44 +0000744version of netcat which can listen to a TCP port and send and receive
745characters via udp. If you have a patched version of netcat which
746activates telnet remote echo and single char transfer, then you can
747use the following options to step up a netcat redirector to allow
748telnet on port 5555 to access the qemu port.
749@table @code
bellard951f1352006-06-27 21:02:43 +0000750@item Qemu Options:
751-serial udp::4555@@:4556
752@item netcat options:
753-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
754@item telnet options:
755localhost 5555
bellard0bab00f2006-06-25 14:49:44 +0000756@end table
757
758
ths89dfe892007-11-21 22:38:37 +0000759@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000760The TCP Net Console has two modes of operation. It can send the serial
761I/O to a location or wait for a connection from a location. By default
762the TCP Net Console is sent to @var{host} at the @var{port}. If you use
bellardf5420862006-08-21 20:26:44 +0000763the @var{server} option QEMU will wait for a client socket application
764to connect to the port before continuing, unless the @code{nowait}
pbrookf7499982007-01-28 00:10:01 +0000765option was specified. The @code{nodelay} option disables the Nagle buffering
ths4be456f2007-06-03 13:41:28 +0000766algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
bellard951f1352006-06-27 21:02:43 +0000767one TCP connection at a time is accepted. You can use @code{telnet} to
768connect to the corresponding character device.
769@table @code
770@item Example to send tcp console to 192.168.0.2 port 4444
771-serial tcp:192.168.0.2:4444
772@item Example to listen and wait on port 4444 for connection
773-serial tcp::4444,server
774@item Example to not wait and listen on ip 192.168.0.100 port 4444
775-serial tcp:192.168.0.100:4444,server,nowait
776@end table
777
ths89dfe892007-11-21 22:38:37 +0000778@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000779The telnet protocol is used instead of raw tcp sockets. The options
780work the same as if you had specified @code{-serial tcp}. The
781difference is that the port acts like a telnet server or client using
782telnet option negotiation. This will also allow you to send the
783MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
784sequence. Typically in unix telnet you do it with Control-] and then
785type "send break" followed by pressing the enter key.
786
ths89dfe892007-11-21 22:38:37 +0000787@item unix:@var{path}[,server][,nowait]
thsffd843b2006-12-21 19:46:43 +0000788A unix domain socket is used instead of a tcp socket. The option works the
789same as if you had specified @code{-serial tcp} except the unix domain socket
790@var{path} is used for connections.
791
ths89dfe892007-11-21 22:38:37 +0000792@item mon:@var{dev_string}
ths20d8a3e2007-02-18 17:04:49 +0000793This is a special option to allow the monitor to be multiplexed onto
794another serial port. The monitor is accessed with key sequence of
795@key{Control-a} and then pressing @key{c}. See monitor access
796@ref{pcsys_keys} in the -nographic section for more keys.
797@var{dev_string} should be any one of the serial devices specified
798above. An example to multiplex the monitor onto a telnet server
799listening on port 4444 would be:
800@table @code
801@item -serial mon:telnet::4444,server,nowait
802@end table
803
bellard0bab00f2006-06-25 14:49:44 +0000804@end table
bellard05d58182004-08-24 21:12:04 +0000805
ths89dfe892007-11-21 22:38:37 +0000806@item -parallel @var{dev}
bellarde57a8c02005-11-10 23:58:52 +0000807Redirect the virtual parallel port to host device @var{dev} (same
808devices as the serial port). On Linux hosts, @file{/dev/parportN} can
809be used to use hardware devices connected on the corresponding host
810parallel port.
811
812This option can be used several times to simulate up to 3 parallel
813ports.
814
bellardc03b0f02006-09-03 14:10:53 +0000815Use @code{-parallel none} to disable all parallel ports.
816
ths89dfe892007-11-21 22:38:37 +0000817@item -monitor @var{dev}
bellarda0a821a2004-07-14 17:38:57 +0000818Redirect the monitor to host device @var{dev} (same devices as the
819serial port).
820The default device is @code{vc} in graphical mode and @code{stdio} in
821non graphical mode.
822
ths20d8a3e2007-02-18 17:04:49 +0000823@item -echr numeric_ascii_value
824Change the escape character used for switching to the monitor when using
825monitor and serial sharing. The default is @code{0x01} when using the
826@code{-nographic} option. @code{0x01} is equal to pressing
827@code{Control-a}. You can select a different character from the ascii
828control keys where 1 through 26 map to Control-a through Control-z. For
829instance you could use the either of the following to change the escape
830character to Control-t.
831@table @code
832@item -echr 0x14
833@item -echr 20
834@end table
835
bellard1f673132004-04-04 15:21:17 +0000836@item -s
ths5fafdf22007-09-16 21:08:06 +0000837Wait gdb connection to port 1234 (@pxref{gdb_usage}).
ths89dfe892007-11-21 22:38:37 +0000838@item -p @var{port}
pbrook4046d912007-01-28 01:53:16 +0000839Change gdb connection port. @var{port} can be either a decimal number
840to specify a TCP port, or a host device (same devices as the serial port).
bellard52c00a52004-04-25 21:27:03 +0000841@item -S
842Do not start CPU at startup (you must type 'c' in the monitor).
ths3b46e622007-09-17 08:09:54 +0000843@item -d
bellard1f673132004-04-04 15:21:17 +0000844Output log in /tmp/qemu.log
ths89dfe892007-11-21 22:38:37 +0000845@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
bellard46d47672004-11-16 01:45:27 +0000846Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
847@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
848translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
ths4be456f2007-06-03 13:41:28 +0000849all those parameters. This option is useful for old MS-DOS disk
bellard46d47672004-11-16 01:45:27 +0000850images.
bellard7c3fc842005-02-10 21:46:47 +0000851
bellard87b47352006-08-17 17:22:54 +0000852@item -L path
853Set the directory for the BIOS, VGA BIOS and keymaps.
854
bellard15a34c62004-07-08 21:26:26 +0000855@item -std-vga
856Simulate a standard VGA card with Bochs VBE extensions (default is
bellard3cb08532006-06-21 21:19:50 +0000857Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
858VBE extensions (e.g. Windows XP) and if you want to use high
859resolution modes (>= 1280x1024x16) then you should use this option.
860
bellard3c656342006-07-14 13:13:51 +0000861@item -no-acpi
862Disable ACPI (Advanced Configuration and Power Interface) support. Use
863it if your guest OS complains about ACPI problems (PC target machine
864only).
865
bellardd1beab82006-10-02 19:44:22 +0000866@item -no-reboot
867Exit instead of rebooting.
868
bellardd63d3072004-10-03 13:29:03 +0000869@item -loadvm file
870Start right away with a saved state (@code{loadvm} in monitor)
pbrook8e716212007-01-20 17:12:09 +0000871
872@item -semihosting
pbrooka87295e2007-05-26 15:09:38 +0000873Enable semihosting syscall emulation (ARM and M68K target machines only).
874
875On ARM this implements the "Angel" interface.
876On M68K this implements the "ColdFire GDB" interface used by libgloss.
877
pbrook8e716212007-01-20 17:12:09 +0000878Note that this allows guest direct access to the host filesystem,
879so should only be used with trusted guest OS.
bellard1f673132004-04-04 15:21:17 +0000880@end table
881
bellard3e11db92004-07-14 17:47:14 +0000882@c man end
883
bellarddebc7062006-04-30 21:58:41 +0000884@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000885@section Keys
886
887@c man begin OPTIONS
888
bellarda1b74fe2004-05-08 13:26:35 +0000889During the graphical emulation, you can use the following keys:
890@table @key
bellardf9859312004-10-03 14:33:10 +0000891@item Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000892Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000893
bellardf9859312004-10-03 14:33:10 +0000894@item Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000895Switch to virtual console 'n'. Standard console mappings are:
896@table @emph
897@item 1
898Target system display
899@item 2
900Monitor
901@item 3
902Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000903@end table
904
bellardf9859312004-10-03 14:33:10 +0000905@item Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000906Toggle mouse and keyboard grab.
907@end table
908
bellard3e11db92004-07-14 17:47:14 +0000909In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
910@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
911
bellarda0a821a2004-07-14 17:38:57 +0000912During emulation, if you are using the @option{-nographic} option, use
913@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000914
915@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000916@item Ctrl-a h
bellard1f673132004-04-04 15:21:17 +0000917Print this help
ths3b46e622007-09-17 08:09:54 +0000918@item Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000919Exit emulator
ths3b46e622007-09-17 08:09:54 +0000920@item Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000921Save disk data back to file (if -snapshot)
ths20d8a3e2007-02-18 17:04:49 +0000922@item Ctrl-a t
923toggle console timestamps
bellarda1b74fe2004-05-08 13:26:35 +0000924@item Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000925Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000926@item Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000927Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000928@item Ctrl-a Ctrl-a
929Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000930@end table
931@c man end
932
933@ignore
934
bellard1f673132004-04-04 15:21:17 +0000935@c man begin SEEALSO
936The HTML documentation of QEMU for more precise information and Linux
937user mode emulator invocation.
938@c man end
939
940@c man begin AUTHOR
941Fabrice Bellard
942@c man end
943
944@end ignore
945
bellarddebc7062006-04-30 21:58:41 +0000946@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000947@section QEMU Monitor
948
949The QEMU monitor is used to give complex commands to the QEMU
950emulator. You can use it to:
951
952@itemize @minus
953
954@item
thse5987522007-03-30 18:58:01 +0000955Remove or insert removable media images
ths89dfe892007-11-21 22:38:37 +0000956(such as CD-ROM or floppies).
bellard1f673132004-04-04 15:21:17 +0000957
ths5fafdf22007-09-16 21:08:06 +0000958@item
bellard1f673132004-04-04 15:21:17 +0000959Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
960from a disk file.
961
962@item Inspect the VM state without an external debugger.
963
964@end itemize
965
966@subsection Commands
967
968The following commands are available:
969
970@table @option
971
ths89dfe892007-11-21 22:38:37 +0000972@item help or ? [@var{cmd}]
bellard1f673132004-04-04 15:21:17 +0000973Show the help for all commands or just for command @var{cmd}.
974
ths3b46e622007-09-17 08:09:54 +0000975@item commit
ths89dfe892007-11-21 22:38:37 +0000976Commit changes to the disk images (if -snapshot is used).
bellard1f673132004-04-04 15:21:17 +0000977
ths89dfe892007-11-21 22:38:37 +0000978@item info @var{subcommand}
979Show various information about the system state.
bellard1f673132004-04-04 15:21:17 +0000980
981@table @option
982@item info network
bellard41d03942005-11-15 23:02:53 +0000983show the various VLANs and the associated devices
bellard1f673132004-04-04 15:21:17 +0000984@item info block
985show the block devices
986@item info registers
987show the cpu registers
988@item info history
989show the command line history
bellardb389dbf2005-11-06 16:49:55 +0000990@item info pci
991show emulated PCI device
992@item info usb
993show USB devices plugged on the virtual USB hub
994@item info usbhost
995show all USB host devices
bellarda3c25992006-07-18 21:09:59 +0000996@item info capture
997show information about active capturing
bellard13a2e802006-08-06 14:50:31 +0000998@item info snapshots
999show list of VM snapshots
ths455204e2007-01-05 16:42:13 +00001000@item info mice
1001show which guest mouse is receiving events
bellard1f673132004-04-04 15:21:17 +00001002@end table
1003
1004@item q or quit
1005Quit the emulator.
1006
ths89dfe892007-11-21 22:38:37 +00001007@item eject [-f] @var{device}
thse5987522007-03-30 18:58:01 +00001008Eject a removable medium (use -f to force it).
bellard1f673132004-04-04 15:21:17 +00001009
ths89dfe892007-11-21 22:38:37 +00001010@item change @var{device} @var{setting}
thsf858dca2007-08-25 01:40:37 +00001011
ths89dfe892007-11-21 22:38:37 +00001012Change the configuration of a device.
thsf858dca2007-08-25 01:40:37 +00001013
1014@table @option
1015@item change @var{diskdevice} @var{filename}
1016Change the medium for a removable disk device to point to @var{filename}. eg
1017
1018@example
1019(qemu) change cdrom /path/to/some.iso
1020@end example
1021
ths89dfe892007-11-21 22:38:37 +00001022@item change vnc @var{display},@var{options}
thsf858dca2007-08-25 01:40:37 +00001023Change the configuration of the VNC server. The valid syntax for @var{display}
1024and @var{options} are described at @ref{sec_invocation}. eg
1025
1026@example
1027(qemu) change vnc localhost:1
1028@end example
1029
1030@item change vnc password
1031
1032Change the password associated with the VNC server. The monitor will prompt for
1033the new password to be entered. VNC passwords are only significant upto 8 letters.
1034eg.
1035
1036@example
1037(qemu) change vnc password
1038Password: ********
1039@end example
1040
1041@end table
bellard1f673132004-04-04 15:21:17 +00001042
ths89dfe892007-11-21 22:38:37 +00001043@item screendump @var{filename}
bellard1f673132004-04-04 15:21:17 +00001044Save screen into PPM image @var{filename}.
1045
ths89dfe892007-11-21 22:38:37 +00001046@item mouse_move @var{dx} @var{dy} [@var{dz}]
ths455204e2007-01-05 16:42:13 +00001047Move the active mouse to the specified coordinates @var{dx} @var{dy}
1048with optional scroll axis @var{dz}.
1049
ths89dfe892007-11-21 22:38:37 +00001050@item mouse_button @var{val}
ths455204e2007-01-05 16:42:13 +00001051Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1052
ths89dfe892007-11-21 22:38:37 +00001053@item mouse_set @var{index}
ths455204e2007-01-05 16:42:13 +00001054Set which mouse device receives events at given @var{index}, index
1055can be obtained with
1056@example
1057info mice
1058@end example
1059
ths89dfe892007-11-21 22:38:37 +00001060@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
bellarda3c25992006-07-18 21:09:59 +00001061Capture audio into @var{filename}. Using sample rate @var{frequency}
1062bits per sample @var{bits} and number of channels @var{channels}.
1063
1064Defaults:
1065@itemize @minus
1066@item Sample rate = 44100 Hz - CD quality
1067@item Bits = 16
1068@item Number of channels = 2 - Stereo
1069@end itemize
1070
ths89dfe892007-11-21 22:38:37 +00001071@item stopcapture @var{index}
bellarda3c25992006-07-18 21:09:59 +00001072Stop capture with a given @var{index}, index can be obtained with
1073@example
1074info capture
1075@end example
1076
ths89dfe892007-11-21 22:38:37 +00001077@item log @var{item1}[,...]
bellard1f673132004-04-04 15:21:17 +00001078Activate logging of the specified items to @file{/tmp/qemu.log}.
1079
ths89dfe892007-11-21 22:38:37 +00001080@item savevm [@var{tag}|@var{id}]
bellard13a2e802006-08-06 14:50:31 +00001081Create a snapshot of the whole virtual machine. If @var{tag} is
1082provided, it is used as human readable identifier. If there is already
1083a snapshot with the same tag or ID, it is replaced. More info at
1084@ref{vm_snapshots}.
bellard1f673132004-04-04 15:21:17 +00001085
ths89dfe892007-11-21 22:38:37 +00001086@item loadvm @var{tag}|@var{id}
bellard13a2e802006-08-06 14:50:31 +00001087Set the whole virtual machine to the snapshot identified by the tag
1088@var{tag} or the unique snapshot ID @var{id}.
1089
ths89dfe892007-11-21 22:38:37 +00001090@item delvm @var{tag}|@var{id}
bellard13a2e802006-08-06 14:50:31 +00001091Delete the snapshot identified by @var{tag} or @var{id}.
bellard1f673132004-04-04 15:21:17 +00001092
1093@item stop
1094Stop emulation.
1095
1096@item c or cont
1097Resume emulation.
1098
ths89dfe892007-11-21 22:38:37 +00001099@item gdbserver [@var{port}]
1100Start gdbserver session (default @var{port}=1234)
bellard1f673132004-04-04 15:21:17 +00001101
ths89dfe892007-11-21 22:38:37 +00001102@item x/fmt @var{addr}
bellard1f673132004-04-04 15:21:17 +00001103Virtual memory dump starting at @var{addr}.
1104
ths89dfe892007-11-21 22:38:37 +00001105@item xp /@var{fmt} @var{addr}
bellard1f673132004-04-04 15:21:17 +00001106Physical memory dump starting at @var{addr}.
1107
1108@var{fmt} is a format which tells the command how to format the
1109data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1110
1111@table @var
ths5fafdf22007-09-16 21:08:06 +00001112@item count
bellard1f673132004-04-04 15:21:17 +00001113is the number of items to be dumped.
1114
1115@item format
ths4be456f2007-06-03 13:41:28 +00001116can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
bellard1f673132004-04-04 15:21:17 +00001117c (char) or i (asm instruction).
1118
1119@item size
bellard52c00a52004-04-25 21:27:03 +00001120can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1121@code{h} or @code{w} can be specified with the @code{i} format to
1122respectively select 16 or 32 bit code instruction size.
bellard1f673132004-04-04 15:21:17 +00001123
1124@end table
1125
ths5fafdf22007-09-16 21:08:06 +00001126Examples:
bellard1f673132004-04-04 15:21:17 +00001127@itemize
1128@item
1129Dump 10 instructions at the current instruction pointer:
ths5fafdf22007-09-16 21:08:06 +00001130@example
bellard1f673132004-04-04 15:21:17 +00001131(qemu) x/10i $eip
11320x90107063: ret
11330x90107064: sti
11340x90107065: lea 0x0(%esi,1),%esi
11350x90107069: lea 0x0(%edi,1),%edi
11360x90107070: ret
11370x90107071: jmp 0x90107080
11380x90107073: nop
11390x90107074: nop
11400x90107075: nop
11410x90107076: nop
1142@end example
1143
1144@item
1145Dump 80 16 bit values at the start of the video memory.
ths5fafdf22007-09-16 21:08:06 +00001146@smallexample
bellard1f673132004-04-04 15:21:17 +00001147(qemu) xp/80hx 0xb8000
11480x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
11490x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
11500x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
11510x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
11520x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
11530x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
11540x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
11550x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
11560x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
11570x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
bellarddebc7062006-04-30 21:58:41 +00001158@end smallexample
bellard1f673132004-04-04 15:21:17 +00001159@end itemize
1160
ths89dfe892007-11-21 22:38:37 +00001161@item p or print/@var{fmt} @var{expr}
bellard1f673132004-04-04 15:21:17 +00001162
1163Print expression value. Only the @var{format} part of @var{fmt} is
1164used.
1165
ths89dfe892007-11-21 22:38:37 +00001166@item sendkey @var{keys}
bellarda3a91a32004-06-04 11:06:21 +00001167
1168Send @var{keys} to the emulator. Use @code{-} to press several keys
1169simultaneously. Example:
1170@example
1171sendkey ctrl-alt-f1
1172@end example
1173
1174This command is useful to send keys that your graphical user interface
1175intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1176
bellard15a34c62004-07-08 21:26:26 +00001177@item system_reset
1178
1179Reset the system.
1180
ths89dfe892007-11-21 22:38:37 +00001181@item usb_add @var{devname}
bellardb389dbf2005-11-06 16:49:55 +00001182
pbrook0aff66b2006-05-26 00:49:52 +00001183Add the USB device @var{devname}. For details of available devices see
1184@ref{usb_devices}
bellardb389dbf2005-11-06 16:49:55 +00001185
ths89dfe892007-11-21 22:38:37 +00001186@item usb_del @var{devname}
bellardb389dbf2005-11-06 16:49:55 +00001187
1188Remove the USB device @var{devname} from the QEMU virtual USB
1189hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1190command @code{info usb} to see the devices you can remove.
1191
bellard1f673132004-04-04 15:21:17 +00001192@end table
1193
1194@subsection Integer expressions
1195
1196The monitor understands integers expressions for every integer
1197argument. You can use register names to get the value of specifics
1198CPU registers by prefixing them with @emph{$}.
1199
1200@node disk_images
1201@section Disk Images
1202
bellardacd935e2004-11-15 22:57:26 +00001203Since version 0.6.1, QEMU supports many disk image formats, including
1204growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +00001205written), compressed and encrypted disk images. Version 0.8.3 added
1206the new qcow2 disk image format which is essential to support VM
1207snapshots.
bellard1f673132004-04-04 15:21:17 +00001208
bellarddebc7062006-04-30 21:58:41 +00001209@menu
1210* disk_images_quickstart:: Quick start for disk image creation
1211* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +00001212* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +00001213* qemu_img_invocation:: qemu-img Invocation
bellard19cb3732006-08-19 11:45:59 +00001214* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +00001215* disk_images_fat_images:: Virtual FAT disk images
1216@end menu
1217
1218@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +00001219@subsection Quick start for disk image creation
1220
1221You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +00001222@example
bellardacd935e2004-11-15 22:57:26 +00001223qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +00001224@end example
bellardacd935e2004-11-15 22:57:26 +00001225where @var{myimage.img} is the disk image filename and @var{mysize} is its
1226size in kilobytes. You can add an @code{M} suffix to give the size in
1227megabytes and a @code{G} suffix for gigabytes.
1228
bellarddebc7062006-04-30 21:58:41 +00001229See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +00001230
bellarddebc7062006-04-30 21:58:41 +00001231@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +00001232@subsection Snapshot mode
1233
1234If you use the option @option{-snapshot}, all disk images are
1235considered as read only. When sectors in written, they are written in
1236a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +00001237write back to the raw disk images by using the @code{commit} monitor
1238command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +00001239
bellard13a2e802006-08-06 14:50:31 +00001240@node vm_snapshots
1241@subsection VM snapshots
1242
1243VM snapshots are snapshots of the complete virtual machine including
1244CPU state, RAM, device state and the content of all the writable
1245disks. In order to use VM snapshots, you must have at least one non
1246removable and writable block device using the @code{qcow2} disk image
1247format. Normally this device is the first virtual hard drive.
1248
1249Use the monitor command @code{savevm} to create a new VM snapshot or
1250replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +00001251snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +00001252
1253Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1254a VM snapshot. @code{info snapshots} lists the available snapshots
1255with their associated information:
1256
1257@example
1258(qemu) info snapshots
1259Snapshot devices: hda
1260Snapshot list (from hda):
1261ID TAG VM SIZE DATE VM CLOCK
12621 start 41M 2006-08-06 12:38:02 00:00:14.954
12632 40M 2006-08-06 12:43:29 00:00:18.633
12643 msys 40M 2006-08-06 12:44:04 00:00:23.514
1265@end example
1266
1267A VM snapshot is made of a VM state info (its size is shown in
1268@code{info snapshots}) and a snapshot of every writable disk image.
1269The VM state info is stored in the first @code{qcow2} non removable
1270and writable block device. The disk image snapshots are stored in
1271every disk image. The size of a snapshot in a disk image is difficult
1272to evaluate and is not shown by @code{info snapshots} because the
1273associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +00001274disk space (otherwise each snapshot would need a full copy of all the
1275disk images).
bellard13a2e802006-08-06 14:50:31 +00001276
1277When using the (unrelated) @code{-snapshot} option
1278(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1279but they are deleted as soon as you exit QEMU.
1280
1281VM snapshots currently have the following known limitations:
1282@itemize
ths5fafdf22007-09-16 21:08:06 +00001283@item
bellard13a2e802006-08-06 14:50:31 +00001284They cannot cope with removable devices if they are removed or
1285inserted after a snapshot is done.
ths5fafdf22007-09-16 21:08:06 +00001286@item
bellard13a2e802006-08-06 14:50:31 +00001287A few device drivers still have incomplete snapshot support so their
1288state is not saved or restored properly (in particular USB).
1289@end itemize
1290
bellardacd935e2004-11-15 22:57:26 +00001291@node qemu_img_invocation
1292@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +00001293
bellardacd935e2004-11-15 22:57:26 +00001294@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +00001295
bellard19cb3732006-08-19 11:45:59 +00001296@node host_drives
1297@subsection Using host drives
1298
1299In addition to disk image files, QEMU can directly access host
1300devices. We describe here the usage for QEMU version >= 0.8.3.
1301
1302@subsubsection Linux
1303
1304On Linux, you can directly use the host device filename instead of a
ths4be456f2007-06-03 13:41:28 +00001305disk image filename provided you have enough privileges to access
bellard19cb3732006-08-19 11:45:59 +00001306it. For example, use @file{/dev/cdrom} to access to the CDROM or
1307@file{/dev/fd0} for the floppy.
1308
bellardf5420862006-08-21 20:26:44 +00001309@table @code
bellard19cb3732006-08-19 11:45:59 +00001310@item CD
1311You can specify a CDROM device even if no CDROM is loaded. QEMU has
1312specific code to detect CDROM insertion or removal. CDROM ejection by
1313the guest OS is supported. Currently only data CDs are supported.
1314@item Floppy
1315You can specify a floppy device even if no floppy is loaded. Floppy
1316removal is currently not detected accurately (if you change floppy
1317without doing floppy access while the floppy is not loaded, the guest
1318OS will think that the same floppy is loaded).
1319@item Hard disks
1320Hard disks can be used. Normally you must specify the whole disk
1321(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1322see it as a partitioned disk. WARNING: unless you know what you do, it
1323is better to only make READ-ONLY accesses to the hard disk otherwise
1324you may corrupt your host data (use the @option{-snapshot} command
1325line option or modify the device permissions accordingly).
1326@end table
1327
1328@subsubsection Windows
1329
bellard01781962007-01-07 22:43:30 +00001330@table @code
1331@item CD
ths4be456f2007-06-03 13:41:28 +00001332The preferred syntax is the drive letter (e.g. @file{d:}). The
bellard01781962007-01-07 22:43:30 +00001333alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1334supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +00001335
thse5987522007-03-30 18:58:01 +00001336Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +00001337is better to use the @code{change} or @code{eject} monitor commands to
1338change or eject media.
bellard01781962007-01-07 22:43:30 +00001339@item Hard disks
ths89dfe892007-11-21 22:38:37 +00001340Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
bellard01781962007-01-07 22:43:30 +00001341where @var{N} is the drive number (0 is the first hard disk).
1342
1343WARNING: unless you know what you do, it is better to only make
1344READ-ONLY accesses to the hard disk otherwise you may corrupt your
1345host data (use the @option{-snapshot} command line so that the
1346modifications are written in a temporary file).
1347@end table
1348
bellard19cb3732006-08-19 11:45:59 +00001349
1350@subsubsection Mac OS X
1351
ths5fafdf22007-09-16 21:08:06 +00001352@file{/dev/cdrom} is an alias to the first CDROM.
bellard19cb3732006-08-19 11:45:59 +00001353
thse5987522007-03-30 18:58:01 +00001354Currently there is no specific code to handle removable media, so it
bellard19cb3732006-08-19 11:45:59 +00001355is better to use the @code{change} or @code{eject} monitor commands to
1356change or eject media.
1357
bellarddebc7062006-04-30 21:58:41 +00001358@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +00001359@subsection Virtual FAT disk images
1360
1361QEMU can automatically create a virtual FAT disk image from a
1362directory tree. In order to use it, just type:
1363
ths5fafdf22007-09-16 21:08:06 +00001364@example
bellard2c6cadd2005-12-18 18:31:45 +00001365qemu linux.img -hdb fat:/my_directory
1366@end example
1367
1368Then you access access to all the files in the @file{/my_directory}
1369directory without having to copy them in a disk image or to export
1370them via SAMBA or NFS. The default access is @emph{read-only}.
1371
1372Floppies can be emulated with the @code{:floppy:} option:
1373
ths5fafdf22007-09-16 21:08:06 +00001374@example
bellard2c6cadd2005-12-18 18:31:45 +00001375qemu linux.img -fda fat:floppy:/my_directory
1376@end example
1377
1378A read/write support is available for testing (beta stage) with the
1379@code{:rw:} option:
1380
ths5fafdf22007-09-16 21:08:06 +00001381@example
bellard2c6cadd2005-12-18 18:31:45 +00001382qemu linux.img -fda fat:floppy:rw:/my_directory
1383@end example
1384
1385What you should @emph{never} do:
1386@itemize
1387@item use non-ASCII filenames ;
1388@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +00001389@item expect it to work when loadvm'ing ;
1390@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +00001391@end itemize
1392
bellarddebc7062006-04-30 21:58:41 +00001393@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001394@section Network emulation
1395
ths4be456f2007-06-03 13:41:28 +00001396QEMU can simulate several network cards (PCI or ISA cards on the PC
bellard41d03942005-11-15 23:02:53 +00001397target) and can connect them to an arbitrary number of Virtual Local
1398Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1399VLAN. VLAN can be connected between separate instances of QEMU to
ths4be456f2007-06-03 13:41:28 +00001400simulate large networks. For simpler usage, a non privileged user mode
bellard41d03942005-11-15 23:02:53 +00001401network stack can replace the TAP device to have a basic network
1402connection.
bellard9d4fb822004-04-26 20:55:38 +00001403
bellard41d03942005-11-15 23:02:53 +00001404@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001405
bellard41d03942005-11-15 23:02:53 +00001406QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1407connection between several network devices. These devices can be for
1408example QEMU virtual Ethernet cards or virtual Host ethernet devices
1409(TAP devices).
1410
1411@subsection Using TAP network interfaces
1412
1413This is the standard way to connect QEMU to a real network. QEMU adds
1414a virtual network device on your host (called @code{tapN}), and you
1415can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001416
bellard8f40c382006-09-20 20:28:05 +00001417@subsubsection Linux host
1418
bellard9d4fb822004-04-26 20:55:38 +00001419As an example, you can download the @file{linux-test-xxx.tar.gz}
1420archive and copy the script @file{qemu-ifup} in @file{/etc} and
1421configure properly @code{sudo} so that the command @code{ifconfig}
1422contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001423that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001424device @file{/dev/net/tun} must be present.
1425
bellardee0f4752006-08-19 16:56:18 +00001426See @ref{sec_invocation} to have examples of command lines using the
1427TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001428
bellard8f40c382006-09-20 20:28:05 +00001429@subsubsection Windows host
1430
1431There is a virtual ethernet driver for Windows 2000/XP systems, called
1432TAP-Win32. But it is not included in standard QEMU for Windows,
1433so you will need to get it separately. It is part of OpenVPN package,
1434so download OpenVPN from : @url{http://openvpn.net/}.
1435
bellard9d4fb822004-04-26 20:55:38 +00001436@subsection Using the user mode network stack
1437
bellard41d03942005-11-15 23:02:53 +00001438By using the option @option{-net user} (default configuration if no
1439@option{-net} option is specified), QEMU uses a completely user mode
ths4be456f2007-06-03 13:41:28 +00001440network stack (you don't need root privilege to use the virtual
bellard41d03942005-11-15 23:02:53 +00001441network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001442
1443@example
1444
bellard41d03942005-11-15 23:02:53 +00001445 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1446 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001447 |
bellard2518bd02004-09-30 22:35:13 +00001448 ----> DNS server (10.0.2.3)
ths3b46e622007-09-17 08:09:54 +00001449 |
bellard2518bd02004-09-30 22:35:13 +00001450 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001451@end example
1452
1453The QEMU VM behaves as if it was behind a firewall which blocks all
1454incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001455configure the network in the QEMU VM. The DHCP server assign addresses
1456to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001457
1458In order to check that the user mode network is working, you can ping
1459the address 10.0.2.2 and verify that you got an address in the range
146010.0.2.x from the QEMU virtual DHCP server.
1461
bellardb415a402004-05-23 21:04:06 +00001462Note that @code{ping} is not supported reliably to the internet as it
ths4be456f2007-06-03 13:41:28 +00001463would require root privileges. It means you can only ping the local
bellardb415a402004-05-23 21:04:06 +00001464router (10.0.2.2).
1465
bellard9bf05442004-08-25 22:12:49 +00001466When using the built-in TFTP server, the router is also the TFTP
1467server.
1468
1469When using the @option{-redir} option, TCP or UDP connections can be
1470redirected from the host to the guest. It allows for example to
1471redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001472
bellard41d03942005-11-15 23:02:53 +00001473@subsection Connecting VLANs between QEMU instances
1474
1475Using the @option{-net socket} option, it is possible to make VLANs
1476that span several QEMU instances. See @ref{sec_invocation} to have a
1477basic example.
1478
bellard9d4fb822004-04-26 20:55:38 +00001479@node direct_linux_boot
1480@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001481
1482This section explains how to launch a Linux kernel inside QEMU without
1483having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001484kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001485
bellardee0f4752006-08-19 16:56:18 +00001486The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001487@example
bellardee0f4752006-08-19 16:56:18 +00001488qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001489@end example
1490
bellardee0f4752006-08-19 16:56:18 +00001491Use @option{-kernel} to provide the Linux kernel image and
1492@option{-append} to give the kernel command line arguments. The
1493@option{-initrd} option can be used to provide an INITRD image.
1494
1495When using the direct Linux boot, a disk image for the first hard disk
1496@file{hda} is required because its boot sector is used to launch the
1497Linux kernel.
1498
1499If you do not need graphical output, you can disable it and redirect
1500the virtual serial port and the QEMU monitor to the console with the
1501@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001502@example
bellardee0f4752006-08-19 16:56:18 +00001503qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1504 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001505@end example
1506
bellardee0f4752006-08-19 16:56:18 +00001507Use @key{Ctrl-a c} to switch between the serial console and the
1508monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001509
bellarddebc7062006-04-30 21:58:41 +00001510@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001511@section USB emulation
1512
pbrook0aff66b2006-05-26 00:49:52 +00001513QEMU emulates a PCI UHCI USB controller. You can virtually plug
1514virtual USB devices or real host USB devices (experimental, works only
1515on Linux hosts). Qemu will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001516as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001517
pbrook0aff66b2006-05-26 00:49:52 +00001518@menu
1519* usb_devices::
1520* host_usb_devices::
1521@end menu
1522@node usb_devices
1523@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001524
pbrook0aff66b2006-05-26 00:49:52 +00001525USB devices can be connected with the @option{-usbdevice} commandline option
1526or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001527
pbrook0aff66b2006-05-26 00:49:52 +00001528@table @var
1529@item @code{mouse}
1530Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1531@item @code{tablet}
bellardc6d46c22006-09-03 17:10:41 +00001532Pointer device that uses absolute coordinates (like a touchscreen).
pbrook0aff66b2006-05-26 00:49:52 +00001533This means qemu is able to report the mouse position without having
1534to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
ths89dfe892007-11-21 22:38:37 +00001535@item @code{disk:@var{file}}
pbrook0aff66b2006-05-26 00:49:52 +00001536Mass storage device based on @var{file} (@pxref{disk_images})
ths89dfe892007-11-21 22:38:37 +00001537@item @code{host:@var{bus.addr}}
pbrook0aff66b2006-05-26 00:49:52 +00001538Pass through the host device identified by @var{bus.addr}
1539(Linux only)
ths89dfe892007-11-21 22:38:37 +00001540@item @code{host:@var{vendor_id:product_id}}
pbrook0aff66b2006-05-26 00:49:52 +00001541Pass through the host device identified by @var{vendor_id:product_id}
1542(Linux only)
balrogf6d2a312007-06-10 19:21:04 +00001543@item @code{wacom-tablet}
1544Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1545above but it can be used with the tslib library because in addition to touch
1546coordinates it reports touch pressure.
balrog47b2d332007-06-22 08:16:00 +00001547@item @code{keyboard}
1548Standard USB keyboard. Will override the PS/2 keyboard (if present).
pbrook0aff66b2006-05-26 00:49:52 +00001549@end table
bellardb389dbf2005-11-06 16:49:55 +00001550
pbrook0aff66b2006-05-26 00:49:52 +00001551@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001552@subsection Using host USB devices on a Linux host
1553
1554WARNING: this is an experimental feature. QEMU will slow down when
1555using it. USB devices requiring real time streaming (i.e. USB Video
1556Cameras) are not supported yet.
1557
1558@enumerate
ths5fafdf22007-09-16 21:08:06 +00001559@item If you use an early Linux 2.4 kernel, verify that no Linux driver
bellardb389dbf2005-11-06 16:49:55 +00001560is actually using the USB device. A simple way to do that is simply to
1561disable the corresponding kernel module by renaming it from @file{mydriver.o}
1562to @file{mydriver.o.disabled}.
1563
1564@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1565@example
1566ls /proc/bus/usb
1567001 devices drivers
1568@end example
1569
1570@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:
1571@example
1572chown -R myuid /proc/bus/usb
1573@end example
1574
1575@item Launch QEMU and do in the monitor:
ths5fafdf22007-09-16 21:08:06 +00001576@example
bellardb389dbf2005-11-06 16:49:55 +00001577info usbhost
1578 Device 1.2, speed 480 Mb/s
1579 Class 00: USB device 1234:5678, USB DISK
1580@end example
1581You should see the list of the devices you can use (Never try to use
1582hubs, it won't work).
1583
1584@item Add the device in QEMU by using:
ths5fafdf22007-09-16 21:08:06 +00001585@example
bellardb389dbf2005-11-06 16:49:55 +00001586usb_add host:1234:5678
1587@end example
1588
1589Normally the guest OS should report that a new USB device is
1590plugged. You can use the option @option{-usbdevice} to do the same.
1591
1592@item Now you can try to use the host USB device in QEMU.
1593
1594@end enumerate
1595
1596When relaunching QEMU, you may have to unplug and plug again the USB
1597device to make it work again (this is a bug).
1598
thsf858dca2007-08-25 01:40:37 +00001599@node vnc_security
1600@section VNC security
1601
1602The VNC server capability provides access to the graphical console
1603of the guest VM across the network. This has a number of security
1604considerations depending on the deployment scenarios.
1605
1606@menu
1607* vnc_sec_none::
1608* vnc_sec_password::
1609* vnc_sec_certificate::
1610* vnc_sec_certificate_verify::
1611* vnc_sec_certificate_pw::
1612* vnc_generate_cert::
1613@end menu
1614@node vnc_sec_none
1615@subsection Without passwords
1616
1617The simplest VNC server setup does not include any form of authentication.
1618For this setup it is recommended to restrict it to listen on a UNIX domain
1619socket only. For example
1620
1621@example
1622qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1623@end example
1624
1625This ensures that only users on local box with read/write access to that
1626path can access the VNC server. To securely access the VNC server from a
1627remote machine, a combination of netcat+ssh can be used to provide a secure
1628tunnel.
1629
1630@node vnc_sec_password
1631@subsection With passwords
1632
1633The VNC protocol has limited support for password based authentication. Since
1634the protocol limits passwords to 8 characters it should not be considered
1635to provide high security. The password can be fairly easily brute-forced by
1636a client making repeat connections. For this reason, a VNC server using password
1637authentication should be restricted to only listen on the loopback interface
1638or UNIX domain sockets. Password ayuthentication is requested with the @code{password}
1639option, and then once QEMU is running the password is set with the monitor. Until
1640the monitor is used to set the password all clients will be rejected.
1641
1642@example
1643qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1644(qemu) change vnc password
1645Password: ********
1646(qemu)
1647@end example
1648
1649@node vnc_sec_certificate
1650@subsection With x509 certificates
1651
1652The QEMU VNC server also implements the VeNCrypt extension allowing use of
1653TLS for encryption of the session, and x509 certificates for authentication.
1654The use of x509 certificates is strongly recommended, because TLS on its
1655own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1656support provides a secure session, but no authentication. This allows any
1657client to connect, and provides an encrypted session.
1658
1659@example
1660qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1661@end example
1662
1663In the above example @code{/etc/pki/qemu} should contain at least three files,
1664@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1665users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1666NB the @code{server-key.pem} file should be protected with file mode 0600 to
1667only be readable by the user owning it.
1668
1669@node vnc_sec_certificate_verify
1670@subsection With x509 certificates and client verification
1671
1672Certificates can also provide a means to authenticate the client connecting.
1673The server will request that the client provide a certificate, which it will
1674then validate against the CA certificate. This is a good choice if deploying
1675in an environment with a private internal certificate authority.
1676
1677@example
1678qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1679@end example
1680
1681
1682@node vnc_sec_certificate_pw
1683@subsection With x509 certificates, client verification and passwords
1684
1685Finally, the previous method can be combined with VNC password authentication
1686to provide two layers of authentication for clients.
1687
1688@example
1689qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1690(qemu) change vnc password
1691Password: ********
1692(qemu)
1693@end example
1694
1695@node vnc_generate_cert
1696@subsection Generating certificates for VNC
1697
1698The GNU TLS packages provides a command called @code{certtool} which can
1699be used to generate certificates and keys in PEM format. At a minimum it
1700is neccessary to setup a certificate authority, and issue certificates to
1701each server. If using certificates for authentication, then each client
1702will also need to be issued a certificate. The recommendation is for the
1703server to keep its certificates in either @code{/etc/pki/qemu} or for
1704unprivileged users in @code{$HOME/.pki/qemu}.
1705
1706@menu
1707* vnc_generate_ca::
1708* vnc_generate_server::
1709* vnc_generate_client::
1710@end menu
1711@node vnc_generate_ca
1712@subsubsection Setup the Certificate Authority
1713
1714This step only needs to be performed once per organization / organizational
1715unit. First the CA needs a private key. This key must be kept VERY secret
1716and secure. If this key is compromised the entire trust chain of the certificates
1717issued with it is lost.
1718
1719@example
1720# certtool --generate-privkey > ca-key.pem
1721@end example
1722
1723A CA needs to have a public certificate. For simplicity it can be a self-signed
1724certificate, or one issue by a commercial certificate issuing authority. To
1725generate a self-signed certificate requires one core piece of information, the
1726name of the organization.
1727
1728@example
1729# cat > ca.info <<EOF
1730cn = Name of your organization
1731ca
1732cert_signing_key
1733EOF
1734# certtool --generate-self-signed \
1735 --load-privkey ca-key.pem
1736 --template ca.info \
1737 --outfile ca-cert.pem
1738@end example
1739
1740The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1741TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1742
1743@node vnc_generate_server
1744@subsubsection Issuing server certificates
1745
1746Each server (or host) needs to be issued with a key and certificate. When connecting
1747the certificate is sent to the client which validates it against the CA certificate.
1748The core piece of information for a server certificate is the hostname. This should
1749be the fully qualified hostname that the client will connect with, since the client
1750will typically also verify the hostname in the certificate. On the host holding the
1751secure CA private key:
1752
1753@example
1754# cat > server.info <<EOF
1755organization = Name of your organization
1756cn = server.foo.example.com
1757tls_www_server
1758encryption_key
1759signing_key
1760EOF
1761# certtool --generate-privkey > server-key.pem
1762# certtool --generate-certificate \
1763 --load-ca-certificate ca-cert.pem \
1764 --load-ca-privkey ca-key.pem \
1765 --load-privkey server server-key.pem \
1766 --template server.info \
1767 --outfile server-cert.pem
1768@end example
1769
1770The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1771to the server for which they were generated. The @code{server-key.pem} is security
1772sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1773
1774@node vnc_generate_client
1775@subsubsection Issuing client certificates
1776
1777If the QEMU VNC server is to use the @code{x509verify} option to validate client
1778certificates as its authentication mechanism, each client also needs to be issued
1779a certificate. The client certificate contains enough metadata to uniquely identify
1780the client, typically organization, state, city, building, etc. On the host holding
1781the secure CA private key:
1782
1783@example
1784# cat > client.info <<EOF
1785country = GB
1786state = London
1787locality = London
1788organiazation = Name of your organization
1789cn = client.foo.example.com
1790tls_www_client
1791encryption_key
1792signing_key
1793EOF
1794# certtool --generate-privkey > client-key.pem
1795# certtool --generate-certificate \
1796 --load-ca-certificate ca-cert.pem \
1797 --load-ca-privkey ca-key.pem \
1798 --load-privkey client-key.pem \
1799 --template client.info \
1800 --outfile client-cert.pem
1801@end example
1802
1803The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1804copied to the client for which they were generated.
1805
bellard0806e3f2003-10-01 00:15:32 +00001806@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001807@section GDB usage
1808
1809QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001810'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001811
bellard9d4520d2003-10-28 01:38:57 +00001812In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001813gdb connection:
1814@example
bellarddebc7062006-04-30 21:58:41 +00001815> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1816 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001817Connected to host network interface: tun0
1818Waiting gdb connection on port 1234
1819@end example
1820
1821Then launch gdb on the 'vmlinux' executable:
1822@example
1823> gdb vmlinux
1824@end example
1825
1826In gdb, connect to QEMU:
1827@example
bellard6c9bf892004-01-24 13:46:56 +00001828(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001829@end example
1830
1831Then you can use gdb normally. For example, type 'c' to launch the kernel:
1832@example
1833(gdb) c
1834@end example
1835
bellard0806e3f2003-10-01 00:15:32 +00001836Here are some useful tips in order to use gdb on system code:
1837
1838@enumerate
1839@item
1840Use @code{info reg} to display all the CPU registers.
1841@item
1842Use @code{x/10i $eip} to display the code at the PC position.
1843@item
1844Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001845@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001846@end enumerate
1847
bellarddebc7062006-04-30 21:58:41 +00001848@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001849@section Target OS specific information
1850
1851@subsection Linux
1852
bellard15a34c62004-07-08 21:26:26 +00001853To have access to SVGA graphic modes under X11, use the @code{vesa} or
1854the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1855color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001856
bellarde3371e62004-07-10 16:26:02 +00001857When using a 2.6 guest Linux kernel, you should add the option
1858@code{clock=pit} on the kernel command line because the 2.6 Linux
1859kernels make very strict real time clock checks by default that QEMU
1860cannot simulate exactly.
1861
bellard7c3fc842005-02-10 21:46:47 +00001862When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1863not activated because QEMU is slower with this patch. The QEMU
1864Accelerator Module is also much slower in this case. Earlier Fedora
ths4be456f2007-06-03 13:41:28 +00001865Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
bellard7c3fc842005-02-10 21:46:47 +00001866patch by default. Newer kernels don't have it.
1867
bellard1a084f32004-05-13 22:34:49 +00001868@subsection Windows
1869
1870If you have a slow host, using Windows 95 is better as it gives the
1871best speed. Windows 2000 is also a good choice.
1872
bellarde3371e62004-07-10 16:26:02 +00001873@subsubsection SVGA graphic modes support
1874
1875QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001876card. All Windows versions starting from Windows 95 should recognize
1877and use this graphic card. For optimal performances, use 16 bit color
1878depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001879
bellard3cb08532006-06-21 21:19:50 +00001880If you are using Windows XP as guest OS and if you want to use high
1881resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
18821280x1024x16), then you should use the VESA VBE virtual graphic card
1883(option @option{-std-vga}).
1884
bellarde3371e62004-07-10 16:26:02 +00001885@subsubsection CPU usage reduction
1886
1887Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001888instruction. The result is that it takes host CPU cycles even when
1889idle. You can install the utility from
1890@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1891problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001892
bellard9d0a8e62005-07-03 17:34:05 +00001893@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001894
bellard9d0a8e62005-07-03 17:34:05 +00001895Windows 2000 has a bug which gives a disk full problem during its
1896installation. When installing it, use the @option{-win2k-hack} QEMU
1897option to enable a specific workaround. After Windows 2000 is
1898installed, you no longer need this option (this option slows down the
1899IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001900
bellard6cc721c2005-07-28 22:27:28 +00001901@subsubsection Windows 2000 shutdown
1902
1903Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1904can. It comes from the fact that Windows 2000 does not automatically
1905use the APM driver provided by the BIOS.
1906
1907In order to correct that, do the following (thanks to Struan
1908Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1909Add/Troubleshoot a device => Add a new device & Next => No, select the
1910hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1911(again) a few times. Now the driver is installed and Windows 2000 now
ths5fafdf22007-09-16 21:08:06 +00001912correctly instructs QEMU to shutdown at the appropriate moment.
bellard6cc721c2005-07-28 22:27:28 +00001913
1914@subsubsection Share a directory between Unix and Windows
1915
1916See @ref{sec_invocation} about the help of the option @option{-smb}.
1917
bellard2192c332006-08-21 20:28:18 +00001918@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001919
1920Some releases of Windows XP install correctly but give a security
1921error when booting:
1922@example
1923A problem is preventing Windows from accurately checking the
1924license for this computer. Error code: 0x800703e6.
1925@end example
bellarde3371e62004-07-10 16:26:02 +00001926
bellard2192c332006-08-21 20:28:18 +00001927The workaround is to install a service pack for XP after a boot in safe
1928mode. Then reboot, and the problem should go away. Since there is no
1929network while in safe mode, its recommended to download the full
1930installation of SP1 or SP2 and transfer that via an ISO or using the
1931vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001932
bellarda0a821a2004-07-14 17:38:57 +00001933@subsection MS-DOS and FreeDOS
1934
1935@subsubsection CPU usage reduction
1936
1937DOS does not correctly use the CPU HLT instruction. The result is that
1938it takes host CPU cycles even when idle. You can install the utility
1939from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1940problem.
1941
bellarddebc7062006-04-30 21:58:41 +00001942@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001943@chapter QEMU System emulator for non PC targets
1944
1945QEMU is a generic emulator and it emulates many non PC
1946machines. Most of the options are similar to the PC emulator. The
ths4be456f2007-06-03 13:41:28 +00001947differences are mentioned in the following sections.
bellard3f9f3aa2005-12-18 20:11:37 +00001948
bellarddebc7062006-04-30 21:58:41 +00001949@menu
1950* QEMU PowerPC System emulator::
ths24d4de42007-07-11 10:24:28 +00001951* Sparc32 System emulator::
1952* Sparc64 System emulator::
1953* MIPS System emulator::
1954* ARM System emulator::
1955* ColdFire System emulator::
bellarddebc7062006-04-30 21:58:41 +00001956@end menu
1957
1958@node QEMU PowerPC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +00001959@section QEMU PowerPC System emulator
bellard52c00a52004-04-25 21:27:03 +00001960
1961Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001962or PowerMac PowerPC system.
1963
bellardb671f9e2005-04-30 15:08:33 +00001964QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001965
1966@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001967@item
1968UniNorth PCI Bridge
bellard15a34c62004-07-08 21:26:26 +00001969@item
1970PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001971@item
bellard15a34c62004-07-08 21:26:26 +000019722 PMAC IDE interfaces with hard disk and CD-ROM support
ths5fafdf22007-09-16 21:08:06 +00001973@item
bellard15a34c62004-07-08 21:26:26 +00001974NE2000 PCI adapters
1975@item
1976Non Volatile RAM
1977@item
1978VIA-CUDA with ADB keyboard and mouse.
1979@end itemize
bellard52c00a52004-04-25 21:27:03 +00001980
bellardb671f9e2005-04-30 15:08:33 +00001981QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001982
1983@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00001984@item
bellard15a34c62004-07-08 21:26:26 +00001985PCI Bridge
1986@item
1987PCI VGA compatible card with VESA Bochs Extensions
ths5fafdf22007-09-16 21:08:06 +00001988@item
bellard52c00a52004-04-25 21:27:03 +000019892 IDE interfaces with hard disk and CD-ROM support
1990@item
1991Floppy disk
ths5fafdf22007-09-16 21:08:06 +00001992@item
bellard15a34c62004-07-08 21:26:26 +00001993NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001994@item
1995Serial port
1996@item
1997PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001998@item
1999PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00002000@end itemize
2001
bellard15a34c62004-07-08 21:26:26 +00002002QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00002003@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00002004
bellard15a34c62004-07-08 21:26:26 +00002005@c man begin OPTIONS
2006
2007The following options are specific to the PowerPC emulation:
2008
2009@table @option
2010
ths3b46e622007-09-17 08:09:54 +00002011@item -g WxH[xDEPTH]
bellard15a34c62004-07-08 21:26:26 +00002012
2013Set the initial VGA graphic mode. The default is 800x600x15.
2014
2015@end table
2016
ths5fafdf22007-09-16 21:08:06 +00002017@c man end
bellard15a34c62004-07-08 21:26:26 +00002018
2019
bellard52c00a52004-04-25 21:27:03 +00002020More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00002021@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00002022
ths24d4de42007-07-11 10:24:28 +00002023@node Sparc32 System emulator
2024@section Sparc32 System emulator
bellarde80cfcf2004-12-19 23:18:01 +00002025
blueswir16a3b9cc2007-11-11 17:56:38 +00002026Use the executable @file{qemu-system-sparc} to simulate a SPARCstation
20275, SPARCstation 10, or SPARCserver 600MP (sun4m architecture). The
2028emulation is somewhat complete. SMP up to 16 CPUs is supported, but
2029Linux limits the number of usable CPUs to 4.
bellarde80cfcf2004-12-19 23:18:01 +00002030
bellardb671f9e2005-04-30 15:08:33 +00002031QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00002032
2033@itemize @minus
bellard34751872005-07-02 14:31:34 +00002034@item
bellarde80cfcf2004-12-19 23:18:01 +00002035IOMMU
2036@item
2037TCX Frame buffer
ths5fafdf22007-09-16 21:08:06 +00002038@item
bellarde80cfcf2004-12-19 23:18:01 +00002039Lance (Am7990) Ethernet
2040@item
2041Non Volatile RAM M48T08
2042@item
bellard34751872005-07-02 14:31:34 +00002043Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2044and power/reset logic
2045@item
2046ESP SCSI controller with hard disk and CD-ROM support
2047@item
blueswir16a3b9cc2007-11-11 17:56:38 +00002048Floppy drive (not on SS-600MP)
blueswir1a2502b52007-06-10 17:01:00 +00002049@item
2050CS4231 sound device (only on SS-5, not working yet)
bellarde80cfcf2004-12-19 23:18:01 +00002051@end itemize
2052
blueswir16a3b9cc2007-11-11 17:56:38 +00002053The number of peripherals is fixed in the architecture. Maximum
2054memory size depends on the machine type, for SS-5 it is 256MB and for
2055SS-10 and SS-600MP 2047MB.
bellarde80cfcf2004-12-19 23:18:01 +00002056
bellard30a604f2006-06-14 18:35:18 +00002057Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00002058@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2059firmware implementation. The goal is to implement a 100% IEEE
20601275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00002061
2062A sample Linux 2.6 series kernel and ram disk image are available on
bellard0986ac32006-06-14 12:36:32 +00002063the QEMU web site. Please note that currently NetBSD, OpenBSD or
2064Solaris kernels don't work.
bellard34751872005-07-02 14:31:34 +00002065
2066@c man begin OPTIONS
2067
blueswir1a2502b52007-06-10 17:01:00 +00002068The following options are specific to the Sparc32 emulation:
bellard34751872005-07-02 14:31:34 +00002069
2070@table @option
2071
blueswir1a2502b52007-06-10 17:01:00 +00002072@item -g WxHx[xDEPTH]
bellard34751872005-07-02 14:31:34 +00002073
blueswir1a2502b52007-06-10 17:01:00 +00002074Set the initial TCX graphic mode. The default is 1024x768x8, currently
2075the only other possible mode is 1024x768x24.
bellard34751872005-07-02 14:31:34 +00002076
blueswir166508602007-05-01 14:16:52 +00002077@item -prom-env string
2078
2079Set OpenBIOS variables in NVRAM, for example:
2080
2081@example
2082qemu-system-sparc -prom-env 'auto-boot?=false' \
2083 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2084@end example
2085
blueswir166d45572007-11-26 18:46:38 +00002086@item -M [SS-5|SS-10|SS-600MP]
blueswir1a2502b52007-06-10 17:01:00 +00002087
2088Set the emulated machine type. Default is SS-5.
2089
bellard34751872005-07-02 14:31:34 +00002090@end table
2091
ths5fafdf22007-09-16 21:08:06 +00002092@c man end
bellard34751872005-07-02 14:31:34 +00002093
ths24d4de42007-07-11 10:24:28 +00002094@node Sparc64 System emulator
2095@section Sparc64 System emulator
bellard34751872005-07-02 14:31:34 +00002096
2097Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
2098The emulator is not usable for anything yet.
bellardb7569212005-03-13 09:43:05 +00002099
bellard83469012005-07-23 14:27:54 +00002100QEMU emulates the following sun4u peripherals:
2101
2102@itemize @minus
2103@item
ths5fafdf22007-09-16 21:08:06 +00002104UltraSparc IIi APB PCI Bridge
bellard83469012005-07-23 14:27:54 +00002105@item
2106PCI VGA compatible card with VESA Bochs Extensions
2107@item
2108Non Volatile RAM M48T59
2109@item
2110PC-compatible serial ports
2111@end itemize
2112
ths24d4de42007-07-11 10:24:28 +00002113@node MIPS System emulator
2114@section MIPS System emulator
bellard9d0a8e62005-07-03 17:34:05 +00002115
thsd9aedc32007-12-17 03:47:55 +00002116Four executables cover simulation of 32 and 64-bit MIPS systems in
2117both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2118@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2119Four different machine types are emulated:
ths24d4de42007-07-11 10:24:28 +00002120
2121@itemize @minus
2122@item
2123A generic ISA PC-like machine "mips"
2124@item
2125The MIPS Malta prototype board "malta"
2126@item
thsd9aedc32007-12-17 03:47:55 +00002127An ACER Pica "pica61". This machine needs the 64-bit emulator.
ths6bf5b4e2007-10-17 13:08:32 +00002128@item
thsf0fc6f82007-10-17 13:39:42 +00002129MIPS emulator pseudo board "mipssim"
ths24d4de42007-07-11 10:24:28 +00002130@end itemize
2131
2132The generic emulation is supported by Debian 'Etch' and is able to
2133install Debian into a virtual disk image. The following devices are
2134emulated:
bellard9d0a8e62005-07-03 17:34:05 +00002135
bellard3f9f3aa2005-12-18 20:11:37 +00002136@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002137@item
ths6bf5b4e2007-10-17 13:08:32 +00002138A range of MIPS CPUs, default is the 24Kf
bellard3f9f3aa2005-12-18 20:11:37 +00002139@item
2140PC style serial port
2141@item
ths24d4de42007-07-11 10:24:28 +00002142PC style IDE disk
2143@item
bellard3f9f3aa2005-12-18 20:11:37 +00002144NE2000 network card
2145@end itemize
2146
ths24d4de42007-07-11 10:24:28 +00002147The Malta emulation supports the following devices:
bellard3f9f3aa2005-12-18 20:11:37 +00002148
ths24d4de42007-07-11 10:24:28 +00002149@itemize @minus
2150@item
ths0b64d002007-07-11 21:43:14 +00002151Core board with MIPS 24Kf CPU and Galileo system controller
ths24d4de42007-07-11 10:24:28 +00002152@item
2153PIIX4 PCI/USB/SMbus controller
2154@item
2155The Multi-I/O chip's serial device
2156@item
2157PCnet32 PCI network card
2158@item
2159Malta FPGA serial device
2160@item
2161Cirrus VGA graphics card
2162@end itemize
2163
2164The ACER Pica emulation supports:
2165
2166@itemize @minus
2167@item
2168MIPS R4000 CPU
2169@item
2170PC-style IRQ and DMA controllers
2171@item
2172PC Keyboard
2173@item
2174IDE controller
2175@end itemize
2176
thsf0fc6f82007-10-17 13:39:42 +00002177The mipssim pseudo board emulation provides an environment similiar
2178to what the proprietary MIPS emulator uses for running Linux.
2179It supports:
ths6bf5b4e2007-10-17 13:08:32 +00002180
2181@itemize @minus
2182@item
2183A range of MIPS CPUs, default is the 24Kf
2184@item
2185PC style serial port
2186@item
2187MIPSnet network emulation
2188@end itemize
2189
ths24d4de42007-07-11 10:24:28 +00002190@node ARM System emulator
2191@section ARM System emulator
bellard3f9f3aa2005-12-18 20:11:37 +00002192
2193Use the executable @file{qemu-system-arm} to simulate a ARM
2194machine. The ARM Integrator/CP board is emulated with the following
2195devices:
2196
2197@itemize @minus
2198@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002199ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
bellard3f9f3aa2005-12-18 20:11:37 +00002200@item
2201Two PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002202@item
bellard3f9f3aa2005-12-18 20:11:37 +00002203SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00002204@item
2205PL110 LCD controller
2206@item
2207PL050 KMI with PS/2 keyboard and mouse.
pbrooka1bb27b2007-04-06 16:49:48 +00002208@item
2209PL181 MultiMedia Card Interface with SD card.
pbrook00a9bf12006-05-13 16:55:46 +00002210@end itemize
2211
2212The ARM Versatile baseboard is emulated with the following devices:
2213
2214@itemize @minus
2215@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002216ARM926E, ARM1136 or Cortex-A8 CPU
pbrook00a9bf12006-05-13 16:55:46 +00002217@item
2218PL190 Vectored Interrupt Controller
2219@item
2220Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002221@item
pbrook00a9bf12006-05-13 16:55:46 +00002222SMC 91c111 Ethernet adapter
2223@item
2224PL110 LCD controller
2225@item
2226PL050 KMI with PS/2 keyboard and mouse.
2227@item
2228PCI host bridge. Note the emulated PCI bridge only provides access to
2229PCI memory space. It does not provide access to PCI IO space.
ths4be456f2007-06-03 13:41:28 +00002230This means some devices (eg. ne2k_pci NIC) are not usable, and others
2231(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
pbrook00a9bf12006-05-13 16:55:46 +00002232mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00002233@item
2234PCI OHCI USB controller.
2235@item
2236LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
pbrooka1bb27b2007-04-06 16:49:48 +00002237@item
2238PL181 MultiMedia Card Interface with SD card.
bellard3f9f3aa2005-12-18 20:11:37 +00002239@end itemize
2240
pbrookd7739d72007-02-28 16:25:17 +00002241The ARM RealView Emulation baseboard is emulated with the following devices:
2242
2243@itemize @minus
2244@item
pbrook9ee6e8b2007-11-11 00:04:49 +00002245ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
pbrookd7739d72007-02-28 16:25:17 +00002246@item
2247ARM AMBA Generic/Distributed Interrupt Controller
2248@item
2249Four PL011 UARTs
ths5fafdf22007-09-16 21:08:06 +00002250@item
pbrookd7739d72007-02-28 16:25:17 +00002251SMC 91c111 Ethernet adapter
2252@item
2253PL110 LCD controller
2254@item
2255PL050 KMI with PS/2 keyboard and mouse
2256@item
2257PCI host bridge
2258@item
2259PCI OHCI USB controller
2260@item
2261LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
pbrooka1bb27b2007-04-06 16:49:48 +00002262@item
2263PL181 MultiMedia Card Interface with SD card.
pbrookd7739d72007-02-28 16:25:17 +00002264@end itemize
2265
balrogb00052e2007-04-30 02:22:06 +00002266The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2267and "Terrier") emulation includes the following peripherals:
2268
2269@itemize @minus
2270@item
2271Intel PXA270 System-on-chip (ARM V5TE core)
2272@item
2273NAND Flash memory
2274@item
2275IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2276@item
2277On-chip OHCI USB controller
2278@item
2279On-chip LCD controller
2280@item
2281On-chip Real Time Clock
2282@item
2283TI ADS7846 touchscreen controller on SSP bus
2284@item
2285Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2286@item
2287GPIO-connected keyboard controller and LEDs
2288@item
balrog549444e2007-05-01 17:53:37 +00002289Secure Digital card connected to PXA MMC/SD host
balrogb00052e2007-04-30 02:22:06 +00002290@item
2291Three on-chip UARTs
2292@item
2293WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2294@end itemize
2295
balrog02645922007-11-03 12:50:46 +00002296The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2297following elements:
2298
2299@itemize @minus
2300@item
2301Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2302@item
2303ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2304@item
2305On-chip LCD controller
2306@item
2307On-chip Real Time Clock
2308@item
2309TI TSC2102i touchscreen controller / analog-digital converter / Audio
2310CODEC, connected through MicroWire and I@math{^2}S busses
2311@item
2312GPIO-connected matrix keypad
2313@item
2314Secure Digital card connected to OMAP MMC/SD host
2315@item
2316Three on-chip UARTs
2317@end itemize
2318
pbrook9ee6e8b2007-11-11 00:04:49 +00002319The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2320devices:
2321
2322@itemize @minus
2323@item
2324Cortex-M3 CPU core.
2325@item
232664k Flash and 8k SRAM.
2327@item
2328Timers, UARTs, ADC and I@math{^2}C interface.
2329@item
2330OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2331@end itemize
2332
2333The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2334devices:
2335
2336@itemize @minus
2337@item
2338Cortex-M3 CPU core.
2339@item
2340256k Flash and 64k SRAM.
2341@item
2342Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2343@item
2344OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2345@end itemize
2346
bellard3f9f3aa2005-12-18 20:11:37 +00002347A Linux 2.6 test image is available on the QEMU web site. More
2348information is available in the QEMU mailing-list archive.
2349
ths24d4de42007-07-11 10:24:28 +00002350@node ColdFire System emulator
2351@section ColdFire System emulator
pbrook209a4e62007-05-23 20:16:15 +00002352
2353Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2354The emulator is able to boot a uClinux kernel.
pbrook707e0112007-06-04 00:50:06 +00002355
2356The M5208EVB emulation includes the following devices:
2357
2358@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002359@item
pbrook707e0112007-06-04 00:50:06 +00002360MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2361@item
2362Three Two on-chip UARTs.
2363@item
2364Fast Ethernet Controller (FEC)
2365@end itemize
2366
2367The AN5206 emulation includes the following devices:
pbrook209a4e62007-05-23 20:16:15 +00002368
2369@itemize @minus
ths5fafdf22007-09-16 21:08:06 +00002370@item
pbrook209a4e62007-05-23 20:16:15 +00002371MCF5206 ColdFire V2 Microprocessor.
2372@item
2373Two on-chip UARTs.
2374@end itemize
2375
ths5fafdf22007-09-16 21:08:06 +00002376@node QEMU User space emulator
2377@chapter QEMU User space emulator
bellard83195232007-02-05 19:42:07 +00002378
2379@menu
2380* Supported Operating Systems ::
2381* Linux User space emulator::
2382* Mac OS X/Darwin User space emulator ::
2383@end menu
2384
2385@node Supported Operating Systems
2386@section Supported Operating Systems
2387
2388The following OS are supported in user space emulation:
2389
2390@itemize @minus
2391@item
ths4be456f2007-06-03 13:41:28 +00002392Linux (referred as qemu-linux-user)
bellard83195232007-02-05 19:42:07 +00002393@item
ths4be456f2007-06-03 13:41:28 +00002394Mac OS X/Darwin (referred as qemu-darwin-user)
bellard83195232007-02-05 19:42:07 +00002395@end itemize
2396
2397@node Linux User space emulator
2398@section Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00002399
bellarddebc7062006-04-30 21:58:41 +00002400@menu
2401* Quick Start::
2402* Wine launch::
2403* Command line options::
pbrook79737e42006-06-11 16:28:41 +00002404* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00002405@end menu
2406
2407@node Quick Start
bellard83195232007-02-05 19:42:07 +00002408@subsection Quick Start
bellard386405f2003-03-23 21:28:45 +00002409
bellard1f673132004-04-04 15:21:17 +00002410In order to launch a Linux process, QEMU needs the process executable
ths5fafdf22007-09-16 21:08:06 +00002411itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00002412
bellard1f673132004-04-04 15:21:17 +00002413@itemize
bellard386405f2003-03-23 21:28:45 +00002414
bellard1f673132004-04-04 15:21:17 +00002415@item On x86, you can just try to launch any process by using the native
2416libraries:
bellard386405f2003-03-23 21:28:45 +00002417
ths5fafdf22007-09-16 21:08:06 +00002418@example
bellard1f673132004-04-04 15:21:17 +00002419qemu-i386 -L / /bin/ls
2420@end example
bellardfd429f22003-03-30 20:59:46 +00002421
bellard1f673132004-04-04 15:21:17 +00002422@code{-L /} tells that the x86 dynamic linker must be searched with a
2423@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00002424
thsdbcf5e82007-02-10 22:14:55 +00002425@item Since QEMU is also a linux process, you can launch qemu with
2426qemu (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00002427
ths5fafdf22007-09-16 21:08:06 +00002428@example
bellard1f673132004-04-04 15:21:17 +00002429qemu-i386 -L / qemu-i386 -L / /bin/ls
2430@end example
bellard386405f2003-03-23 21:28:45 +00002431
bellard1f673132004-04-04 15:21:17 +00002432@item On non x86 CPUs, you need first to download at least an x86 glibc
2433(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2434@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00002435
bellard1f673132004-04-04 15:21:17 +00002436@example
ths5fafdf22007-09-16 21:08:06 +00002437unset LD_LIBRARY_PATH
bellard1f673132004-04-04 15:21:17 +00002438@end example
bellard386405f2003-03-23 21:28:45 +00002439
bellard1f673132004-04-04 15:21:17 +00002440Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00002441
bellard1f673132004-04-04 15:21:17 +00002442@example
2443qemu-i386 tests/i386/ls
2444@end example
2445You can look at @file{qemu-binfmt-conf.sh} so that
2446QEMU is automatically launched by the Linux kernel when you try to
2447launch x86 executables. It requires the @code{binfmt_misc} module in the
2448Linux kernel.
bellard386405f2003-03-23 21:28:45 +00002449
bellard1f673132004-04-04 15:21:17 +00002450@item The x86 version of QEMU is also included. You can try weird things such as:
2451@example
bellarddebc7062006-04-30 21:58:41 +00002452qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2453 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00002454@end example
bellard386405f2003-03-23 21:28:45 +00002455
bellard1f673132004-04-04 15:21:17 +00002456@end itemize
bellard386405f2003-03-23 21:28:45 +00002457
bellarddebc7062006-04-30 21:58:41 +00002458@node Wine launch
bellard83195232007-02-05 19:42:07 +00002459@subsection Wine launch
bellard386405f2003-03-23 21:28:45 +00002460
bellard1f673132004-04-04 15:21:17 +00002461@itemize
bellard386405f2003-03-23 21:28:45 +00002462
bellard1f673132004-04-04 15:21:17 +00002463@item Ensure that you have a working QEMU with the x86 glibc
2464distribution (see previous section). In order to verify it, you must be
2465able to do:
bellard386405f2003-03-23 21:28:45 +00002466
bellard1f673132004-04-04 15:21:17 +00002467@example
2468qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2469@end example
bellard386405f2003-03-23 21:28:45 +00002470
bellard1f673132004-04-04 15:21:17 +00002471@item Download the binary x86 Wine install
ths5fafdf22007-09-16 21:08:06 +00002472(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00002473
bellard1f673132004-04-04 15:21:17 +00002474@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00002475@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00002476@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00002477
bellard1f673132004-04-04 15:21:17 +00002478@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00002479
bellard1f673132004-04-04 15:21:17 +00002480@example
bellarddebc7062006-04-30 21:58:41 +00002481qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2482 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00002483@end example
bellard386405f2003-03-23 21:28:45 +00002484
bellard1f673132004-04-04 15:21:17 +00002485@end itemize
bellard386405f2003-03-23 21:28:45 +00002486
bellarddebc7062006-04-30 21:58:41 +00002487@node Command line options
bellard83195232007-02-05 19:42:07 +00002488@subsection Command line options
bellard386405f2003-03-23 21:28:45 +00002489
bellard1f673132004-04-04 15:21:17 +00002490@example
2491usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2492@end example
bellard386405f2003-03-23 21:28:45 +00002493
bellard1f673132004-04-04 15:21:17 +00002494@table @option
2495@item -h
2496Print the help
ths3b46e622007-09-17 08:09:54 +00002497@item -L path
bellard1f673132004-04-04 15:21:17 +00002498Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2499@item -s size
2500Set the x86 stack size in bytes (default=524288)
bellard386405f2003-03-23 21:28:45 +00002501@end table
2502
bellard1f673132004-04-04 15:21:17 +00002503Debug options:
bellard386405f2003-03-23 21:28:45 +00002504
bellard1f673132004-04-04 15:21:17 +00002505@table @option
2506@item -d
2507Activate log (logfile=/tmp/qemu.log)
2508@item -p pagesize
2509Act as if the host page size was 'pagesize' bytes
2510@end table
bellard386405f2003-03-23 21:28:45 +00002511
balrogb01bcae2007-12-16 13:05:59 +00002512Environment variables:
2513
2514@table @env
2515@item QEMU_STRACE
2516Print system calls and arguments similar to the 'strace' program
2517(NOTE: the actual 'strace' program will not work because the user
2518space emulator hasn't implemented ptrace). At the moment this is
2519incomplete. All system calls that don't have a specific argument
2520format are printed with information for six arguments. Many
2521flag-style arguments don't have decoders and will show up as numbers.
ths5cfdf932007-12-17 03:38:26 +00002522@end table
balrogb01bcae2007-12-16 13:05:59 +00002523
pbrook79737e42006-06-11 16:28:41 +00002524@node Other binaries
bellard83195232007-02-05 19:42:07 +00002525@subsection Other binaries
pbrook79737e42006-06-11 16:28:41 +00002526
2527@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2528binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2529configurations), and arm-uclinux bFLT format binaries.
2530
pbrooke6e59062006-10-22 00:18:54 +00002531@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2532(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2533coldfire uClinux bFLT format binaries.
2534
pbrook79737e42006-06-11 16:28:41 +00002535The binary format is detected automatically.
2536
blueswir1a785e422007-10-20 08:09:05 +00002537@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2538(Sparc64 CPU, 32 bit ABI).
2539
2540@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2541SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2542
bellard83195232007-02-05 19:42:07 +00002543@node Mac OS X/Darwin User space emulator
2544@section Mac OS X/Darwin User space emulator
2545
2546@menu
2547* Mac OS X/Darwin Status::
2548* Mac OS X/Darwin Quick Start::
2549* Mac OS X/Darwin Command line options::
2550@end menu
2551
2552@node Mac OS X/Darwin Status
2553@subsection Mac OS X/Darwin Status
2554
2555@itemize @minus
2556@item
2557target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2558@item
2559target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2560@item
thsdbcf5e82007-02-10 22:14:55 +00002561target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
bellard83195232007-02-05 19:42:07 +00002562@item
2563target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2564@end itemize
2565
2566[1] If you're host commpage can be executed by qemu.
2567
2568@node Mac OS X/Darwin Quick Start
2569@subsection Quick Start
2570
2571In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2572itself and all the target dynamic libraries used by it. If you don't have the FAT
2573libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2574CD or compile them by hand.
2575
2576@itemize
2577
2578@item On x86, you can just try to launch any process by using the native
2579libraries:
2580
ths5fafdf22007-09-16 21:08:06 +00002581@example
thsdbcf5e82007-02-10 22:14:55 +00002582qemu-i386 /bin/ls
bellard83195232007-02-05 19:42:07 +00002583@end example
2584
2585or to run the ppc version of the executable:
2586
ths5fafdf22007-09-16 21:08:06 +00002587@example
thsdbcf5e82007-02-10 22:14:55 +00002588qemu-ppc /bin/ls
bellard83195232007-02-05 19:42:07 +00002589@end example
2590
2591@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2592are installed:
2593
ths5fafdf22007-09-16 21:08:06 +00002594@example
thsdbcf5e82007-02-10 22:14:55 +00002595qemu-i386 -L /opt/x86_root/ /bin/ls
bellard83195232007-02-05 19:42:07 +00002596@end example
2597
2598@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2599@file{/opt/x86_root/usr/bin/dyld}.
2600
2601@end itemize
2602
2603@node Mac OS X/Darwin Command line options
2604@subsection Command line options
2605
2606@example
thsdbcf5e82007-02-10 22:14:55 +00002607usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
bellard83195232007-02-05 19:42:07 +00002608@end example
2609
2610@table @option
2611@item -h
2612Print the help
ths3b46e622007-09-17 08:09:54 +00002613@item -L path
bellard83195232007-02-05 19:42:07 +00002614Set the library root path (default=/)
2615@item -s size
2616Set the stack size in bytes (default=524288)
2617@end table
2618
2619Debug options:
2620
2621@table @option
2622@item -d
2623Activate log (logfile=/tmp/qemu.log)
2624@item -p pagesize
2625Act as if the host page size was 'pagesize' bytes
2626@end table
2627
bellard15a34c62004-07-08 21:26:26 +00002628@node compilation
2629@chapter Compilation from the sources
2630
bellarddebc7062006-04-30 21:58:41 +00002631@menu
2632* Linux/Unix::
2633* Windows::
2634* Cross compilation for Windows with Linux::
2635* Mac OS X::
2636@end menu
2637
2638@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00002639@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00002640
bellard7c3fc842005-02-10 21:46:47 +00002641@subsection Compilation
2642
2643First you must decompress the sources:
2644@example
2645cd /tmp
2646tar zxvf qemu-x.y.z.tar.gz
2647cd qemu-x.y.z
2648@end example
2649
2650Then you configure QEMU and build it (usually no options are needed):
2651@example
2652./configure
2653make
2654@end example
2655
2656Then type as root user:
2657@example
2658make install
2659@end example
2660to install QEMU in @file{/usr/local}.
2661
bellard4fe8b872007-02-05 19:38:35 +00002662@subsection GCC version
bellard7c3fc842005-02-10 21:46:47 +00002663
ths366dfc52006-12-11 18:35:08 +00002664In order to compile QEMU successfully, it is very important that you
bellard4fe8b872007-02-05 19:38:35 +00002665have the right tools. The most important one is gcc. On most hosts and
2666in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
2667Linux distribution includes a gcc 4.x compiler, you can usually
2668install an older version (it is invoked by @code{gcc32} or
2669@code{gcc34}). The QEMU configure script automatically probes for
ths4be456f2007-06-03 13:41:28 +00002670these older versions so that usually you don't have to do anything.
bellard15a34c62004-07-08 21:26:26 +00002671
bellarddebc7062006-04-30 21:58:41 +00002672@node Windows
bellard15a34c62004-07-08 21:26:26 +00002673@section Windows
2674
2675@itemize
2676@item Install the current versions of MSYS and MinGW from
2677@url{http://www.mingw.org/}. You can find detailed installation
2678instructions in the download section and the FAQ.
2679
ths5fafdf22007-09-16 21:08:06 +00002680@item Download
bellard15a34c62004-07-08 21:26:26 +00002681the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00002682(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
bellard15a34c62004-07-08 21:26:26 +00002683@url{http://www.libsdl.org}. Unpack it in a temporary place, and
2684unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2685directory. Edit the @file{sdl-config} script so that it gives the
2686correct SDL directory when invoked.
2687
2688@item Extract the current version of QEMU.
ths5fafdf22007-09-16 21:08:06 +00002689
bellard15a34c62004-07-08 21:26:26 +00002690@item Start the MSYS shell (file @file{msys.bat}).
2691
ths5fafdf22007-09-16 21:08:06 +00002692@item Change to the QEMU directory. Launch @file{./configure} and
bellard15a34c62004-07-08 21:26:26 +00002693@file{make}. If you have problems using SDL, verify that
2694@file{sdl-config} can be launched from the MSYS command line.
2695
ths5fafdf22007-09-16 21:08:06 +00002696@item You can install QEMU in @file{Program Files/Qemu} by typing
bellard15a34c62004-07-08 21:26:26 +00002697@file{make install}. Don't forget to copy @file{SDL.dll} in
2698@file{Program Files/Qemu}.
2699
2700@end itemize
2701
bellarddebc7062006-04-30 21:58:41 +00002702@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00002703@section Cross compilation for Windows with Linux
2704
2705@itemize
2706@item
2707Install the MinGW cross compilation tools available at
2708@url{http://www.mingw.org/}.
2709
ths5fafdf22007-09-16 21:08:06 +00002710@item
bellard15a34c62004-07-08 21:26:26 +00002711Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
2712unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
2713variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
2714the QEMU configuration script.
2715
ths5fafdf22007-09-16 21:08:06 +00002716@item
bellard15a34c62004-07-08 21:26:26 +00002717Configure QEMU for Windows cross compilation:
2718@example
2719./configure --enable-mingw32
2720@end example
2721If necessary, you can change the cross-prefix according to the prefix
ths4be456f2007-06-03 13:41:28 +00002722chosen for the MinGW tools with --cross-prefix. You can also use
bellard15a34c62004-07-08 21:26:26 +00002723--prefix to set the Win32 install path.
2724
ths5fafdf22007-09-16 21:08:06 +00002725@item You can install QEMU in the installation directory by typing
bellard15a34c62004-07-08 21:26:26 +00002726@file{make install}. Don't forget to copy @file{SDL.dll} in the
ths5fafdf22007-09-16 21:08:06 +00002727installation directory.
bellard15a34c62004-07-08 21:26:26 +00002728
2729@end itemize
2730
2731Note: Currently, Wine does not seem able to launch
2732QEMU for Win32.
2733
bellarddebc7062006-04-30 21:58:41 +00002734@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00002735@section Mac OS X
2736
2737The Mac OS X patches are not fully merged in QEMU, so you should look
2738at the QEMU mailing list archive to have all the necessary
2739information.
2740
bellarddebc7062006-04-30 21:58:41 +00002741@node Index
2742@chapter Index
2743@printindex cp
2744
2745@bye