blob: 34f5a59d6dd311935ede801dbe1b78f4c0e0854a [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::
28* QEMU Linux User space emulator::
29* 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
53@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
bellard0806e3f2003-10-01 00:15:32 +000059@item
bellard1f673132004-04-04 15:21:17 +000060User mode emulation (Linux host only). In this mode, QEMU can launch
61Linux processes compiled for one CPU on another CPU. It can be used to
62launch 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
bellard6f2f2b22005-02-20 19:09:44 +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)
bellard3f9f3aa2005-12-18 20:11:37 +000079@item Malta board (32-bit MIPS processor)
pbrooked96ca32006-02-20 00:35:00 +000080@item ARM Integrator/CP (ARM926E or 1026E processor)
pbrook00a9bf12006-05-13 16:55:46 +000081@item ARM Versatile baseboard (ARM926E)
bellard52c00a52004-04-25 21:27:03 +000082@end itemize
bellard386405f2003-03-23 21:28:45 +000083
pbrooke6e59062006-10-22 00:18:54 +000084For user emulation, x86, PowerPC, ARM, MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +000085
bellarddebc7062006-04-30 21:58:41 +000086@node Installation
bellard5b9f4572003-10-28 00:49:54 +000087@chapter Installation
88
bellard15a34c62004-07-08 21:26:26 +000089If you want to compile QEMU yourself, see @ref{compilation}.
90
bellarddebc7062006-04-30 21:58:41 +000091@menu
92* install_linux:: Linux
93* install_windows:: Windows
94* install_mac:: Macintosh
95@end menu
96
97@node install_linux
bellard1f673132004-04-04 15:21:17 +000098@section Linux
99
bellard7c3fc842005-02-10 21:46:47 +0000100If a precompiled package is available for your distribution - you just
101have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +0000102
bellarddebc7062006-04-30 21:58:41 +0000103@node install_windows
bellard1f673132004-04-04 15:21:17 +0000104@section Windows
bellard8cd0ac22004-05-12 19:09:16 +0000105
bellard15a34c62004-07-08 21:26:26 +0000106Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000107@url{http://www.free.oszoo.org/@/download.html}.
bellardd691f662003-03-24 21:58:34 +0000108
bellarddebc7062006-04-30 21:58:41 +0000109@node install_mac
bellard1f673132004-04-04 15:21:17 +0000110@section Mac OS X
bellardd691f662003-03-24 21:58:34 +0000111
bellard15a34c62004-07-08 21:26:26 +0000112Download the experimental binary installer at
bellarddebc7062006-04-30 21:58:41 +0000113@url{http://www.free.oszoo.org/@/download.html}.
bellarddf0f11a2003-05-28 00:27:57 +0000114
bellarddebc7062006-04-30 21:58:41 +0000115@node QEMU PC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +0000116@chapter QEMU PC System emulator
bellard1eb20522003-06-25 16:21:49 +0000117
bellarddebc7062006-04-30 21:58:41 +0000118@menu
119* pcsys_introduction:: Introduction
120* pcsys_quickstart:: Quick Start
121* sec_invocation:: Invocation
122* pcsys_keys:: Keys
123* pcsys_monitor:: QEMU Monitor
124* disk_images:: Disk Images
125* pcsys_network:: Network emulation
126* direct_linux_boot:: Direct Linux Boot
127* pcsys_usb:: USB emulation
128* gdb_usage:: GDB usage
129* pcsys_os_specific:: Target OS specific information
130@end menu
131
132@node pcsys_introduction
bellard0806e3f2003-10-01 00:15:32 +0000133@section Introduction
134
135@c man begin DESCRIPTION
136
bellard3f9f3aa2005-12-18 20:11:37 +0000137The QEMU PC System emulator simulates the
138following peripherals:
bellard0806e3f2003-10-01 00:15:32 +0000139
140@itemize @minus
bellard15a34c62004-07-08 21:26:26 +0000141@item
142i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +0000143@item
bellard15a34c62004-07-08 21:26:26 +0000144Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
145extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +0000146@item
147PS/2 mouse and keyboard
148@item
bellard15a34c62004-07-08 21:26:26 +00001492 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +0000150@item
151Floppy disk
bellard0806e3f2003-10-01 00:15:32 +0000152@item
bellard15a34c62004-07-08 21:26:26 +0000153NE2000 PCI network adapters
bellard0806e3f2003-10-01 00:15:32 +0000154@item
bellard05d58182004-08-24 21:12:04 +0000155Serial ports
156@item
bellardc0fe3822005-11-05 18:55:28 +0000157Creative SoundBlaster 16 sound card
158@item
159ENSONIQ AudioPCI ES1370 sound card
160@item
161Adlib(OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000162@item
163PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000164@end itemize
165
bellard3f9f3aa2005-12-18 20:11:37 +0000166SMP is supported with up to 255 CPUs.
167
bellardc0fe3822005-11-05 18:55:28 +0000168Note that adlib is only available when QEMU was configured with
169-enable-adlib
170
bellard15a34c62004-07-08 21:26:26 +0000171QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
172VGA BIOS.
173
bellardc0fe3822005-11-05 18:55:28 +0000174QEMU uses YM3812 emulation by Tatsuyuki Satoh.
175
bellard0806e3f2003-10-01 00:15:32 +0000176@c man end
177
bellarddebc7062006-04-30 21:58:41 +0000178@node pcsys_quickstart
bellard1eb20522003-06-25 16:21:49 +0000179@section Quick Start
180
bellard285dc332003-10-27 23:58:04 +0000181Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000182
183@example
bellard285dc332003-10-27 23:58:04 +0000184qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000185@end example
186
187Linux should boot and give you a prompt.
188
bellard6cc721c2005-07-28 22:27:28 +0000189@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000190@section Invocation
191
192@example
193@c man begin SYNOPSIS
194usage: qemu [options] [disk_image]
195@c man end
196@end example
197
198@c man begin OPTIONS
199@var{disk_image} is a raw hard disk image for IDE hard disk 0.
200
201General options:
202@table @option
bellard3dbbdc22005-11-06 18:20:37 +0000203@item -M machine
204Select the emulated machine (@code{-M ?} for list)
205
bellard1f673132004-04-04 15:21:17 +0000206@item -fda file
207@item -fdb file
bellarddebc7062006-04-30 21:58:41 +0000208Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
bellard19cb3732006-08-19 11:45:59 +0000209use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000210
211@item -hda file
212@item -hdb file
213@item -hdc file
214@item -hdd file
bellarddebc7062006-04-30 21:58:41 +0000215Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000216
217@item -cdrom file
218Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
bellardbe3edd92004-06-03 12:48:45 +0000219@option{-cdrom} at the same time). You can use the host CD-ROM by
bellard19cb3732006-08-19 11:45:59 +0000220using @file{/dev/cdrom} as filename (@pxref{host_drives}).
bellard1f673132004-04-04 15:21:17 +0000221
thseec85c22007-01-05 17:41:07 +0000222@item -boot [a|c|d|n]
223Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
224is the default.
bellard1f673132004-04-04 15:21:17 +0000225
226@item -snapshot
227Write to temporary files instead of disk image files. In this case,
228the raw disk image you use is not written back. You can however force
ths42550fd2006-12-22 16:34:12 +0000229the write back by pressing @key{C-a s} (@pxref{disk_images}).
bellard1f673132004-04-04 15:21:17 +0000230
bellard52ca8d62006-06-14 16:03:05 +0000231@item -no-fd-bootchk
232Disable boot signature checking for floppy disks in Bochs BIOS. It may
233be needed to boot from old floppy disks.
234
bellard1f673132004-04-04 15:21:17 +0000235@item -m megs
bellard15a34c62004-07-08 21:26:26 +0000236Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
bellard1f673132004-04-04 15:21:17 +0000237
bellard3f9f3aa2005-12-18 20:11:37 +0000238@item -smp n
239Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
240CPUs are supported.
241
bellard1f673132004-04-04 15:21:17 +0000242@item -nographic
243
244Normally, QEMU uses SDL to display the VGA output. With this option,
245you can totally disable graphical output so that QEMU is a simple
246command line application. The emulated serial port is redirected on
247the console. Therefore, you can still use QEMU to debug a Linux kernel
248with a serial console.
249
ths73fc9742006-12-22 02:09:07 +0000250@item -vnc display
bellard24236862006-04-30 21:28:36 +0000251
252Normally, QEMU uses SDL to display the VGA output. With this option,
ths73fc9742006-12-22 02:09:07 +0000253you can have QEMU listen on VNC display @var{display} and redirect the VGA
bellard3c656342006-07-14 13:13:51 +0000254display over the VNC session. It is very useful to enable the usb
255tablet device when using this option (option @option{-usbdevice
256tablet}). When using the VNC display, you must use the @option{-k}
ths73fc9742006-12-22 02:09:07 +0000257option to set the keyboard layout if you are not using en-us.
258
259@var{display} may be in the form @var{interface:d}, in which case connections
260will only be allowed from @var{interface} on display @var{d}. Optionally,
261@var{interface} can be omitted. @var{display} can also be in the form
262@var{unix:path} where @var{path} is the location of a unix socket to listen for
263connections on.
264
bellard24236862006-04-30 21:28:36 +0000265
bellard3d11d0e2004-12-12 16:56:30 +0000266@item -k language
267
268Use keyboard layout @var{language} (for example @code{fr} for
269French). This option is only needed where it is not easy to get raw PC
bellard3c656342006-07-14 13:13:51 +0000270keycodes (e.g. on Macs, with some X11 servers or with a VNC
271display). You don't normally need to use it on PC/Linux or PC/Windows
272hosts.
bellard3d11d0e2004-12-12 16:56:30 +0000273
274The available layouts are:
275@example
276ar de-ch es fo fr-ca hu ja mk no pt-br sv
277da en-gb et fr fr-ch is lt nl pl ru th
278de en-us fi fr-be hr it lv nl-be pt sl tr
279@end example
280
281The default is @code{en-us}.
282
bellard1d14ffa2005-10-30 18:58:22 +0000283@item -audio-help
284
285Will show the audio subsystem help: list of drivers, tunable
286parameters.
287
bellard6a36d842005-12-18 20:34:32 +0000288@item -soundhw card1,card2,... or -soundhw all
bellard1d14ffa2005-10-30 18:58:22 +0000289
290Enable audio and selected sound hardware. Use ? to print all
291available sound hardware.
292
293@example
294qemu -soundhw sb16,adlib hda
295qemu -soundhw es1370 hda
bellard6a36d842005-12-18 20:34:32 +0000296qemu -soundhw all hda
bellard1d14ffa2005-10-30 18:58:22 +0000297qemu -soundhw ?
298@end example
bellarda8c490c2004-04-26 20:59:17 +0000299
bellard15a34c62004-07-08 21:26:26 +0000300@item -localtime
301Set the real time clock to local time (the default is to UTC
302time). This option is needed to have correct date in MS-DOS or
303Windows.
304
bellardd63d3072004-10-03 13:29:03 +0000305@item -full-screen
306Start in full screen.
307
bellardf7cce892004-12-08 22:21:25 +0000308@item -pidfile file
309Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
310from a script.
311
ths71e3ceb2006-12-22 02:11:31 +0000312@item -daemonize
313Daemonize the QEMU process after initialization. QEMU will not detach from
314standard IO until it is ready to receive connections on any of its devices.
315This option is a useful way for external programs to launch QEMU without having
316to cope with initialization race conditions.
317
bellard9d0a8e62005-07-03 17:34:05 +0000318@item -win2k-hack
319Use it when installing Windows 2000 to avoid a disk full bug. After
320Windows 2000 is installed, you no longer need this option (this option
321slows down the IDE transfers).
322
ths9ae02552007-01-05 17:39:04 +0000323@item -option-rom file
324Load the contents of file as an option ROM. This option is useful to load
325things like EtherBoot.
326
bellard1f673132004-04-04 15:21:17 +0000327@end table
328
bellardb389dbf2005-11-06 16:49:55 +0000329USB options:
330@table @option
331
332@item -usb
333Enable the USB driver (will be the default soon)
334
335@item -usbdevice devname
pbrook0aff66b2006-05-26 00:49:52 +0000336Add the USB device @var{devname}. @xref{usb_devices}.
bellardb389dbf2005-11-06 16:49:55 +0000337@end table
338
bellard1f673132004-04-04 15:21:17 +0000339Network options:
340
341@table @option
342
pbrooka41b2ff2006-02-05 04:14:41 +0000343@item -net nic[,vlan=n][,macaddr=addr][,model=type]
bellard41d03942005-11-15 23:02:53 +0000344Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
345= 0 is the default). The NIC is currently an NE2000 on the PC
346target. Optionally, the MAC address can be changed. If no
347@option{-net} option is specified, a single NIC is created.
pbrooka41b2ff2006-02-05 04:14:41 +0000348Qemu can emulate several different models of network card. Valid values for
349@var{type} are @code{ne2k_pci}, @code{ne2k_isa}, @code{rtl8139},
350@code{smc91c111} and @code{lance}. Not all devices are supported on all
351targets.
bellard1f673132004-04-04 15:21:17 +0000352
pbrook115defd2006-04-16 11:06:58 +0000353@item -net user[,vlan=n][,hostname=name]
bellard7e894632005-11-19 17:42:52 +0000354Use the user mode network stack which requires no administrator
pbrooka03a6052006-04-16 18:46:12 +0000355priviledge to run. @option{hostname=name} can be used to specify the client
pbrook115defd2006-04-16 11:06:58 +0000356hostname reported by the builtin DHCP server.
bellard3f1a88f2005-06-05 16:48:41 +0000357
bellard41d03942005-11-15 23:02:53 +0000358@item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
359Connect the host TAP network interface @var{name} to VLAN @var{n} and
360use the network script @var{file} to configure it. The default
ths6a1cbf62007-02-02 00:37:56 +0000361network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
362disable script execution. If @var{name} is not
bellard41d03942005-11-15 23:02:53 +0000363provided, the OS automatically provides one. @option{fd=h} can be
364used to specify the handle of an already opened host TAP interface. Example:
bellard3f1a88f2005-06-05 16:48:41 +0000365
bellard41d03942005-11-15 23:02:53 +0000366@example
367qemu linux.img -net nic -net tap
368@end example
bellard1f673132004-04-04 15:21:17 +0000369
bellard41d03942005-11-15 23:02:53 +0000370More complicated example (two NICs, each one connected to a TAP device)
371@example
372qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
373 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
374@end example
bellard1f673132004-04-04 15:21:17 +0000375
bellard52c00a52004-04-25 21:27:03 +0000376
bellard41d03942005-11-15 23:02:53 +0000377@item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
378
379Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
380machine using a TCP socket connection. If @option{listen} is
381specified, QEMU waits for incoming connections on @var{port}
382(@var{host} is optional). @option{connect} is used to connect to
bellard3d830452005-12-18 16:36:49 +0000383another QEMU instance using the @option{listen} option. @option{fd=h}
384specifies an already opened TCP socket.
bellard41d03942005-11-15 23:02:53 +0000385
386Example:
387@example
388# launch a first QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000389qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
390 -net socket,listen=:1234
391# connect the VLAN 0 of this instance to the VLAN 0
392# of the first instance
393qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
394 -net socket,connect=127.0.0.1:1234
bellard41d03942005-11-15 23:02:53 +0000395@end example
396
bellard3d830452005-12-18 16:36:49 +0000397@item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]
398
399Create a VLAN @var{n} shared with another QEMU virtual
400machines using a UDP multicast socket, effectively making a bus for
401every QEMU with same multicast address @var{maddr} and @var{port}.
402NOTES:
403@enumerate
404@item
405Several QEMU can be running on different hosts and share same bus (assuming
406correct multicast setup for these hosts).
407@item
408mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
409@url{http://user-mode-linux.sf.net}.
410@item Use @option{fd=h} to specify an already opened UDP multicast socket.
411@end enumerate
412
413Example:
414@example
415# launch one QEMU instance
bellarddebc7062006-04-30 21:58:41 +0000416qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
417 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000418# launch another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000419qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
420 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000421# launch yet another QEMU instance on same "bus"
bellarddebc7062006-04-30 21:58:41 +0000422qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
423 -net socket,mcast=230.0.0.1:1234
bellard3d830452005-12-18 16:36:49 +0000424@end example
425
426Example (User Mode Linux compat.):
427@example
bellarddebc7062006-04-30 21:58:41 +0000428# launch QEMU instance (note mcast address selected
429# is UML's default)
430qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
431 -net socket,mcast=239.192.168.1:1102
bellard3d830452005-12-18 16:36:49 +0000432# launch UML
433/path/to/linux ubd0=/path/to/root_fs eth0=mcast
434@end example
435
bellard41d03942005-11-15 23:02:53 +0000436@item -net none
437Indicate that no network devices should be configured. It is used to
bellard039af322006-02-01 21:30:55 +0000438override the default configuration (@option{-net nic -net user}) which
439is activated if no @option{-net} options are provided.
bellard52c00a52004-04-25 21:27:03 +0000440
bellard9bf05442004-08-25 22:12:49 +0000441@item -tftp prefix
442When using the user mode network stack, activate a built-in TFTP
443server. All filenames beginning with @var{prefix} can be downloaded
444from the host to the guest using a TFTP client. The TFTP client on the
445guest must be configured in binary mode (use the command @code{bin} of
446the Unix TFTP client). The host IP address on the guest is as usual
44710.0.2.2.
448
bellard2518bd02004-09-30 22:35:13 +0000449@item -smb dir
450When using the user mode network stack, activate a built-in SMB
451server so that Windows OSes can access to the host files in @file{dir}
452transparently.
453
454In the guest Windows OS, the line:
455@example
45610.0.2.4 smbserver
457@end example
458must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
459or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
460
461Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
462
463Note that a SAMBA server must be installed on the host OS in
ths366dfc52006-12-11 18:35:08 +0000464@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
bellard6cc721c2005-07-28 22:27:28 +00004652.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
bellard2518bd02004-09-30 22:35:13 +0000466
bellard9bf05442004-08-25 22:12:49 +0000467@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
468
469When using the user mode network stack, redirect incoming TCP or UDP
470connections to the host port @var{host-port} to the guest
471@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
472is not specified, its value is 10.0.2.15 (default address given by the
473built-in DHCP server).
474
475For example, to redirect host X11 connection from screen 1 to guest
476screen 0, use the following:
477
478@example
479# on the host
480qemu -redir tcp:6001::6000 [...]
481# this host xterm should open in the guest X11 server
482xterm -display :1
483@end example
484
485To redirect telnet connections from host port 5555 to telnet port on
486the guest, use the following:
487
488@example
489# on the host
490qemu -redir tcp:5555::23 [...]
491telnet localhost 5555
492@end example
493
494Then when you use on the host @code{telnet localhost 5555}, you
495connect to the guest telnet server.
496
bellard1f673132004-04-04 15:21:17 +0000497@end table
498
bellard41d03942005-11-15 23:02:53 +0000499Linux boot specific: When using these options, you can use a given
bellard1f673132004-04-04 15:21:17 +0000500Linux kernel without installing it in the disk image. It can be useful
501for easier testing of various kernels.
502
503@table @option
504
505@item -kernel bzImage
506Use @var{bzImage} as kernel image.
507
508@item -append cmdline
509Use @var{cmdline} as kernel command line
510
511@item -initrd file
512Use @var{file} as initial ram disk.
513
514@end table
515
bellard15a34c62004-07-08 21:26:26 +0000516Debug/Expert options:
bellard1f673132004-04-04 15:21:17 +0000517@table @option
bellarda0a821a2004-07-14 17:38:57 +0000518
519@item -serial dev
bellard0bab00f2006-06-25 14:49:44 +0000520Redirect the virtual serial port to host character device
521@var{dev}. The default device is @code{vc} in graphical mode and
522@code{stdio} in non graphical mode.
523
524This option can be used several times to simulate up to 4 serials
525ports.
526
bellardc03b0f02006-09-03 14:10:53 +0000527Use @code{-serial none} to disable all serial ports.
528
bellard0bab00f2006-06-25 14:49:44 +0000529Available character devices are:
bellarda0a821a2004-07-14 17:38:57 +0000530@table @code
531@item vc
532Virtual console
533@item pty
534[Linux only] Pseudo TTY (a new PTY is automatically allocated)
bellardc03b0f02006-09-03 14:10:53 +0000535@item none
536No device is allocated.
bellarda0a821a2004-07-14 17:38:57 +0000537@item null
538void device
bellardf8d179e2005-11-08 22:30:36 +0000539@item /dev/XXX
bellarde57a8c02005-11-10 23:58:52 +0000540[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
bellardf8d179e2005-11-08 22:30:36 +0000541parameters are set according to the emulated ones.
bellarde57a8c02005-11-10 23:58:52 +0000542@item /dev/parportN
543[Linux only, parallel port only] Use host parallel port
544@var{N}. Currently only SPP parallel port features can be used.
bellardf8d179e2005-11-08 22:30:36 +0000545@item file:filename
546Write output to filename. No character can be read.
bellarda0a821a2004-07-14 17:38:57 +0000547@item stdio
548[Unix only] standard input/output
bellardf8d179e2005-11-08 22:30:36 +0000549@item pipe:filename
bellard0bab00f2006-06-25 14:49:44 +0000550name pipe @var{filename}
551@item COMn
552[Windows only] Use host serial port @var{n}
bellard951f1352006-06-27 21:02:43 +0000553@item udp:[remote_host]:remote_port[@@[src_ip]:src_port]
554This implements UDP Net Console. When @var{remote_host} or @var{src_ip} are not specified they default to @code{0.0.0.0}. When not using a specifed @var{src_port} a random port is automatically chosen.
bellarda0a821a2004-07-14 17:38:57 +0000555
bellard951f1352006-06-27 21:02:43 +0000556If you just want a simple readonly console you can use @code{netcat} or
557@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
558@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
559will appear in the netconsole session.
bellard0bab00f2006-06-25 14:49:44 +0000560
561If you plan to send characters back via netconsole or you want to stop
562and start qemu a lot of times, you should have qemu use the same
563source port each time by using something like @code{-serial
bellard951f1352006-06-27 21:02:43 +0000564udp::4555@@:4556} to qemu. Another approach is to use a patched
bellard0bab00f2006-06-25 14:49:44 +0000565version of netcat which can listen to a TCP port and send and receive
566characters via udp. If you have a patched version of netcat which
567activates telnet remote echo and single char transfer, then you can
568use the following options to step up a netcat redirector to allow
569telnet on port 5555 to access the qemu port.
570@table @code
bellard951f1352006-06-27 21:02:43 +0000571@item Qemu Options:
572-serial udp::4555@@:4556
573@item netcat options:
574-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
575@item telnet options:
576localhost 5555
bellard0bab00f2006-06-25 14:49:44 +0000577@end table
578
579
pbrookf7499982007-01-28 00:10:01 +0000580@item tcp:[host]:port[,server][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000581The TCP Net Console has two modes of operation. It can send the serial
582I/O to a location or wait for a connection from a location. By default
583the TCP Net Console is sent to @var{host} at the @var{port}. If you use
bellardf5420862006-08-21 20:26:44 +0000584the @var{server} option QEMU will wait for a client socket application
585to connect to the port before continuing, unless the @code{nowait}
pbrookf7499982007-01-28 00:10:01 +0000586option was specified. The @code{nodelay} option disables the Nagle buffering
587algoritm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
bellard951f1352006-06-27 21:02:43 +0000588one TCP connection at a time is accepted. You can use @code{telnet} to
589connect to the corresponding character device.
590@table @code
591@item Example to send tcp console to 192.168.0.2 port 4444
592-serial tcp:192.168.0.2:4444
593@item Example to listen and wait on port 4444 for connection
594-serial tcp::4444,server
595@item Example to not wait and listen on ip 192.168.0.100 port 4444
596-serial tcp:192.168.0.100:4444,server,nowait
597@end table
598
pbrookf7499982007-01-28 00:10:01 +0000599@item telnet:host:port[,server][,nowait][,nodelay]
bellard951f1352006-06-27 21:02:43 +0000600The telnet protocol is used instead of raw tcp sockets. The options
601work the same as if you had specified @code{-serial tcp}. The
602difference is that the port acts like a telnet server or client using
603telnet option negotiation. This will also allow you to send the
604MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
605sequence. Typically in unix telnet you do it with Control-] and then
606type "send break" followed by pressing the enter key.
607
thsffd843b2006-12-21 19:46:43 +0000608@item unix:path[,server][,nowait]
609A unix domain socket is used instead of a tcp socket. The option works the
610same as if you had specified @code{-serial tcp} except the unix domain socket
611@var{path} is used for connections.
612
bellard0bab00f2006-06-25 14:49:44 +0000613@end table
bellard05d58182004-08-24 21:12:04 +0000614
bellarde57a8c02005-11-10 23:58:52 +0000615@item -parallel dev
616Redirect the virtual parallel port to host device @var{dev} (same
617devices as the serial port). On Linux hosts, @file{/dev/parportN} can
618be used to use hardware devices connected on the corresponding host
619parallel port.
620
621This option can be used several times to simulate up to 3 parallel
622ports.
623
bellardc03b0f02006-09-03 14:10:53 +0000624Use @code{-parallel none} to disable all parallel ports.
625
bellarda0a821a2004-07-14 17:38:57 +0000626@item -monitor dev
627Redirect the monitor to host device @var{dev} (same devices as the
628serial port).
629The default device is @code{vc} in graphical mode and @code{stdio} in
630non graphical mode.
631
bellard1f673132004-04-04 15:21:17 +0000632@item -s
bellarddebc7062006-04-30 21:58:41 +0000633Wait gdb connection to port 1234 (@pxref{gdb_usage}).
bellard1f673132004-04-04 15:21:17 +0000634@item -p port
pbrook4046d912007-01-28 01:53:16 +0000635Change gdb connection port. @var{port} can be either a decimal number
636to specify a TCP port, or a host device (same devices as the serial port).
bellard52c00a52004-04-25 21:27:03 +0000637@item -S
638Do not start CPU at startup (you must type 'c' in the monitor).
bellard1f673132004-04-04 15:21:17 +0000639@item -d
640Output log in /tmp/qemu.log
bellard46d47672004-11-16 01:45:27 +0000641@item -hdachs c,h,s,[,t]
642Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
643@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
644translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
645all thoses parameters. This option is useful for old MS-DOS disk
646images.
bellard7c3fc842005-02-10 21:46:47 +0000647
bellard87b47352006-08-17 17:22:54 +0000648@item -L path
649Set the directory for the BIOS, VGA BIOS and keymaps.
650
bellard15a34c62004-07-08 21:26:26 +0000651@item -std-vga
652Simulate a standard VGA card with Bochs VBE extensions (default is
bellard3cb08532006-06-21 21:19:50 +0000653Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
654VBE extensions (e.g. Windows XP) and if you want to use high
655resolution modes (>= 1280x1024x16) then you should use this option.
656
bellard3c656342006-07-14 13:13:51 +0000657@item -no-acpi
658Disable ACPI (Advanced Configuration and Power Interface) support. Use
659it if your guest OS complains about ACPI problems (PC target machine
660only).
661
bellardd1beab82006-10-02 19:44:22 +0000662@item -no-reboot
663Exit instead of rebooting.
664
bellardd63d3072004-10-03 13:29:03 +0000665@item -loadvm file
666Start right away with a saved state (@code{loadvm} in monitor)
pbrook8e716212007-01-20 17:12:09 +0000667
668@item -semihosting
669Enable "Angel" semihosting interface (ARM target machines only).
670Note that this allows guest direct access to the host filesystem,
671so should only be used with trusted guest OS.
bellard1f673132004-04-04 15:21:17 +0000672@end table
673
bellard3e11db92004-07-14 17:47:14 +0000674@c man end
675
bellarddebc7062006-04-30 21:58:41 +0000676@node pcsys_keys
bellard3e11db92004-07-14 17:47:14 +0000677@section Keys
678
679@c man begin OPTIONS
680
bellarda1b74fe2004-05-08 13:26:35 +0000681During the graphical emulation, you can use the following keys:
682@table @key
bellardf9859312004-10-03 14:33:10 +0000683@item Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000684Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000685
bellardf9859312004-10-03 14:33:10 +0000686@item Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000687Switch to virtual console 'n'. Standard console mappings are:
688@table @emph
689@item 1
690Target system display
691@item 2
692Monitor
693@item 3
694Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000695@end table
696
bellardf9859312004-10-03 14:33:10 +0000697@item Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000698Toggle mouse and keyboard grab.
699@end table
700
bellard3e11db92004-07-14 17:47:14 +0000701In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
702@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
703
bellarda0a821a2004-07-14 17:38:57 +0000704During emulation, if you are using the @option{-nographic} option, use
705@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000706
707@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000708@item Ctrl-a h
bellard1f673132004-04-04 15:21:17 +0000709Print this help
bellarda1b74fe2004-05-08 13:26:35 +0000710@item Ctrl-a x
ths366dfc52006-12-11 18:35:08 +0000711Exit emulator
bellarda1b74fe2004-05-08 13:26:35 +0000712@item Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000713Save disk data back to file (if -snapshot)
bellarda1b74fe2004-05-08 13:26:35 +0000714@item Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000715Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000716@item Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000717Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000718@item Ctrl-a Ctrl-a
719Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000720@end table
721@c man end
722
723@ignore
724
bellard1f673132004-04-04 15:21:17 +0000725@c man begin SEEALSO
726The HTML documentation of QEMU for more precise information and Linux
727user mode emulator invocation.
728@c man end
729
730@c man begin AUTHOR
731Fabrice Bellard
732@c man end
733
734@end ignore
735
bellarddebc7062006-04-30 21:58:41 +0000736@node pcsys_monitor
bellard1f673132004-04-04 15:21:17 +0000737@section QEMU Monitor
738
739The QEMU monitor is used to give complex commands to the QEMU
740emulator. You can use it to:
741
742@itemize @minus
743
744@item
745Remove or insert removable medias images
746(such as CD-ROM or floppies)
747
748@item
749Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
750from a disk file.
751
752@item Inspect the VM state without an external debugger.
753
754@end itemize
755
756@subsection Commands
757
758The following commands are available:
759
760@table @option
761
762@item help or ? [cmd]
763Show the help for all commands or just for command @var{cmd}.
764
765@item commit
766Commit changes to the disk images (if -snapshot is used)
767
768@item info subcommand
769show various information about the system state
770
771@table @option
772@item info network
bellard41d03942005-11-15 23:02:53 +0000773show the various VLANs and the associated devices
bellard1f673132004-04-04 15:21:17 +0000774@item info block
775show the block devices
776@item info registers
777show the cpu registers
778@item info history
779show the command line history
bellardb389dbf2005-11-06 16:49:55 +0000780@item info pci
781show emulated PCI device
782@item info usb
783show USB devices plugged on the virtual USB hub
784@item info usbhost
785show all USB host devices
bellarda3c25992006-07-18 21:09:59 +0000786@item info capture
787show information about active capturing
bellard13a2e802006-08-06 14:50:31 +0000788@item info snapshots
789show list of VM snapshots
ths455204e2007-01-05 16:42:13 +0000790@item info mice
791show which guest mouse is receiving events
bellard1f673132004-04-04 15:21:17 +0000792@end table
793
794@item q or quit
795Quit the emulator.
796
797@item eject [-f] device
798Eject a removable media (use -f to force it).
799
800@item change device filename
801Change a removable media.
802
803@item screendump filename
804Save screen into PPM image @var{filename}.
805
ths455204e2007-01-05 16:42:13 +0000806@item mouse_move dx dy [dz]
807Move the active mouse to the specified coordinates @var{dx} @var{dy}
808with optional scroll axis @var{dz}.
809
810@item mouse_button val
811Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
812
813@item mouse_set index
814Set which mouse device receives events at given @var{index}, index
815can be obtained with
816@example
817info mice
818@end example
819
bellarda3c25992006-07-18 21:09:59 +0000820@item wavcapture filename [frequency [bits [channels]]]
821Capture audio into @var{filename}. Using sample rate @var{frequency}
822bits per sample @var{bits} and number of channels @var{channels}.
823
824Defaults:
825@itemize @minus
826@item Sample rate = 44100 Hz - CD quality
827@item Bits = 16
828@item Number of channels = 2 - Stereo
829@end itemize
830
831@item stopcapture index
832Stop capture with a given @var{index}, index can be obtained with
833@example
834info capture
835@end example
836
bellard1f673132004-04-04 15:21:17 +0000837@item log item1[,...]
838Activate logging of the specified items to @file{/tmp/qemu.log}.
839
bellard13a2e802006-08-06 14:50:31 +0000840@item savevm [tag|id]
841Create a snapshot of the whole virtual machine. If @var{tag} is
842provided, it is used as human readable identifier. If there is already
843a snapshot with the same tag or ID, it is replaced. More info at
844@ref{vm_snapshots}.
bellard1f673132004-04-04 15:21:17 +0000845
bellard13a2e802006-08-06 14:50:31 +0000846@item loadvm tag|id
847Set the whole virtual machine to the snapshot identified by the tag
848@var{tag} or the unique snapshot ID @var{id}.
849
850@item delvm tag|id
851Delete the snapshot identified by @var{tag} or @var{id}.
bellard1f673132004-04-04 15:21:17 +0000852
853@item stop
854Stop emulation.
855
856@item c or cont
857Resume emulation.
858
859@item gdbserver [port]
860Start gdbserver session (default port=1234)
861
862@item x/fmt addr
863Virtual memory dump starting at @var{addr}.
864
865@item xp /fmt addr
866Physical memory dump starting at @var{addr}.
867
868@var{fmt} is a format which tells the command how to format the
869data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
870
871@table @var
872@item count
873is the number of items to be dumped.
874
875@item format
876can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
877c (char) or i (asm instruction).
878
879@item size
bellard52c00a52004-04-25 21:27:03 +0000880can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
881@code{h} or @code{w} can be specified with the @code{i} format to
882respectively select 16 or 32 bit code instruction size.
bellard1f673132004-04-04 15:21:17 +0000883
884@end table
885
886Examples:
887@itemize
888@item
889Dump 10 instructions at the current instruction pointer:
890@example
891(qemu) x/10i $eip
8920x90107063: ret
8930x90107064: sti
8940x90107065: lea 0x0(%esi,1),%esi
8950x90107069: lea 0x0(%edi,1),%edi
8960x90107070: ret
8970x90107071: jmp 0x90107080
8980x90107073: nop
8990x90107074: nop
9000x90107075: nop
9010x90107076: nop
902@end example
903
904@item
905Dump 80 16 bit values at the start of the video memory.
bellarddebc7062006-04-30 21:58:41 +0000906@smallexample
bellard1f673132004-04-04 15:21:17 +0000907(qemu) xp/80hx 0xb8000
9080x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
9090x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
9100x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
9110x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
9120x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
9130x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
9140x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
9150x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
9160x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
9170x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
bellarddebc7062006-04-30 21:58:41 +0000918@end smallexample
bellard1f673132004-04-04 15:21:17 +0000919@end itemize
920
921@item p or print/fmt expr
922
923Print expression value. Only the @var{format} part of @var{fmt} is
924used.
925
bellarda3a91a32004-06-04 11:06:21 +0000926@item sendkey keys
927
928Send @var{keys} to the emulator. Use @code{-} to press several keys
929simultaneously. Example:
930@example
931sendkey ctrl-alt-f1
932@end example
933
934This command is useful to send keys that your graphical user interface
935intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
936
bellard15a34c62004-07-08 21:26:26 +0000937@item system_reset
938
939Reset the system.
940
bellardb389dbf2005-11-06 16:49:55 +0000941@item usb_add devname
942
pbrook0aff66b2006-05-26 00:49:52 +0000943Add the USB device @var{devname}. For details of available devices see
944@ref{usb_devices}
bellardb389dbf2005-11-06 16:49:55 +0000945
946@item usb_del devname
947
948Remove the USB device @var{devname} from the QEMU virtual USB
949hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
950command @code{info usb} to see the devices you can remove.
951
bellard1f673132004-04-04 15:21:17 +0000952@end table
953
954@subsection Integer expressions
955
956The monitor understands integers expressions for every integer
957argument. You can use register names to get the value of specifics
958CPU registers by prefixing them with @emph{$}.
959
960@node disk_images
961@section Disk Images
962
bellardacd935e2004-11-15 22:57:26 +0000963Since version 0.6.1, QEMU supports many disk image formats, including
964growable disk images (their size increase as non empty sectors are
bellard13a2e802006-08-06 14:50:31 +0000965written), compressed and encrypted disk images. Version 0.8.3 added
966the new qcow2 disk image format which is essential to support VM
967snapshots.
bellard1f673132004-04-04 15:21:17 +0000968
bellarddebc7062006-04-30 21:58:41 +0000969@menu
970* disk_images_quickstart:: Quick start for disk image creation
971* disk_images_snapshot_mode:: Snapshot mode
bellard13a2e802006-08-06 14:50:31 +0000972* vm_snapshots:: VM snapshots
bellarddebc7062006-04-30 21:58:41 +0000973* qemu_img_invocation:: qemu-img Invocation
bellard19cb3732006-08-19 11:45:59 +0000974* host_drives:: Using host drives
bellarddebc7062006-04-30 21:58:41 +0000975* disk_images_fat_images:: Virtual FAT disk images
976@end menu
977
978@node disk_images_quickstart
bellardacd935e2004-11-15 22:57:26 +0000979@subsection Quick start for disk image creation
980
981You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000982@example
bellardacd935e2004-11-15 22:57:26 +0000983qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000984@end example
bellardacd935e2004-11-15 22:57:26 +0000985where @var{myimage.img} is the disk image filename and @var{mysize} is its
986size in kilobytes. You can add an @code{M} suffix to give the size in
987megabytes and a @code{G} suffix for gigabytes.
988
bellarddebc7062006-04-30 21:58:41 +0000989See @ref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000990
bellarddebc7062006-04-30 21:58:41 +0000991@node disk_images_snapshot_mode
bellard1f673132004-04-04 15:21:17 +0000992@subsection Snapshot mode
993
994If you use the option @option{-snapshot}, all disk images are
995considered as read only. When sectors in written, they are written in
996a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000997write back to the raw disk images by using the @code{commit} monitor
998command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000999
bellard13a2e802006-08-06 14:50:31 +00001000@node vm_snapshots
1001@subsection VM snapshots
1002
1003VM snapshots are snapshots of the complete virtual machine including
1004CPU state, RAM, device state and the content of all the writable
1005disks. In order to use VM snapshots, you must have at least one non
1006removable and writable block device using the @code{qcow2} disk image
1007format. Normally this device is the first virtual hard drive.
1008
1009Use the monitor command @code{savevm} to create a new VM snapshot or
1010replace an existing one. A human readable name can be assigned to each
bellard19d36792006-08-07 21:34:34 +00001011snapshot in addition to its numerical ID.
bellard13a2e802006-08-06 14:50:31 +00001012
1013Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1014a VM snapshot. @code{info snapshots} lists the available snapshots
1015with their associated information:
1016
1017@example
1018(qemu) info snapshots
1019Snapshot devices: hda
1020Snapshot list (from hda):
1021ID TAG VM SIZE DATE VM CLOCK
10221 start 41M 2006-08-06 12:38:02 00:00:14.954
10232 40M 2006-08-06 12:43:29 00:00:18.633
10243 msys 40M 2006-08-06 12:44:04 00:00:23.514
1025@end example
1026
1027A VM snapshot is made of a VM state info (its size is shown in
1028@code{info snapshots}) and a snapshot of every writable disk image.
1029The VM state info is stored in the first @code{qcow2} non removable
1030and writable block device. The disk image snapshots are stored in
1031every disk image. The size of a snapshot in a disk image is difficult
1032to evaluate and is not shown by @code{info snapshots} because the
1033associated disk sectors are shared among all the snapshots to save
bellard19d36792006-08-07 21:34:34 +00001034disk space (otherwise each snapshot would need a full copy of all the
1035disk images).
bellard13a2e802006-08-06 14:50:31 +00001036
1037When using the (unrelated) @code{-snapshot} option
1038(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1039but they are deleted as soon as you exit QEMU.
1040
1041VM snapshots currently have the following known limitations:
1042@itemize
1043@item
1044They cannot cope with removable devices if they are removed or
1045inserted after a snapshot is done.
1046@item
1047A few device drivers still have incomplete snapshot support so their
1048state is not saved or restored properly (in particular USB).
1049@end itemize
1050
bellardacd935e2004-11-15 22:57:26 +00001051@node qemu_img_invocation
1052@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +00001053
bellardacd935e2004-11-15 22:57:26 +00001054@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +00001055
bellard19cb3732006-08-19 11:45:59 +00001056@node host_drives
1057@subsection Using host drives
1058
1059In addition to disk image files, QEMU can directly access host
1060devices. We describe here the usage for QEMU version >= 0.8.3.
1061
1062@subsubsection Linux
1063
1064On Linux, you can directly use the host device filename instead of a
1065disk image filename provided you have enough proviledge to access
1066it. For example, use @file{/dev/cdrom} to access to the CDROM or
1067@file{/dev/fd0} for the floppy.
1068
bellardf5420862006-08-21 20:26:44 +00001069@table @code
bellard19cb3732006-08-19 11:45:59 +00001070@item CD
1071You can specify a CDROM device even if no CDROM is loaded. QEMU has
1072specific code to detect CDROM insertion or removal. CDROM ejection by
1073the guest OS is supported. Currently only data CDs are supported.
1074@item Floppy
1075You can specify a floppy device even if no floppy is loaded. Floppy
1076removal is currently not detected accurately (if you change floppy
1077without doing floppy access while the floppy is not loaded, the guest
1078OS will think that the same floppy is loaded).
1079@item Hard disks
1080Hard disks can be used. Normally you must specify the whole disk
1081(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1082see it as a partitioned disk. WARNING: unless you know what you do, it
1083is better to only make READ-ONLY accesses to the hard disk otherwise
1084you may corrupt your host data (use the @option{-snapshot} command
1085line option or modify the device permissions accordingly).
1086@end table
1087
1088@subsubsection Windows
1089
bellard01781962007-01-07 22:43:30 +00001090@table @code
1091@item CD
1092The prefered syntax is the drive letter (e.g. @file{d:}). The
1093alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1094supported as an alias to the first CDROM drive.
bellard19cb3732006-08-19 11:45:59 +00001095
1096Currently there is no specific code to handle removable medias, so it
1097is better to use the @code{change} or @code{eject} monitor commands to
1098change or eject media.
bellard01781962007-01-07 22:43:30 +00001099@item Hard disks
1100Hard disks can be used with the syntax: @file{\\.\PhysicalDriveN}
1101where @var{N} is the drive number (0 is the first hard disk).
1102
1103WARNING: unless you know what you do, it is better to only make
1104READ-ONLY accesses to the hard disk otherwise you may corrupt your
1105host data (use the @option{-snapshot} command line so that the
1106modifications are written in a temporary file).
1107@end table
1108
bellard19cb3732006-08-19 11:45:59 +00001109
1110@subsubsection Mac OS X
1111
1112@file{/dev/cdrom} is an alias to the first CDROM.
1113
1114Currently there is no specific code to handle removable medias, so it
1115is better to use the @code{change} or @code{eject} monitor commands to
1116change or eject media.
1117
bellarddebc7062006-04-30 21:58:41 +00001118@node disk_images_fat_images
bellard2c6cadd2005-12-18 18:31:45 +00001119@subsection Virtual FAT disk images
1120
1121QEMU can automatically create a virtual FAT disk image from a
1122directory tree. In order to use it, just type:
1123
1124@example
1125qemu linux.img -hdb fat:/my_directory
1126@end example
1127
1128Then you access access to all the files in the @file{/my_directory}
1129directory without having to copy them in a disk image or to export
1130them via SAMBA or NFS. The default access is @emph{read-only}.
1131
1132Floppies can be emulated with the @code{:floppy:} option:
1133
1134@example
1135qemu linux.img -fda fat:floppy:/my_directory
1136@end example
1137
1138A read/write support is available for testing (beta stage) with the
1139@code{:rw:} option:
1140
1141@example
1142qemu linux.img -fda fat:floppy:rw:/my_directory
1143@end example
1144
1145What you should @emph{never} do:
1146@itemize
1147@item use non-ASCII filenames ;
1148@item use "-snapshot" together with ":rw:" ;
bellard85b2c682005-12-19 22:12:34 +00001149@item expect it to work when loadvm'ing ;
1150@item write to the FAT directory on the host system while accessing it with the guest system.
bellard2c6cadd2005-12-18 18:31:45 +00001151@end itemize
1152
bellarddebc7062006-04-30 21:58:41 +00001153@node pcsys_network
bellard9d4fb822004-04-26 20:55:38 +00001154@section Network emulation
1155
bellard41d03942005-11-15 23:02:53 +00001156QEMU can simulate several networks cards (NE2000 boards on the PC
1157target) and can connect them to an arbitrary number of Virtual Local
1158Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1159VLAN. VLAN can be connected between separate instances of QEMU to
1160simulate large networks. For simpler usage, a non priviledged user mode
1161network stack can replace the TAP device to have a basic network
1162connection.
bellard9d4fb822004-04-26 20:55:38 +00001163
bellard41d03942005-11-15 23:02:53 +00001164@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +00001165
bellard41d03942005-11-15 23:02:53 +00001166QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1167connection between several network devices. These devices can be for
1168example QEMU virtual Ethernet cards or virtual Host ethernet devices
1169(TAP devices).
1170
1171@subsection Using TAP network interfaces
1172
1173This is the standard way to connect QEMU to a real network. QEMU adds
1174a virtual network device on your host (called @code{tapN}), and you
1175can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +00001176
bellard8f40c382006-09-20 20:28:05 +00001177@subsubsection Linux host
1178
bellard9d4fb822004-04-26 20:55:38 +00001179As an example, you can download the @file{linux-test-xxx.tar.gz}
1180archive and copy the script @file{qemu-ifup} in @file{/etc} and
1181configure properly @code{sudo} so that the command @code{ifconfig}
1182contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +00001183that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +00001184device @file{/dev/net/tun} must be present.
1185
bellardee0f4752006-08-19 16:56:18 +00001186See @ref{sec_invocation} to have examples of command lines using the
1187TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +00001188
bellard8f40c382006-09-20 20:28:05 +00001189@subsubsection Windows host
1190
1191There is a virtual ethernet driver for Windows 2000/XP systems, called
1192TAP-Win32. But it is not included in standard QEMU for Windows,
1193so you will need to get it separately. It is part of OpenVPN package,
1194so download OpenVPN from : @url{http://openvpn.net/}.
1195
bellard9d4fb822004-04-26 20:55:38 +00001196@subsection Using the user mode network stack
1197
bellard41d03942005-11-15 23:02:53 +00001198By using the option @option{-net user} (default configuration if no
1199@option{-net} option is specified), QEMU uses a completely user mode
1200network stack (you don't need root priviledge to use the virtual
1201network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +00001202
1203@example
1204
bellard41d03942005-11-15 23:02:53 +00001205 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1206 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +00001207 |
bellard2518bd02004-09-30 22:35:13 +00001208 ----> DNS server (10.0.2.3)
1209 |
1210 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +00001211@end example
1212
1213The QEMU VM behaves as if it was behind a firewall which blocks all
1214incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +00001215configure the network in the QEMU VM. The DHCP server assign addresses
1216to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +00001217
1218In order to check that the user mode network is working, you can ping
1219the address 10.0.2.2 and verify that you got an address in the range
122010.0.2.x from the QEMU virtual DHCP server.
1221
bellardb415a402004-05-23 21:04:06 +00001222Note that @code{ping} is not supported reliably to the internet as it
1223would require root priviledges. It means you can only ping the local
1224router (10.0.2.2).
1225
bellard9bf05442004-08-25 22:12:49 +00001226When using the built-in TFTP server, the router is also the TFTP
1227server.
1228
1229When using the @option{-redir} option, TCP or UDP connections can be
1230redirected from the host to the guest. It allows for example to
1231redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +00001232
bellard41d03942005-11-15 23:02:53 +00001233@subsection Connecting VLANs between QEMU instances
1234
1235Using the @option{-net socket} option, it is possible to make VLANs
1236that span several QEMU instances. See @ref{sec_invocation} to have a
1237basic example.
1238
bellard9d4fb822004-04-26 20:55:38 +00001239@node direct_linux_boot
1240@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +00001241
1242This section explains how to launch a Linux kernel inside QEMU without
1243having to make a full bootable image. It is very useful for fast Linux
bellardee0f4752006-08-19 16:56:18 +00001244kernel testing.
bellard1eb20522003-06-25 16:21:49 +00001245
bellardee0f4752006-08-19 16:56:18 +00001246The syntax is:
bellard1eb20522003-06-25 16:21:49 +00001247@example
bellardee0f4752006-08-19 16:56:18 +00001248qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard1eb20522003-06-25 16:21:49 +00001249@end example
1250
bellardee0f4752006-08-19 16:56:18 +00001251Use @option{-kernel} to provide the Linux kernel image and
1252@option{-append} to give the kernel command line arguments. The
1253@option{-initrd} option can be used to provide an INITRD image.
1254
1255When using the direct Linux boot, a disk image for the first hard disk
1256@file{hda} is required because its boot sector is used to launch the
1257Linux kernel.
1258
1259If you do not need graphical output, you can disable it and redirect
1260the virtual serial port and the QEMU monitor to the console with the
1261@option{-nographic} option. The typical command line is:
bellard1eb20522003-06-25 16:21:49 +00001262@example
bellardee0f4752006-08-19 16:56:18 +00001263qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1264 -append "root=/dev/hda console=ttyS0" -nographic
bellard1eb20522003-06-25 16:21:49 +00001265@end example
1266
bellardee0f4752006-08-19 16:56:18 +00001267Use @key{Ctrl-a c} to switch between the serial console and the
1268monitor (@pxref{pcsys_keys}).
bellardd5a0b502003-06-27 12:02:03 +00001269
bellarddebc7062006-04-30 21:58:41 +00001270@node pcsys_usb
bellardb389dbf2005-11-06 16:49:55 +00001271@section USB emulation
1272
pbrook0aff66b2006-05-26 00:49:52 +00001273QEMU emulates a PCI UHCI USB controller. You can virtually plug
1274virtual USB devices or real host USB devices (experimental, works only
1275on Linux hosts). Qemu will automatically create and connect virtual USB hubs
bellardf5420862006-08-21 20:26:44 +00001276as necessary to connect multiple USB devices.
bellardb389dbf2005-11-06 16:49:55 +00001277
pbrook0aff66b2006-05-26 00:49:52 +00001278@menu
1279* usb_devices::
1280* host_usb_devices::
1281@end menu
1282@node usb_devices
1283@subsection Connecting USB devices
bellardb389dbf2005-11-06 16:49:55 +00001284
pbrook0aff66b2006-05-26 00:49:52 +00001285USB devices can be connected with the @option{-usbdevice} commandline option
1286or the @code{usb_add} monitor command. Available devices are:
bellardb389dbf2005-11-06 16:49:55 +00001287
pbrook0aff66b2006-05-26 00:49:52 +00001288@table @var
1289@item @code{mouse}
1290Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1291@item @code{tablet}
bellardc6d46c22006-09-03 17:10:41 +00001292Pointer device that uses absolute coordinates (like a touchscreen).
pbrook0aff66b2006-05-26 00:49:52 +00001293This means qemu is able to report the mouse position without having
1294to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
1295@item @code{disk:file}
1296Mass storage device based on @var{file} (@pxref{disk_images})
1297@item @code{host:bus.addr}
1298Pass through the host device identified by @var{bus.addr}
1299(Linux only)
1300@item @code{host:vendor_id:product_id}
1301Pass through the host device identified by @var{vendor_id:product_id}
1302(Linux only)
1303@end table
bellardb389dbf2005-11-06 16:49:55 +00001304
pbrook0aff66b2006-05-26 00:49:52 +00001305@node host_usb_devices
bellardb389dbf2005-11-06 16:49:55 +00001306@subsection Using host USB devices on a Linux host
1307
1308WARNING: this is an experimental feature. QEMU will slow down when
1309using it. USB devices requiring real time streaming (i.e. USB Video
1310Cameras) are not supported yet.
1311
1312@enumerate
1313@item If you use an early Linux 2.4 kernel, verify that no Linux driver
1314is actually using the USB device. A simple way to do that is simply to
1315disable the corresponding kernel module by renaming it from @file{mydriver.o}
1316to @file{mydriver.o.disabled}.
1317
1318@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1319@example
1320ls /proc/bus/usb
1321001 devices drivers
1322@end example
1323
1324@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:
1325@example
1326chown -R myuid /proc/bus/usb
1327@end example
1328
1329@item Launch QEMU and do in the monitor:
1330@example
1331info usbhost
1332 Device 1.2, speed 480 Mb/s
1333 Class 00: USB device 1234:5678, USB DISK
1334@end example
1335You should see the list of the devices you can use (Never try to use
1336hubs, it won't work).
1337
1338@item Add the device in QEMU by using:
1339@example
1340usb_add host:1234:5678
1341@end example
1342
1343Normally the guest OS should report that a new USB device is
1344plugged. You can use the option @option{-usbdevice} to do the same.
1345
1346@item Now you can try to use the host USB device in QEMU.
1347
1348@end enumerate
1349
1350When relaunching QEMU, you may have to unplug and plug again the USB
1351device to make it work again (this is a bug).
1352
bellard0806e3f2003-10-01 00:15:32 +00001353@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001354@section GDB usage
1355
1356QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001357'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001358
bellard9d4520d2003-10-28 01:38:57 +00001359In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001360gdb connection:
1361@example
bellarddebc7062006-04-30 21:58:41 +00001362> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1363 -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001364Connected to host network interface: tun0
1365Waiting gdb connection on port 1234
1366@end example
1367
1368Then launch gdb on the 'vmlinux' executable:
1369@example
1370> gdb vmlinux
1371@end example
1372
1373In gdb, connect to QEMU:
1374@example
bellard6c9bf892004-01-24 13:46:56 +00001375(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001376@end example
1377
1378Then you can use gdb normally. For example, type 'c' to launch the kernel:
1379@example
1380(gdb) c
1381@end example
1382
bellard0806e3f2003-10-01 00:15:32 +00001383Here are some useful tips in order to use gdb on system code:
1384
1385@enumerate
1386@item
1387Use @code{info reg} to display all the CPU registers.
1388@item
1389Use @code{x/10i $eip} to display the code at the PC position.
1390@item
1391Use @code{set architecture i8086} to dump 16 bit code. Then use
bellard294e8632006-05-06 14:23:06 +00001392@code{x/10i $cs*16+$eip} to dump the code at the PC position.
bellard0806e3f2003-10-01 00:15:32 +00001393@end enumerate
1394
bellarddebc7062006-04-30 21:58:41 +00001395@node pcsys_os_specific
bellard1a084f32004-05-13 22:34:49 +00001396@section Target OS specific information
1397
1398@subsection Linux
1399
bellard15a34c62004-07-08 21:26:26 +00001400To have access to SVGA graphic modes under X11, use the @code{vesa} or
1401the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1402color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001403
bellarde3371e62004-07-10 16:26:02 +00001404When using a 2.6 guest Linux kernel, you should add the option
1405@code{clock=pit} on the kernel command line because the 2.6 Linux
1406kernels make very strict real time clock checks by default that QEMU
1407cannot simulate exactly.
1408
bellard7c3fc842005-02-10 21:46:47 +00001409When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1410not activated because QEMU is slower with this patch. The QEMU
1411Accelerator Module is also much slower in this case. Earlier Fedora
1412Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
1413patch by default. Newer kernels don't have it.
1414
bellard1a084f32004-05-13 22:34:49 +00001415@subsection Windows
1416
1417If you have a slow host, using Windows 95 is better as it gives the
1418best speed. Windows 2000 is also a good choice.
1419
bellarde3371e62004-07-10 16:26:02 +00001420@subsubsection SVGA graphic modes support
1421
1422QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001423card. All Windows versions starting from Windows 95 should recognize
1424and use this graphic card. For optimal performances, use 16 bit color
1425depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001426
bellard3cb08532006-06-21 21:19:50 +00001427If you are using Windows XP as guest OS and if you want to use high
1428resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
14291280x1024x16), then you should use the VESA VBE virtual graphic card
1430(option @option{-std-vga}).
1431
bellarde3371e62004-07-10 16:26:02 +00001432@subsubsection CPU usage reduction
1433
1434Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001435instruction. The result is that it takes host CPU cycles even when
1436idle. You can install the utility from
1437@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1438problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001439
bellard9d0a8e62005-07-03 17:34:05 +00001440@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001441
bellard9d0a8e62005-07-03 17:34:05 +00001442Windows 2000 has a bug which gives a disk full problem during its
1443installation. When installing it, use the @option{-win2k-hack} QEMU
1444option to enable a specific workaround. After Windows 2000 is
1445installed, you no longer need this option (this option slows down the
1446IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001447
bellard6cc721c2005-07-28 22:27:28 +00001448@subsubsection Windows 2000 shutdown
1449
1450Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1451can. It comes from the fact that Windows 2000 does not automatically
1452use the APM driver provided by the BIOS.
1453
1454In order to correct that, do the following (thanks to Struan
1455Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1456Add/Troubleshoot a device => Add a new device & Next => No, select the
1457hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1458(again) a few times. Now the driver is installed and Windows 2000 now
1459correctly instructs QEMU to shutdown at the appropriate moment.
1460
1461@subsubsection Share a directory between Unix and Windows
1462
1463See @ref{sec_invocation} about the help of the option @option{-smb}.
1464
bellard2192c332006-08-21 20:28:18 +00001465@subsubsection Windows XP security problem
bellarde3371e62004-07-10 16:26:02 +00001466
1467Some releases of Windows XP install correctly but give a security
1468error when booting:
1469@example
1470A problem is preventing Windows from accurately checking the
1471license for this computer. Error code: 0x800703e6.
1472@end example
bellarde3371e62004-07-10 16:26:02 +00001473
bellard2192c332006-08-21 20:28:18 +00001474The workaround is to install a service pack for XP after a boot in safe
1475mode. Then reboot, and the problem should go away. Since there is no
1476network while in safe mode, its recommended to download the full
1477installation of SP1 or SP2 and transfer that via an ISO or using the
1478vvfat block device ("-hdb fat:directory_which_holds_the_SP").
bellarde3371e62004-07-10 16:26:02 +00001479
bellarda0a821a2004-07-14 17:38:57 +00001480@subsection MS-DOS and FreeDOS
1481
1482@subsubsection CPU usage reduction
1483
1484DOS does not correctly use the CPU HLT instruction. The result is that
1485it takes host CPU cycles even when idle. You can install the utility
1486from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1487problem.
1488
bellarddebc7062006-04-30 21:58:41 +00001489@node QEMU System emulator for non PC targets
bellard3f9f3aa2005-12-18 20:11:37 +00001490@chapter QEMU System emulator for non PC targets
1491
1492QEMU is a generic emulator and it emulates many non PC
1493machines. Most of the options are similar to the PC emulator. The
1494differences are mentionned in the following sections.
1495
bellarddebc7062006-04-30 21:58:41 +00001496@menu
1497* QEMU PowerPC System emulator::
1498* Sparc32 System emulator invocation::
1499* Sparc64 System emulator invocation::
1500* MIPS System emulator invocation::
1501* ARM System emulator invocation::
1502@end menu
1503
1504@node QEMU PowerPC System emulator
bellard3f9f3aa2005-12-18 20:11:37 +00001505@section QEMU PowerPC System emulator
bellard52c00a52004-04-25 21:27:03 +00001506
1507Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001508or PowerMac PowerPC system.
1509
bellardb671f9e2005-04-30 15:08:33 +00001510QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001511
1512@itemize @minus
1513@item
1514UniNorth PCI Bridge
1515@item
1516PCI VGA compatible card with VESA Bochs Extensions
1517@item
15182 PMAC IDE interfaces with hard disk and CD-ROM support
1519@item
1520NE2000 PCI adapters
1521@item
1522Non Volatile RAM
1523@item
1524VIA-CUDA with ADB keyboard and mouse.
1525@end itemize
bellard52c00a52004-04-25 21:27:03 +00001526
bellardb671f9e2005-04-30 15:08:33 +00001527QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001528
1529@itemize @minus
1530@item
bellard15a34c62004-07-08 21:26:26 +00001531PCI Bridge
1532@item
1533PCI VGA compatible card with VESA Bochs Extensions
1534@item
bellard52c00a52004-04-25 21:27:03 +000015352 IDE interfaces with hard disk and CD-ROM support
1536@item
1537Floppy disk
1538@item
bellard15a34c62004-07-08 21:26:26 +00001539NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001540@item
1541Serial port
1542@item
1543PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001544@item
1545PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001546@end itemize
1547
bellard15a34c62004-07-08 21:26:26 +00001548QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard3f9f3aa2005-12-18 20:11:37 +00001549@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard52c00a52004-04-25 21:27:03 +00001550
bellard15a34c62004-07-08 21:26:26 +00001551@c man begin OPTIONS
1552
1553The following options are specific to the PowerPC emulation:
1554
1555@table @option
1556
bellard15a34c62004-07-08 21:26:26 +00001557@item -g WxH[xDEPTH]
1558
1559Set the initial VGA graphic mode. The default is 800x600x15.
1560
1561@end table
1562
1563@c man end
1564
1565
bellard52c00a52004-04-25 21:27:03 +00001566More information is available at
bellard3f9f3aa2005-12-18 20:11:37 +00001567@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard52c00a52004-04-25 21:27:03 +00001568
bellarddebc7062006-04-30 21:58:41 +00001569@node Sparc32 System emulator invocation
bellard3f9f3aa2005-12-18 20:11:37 +00001570@section Sparc32 System emulator invocation
bellarde80cfcf2004-12-19 23:18:01 +00001571
bellard0986ac32006-06-14 12:36:32 +00001572Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5
bellard34751872005-07-02 14:31:34 +00001573(sun4m architecture). The emulation is somewhat complete.
bellarde80cfcf2004-12-19 23:18:01 +00001574
bellardb671f9e2005-04-30 15:08:33 +00001575QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00001576
1577@itemize @minus
bellard34751872005-07-02 14:31:34 +00001578@item
bellarde80cfcf2004-12-19 23:18:01 +00001579IOMMU
1580@item
1581TCX Frame buffer
1582@item
1583Lance (Am7990) Ethernet
1584@item
1585Non Volatile RAM M48T08
1586@item
bellard34751872005-07-02 14:31:34 +00001587Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1588and power/reset logic
1589@item
1590ESP SCSI controller with hard disk and CD-ROM support
1591@item
1592Floppy drive
bellarde80cfcf2004-12-19 23:18:01 +00001593@end itemize
1594
bellard34751872005-07-02 14:31:34 +00001595The number of peripherals is fixed in the architecture.
bellarde80cfcf2004-12-19 23:18:01 +00001596
bellard30a604f2006-06-14 18:35:18 +00001597Since version 0.8.2, QEMU uses OpenBIOS
bellard0986ac32006-06-14 12:36:32 +00001598@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1599firmware implementation. The goal is to implement a 100% IEEE
16001275-1994 (referred to as Open Firmware) compliant firmware.
bellard34751872005-07-02 14:31:34 +00001601
1602A sample Linux 2.6 series kernel and ram disk image are available on
bellard0986ac32006-06-14 12:36:32 +00001603the QEMU web site. Please note that currently NetBSD, OpenBSD or
1604Solaris kernels don't work.
bellard34751872005-07-02 14:31:34 +00001605
1606@c man begin OPTIONS
1607
1608The following options are specific to the Sparc emulation:
1609
1610@table @option
1611
1612@item -g WxH
1613
1614Set the initial TCX graphic mode. The default is 1024x768.
1615
1616@end table
1617
1618@c man end
1619
bellarddebc7062006-04-30 21:58:41 +00001620@node Sparc64 System emulator invocation
bellard3f9f3aa2005-12-18 20:11:37 +00001621@section Sparc64 System emulator invocation
bellard34751872005-07-02 14:31:34 +00001622
1623Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
1624The emulator is not usable for anything yet.
bellardb7569212005-03-13 09:43:05 +00001625
bellard83469012005-07-23 14:27:54 +00001626QEMU emulates the following sun4u peripherals:
1627
1628@itemize @minus
1629@item
1630UltraSparc IIi APB PCI Bridge
1631@item
1632PCI VGA compatible card with VESA Bochs Extensions
1633@item
1634Non Volatile RAM M48T59
1635@item
1636PC-compatible serial ports
1637@end itemize
1638
bellarddebc7062006-04-30 21:58:41 +00001639@node MIPS System emulator invocation
bellard3f9f3aa2005-12-18 20:11:37 +00001640@section MIPS System emulator invocation
bellard9d0a8e62005-07-03 17:34:05 +00001641
1642Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
bellard3f9f3aa2005-12-18 20:11:37 +00001643The emulator is able to boot a Linux kernel and to run a Linux Debian
1644installation from NFS. The following devices are emulated:
bellard9d0a8e62005-07-03 17:34:05 +00001645
bellard3f9f3aa2005-12-18 20:11:37 +00001646@itemize @minus
1647@item
1648MIPS R4K CPU
1649@item
1650PC style serial port
1651@item
1652NE2000 network card
1653@end itemize
1654
1655More information is available in the QEMU mailing-list archive.
1656
bellarddebc7062006-04-30 21:58:41 +00001657@node ARM System emulator invocation
bellard3f9f3aa2005-12-18 20:11:37 +00001658@section ARM System emulator invocation
1659
1660Use the executable @file{qemu-system-arm} to simulate a ARM
1661machine. The ARM Integrator/CP board is emulated with the following
1662devices:
1663
1664@itemize @minus
1665@item
pbrooked96ca32006-02-20 00:35:00 +00001666ARM926E or ARM1026E CPU
bellard3f9f3aa2005-12-18 20:11:37 +00001667@item
1668Two PL011 UARTs
1669@item
1670SMC 91c111 Ethernet adapter
pbrook00a9bf12006-05-13 16:55:46 +00001671@item
1672PL110 LCD controller
1673@item
1674PL050 KMI with PS/2 keyboard and mouse.
1675@end itemize
1676
1677The ARM Versatile baseboard is emulated with the following devices:
1678
1679@itemize @minus
1680@item
1681ARM926E CPU
1682@item
1683PL190 Vectored Interrupt Controller
1684@item
1685Four PL011 UARTs
1686@item
1687SMC 91c111 Ethernet adapter
1688@item
1689PL110 LCD controller
1690@item
1691PL050 KMI with PS/2 keyboard and mouse.
1692@item
1693PCI host bridge. Note the emulated PCI bridge only provides access to
1694PCI memory space. It does not provide access to PCI IO space.
1695This means some devices (eg. ne2k_pci NIC) are not useable, and others
1696(eg. rtl8139 NIC) are only useable when the guest drivers use the memory
1697mapped control registers.
pbrooke6de1ba2006-06-16 21:48:48 +00001698@item
1699PCI OHCI USB controller.
1700@item
1701LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
bellard3f9f3aa2005-12-18 20:11:37 +00001702@end itemize
1703
1704A Linux 2.6 test image is available on the QEMU web site. More
1705information is available in the QEMU mailing-list archive.
1706
bellarddebc7062006-04-30 21:58:41 +00001707@node QEMU Linux User space emulator
bellard3f9f3aa2005-12-18 20:11:37 +00001708@chapter QEMU Linux User space emulator
bellard386405f2003-03-23 21:28:45 +00001709
bellarddebc7062006-04-30 21:58:41 +00001710@menu
1711* Quick Start::
1712* Wine launch::
1713* Command line options::
pbrook79737e42006-06-11 16:28:41 +00001714* Other binaries::
bellarddebc7062006-04-30 21:58:41 +00001715@end menu
1716
1717@node Quick Start
bellard1f673132004-04-04 15:21:17 +00001718@section Quick Start
bellard386405f2003-03-23 21:28:45 +00001719
bellard1f673132004-04-04 15:21:17 +00001720In order to launch a Linux process, QEMU needs the process executable
1721itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00001722
bellard1f673132004-04-04 15:21:17 +00001723@itemize
bellard386405f2003-03-23 21:28:45 +00001724
bellard1f673132004-04-04 15:21:17 +00001725@item On x86, you can just try to launch any process by using the native
1726libraries:
bellard386405f2003-03-23 21:28:45 +00001727
bellard1f673132004-04-04 15:21:17 +00001728@example
1729qemu-i386 -L / /bin/ls
1730@end example
bellardfd429f22003-03-30 20:59:46 +00001731
bellard1f673132004-04-04 15:21:17 +00001732@code{-L /} tells that the x86 dynamic linker must be searched with a
1733@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00001734
bellard1f673132004-04-04 15:21:17 +00001735@item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources):
bellard1eb20522003-06-25 16:21:49 +00001736
bellard1f673132004-04-04 15:21:17 +00001737@example
1738qemu-i386 -L / qemu-i386 -L / /bin/ls
1739@end example
bellard386405f2003-03-23 21:28:45 +00001740
bellard1f673132004-04-04 15:21:17 +00001741@item On non x86 CPUs, you need first to download at least an x86 glibc
1742(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1743@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00001744
bellard1f673132004-04-04 15:21:17 +00001745@example
1746unset LD_LIBRARY_PATH
1747@end example
bellard386405f2003-03-23 21:28:45 +00001748
bellard1f673132004-04-04 15:21:17 +00001749Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00001750
bellard1f673132004-04-04 15:21:17 +00001751@example
1752qemu-i386 tests/i386/ls
1753@end example
1754You can look at @file{qemu-binfmt-conf.sh} so that
1755QEMU is automatically launched by the Linux kernel when you try to
1756launch x86 executables. It requires the @code{binfmt_misc} module in the
1757Linux kernel.
bellard386405f2003-03-23 21:28:45 +00001758
bellard1f673132004-04-04 15:21:17 +00001759@item The x86 version of QEMU is also included. You can try weird things such as:
1760@example
bellarddebc7062006-04-30 21:58:41 +00001761qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
1762 /usr/local/qemu-i386/bin/ls-i386
bellard1f673132004-04-04 15:21:17 +00001763@end example
bellard386405f2003-03-23 21:28:45 +00001764
bellard1f673132004-04-04 15:21:17 +00001765@end itemize
bellard386405f2003-03-23 21:28:45 +00001766
bellarddebc7062006-04-30 21:58:41 +00001767@node Wine launch
bellard1f673132004-04-04 15:21:17 +00001768@section Wine launch
bellard386405f2003-03-23 21:28:45 +00001769
bellard1f673132004-04-04 15:21:17 +00001770@itemize
bellard386405f2003-03-23 21:28:45 +00001771
bellard1f673132004-04-04 15:21:17 +00001772@item Ensure that you have a working QEMU with the x86 glibc
1773distribution (see previous section). In order to verify it, you must be
1774able to do:
bellard386405f2003-03-23 21:28:45 +00001775
bellard1f673132004-04-04 15:21:17 +00001776@example
1777qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1778@end example
bellard386405f2003-03-23 21:28:45 +00001779
bellard1f673132004-04-04 15:21:17 +00001780@item Download the binary x86 Wine install
1781(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00001782
bellard1f673132004-04-04 15:21:17 +00001783@item Configure Wine on your account. Look at the provided script
bellarddebc7062006-04-30 21:58:41 +00001784@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
bellard1f673132004-04-04 15:21:17 +00001785@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00001786
bellard1f673132004-04-04 15:21:17 +00001787@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00001788
bellard1f673132004-04-04 15:21:17 +00001789@example
bellarddebc7062006-04-30 21:58:41 +00001790qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
1791 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
bellard1f673132004-04-04 15:21:17 +00001792@end example
bellard386405f2003-03-23 21:28:45 +00001793
bellard1f673132004-04-04 15:21:17 +00001794@end itemize
bellard386405f2003-03-23 21:28:45 +00001795
bellarddebc7062006-04-30 21:58:41 +00001796@node Command line options
bellard1f673132004-04-04 15:21:17 +00001797@section Command line options
bellard386405f2003-03-23 21:28:45 +00001798
bellard1f673132004-04-04 15:21:17 +00001799@example
1800usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1801@end example
bellard386405f2003-03-23 21:28:45 +00001802
bellard1f673132004-04-04 15:21:17 +00001803@table @option
1804@item -h
1805Print the help
1806@item -L path
1807Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1808@item -s size
1809Set the x86 stack size in bytes (default=524288)
bellard386405f2003-03-23 21:28:45 +00001810@end table
1811
bellard1f673132004-04-04 15:21:17 +00001812Debug options:
bellard386405f2003-03-23 21:28:45 +00001813
bellard1f673132004-04-04 15:21:17 +00001814@table @option
1815@item -d
1816Activate log (logfile=/tmp/qemu.log)
1817@item -p pagesize
1818Act as if the host page size was 'pagesize' bytes
1819@end table
bellard386405f2003-03-23 21:28:45 +00001820
pbrook79737e42006-06-11 16:28:41 +00001821@node Other binaries
1822@section Other binaries
1823
1824@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
1825binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
1826configurations), and arm-uclinux bFLT format binaries.
1827
pbrooke6e59062006-10-22 00:18:54 +00001828@command{qemu-m68k} is capable of running semihosted binaries using the BDM
1829(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
1830coldfire uClinux bFLT format binaries.
1831
pbrook79737e42006-06-11 16:28:41 +00001832The binary format is detected automatically.
1833
bellard15a34c62004-07-08 21:26:26 +00001834@node compilation
1835@chapter Compilation from the sources
1836
bellarddebc7062006-04-30 21:58:41 +00001837@menu
1838* Linux/Unix::
1839* Windows::
1840* Cross compilation for Windows with Linux::
1841* Mac OS X::
1842@end menu
1843
1844@node Linux/Unix
bellard7c3fc842005-02-10 21:46:47 +00001845@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00001846
bellard7c3fc842005-02-10 21:46:47 +00001847@subsection Compilation
1848
1849First you must decompress the sources:
1850@example
1851cd /tmp
1852tar zxvf qemu-x.y.z.tar.gz
1853cd qemu-x.y.z
1854@end example
1855
1856Then you configure QEMU and build it (usually no options are needed):
1857@example
1858./configure
1859make
1860@end example
1861
1862Then type as root user:
1863@example
1864make install
1865@end example
1866to install QEMU in @file{/usr/local}.
1867
bellard7c3fc842005-02-10 21:46:47 +00001868@subsection Tested tool versions
1869
ths366dfc52006-12-11 18:35:08 +00001870In order to compile QEMU successfully, it is very important that you
bellard7c3fc842005-02-10 21:46:47 +00001871have the right tools. The most important one is gcc. I cannot guaranty
1872that QEMU works if you do not use a tested gcc version. Look at
1873'configure' and 'Makefile' if you want to make a different gcc
1874version work.
1875
1876@example
1877host gcc binutils glibc linux distribution
1878----------------------------------------------------------------------
1879x86 3.2 2.13.2 2.1.3 2.4.18
1880 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3
1881 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9
1882
1883PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq
1884 3.2
1885
1886Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0
1887
1888Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0
1889
1890ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0
1891
1892[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
1893 for gcc version >= 3.3.
1894[2] Linux >= 2.4.20 is necessary for precise exception support
1895 (untested).
1896[3] 2.4.9-ac10-rmk2-np1-cerf2
1897
1898[4] gcc 2.95.x generates invalid code when using too many register
1899variables. You must use gcc 3.x on PowerPC.
1900@end example
bellard15a34c62004-07-08 21:26:26 +00001901
bellarddebc7062006-04-30 21:58:41 +00001902@node Windows
bellard15a34c62004-07-08 21:26:26 +00001903@section Windows
1904
1905@itemize
1906@item Install the current versions of MSYS and MinGW from
1907@url{http://www.mingw.org/}. You can find detailed installation
1908instructions in the download section and the FAQ.
1909
1910@item Download
1911the MinGW development library of SDL 1.2.x
bellarddebc7062006-04-30 21:58:41 +00001912(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
bellard15a34c62004-07-08 21:26:26 +00001913@url{http://www.libsdl.org}. Unpack it in a temporary place, and
1914unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
1915directory. Edit the @file{sdl-config} script so that it gives the
1916correct SDL directory when invoked.
1917
1918@item Extract the current version of QEMU.
1919
1920@item Start the MSYS shell (file @file{msys.bat}).
1921
1922@item Change to the QEMU directory. Launch @file{./configure} and
1923@file{make}. If you have problems using SDL, verify that
1924@file{sdl-config} can be launched from the MSYS command line.
1925
1926@item You can install QEMU in @file{Program Files/Qemu} by typing
1927@file{make install}. Don't forget to copy @file{SDL.dll} in
1928@file{Program Files/Qemu}.
1929
1930@end itemize
1931
bellarddebc7062006-04-30 21:58:41 +00001932@node Cross compilation for Windows with Linux
bellard15a34c62004-07-08 21:26:26 +00001933@section Cross compilation for Windows with Linux
1934
1935@itemize
1936@item
1937Install the MinGW cross compilation tools available at
1938@url{http://www.mingw.org/}.
1939
1940@item
1941Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
1942unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
1943variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
1944the QEMU configuration script.
1945
1946@item
1947Configure QEMU for Windows cross compilation:
1948@example
1949./configure --enable-mingw32
1950@end example
1951If necessary, you can change the cross-prefix according to the prefix
1952choosen for the MinGW tools with --cross-prefix. You can also use
1953--prefix to set the Win32 install path.
1954
1955@item You can install QEMU in the installation directory by typing
1956@file{make install}. Don't forget to copy @file{SDL.dll} in the
1957installation directory.
1958
1959@end itemize
1960
1961Note: Currently, Wine does not seem able to launch
1962QEMU for Win32.
1963
bellarddebc7062006-04-30 21:58:41 +00001964@node Mac OS X
bellard15a34c62004-07-08 21:26:26 +00001965@section Mac OS X
1966
1967The Mac OS X patches are not fully merged in QEMU, so you should look
1968at the QEMU mailing list archive to have all the necessary
1969information.
1970
bellarddebc7062006-04-30 21:58:41 +00001971@node Index
1972@chapter Index
1973@printindex cp
1974
1975@bye