blob: f970b2a59ef7fa714886371540d04f308d3eb2b4 [file] [log] [blame]
bellard386405f2003-03-23 21:28:45 +00001\input texinfo @c -*- texinfo -*-
2
bellard0806e3f2003-10-01 00:15:32 +00003@iftex
bellard1f673132004-04-04 15:21:17 +00004@settitle QEMU CPU Emulator User Documentation
bellard386405f2003-03-23 21:28:45 +00005@titlepage
6@sp 7
bellard1f673132004-04-04 15:21:17 +00007@center @titlefont{QEMU CPU Emulator User Documentation}
bellard386405f2003-03-23 21:28:45 +00008@sp 3
9@end titlepage
bellard0806e3f2003-10-01 00:15:32 +000010@end iftex
bellard386405f2003-03-23 21:28:45 +000011
12@chapter Introduction
13
bellard322d0c62003-06-15 23:29:28 +000014@section Features
bellard386405f2003-03-23 21:28:45 +000015
bellard1f673132004-04-04 15:21:17 +000016QEMU is a FAST! processor emulator using dynamic translation to
17achieve good emulation speed.
bellard1eb20522003-06-25 16:21:49 +000018
19QEMU has two operating modes:
bellard0806e3f2003-10-01 00:15:32 +000020
21@itemize @minus
22
23@item
bellard1f673132004-04-04 15:21:17 +000024Full system emulation. In this mode, QEMU emulates a full system (for
bellardb671f9e2005-04-30 15:08:33 +000025example a PC), including a processor and various peripherals. It can
bellard1f673132004-04-04 15:21:17 +000026be used to launch different Operating Systems without rebooting the
27PC or to debug system code.
bellard1eb20522003-06-25 16:21:49 +000028
bellard0806e3f2003-10-01 00:15:32 +000029@item
bellard1f673132004-04-04 15:21:17 +000030User mode emulation (Linux host only). In this mode, QEMU can launch
31Linux processes compiled for one CPU on another CPU. It can be used to
32launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
33to ease cross-compilation and cross-debugging.
bellard1eb20522003-06-25 16:21:49 +000034
35@end itemize
36
bellard7c3fc842005-02-10 21:46:47 +000037QEMU can run without an host kernel driver and yet gives acceptable
bellard6f2f2b22005-02-20 19:09:44 +000038performance.
bellard322d0c62003-06-15 23:29:28 +000039
bellard52c00a52004-04-25 21:27:03 +000040For system emulation, the following hardware targets are supported:
41@itemize
bellard9d0a8e62005-07-03 17:34:05 +000042@item PC (x86 or x86_64 processor)
bellard52c00a52004-04-25 21:27:03 +000043@item PREP (PowerPC processor)
bellard9d0a8e62005-07-03 17:34:05 +000044@item G3 BW PowerMac (PowerPC processor)
45@item Mac99 PowerMac (PowerPC processor, in progress)
bellard34751872005-07-02 14:31:34 +000046@item Sun4m (32-bit Sparc processor)
47@item Sun4u (64-bit Sparc processor, in progress)
bellard9d0a8e62005-07-03 17:34:05 +000048@item Malta board (32-bit MIPS processor, in progress)
bellard52c00a52004-04-25 21:27:03 +000049@end itemize
bellard386405f2003-03-23 21:28:45 +000050
bellard34751872005-07-02 14:31:34 +000051For user emulation, x86, PowerPC, ARM, and Sparc32/64 CPUs are supported.
bellard0806e3f2003-10-01 00:15:32 +000052
bellard5b9f4572003-10-28 00:49:54 +000053@chapter Installation
54
bellard15a34c62004-07-08 21:26:26 +000055If you want to compile QEMU yourself, see @ref{compilation}.
56
bellard1f673132004-04-04 15:21:17 +000057@section Linux
58
bellard7c3fc842005-02-10 21:46:47 +000059If a precompiled package is available for your distribution - you just
60have to install it. Otherwise, see @ref{compilation}.
bellard5b9f4572003-10-28 00:49:54 +000061
bellard1f673132004-04-04 15:21:17 +000062@section Windows
bellard8cd0ac22004-05-12 19:09:16 +000063
bellard15a34c62004-07-08 21:26:26 +000064Download the experimental binary installer at
65@url{http://www.freeoszoo.org/download.php}.
bellardd691f662003-03-24 21:58:34 +000066
bellard1f673132004-04-04 15:21:17 +000067@section Mac OS X
bellardd691f662003-03-24 21:58:34 +000068
bellard15a34c62004-07-08 21:26:26 +000069Download the experimental binary installer at
70@url{http://www.freeoszoo.org/download.php}.
bellarddf0f11a2003-05-28 00:27:57 +000071
bellard52c00a52004-04-25 21:27:03 +000072@chapter QEMU PC System emulator invocation
bellard1eb20522003-06-25 16:21:49 +000073
bellard0806e3f2003-10-01 00:15:32 +000074@section Introduction
75
76@c man begin DESCRIPTION
77
bellard7c3fc842005-02-10 21:46:47 +000078The QEMU System emulator simulates the
bellardb671f9e2005-04-30 15:08:33 +000079following PC peripherals:
bellard0806e3f2003-10-01 00:15:32 +000080
81@itemize @minus
bellard15a34c62004-07-08 21:26:26 +000082@item
83i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard0806e3f2003-10-01 00:15:32 +000084@item
bellard15a34c62004-07-08 21:26:26 +000085Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
86extensions (hardware level, including all non standard modes).
bellard0806e3f2003-10-01 00:15:32 +000087@item
88PS/2 mouse and keyboard
89@item
bellard15a34c62004-07-08 21:26:26 +0000902 PCI IDE interfaces with hard disk and CD-ROM support
bellard1f673132004-04-04 15:21:17 +000091@item
92Floppy disk
bellard0806e3f2003-10-01 00:15:32 +000093@item
bellard15a34c62004-07-08 21:26:26 +000094NE2000 PCI network adapters
bellard0806e3f2003-10-01 00:15:32 +000095@item
bellard05d58182004-08-24 21:12:04 +000096Serial ports
97@item
bellardc0fe3822005-11-05 18:55:28 +000098Creative SoundBlaster 16 sound card
99@item
100ENSONIQ AudioPCI ES1370 sound card
101@item
102Adlib(OPL2) - Yamaha YM3812 compatible chip
bellardb389dbf2005-11-06 16:49:55 +0000103@item
104PCI UHCI USB controller and a virtual USB hub.
bellard0806e3f2003-10-01 00:15:32 +0000105@end itemize
106
bellardc0fe3822005-11-05 18:55:28 +0000107Note that adlib is only available when QEMU was configured with
108-enable-adlib
109
bellard15a34c62004-07-08 21:26:26 +0000110QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
111VGA BIOS.
112
bellardc0fe3822005-11-05 18:55:28 +0000113QEMU uses YM3812 emulation by Tatsuyuki Satoh.
114
bellard0806e3f2003-10-01 00:15:32 +0000115@c man end
116
bellard1eb20522003-06-25 16:21:49 +0000117@section Quick Start
118
bellard285dc332003-10-27 23:58:04 +0000119Download and uncompress the linux image (@file{linux.img}) and type:
bellard0806e3f2003-10-01 00:15:32 +0000120
121@example
bellard285dc332003-10-27 23:58:04 +0000122qemu linux.img
bellard0806e3f2003-10-01 00:15:32 +0000123@end example
124
125Linux should boot and give you a prompt.
126
bellard6cc721c2005-07-28 22:27:28 +0000127@node sec_invocation
bellard1f673132004-04-04 15:21:17 +0000128@section Invocation
129
130@example
131@c man begin SYNOPSIS
132usage: qemu [options] [disk_image]
133@c man end
134@end example
135
136@c man begin OPTIONS
137@var{disk_image} is a raw hard disk image for IDE hard disk 0.
138
139General options:
140@table @option
bellard3dbbdc22005-11-06 18:20:37 +0000141@item -M machine
142Select the emulated machine (@code{-M ?} for list)
143
bellard1f673132004-04-04 15:21:17 +0000144@item -fda file
145@item -fdb file
bellardbe3edd92004-06-03 12:48:45 +0000146Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
147use the host floppy by using @file{/dev/fd0} as filename.
bellard1f673132004-04-04 15:21:17 +0000148
149@item -hda file
150@item -hdb file
151@item -hdc file
152@item -hdd file
153Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
154
155@item -cdrom file
156Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
bellardbe3edd92004-06-03 12:48:45 +0000157@option{-cdrom} at the same time). You can use the host CD-ROM by
158using @file{/dev/cdrom} as filename.
bellard1f673132004-04-04 15:21:17 +0000159
160@item -boot [a|c|d]
161Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
162the default.
163
164@item -snapshot
165Write to temporary files instead of disk image files. In this case,
166the raw disk image you use is not written back. You can however force
167the write back by pressing @key{C-a s} (@xref{disk_images}).
168
169@item -m megs
bellard15a34c62004-07-08 21:26:26 +0000170Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
bellard1f673132004-04-04 15:21:17 +0000171
bellard1f673132004-04-04 15:21:17 +0000172@item -nographic
173
174Normally, QEMU uses SDL to display the VGA output. With this option,
175you can totally disable graphical output so that QEMU is a simple
176command line application. The emulated serial port is redirected on
177the console. Therefore, you can still use QEMU to debug a Linux kernel
178with a serial console.
179
bellard3d11d0e2004-12-12 16:56:30 +0000180@item -k language
181
182Use keyboard layout @var{language} (for example @code{fr} for
183French). This option is only needed where it is not easy to get raw PC
184keycodes (e.g. on Macs or with some X11 servers). You don't need to
185use it on PC/Linux or PC/Windows hosts.
186
187The available layouts are:
188@example
189ar de-ch es fo fr-ca hu ja mk no pt-br sv
190da en-gb et fr fr-ch is lt nl pl ru th
191de en-us fi fr-be hr it lv nl-be pt sl tr
192@end example
193
194The default is @code{en-us}.
195
bellarda8c490c2004-04-26 20:59:17 +0000196@item -enable-audio
197
bellard1d14ffa2005-10-30 18:58:22 +0000198Will enable audio and all the sound hardware QEMU was built with.
199
200@item -audio-help
201
202Will show the audio subsystem help: list of drivers, tunable
203parameters.
204
205@item -soundhw card1,card2,...
206
207Enable audio and selected sound hardware. Use ? to print all
208available sound hardware.
209
210@example
211qemu -soundhw sb16,adlib hda
212qemu -soundhw es1370 hda
213qemu -soundhw ?
214@end example
bellarda8c490c2004-04-26 20:59:17 +0000215
bellard15a34c62004-07-08 21:26:26 +0000216@item -localtime
217Set the real time clock to local time (the default is to UTC
218time). This option is needed to have correct date in MS-DOS or
219Windows.
220
bellardd63d3072004-10-03 13:29:03 +0000221@item -full-screen
222Start in full screen.
223
bellardf7cce892004-12-08 22:21:25 +0000224@item -pidfile file
225Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
226from a script.
227
bellard9d0a8e62005-07-03 17:34:05 +0000228@item -win2k-hack
229Use it when installing Windows 2000 to avoid a disk full bug. After
230Windows 2000 is installed, you no longer need this option (this option
231slows down the IDE transfers).
232
bellard1f673132004-04-04 15:21:17 +0000233@end table
234
bellardb389dbf2005-11-06 16:49:55 +0000235USB options:
236@table @option
237
238@item -usb
239Enable the USB driver (will be the default soon)
240
241@item -usbdevice devname
242Add the USB device @var{devname}. See the monitor command
243@code{usb_add} to have more information.
244@end table
245
bellard1f673132004-04-04 15:21:17 +0000246Network options:
247
248@table @option
249
bellard41d03942005-11-15 23:02:53 +0000250@item -net nic[,vlan=n][,macaddr=addr]
251Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
252= 0 is the default). The NIC is currently an NE2000 on the PC
253target. Optionally, the MAC address can be changed. If no
254@option{-net} option is specified, a single NIC is created.
bellard1f673132004-04-04 15:21:17 +0000255
bellard41d03942005-11-15 23:02:53 +0000256@item -net user[,vlan=n]
bellard7e894632005-11-19 17:42:52 +0000257Use the user mode network stack which requires no administrator
bellard41d03942005-11-15 23:02:53 +0000258priviledge to run. This is the default if no @option{-net} option is
259specified.
bellard3f1a88f2005-06-05 16:48:41 +0000260
bellard41d03942005-11-15 23:02:53 +0000261@item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
262Connect the host TAP network interface @var{name} to VLAN @var{n} and
263use the network script @var{file} to configure it. The default
264network script is @file{/etc/qemu-ifup}. If @var{name} is not
265provided, the OS automatically provides one. @option{fd=h} can be
266used to specify the handle of an already opened host TAP interface. Example:
bellard3f1a88f2005-06-05 16:48:41 +0000267
bellard41d03942005-11-15 23:02:53 +0000268@example
269qemu linux.img -net nic -net tap
270@end example
bellard1f673132004-04-04 15:21:17 +0000271
bellard41d03942005-11-15 23:02:53 +0000272More complicated example (two NICs, each one connected to a TAP device)
273@example
274qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
275 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
276@end example
bellard1f673132004-04-04 15:21:17 +0000277
bellard52c00a52004-04-25 21:27:03 +0000278
bellard41d03942005-11-15 23:02:53 +0000279@item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
280
281Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
282machine using a TCP socket connection. If @option{listen} is
283specified, QEMU waits for incoming connections on @var{port}
284(@var{host} is optional). @option{connect} is used to connect to
bellard3d830452005-12-18 16:36:49 +0000285another QEMU instance using the @option{listen} option. @option{fd=h}
286specifies an already opened TCP socket.
bellard41d03942005-11-15 23:02:53 +0000287
288Example:
289@example
290# launch a first QEMU instance
bellard7e894632005-11-19 17:42:52 +0000291qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,listen=:1234
bellard41d03942005-11-15 23:02:53 +0000292# connect the VLAN 0 of this instance to the VLAN 0 of the first instance
bellard7e894632005-11-19 17:42:52 +0000293qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,connect=127.0.0.1:1234
bellard41d03942005-11-15 23:02:53 +0000294@end example
295
bellard3d830452005-12-18 16:36:49 +0000296@item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]
297
298Create a VLAN @var{n} shared with another QEMU virtual
299machines using a UDP multicast socket, effectively making a bus for
300every QEMU with same multicast address @var{maddr} and @var{port}.
301NOTES:
302@enumerate
303@item
304Several QEMU can be running on different hosts and share same bus (assuming
305correct multicast setup for these hosts).
306@item
307mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
308@url{http://user-mode-linux.sf.net}.
309@item Use @option{fd=h} to specify an already opened UDP multicast socket.
310@end enumerate
311
312Example:
313@example
314# launch one QEMU instance
315qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=230.0.0.1:1234
316# launch another QEMU instance on same "bus"
317qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,mcast=230.0.0.1:1234
318# launch yet another QEMU instance on same "bus"
319qemu linux.img -net nic,macaddr=52:54:00:12:34:58 -net socket,mcast=230.0.0.1:1234
320@end example
321
322Example (User Mode Linux compat.):
323@example
324# launch QEMU instance (note mcast address selected is UML's default)
325qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=239.192.168.1:1102
326# launch UML
327/path/to/linux ubd0=/path/to/root_fs eth0=mcast
328@end example
329
bellard41d03942005-11-15 23:02:53 +0000330@item -net none
331Indicate that no network devices should be configured. It is used to
332override the default configuration which is activated if no
333@option{-net} options are provided.
bellard52c00a52004-04-25 21:27:03 +0000334
bellard9bf05442004-08-25 22:12:49 +0000335@item -tftp prefix
336When using the user mode network stack, activate a built-in TFTP
337server. All filenames beginning with @var{prefix} can be downloaded
338from the host to the guest using a TFTP client. The TFTP client on the
339guest must be configured in binary mode (use the command @code{bin} of
340the Unix TFTP client). The host IP address on the guest is as usual
34110.0.2.2.
342
bellard2518bd02004-09-30 22:35:13 +0000343@item -smb dir
344When using the user mode network stack, activate a built-in SMB
345server so that Windows OSes can access to the host files in @file{dir}
346transparently.
347
348In the guest Windows OS, the line:
349@example
35010.0.2.4 smbserver
351@end example
352must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
353or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
354
355Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
356
357Note that a SAMBA server must be installed on the host OS in
358@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
bellard6cc721c2005-07-28 22:27:28 +00003592.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
bellard2518bd02004-09-30 22:35:13 +0000360
bellard9bf05442004-08-25 22:12:49 +0000361@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
362
363When using the user mode network stack, redirect incoming TCP or UDP
364connections to the host port @var{host-port} to the guest
365@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
366is not specified, its value is 10.0.2.15 (default address given by the
367built-in DHCP server).
368
369For example, to redirect host X11 connection from screen 1 to guest
370screen 0, use the following:
371
372@example
373# on the host
374qemu -redir tcp:6001::6000 [...]
375# this host xterm should open in the guest X11 server
376xterm -display :1
377@end example
378
379To redirect telnet connections from host port 5555 to telnet port on
380the guest, use the following:
381
382@example
383# on the host
384qemu -redir tcp:5555::23 [...]
385telnet localhost 5555
386@end example
387
388Then when you use on the host @code{telnet localhost 5555}, you
389connect to the guest telnet server.
390
bellard1f673132004-04-04 15:21:17 +0000391@end table
392
bellard41d03942005-11-15 23:02:53 +0000393Linux boot specific: When using these options, you can use a given
bellard1f673132004-04-04 15:21:17 +0000394Linux kernel without installing it in the disk image. It can be useful
395for easier testing of various kernels.
396
397@table @option
398
399@item -kernel bzImage
400Use @var{bzImage} as kernel image.
401
402@item -append cmdline
403Use @var{cmdline} as kernel command line
404
405@item -initrd file
406Use @var{file} as initial ram disk.
407
408@end table
409
bellard15a34c62004-07-08 21:26:26 +0000410Debug/Expert options:
bellard1f673132004-04-04 15:21:17 +0000411@table @option
bellarda0a821a2004-07-14 17:38:57 +0000412
413@item -serial dev
414Redirect the virtual serial port to host device @var{dev}. Available
415devices are:
416@table @code
417@item vc
418Virtual console
419@item pty
420[Linux only] Pseudo TTY (a new PTY is automatically allocated)
421@item null
422void device
bellardf8d179e2005-11-08 22:30:36 +0000423@item /dev/XXX
bellarde57a8c02005-11-10 23:58:52 +0000424[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
bellardf8d179e2005-11-08 22:30:36 +0000425parameters are set according to the emulated ones.
bellarde57a8c02005-11-10 23:58:52 +0000426@item /dev/parportN
427[Linux only, parallel port only] Use host parallel port
428@var{N}. Currently only SPP parallel port features can be used.
bellardf8d179e2005-11-08 22:30:36 +0000429@item file:filename
430Write output to filename. No character can be read.
bellarda0a821a2004-07-14 17:38:57 +0000431@item stdio
432[Unix only] standard input/output
bellardf8d179e2005-11-08 22:30:36 +0000433@item pipe:filename
434[Unix only] name pipe @var{filename}
bellarda0a821a2004-07-14 17:38:57 +0000435@end table
436The default device is @code{vc} in graphical mode and @code{stdio} in
437non graphical mode.
438
bellard05d58182004-08-24 21:12:04 +0000439This option can be used several times to simulate up to 4 serials
440ports.
441
bellarde57a8c02005-11-10 23:58:52 +0000442@item -parallel dev
443Redirect the virtual parallel port to host device @var{dev} (same
444devices as the serial port). On Linux hosts, @file{/dev/parportN} can
445be used to use hardware devices connected on the corresponding host
446parallel port.
447
448This option can be used several times to simulate up to 3 parallel
449ports.
450
bellarda0a821a2004-07-14 17:38:57 +0000451@item -monitor dev
452Redirect the monitor to host device @var{dev} (same devices as the
453serial port).
454The default device is @code{vc} in graphical mode and @code{stdio} in
455non graphical mode.
456
bellard1f673132004-04-04 15:21:17 +0000457@item -s
458Wait gdb connection to port 1234 (@xref{gdb_usage}).
459@item -p port
460Change gdb connection port.
bellard52c00a52004-04-25 21:27:03 +0000461@item -S
462Do not start CPU at startup (you must type 'c' in the monitor).
bellard1f673132004-04-04 15:21:17 +0000463@item -d
464Output log in /tmp/qemu.log
bellard46d47672004-11-16 01:45:27 +0000465@item -hdachs c,h,s,[,t]
466Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
467@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
468translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
469all thoses parameters. This option is useful for old MS-DOS disk
470images.
bellard7c3fc842005-02-10 21:46:47 +0000471
bellard15a34c62004-07-08 21:26:26 +0000472@item -std-vga
473Simulate a standard VGA card with Bochs VBE extensions (default is
474Cirrus Logic GD5446 PCI VGA)
bellardd63d3072004-10-03 13:29:03 +0000475@item -loadvm file
476Start right away with a saved state (@code{loadvm} in monitor)
bellard1f673132004-04-04 15:21:17 +0000477@end table
478
bellard3e11db92004-07-14 17:47:14 +0000479@c man end
480
481@section Keys
482
483@c man begin OPTIONS
484
bellarda1b74fe2004-05-08 13:26:35 +0000485During the graphical emulation, you can use the following keys:
486@table @key
bellardf9859312004-10-03 14:33:10 +0000487@item Ctrl-Alt-f
bellarda1b74fe2004-05-08 13:26:35 +0000488Toggle full screen
bellarda0a821a2004-07-14 17:38:57 +0000489
bellardf9859312004-10-03 14:33:10 +0000490@item Ctrl-Alt-n
bellarda0a821a2004-07-14 17:38:57 +0000491Switch to virtual console 'n'. Standard console mappings are:
492@table @emph
493@item 1
494Target system display
495@item 2
496Monitor
497@item 3
498Serial port
bellarda1b74fe2004-05-08 13:26:35 +0000499@end table
500
bellardf9859312004-10-03 14:33:10 +0000501@item Ctrl-Alt
bellarda0a821a2004-07-14 17:38:57 +0000502Toggle mouse and keyboard grab.
503@end table
504
bellard3e11db92004-07-14 17:47:14 +0000505In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
506@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
507
bellarda0a821a2004-07-14 17:38:57 +0000508During emulation, if you are using the @option{-nographic} option, use
509@key{Ctrl-a h} to get terminal commands:
bellard1f673132004-04-04 15:21:17 +0000510
511@table @key
bellarda1b74fe2004-05-08 13:26:35 +0000512@item Ctrl-a h
bellard1f673132004-04-04 15:21:17 +0000513Print this help
bellarda1b74fe2004-05-08 13:26:35 +0000514@item Ctrl-a x
bellard1f673132004-04-04 15:21:17 +0000515Exit emulatior
bellarda1b74fe2004-05-08 13:26:35 +0000516@item Ctrl-a s
bellard1f673132004-04-04 15:21:17 +0000517Save disk data back to file (if -snapshot)
bellarda1b74fe2004-05-08 13:26:35 +0000518@item Ctrl-a b
bellard1f673132004-04-04 15:21:17 +0000519Send break (magic sysrq in Linux)
bellarda1b74fe2004-05-08 13:26:35 +0000520@item Ctrl-a c
bellard1f673132004-04-04 15:21:17 +0000521Switch between console and monitor
bellarda1b74fe2004-05-08 13:26:35 +0000522@item Ctrl-a Ctrl-a
523Send Ctrl-a
bellard1f673132004-04-04 15:21:17 +0000524@end table
525@c man end
526
527@ignore
528
529@setfilename qemu
530@settitle QEMU System Emulator
531
532@c man begin SEEALSO
533The HTML documentation of QEMU for more precise information and Linux
534user mode emulator invocation.
535@c man end
536
537@c man begin AUTHOR
538Fabrice Bellard
539@c man end
540
541@end ignore
542
543@end ignore
544
bellard1f673132004-04-04 15:21:17 +0000545@section QEMU Monitor
546
547The QEMU monitor is used to give complex commands to the QEMU
548emulator. You can use it to:
549
550@itemize @minus
551
552@item
553Remove or insert removable medias images
554(such as CD-ROM or floppies)
555
556@item
557Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
558from a disk file.
559
560@item Inspect the VM state without an external debugger.
561
562@end itemize
563
564@subsection Commands
565
566The following commands are available:
567
568@table @option
569
570@item help or ? [cmd]
571Show the help for all commands or just for command @var{cmd}.
572
573@item commit
574Commit changes to the disk images (if -snapshot is used)
575
576@item info subcommand
577show various information about the system state
578
579@table @option
580@item info network
bellard41d03942005-11-15 23:02:53 +0000581show the various VLANs and the associated devices
bellard1f673132004-04-04 15:21:17 +0000582@item info block
583show the block devices
584@item info registers
585show the cpu registers
586@item info history
587show the command line history
bellardb389dbf2005-11-06 16:49:55 +0000588@item info pci
589show emulated PCI device
590@item info usb
591show USB devices plugged on the virtual USB hub
592@item info usbhost
593show all USB host devices
bellard1f673132004-04-04 15:21:17 +0000594@end table
595
596@item q or quit
597Quit the emulator.
598
599@item eject [-f] device
600Eject a removable media (use -f to force it).
601
602@item change device filename
603Change a removable media.
604
605@item screendump filename
606Save screen into PPM image @var{filename}.
607
608@item log item1[,...]
609Activate logging of the specified items to @file{/tmp/qemu.log}.
610
611@item savevm filename
612Save the whole virtual machine state to @var{filename}.
613
614@item loadvm filename
615Restore the whole virtual machine state from @var{filename}.
616
617@item stop
618Stop emulation.
619
620@item c or cont
621Resume emulation.
622
623@item gdbserver [port]
624Start gdbserver session (default port=1234)
625
626@item x/fmt addr
627Virtual memory dump starting at @var{addr}.
628
629@item xp /fmt addr
630Physical memory dump starting at @var{addr}.
631
632@var{fmt} is a format which tells the command how to format the
633data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
634
635@table @var
636@item count
637is the number of items to be dumped.
638
639@item format
640can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
641c (char) or i (asm instruction).
642
643@item size
bellard52c00a52004-04-25 21:27:03 +0000644can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
645@code{h} or @code{w} can be specified with the @code{i} format to
646respectively select 16 or 32 bit code instruction size.
bellard1f673132004-04-04 15:21:17 +0000647
648@end table
649
650Examples:
651@itemize
652@item
653Dump 10 instructions at the current instruction pointer:
654@example
655(qemu) x/10i $eip
6560x90107063: ret
6570x90107064: sti
6580x90107065: lea 0x0(%esi,1),%esi
6590x90107069: lea 0x0(%edi,1),%edi
6600x90107070: ret
6610x90107071: jmp 0x90107080
6620x90107073: nop
6630x90107074: nop
6640x90107075: nop
6650x90107076: nop
666@end example
667
668@item
669Dump 80 16 bit values at the start of the video memory.
670@example
671(qemu) xp/80hx 0xb8000
6720x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
6730x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
6740x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
6750x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
6760x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
6770x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
6780x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
6790x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
6800x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
6810x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
682@end example
683@end itemize
684
685@item p or print/fmt expr
686
687Print expression value. Only the @var{format} part of @var{fmt} is
688used.
689
bellarda3a91a32004-06-04 11:06:21 +0000690@item sendkey keys
691
692Send @var{keys} to the emulator. Use @code{-} to press several keys
693simultaneously. Example:
694@example
695sendkey ctrl-alt-f1
696@end example
697
698This command is useful to send keys that your graphical user interface
699intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
700
bellard15a34c62004-07-08 21:26:26 +0000701@item system_reset
702
703Reset the system.
704
bellardb389dbf2005-11-06 16:49:55 +0000705@item usb_add devname
706
707Plug the USB device devname to the QEMU virtual USB hub. @var{devname}
708is either a virtual device name (for example @code{mouse}) or a host
709USB device identifier. Host USB device identifiers have the following
710syntax: @code{host:bus.addr} or @code{host:vendor_id:product_id}.
711
712@item usb_del devname
713
714Remove the USB device @var{devname} from the QEMU virtual USB
715hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
716command @code{info usb} to see the devices you can remove.
717
bellard1f673132004-04-04 15:21:17 +0000718@end table
719
720@subsection Integer expressions
721
722The monitor understands integers expressions for every integer
723argument. You can use register names to get the value of specifics
724CPU registers by prefixing them with @emph{$}.
725
726@node disk_images
727@section Disk Images
728
bellardacd935e2004-11-15 22:57:26 +0000729Since version 0.6.1, QEMU supports many disk image formats, including
730growable disk images (their size increase as non empty sectors are
731written), compressed and encrypted disk images.
bellard1f673132004-04-04 15:21:17 +0000732
bellardacd935e2004-11-15 22:57:26 +0000733@subsection Quick start for disk image creation
734
735You can create a disk image with the command:
bellard1f673132004-04-04 15:21:17 +0000736@example
bellardacd935e2004-11-15 22:57:26 +0000737qemu-img create myimage.img mysize
bellard1f673132004-04-04 15:21:17 +0000738@end example
bellardacd935e2004-11-15 22:57:26 +0000739where @var{myimage.img} is the disk image filename and @var{mysize} is its
740size in kilobytes. You can add an @code{M} suffix to give the size in
741megabytes and a @code{G} suffix for gigabytes.
742
743@xref{qemu_img_invocation} for more information.
bellard1f673132004-04-04 15:21:17 +0000744
745@subsection Snapshot mode
746
747If you use the option @option{-snapshot}, all disk images are
748considered as read only. When sectors in written, they are written in
749a temporary file created in @file{/tmp}. You can however force the
bellardacd935e2004-11-15 22:57:26 +0000750write back to the raw disk images by using the @code{commit} monitor
751command (or @key{C-a s} in the serial console).
bellard1f673132004-04-04 15:21:17 +0000752
bellardacd935e2004-11-15 22:57:26 +0000753@node qemu_img_invocation
754@subsection @code{qemu-img} Invocation
bellard1f673132004-04-04 15:21:17 +0000755
bellardacd935e2004-11-15 22:57:26 +0000756@include qemu-img.texi
bellard05efe462004-06-16 20:34:33 +0000757
bellard9d4fb822004-04-26 20:55:38 +0000758@section Network emulation
759
bellard41d03942005-11-15 23:02:53 +0000760QEMU can simulate several networks cards (NE2000 boards on the PC
761target) and can connect them to an arbitrary number of Virtual Local
762Area Networks (VLANs). Host TAP devices can be connected to any QEMU
763VLAN. VLAN can be connected between separate instances of QEMU to
764simulate large networks. For simpler usage, a non priviledged user mode
765network stack can replace the TAP device to have a basic network
766connection.
bellard9d4fb822004-04-26 20:55:38 +0000767
bellard41d03942005-11-15 23:02:53 +0000768@subsection VLANs
bellard9d4fb822004-04-26 20:55:38 +0000769
bellard41d03942005-11-15 23:02:53 +0000770QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
771connection between several network devices. These devices can be for
772example QEMU virtual Ethernet cards or virtual Host ethernet devices
773(TAP devices).
774
775@subsection Using TAP network interfaces
776
777This is the standard way to connect QEMU to a real network. QEMU adds
778a virtual network device on your host (called @code{tapN}), and you
779can then configure it as if it was a real ethernet card.
bellard9d4fb822004-04-26 20:55:38 +0000780
781As an example, you can download the @file{linux-test-xxx.tar.gz}
782archive and copy the script @file{qemu-ifup} in @file{/etc} and
783configure properly @code{sudo} so that the command @code{ifconfig}
784contained in @file{qemu-ifup} can be executed as root. You must verify
bellard41d03942005-11-15 23:02:53 +0000785that your host kernel supports the TAP network interfaces: the
bellard9d4fb822004-04-26 20:55:38 +0000786device @file{/dev/net/tun} must be present.
787
788See @ref{direct_linux_boot} to have an example of network use with a
bellard41d03942005-11-15 23:02:53 +0000789Linux distribution and @ref{sec_invocation} to have examples of
790command lines using the TAP network interfaces.
bellard9d4fb822004-04-26 20:55:38 +0000791
792@subsection Using the user mode network stack
793
bellard41d03942005-11-15 23:02:53 +0000794By using the option @option{-net user} (default configuration if no
795@option{-net} option is specified), QEMU uses a completely user mode
796network stack (you don't need root priviledge to use the virtual
797network). The virtual network configuration is the following:
bellard9d4fb822004-04-26 20:55:38 +0000798
799@example
800
bellard41d03942005-11-15 23:02:53 +0000801 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
802 | (10.0.2.2)
bellard9d4fb822004-04-26 20:55:38 +0000803 |
bellard2518bd02004-09-30 22:35:13 +0000804 ----> DNS server (10.0.2.3)
805 |
806 ----> SMB server (10.0.2.4)
bellard9d4fb822004-04-26 20:55:38 +0000807@end example
808
809The QEMU VM behaves as if it was behind a firewall which blocks all
810incoming connections. You can use a DHCP client to automatically
bellard41d03942005-11-15 23:02:53 +0000811configure the network in the QEMU VM. The DHCP server assign addresses
812to the hosts starting from 10.0.2.15.
bellard9d4fb822004-04-26 20:55:38 +0000813
814In order to check that the user mode network is working, you can ping
815the address 10.0.2.2 and verify that you got an address in the range
81610.0.2.x from the QEMU virtual DHCP server.
817
bellardb415a402004-05-23 21:04:06 +0000818Note that @code{ping} is not supported reliably to the internet as it
819would require root priviledges. It means you can only ping the local
820router (10.0.2.2).
821
bellard9bf05442004-08-25 22:12:49 +0000822When using the built-in TFTP server, the router is also the TFTP
823server.
824
825When using the @option{-redir} option, TCP or UDP connections can be
826redirected from the host to the guest. It allows for example to
827redirect X11, telnet or SSH connections.
bellard443f1372004-06-04 11:13:20 +0000828
bellard41d03942005-11-15 23:02:53 +0000829@subsection Connecting VLANs between QEMU instances
830
831Using the @option{-net socket} option, it is possible to make VLANs
832that span several QEMU instances. See @ref{sec_invocation} to have a
833basic example.
834
bellard9d4fb822004-04-26 20:55:38 +0000835@node direct_linux_boot
836@section Direct Linux Boot
bellard0806e3f2003-10-01 00:15:32 +0000837
838This section explains how to launch a Linux kernel inside QEMU without
839having to make a full bootable image. It is very useful for fast Linux
840kernel testing. The QEMU network configuration is also explained.
bellard1eb20522003-06-25 16:21:49 +0000841
842@enumerate
843@item
bellard0806e3f2003-10-01 00:15:32 +0000844Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
845kernel and a disk image.
bellard1eb20522003-06-25 16:21:49 +0000846
847@item Optional: If you want network support (for example to launch X11 examples), you
bellard0806e3f2003-10-01 00:15:32 +0000848must copy the script @file{qemu-ifup} in @file{/etc} and configure
bellard1eb20522003-06-25 16:21:49 +0000849properly @code{sudo} so that the command @code{ifconfig} contained in
bellard0806e3f2003-10-01 00:15:32 +0000850@file{qemu-ifup} can be executed as root. You must verify that your host
bellard1eb20522003-06-25 16:21:49 +0000851kernel supports the TUN/TAP network interfaces: the device
852@file{/dev/net/tun} must be present.
853
854When network is enabled, there is a virtual network connection between
855the host kernel and the emulated kernel. The emulated kernel is seen
856from the host kernel at IP address 172.20.0.2 and the host kernel is
857seen from the emulated kernel at IP address 172.20.0.1.
858
bellard0806e3f2003-10-01 00:15:32 +0000859@item Launch @code{qemu.sh}. You should have the following output:
bellard1eb20522003-06-25 16:21:49 +0000860
861@example
bellard0806e3f2003-10-01 00:15:32 +0000862> ./qemu.sh
bellard181f1552003-11-13 01:47:16 +0000863Connected to host network interface: tun0
864Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
bellard1eb20522003-06-25 16:21:49 +0000865BIOS-provided physical RAM map:
bellard46907642003-07-07 12:17:46 +0000866 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
867 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
bellard1eb20522003-06-25 16:21:49 +000086832MB LOWMEM available.
869On node 0 totalpages: 8192
870zone(0): 4096 pages.
871zone(1): 4096 pages.
872zone(2): 0 pages.
bellard181f1552003-11-13 01:47:16 +0000873Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
bellard46907642003-07-07 12:17:46 +0000874ide_setup: ide2=noprobe
875ide_setup: ide3=noprobe
876ide_setup: ide4=noprobe
877ide_setup: ide5=noprobe
bellard1eb20522003-06-25 16:21:49 +0000878Initializing CPU#0
bellard181f1552003-11-13 01:47:16 +0000879Detected 2399.621 MHz processor.
880Console: colour EGA 80x25
881Calibrating delay loop... 4744.80 BogoMIPS
882Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
bellard1eb20522003-06-25 16:21:49 +0000883Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
884Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
bellard181f1552003-11-13 01:47:16 +0000885Mount cache hash table entries: 512 (order: 0, 4096 bytes)
bellard1eb20522003-06-25 16:21:49 +0000886Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
887Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
888CPU: Intel Pentium Pro stepping 03
889Checking 'hlt' instruction... OK.
890POSIX conformance testing by UNIFIX
891Linux NET4.0 for Linux 2.4
892Based upon Swansea University Computer Society NET3.039
893Initializing RT netlink socket
894apm: BIOS not found.
895Starting kswapd
bellard46907642003-07-07 12:17:46 +0000896Journalled Block Device driver loaded
bellard181f1552003-11-13 01:47:16 +0000897Detected PS/2 Mouse Port.
bellard1eb20522003-06-25 16:21:49 +0000898pty: 256 Unix98 ptys configured
899Serial driver version 5.05c (2001-07-08) with no serial options enabled
900ttyS00 at 0x03f8 (irq = 4) is a 16450
901ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
902Last modified Nov 1, 2000 by Paul Gortmaker
903NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
904eth0: NE2000 found at 0x300, using IRQ 9.
bellard46907642003-07-07 12:17:46 +0000905RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
bellard181f1552003-11-13 01:47:16 +0000906Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
907ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
908hda: QEMU HARDDISK, ATA DISK drive
909ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
910hda: attached ide-disk driver.
911hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
912Partition check:
913 hda:
914Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
bellard1eb20522003-06-25 16:21:49 +0000915NET4: Linux TCP/IP 1.0 for NET4.0
916IP Protocols: ICMP, UDP, TCP, IGMP
917IP: routing cache hash table of 512 buckets, 4Kbytes
bellard46907642003-07-07 12:17:46 +0000918TCP: Hash tables configured (established 2048 bind 4096)
bellard1eb20522003-06-25 16:21:49 +0000919NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
bellard46907642003-07-07 12:17:46 +0000920EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
bellard1eb20522003-06-25 16:21:49 +0000921VFS: Mounted root (ext2 filesystem).
bellard181f1552003-11-13 01:47:16 +0000922Freeing unused kernel memory: 64k freed
923
924Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
925
926QEMU Linux test distribution (based on Redhat 9)
927
928Type 'exit' to halt the system
929
930sh-2.05b#
bellard1eb20522003-06-25 16:21:49 +0000931@end example
932
933@item
934Then you can play with the kernel inside the virtual serial console. You
935can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
936about the keys you can type inside the virtual serial console. In
bellardd5a0b502003-06-27 12:02:03 +0000937particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
938the Magic SysRq key.
bellard1eb20522003-06-25 16:21:49 +0000939
940@item
941If the network is enabled, launch the script @file{/etc/linuxrc} in the
942emulator (don't forget the leading dot):
943@example
944. /etc/linuxrc
945@end example
946
947Then enable X11 connections on your PC from the emulated Linux:
948@example
949xhost +172.20.0.2
950@end example
951
952You can now launch @file{xterm} or @file{xlogo} and verify that you have
953a real Virtual Linux system !
954
955@end enumerate
956
bellardd5a0b502003-06-27 12:02:03 +0000957NOTES:
958@enumerate
959@item
bellard0806e3f2003-10-01 00:15:32 +0000960A 2.5.74 kernel is also included in the archive. Just
961replace the bzImage in qemu.sh to try it.
bellardd5a0b502003-06-27 12:02:03 +0000962
963@item
bellard9d4520d2003-10-28 01:38:57 +0000964In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
965qemu. qemu will automatically exit when the Linux shutdown is done.
bellard46907642003-07-07 12:17:46 +0000966
967@item
968You can boot slightly faster by disabling the probe of non present IDE
969interfaces. To do so, add the following options on the kernel command
970line:
971@example
972ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
973@end example
974
975@item
976The example disk image is a modified version of the one made by Kevin
bellard1eb20522003-06-25 16:21:49 +0000977Lawton for the plex86 Project (@url{www.plex86.org}).
978
bellardd5a0b502003-06-27 12:02:03 +0000979@end enumerate
980
bellardb389dbf2005-11-06 16:49:55 +0000981@section USB emulation
982
983QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
984to it. You can virtually plug to the hub virtual USB devices or real
985host USB devices (experimental, works only on Linux hosts).
986
987@subsection Using virtual USB devices
988
989A virtual USB mouse device is available for testing in QEMU.
990
991You can try it with the following monitor commands:
992
993@example
994# add the mouse device
995(qemu) usb_add mouse
996
997# show the virtual USB devices plugged on the QEMU Virtual USB hub
998(qemu) info usb
999 Device 0.3, speed 12 Mb/s
1000
1001# after some time you can try to remove the mouse
1002(qemu) usb_del 0.3
1003@end example
1004
1005The option @option{-usbdevice} is similar to the monitor command
1006@code{usb_add}.
1007
1008@subsection Using host USB devices on a Linux host
1009
1010WARNING: this is an experimental feature. QEMU will slow down when
1011using it. USB devices requiring real time streaming (i.e. USB Video
1012Cameras) are not supported yet.
1013
1014@enumerate
1015@item If you use an early Linux 2.4 kernel, verify that no Linux driver
1016is actually using the USB device. A simple way to do that is simply to
1017disable the corresponding kernel module by renaming it from @file{mydriver.o}
1018to @file{mydriver.o.disabled}.
1019
1020@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1021@example
1022ls /proc/bus/usb
1023001 devices drivers
1024@end example
1025
1026@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:
1027@example
1028chown -R myuid /proc/bus/usb
1029@end example
1030
1031@item Launch QEMU and do in the monitor:
1032@example
1033info usbhost
1034 Device 1.2, speed 480 Mb/s
1035 Class 00: USB device 1234:5678, USB DISK
1036@end example
1037You should see the list of the devices you can use (Never try to use
1038hubs, it won't work).
1039
1040@item Add the device in QEMU by using:
1041@example
1042usb_add host:1234:5678
1043@end example
1044
1045Normally the guest OS should report that a new USB device is
1046plugged. You can use the option @option{-usbdevice} to do the same.
1047
1048@item Now you can try to use the host USB device in QEMU.
1049
1050@end enumerate
1051
1052When relaunching QEMU, you may have to unplug and plug again the USB
1053device to make it work again (this is a bug).
1054
bellard0806e3f2003-10-01 00:15:32 +00001055@node gdb_usage
bellardda415d52003-06-27 18:50:50 +00001056@section GDB usage
1057
1058QEMU has a primitive support to work with gdb, so that you can do
bellard0806e3f2003-10-01 00:15:32 +00001059'Ctrl-C' while the virtual machine is running and inspect its state.
bellardda415d52003-06-27 18:50:50 +00001060
bellard9d4520d2003-10-28 01:38:57 +00001061In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellardda415d52003-06-27 18:50:50 +00001062gdb connection:
1063@example
bellard6c9bf892004-01-24 13:46:56 +00001064> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellardda415d52003-06-27 18:50:50 +00001065Connected to host network interface: tun0
1066Waiting gdb connection on port 1234
1067@end example
1068
1069Then launch gdb on the 'vmlinux' executable:
1070@example
1071> gdb vmlinux
1072@end example
1073
1074In gdb, connect to QEMU:
1075@example
bellard6c9bf892004-01-24 13:46:56 +00001076(gdb) target remote localhost:1234
bellardda415d52003-06-27 18:50:50 +00001077@end example
1078
1079Then you can use gdb normally. For example, type 'c' to launch the kernel:
1080@example
1081(gdb) c
1082@end example
1083
bellard0806e3f2003-10-01 00:15:32 +00001084Here are some useful tips in order to use gdb on system code:
1085
1086@enumerate
1087@item
1088Use @code{info reg} to display all the CPU registers.
1089@item
1090Use @code{x/10i $eip} to display the code at the PC position.
1091@item
1092Use @code{set architecture i8086} to dump 16 bit code. Then use
1093@code{x/10i $cs*16+*eip} to dump the code at the PC position.
1094@end enumerate
1095
bellard1a084f32004-05-13 22:34:49 +00001096@section Target OS specific information
1097
1098@subsection Linux
1099
bellard15a34c62004-07-08 21:26:26 +00001100To have access to SVGA graphic modes under X11, use the @code{vesa} or
1101the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1102color depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001103
bellarde3371e62004-07-10 16:26:02 +00001104When using a 2.6 guest Linux kernel, you should add the option
1105@code{clock=pit} on the kernel command line because the 2.6 Linux
1106kernels make very strict real time clock checks by default that QEMU
1107cannot simulate exactly.
1108
bellard7c3fc842005-02-10 21:46:47 +00001109When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1110not activated because QEMU is slower with this patch. The QEMU
1111Accelerator Module is also much slower in this case. Earlier Fedora
1112Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
1113patch by default. Newer kernels don't have it.
1114
bellard1a084f32004-05-13 22:34:49 +00001115@subsection Windows
1116
1117If you have a slow host, using Windows 95 is better as it gives the
1118best speed. Windows 2000 is also a good choice.
1119
bellarde3371e62004-07-10 16:26:02 +00001120@subsubsection SVGA graphic modes support
1121
1122QEMU emulates a Cirrus Logic GD5446 Video
bellard15a34c62004-07-08 21:26:26 +00001123card. All Windows versions starting from Windows 95 should recognize
1124and use this graphic card. For optimal performances, use 16 bit color
1125depth in the guest and the host OS.
bellard1a084f32004-05-13 22:34:49 +00001126
bellarde3371e62004-07-10 16:26:02 +00001127@subsubsection CPU usage reduction
1128
1129Windows 9x does not correctly use the CPU HLT
bellard15a34c62004-07-08 21:26:26 +00001130instruction. The result is that it takes host CPU cycles even when
1131idle. You can install the utility from
1132@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1133problem. Note that no such tool is needed for NT, 2000 or XP.
bellard1a084f32004-05-13 22:34:49 +00001134
bellard9d0a8e62005-07-03 17:34:05 +00001135@subsubsection Windows 2000 disk full problem
bellarde3371e62004-07-10 16:26:02 +00001136
bellard9d0a8e62005-07-03 17:34:05 +00001137Windows 2000 has a bug which gives a disk full problem during its
1138installation. When installing it, use the @option{-win2k-hack} QEMU
1139option to enable a specific workaround. After Windows 2000 is
1140installed, you no longer need this option (this option slows down the
1141IDE transfers).
bellarde3371e62004-07-10 16:26:02 +00001142
bellard6cc721c2005-07-28 22:27:28 +00001143@subsubsection Windows 2000 shutdown
1144
1145Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1146can. It comes from the fact that Windows 2000 does not automatically
1147use the APM driver provided by the BIOS.
1148
1149In order to correct that, do the following (thanks to Struan
1150Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1151Add/Troubleshoot a device => Add a new device & Next => No, select the
1152hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1153(again) a few times. Now the driver is installed and Windows 2000 now
1154correctly instructs QEMU to shutdown at the appropriate moment.
1155
1156@subsubsection Share a directory between Unix and Windows
1157
1158See @ref{sec_invocation} about the help of the option @option{-smb}.
1159
bellarde3371e62004-07-10 16:26:02 +00001160@subsubsection Windows XP security problems
1161
1162Some releases of Windows XP install correctly but give a security
1163error when booting:
1164@example
1165A problem is preventing Windows from accurately checking the
1166license for this computer. Error code: 0x800703e6.
1167@end example
1168The only known workaround is to boot in Safe mode
1169without networking support.
1170
1171Future QEMU releases are likely to correct this bug.
1172
bellarda0a821a2004-07-14 17:38:57 +00001173@subsection MS-DOS and FreeDOS
1174
1175@subsubsection CPU usage reduction
1176
1177DOS does not correctly use the CPU HLT instruction. The result is that
1178it takes host CPU cycles even when idle. You can install the utility
1179from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1180problem.
1181
bellard15a34c62004-07-08 21:26:26 +00001182@chapter QEMU PowerPC System emulator invocation
bellard52c00a52004-04-25 21:27:03 +00001183
1184Use the executable @file{qemu-system-ppc} to simulate a complete PREP
bellard15a34c62004-07-08 21:26:26 +00001185or PowerMac PowerPC system.
1186
bellardb671f9e2005-04-30 15:08:33 +00001187QEMU emulates the following PowerMac peripherals:
bellard15a34c62004-07-08 21:26:26 +00001188
1189@itemize @minus
1190@item
1191UniNorth PCI Bridge
1192@item
1193PCI VGA compatible card with VESA Bochs Extensions
1194@item
11952 PMAC IDE interfaces with hard disk and CD-ROM support
1196@item
1197NE2000 PCI adapters
1198@item
1199Non Volatile RAM
1200@item
1201VIA-CUDA with ADB keyboard and mouse.
1202@end itemize
bellard52c00a52004-04-25 21:27:03 +00001203
bellardb671f9e2005-04-30 15:08:33 +00001204QEMU emulates the following PREP peripherals:
bellard52c00a52004-04-25 21:27:03 +00001205
1206@itemize @minus
1207@item
bellard15a34c62004-07-08 21:26:26 +00001208PCI Bridge
1209@item
1210PCI VGA compatible card with VESA Bochs Extensions
1211@item
bellard52c00a52004-04-25 21:27:03 +000012122 IDE interfaces with hard disk and CD-ROM support
1213@item
1214Floppy disk
1215@item
bellard15a34c62004-07-08 21:26:26 +00001216NE2000 network adapters
bellard52c00a52004-04-25 21:27:03 +00001217@item
1218Serial port
1219@item
1220PREP Non Volatile RAM
bellard15a34c62004-07-08 21:26:26 +00001221@item
1222PC compatible keyboard and mouse.
bellard52c00a52004-04-25 21:27:03 +00001223@end itemize
1224
bellard15a34c62004-07-08 21:26:26 +00001225QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1226@url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}.
1227
bellard52c00a52004-04-25 21:27:03 +00001228You can read the qemu PC system emulation chapter to have more
1229informations about QEMU usage.
1230
bellard15a34c62004-07-08 21:26:26 +00001231@c man begin OPTIONS
1232
1233The following options are specific to the PowerPC emulation:
1234
1235@table @option
1236
bellard15a34c62004-07-08 21:26:26 +00001237@item -g WxH[xDEPTH]
1238
1239Set the initial VGA graphic mode. The default is 800x600x15.
1240
1241@end table
1242
1243@c man end
1244
1245
bellard52c00a52004-04-25 21:27:03 +00001246More information is available at
1247@url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
1248
bellard34751872005-07-02 14:31:34 +00001249@chapter Sparc32 System emulator invocation
bellarde80cfcf2004-12-19 23:18:01 +00001250
1251Use the executable @file{qemu-system-sparc} to simulate a JavaStation
bellard34751872005-07-02 14:31:34 +00001252(sun4m architecture). The emulation is somewhat complete.
bellarde80cfcf2004-12-19 23:18:01 +00001253
bellardb671f9e2005-04-30 15:08:33 +00001254QEMU emulates the following sun4m peripherals:
bellarde80cfcf2004-12-19 23:18:01 +00001255
1256@itemize @minus
bellard34751872005-07-02 14:31:34 +00001257@item
bellarde80cfcf2004-12-19 23:18:01 +00001258IOMMU
1259@item
1260TCX Frame buffer
1261@item
1262Lance (Am7990) Ethernet
1263@item
1264Non Volatile RAM M48T08
1265@item
bellard34751872005-07-02 14:31:34 +00001266Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1267and power/reset logic
1268@item
1269ESP SCSI controller with hard disk and CD-ROM support
1270@item
1271Floppy drive
bellarde80cfcf2004-12-19 23:18:01 +00001272@end itemize
1273
bellard34751872005-07-02 14:31:34 +00001274The number of peripherals is fixed in the architecture.
bellarde80cfcf2004-12-19 23:18:01 +00001275
bellard34751872005-07-02 14:31:34 +00001276QEMU uses the Proll, a PROM replacement available at
1277@url{http://people.redhat.com/zaitcev/linux/}. The required
1278QEMU-specific patches are included with the sources.
1279
1280A sample Linux 2.6 series kernel and ram disk image are available on
1281the QEMU web site. Please note that currently neither Linux 2.4
1282series, NetBSD, nor OpenBSD kernels work.
1283
1284@c man begin OPTIONS
1285
1286The following options are specific to the Sparc emulation:
1287
1288@table @option
1289
1290@item -g WxH
1291
1292Set the initial TCX graphic mode. The default is 1024x768.
1293
1294@end table
1295
1296@c man end
1297
1298@chapter Sparc64 System emulator invocation
1299
1300Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
1301The emulator is not usable for anything yet.
bellardb7569212005-03-13 09:43:05 +00001302
bellard83469012005-07-23 14:27:54 +00001303QEMU emulates the following sun4u peripherals:
1304
1305@itemize @minus
1306@item
1307UltraSparc IIi APB PCI Bridge
1308@item
1309PCI VGA compatible card with VESA Bochs Extensions
1310@item
1311Non Volatile RAM M48T59
1312@item
1313PC-compatible serial ports
1314@end itemize
1315
bellard9d0a8e62005-07-03 17:34:05 +00001316@chapter MIPS System emulator invocation
1317
1318Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
1319The emulator begins to launch a Linux kernel.
1320
bellard1f673132004-04-04 15:21:17 +00001321@chapter QEMU User space emulator invocation
bellard386405f2003-03-23 21:28:45 +00001322
bellard1f673132004-04-04 15:21:17 +00001323@section Quick Start
bellard386405f2003-03-23 21:28:45 +00001324
bellard1f673132004-04-04 15:21:17 +00001325In order to launch a Linux process, QEMU needs the process executable
1326itself and all the target (x86) dynamic libraries used by it.
bellard386405f2003-03-23 21:28:45 +00001327
bellard1f673132004-04-04 15:21:17 +00001328@itemize
bellard386405f2003-03-23 21:28:45 +00001329
bellard1f673132004-04-04 15:21:17 +00001330@item On x86, you can just try to launch any process by using the native
1331libraries:
bellard386405f2003-03-23 21:28:45 +00001332
bellard1f673132004-04-04 15:21:17 +00001333@example
1334qemu-i386 -L / /bin/ls
1335@end example
bellardfd429f22003-03-30 20:59:46 +00001336
bellard1f673132004-04-04 15:21:17 +00001337@code{-L /} tells that the x86 dynamic linker must be searched with a
1338@file{/} prefix.
bellard1eb20522003-06-25 16:21:49 +00001339
bellard1f673132004-04-04 15:21:17 +00001340@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 +00001341
bellard1f673132004-04-04 15:21:17 +00001342@example
1343qemu-i386 -L / qemu-i386 -L / /bin/ls
1344@end example
bellard386405f2003-03-23 21:28:45 +00001345
bellard1f673132004-04-04 15:21:17 +00001346@item On non x86 CPUs, you need first to download at least an x86 glibc
1347(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1348@code{LD_LIBRARY_PATH} is not set:
bellard386405f2003-03-23 21:28:45 +00001349
bellard1f673132004-04-04 15:21:17 +00001350@example
1351unset LD_LIBRARY_PATH
1352@end example
bellard386405f2003-03-23 21:28:45 +00001353
bellard1f673132004-04-04 15:21:17 +00001354Then you can launch the precompiled @file{ls} x86 executable:
bellard386405f2003-03-23 21:28:45 +00001355
bellard1f673132004-04-04 15:21:17 +00001356@example
1357qemu-i386 tests/i386/ls
1358@end example
1359You can look at @file{qemu-binfmt-conf.sh} so that
1360QEMU is automatically launched by the Linux kernel when you try to
1361launch x86 executables. It requires the @code{binfmt_misc} module in the
1362Linux kernel.
bellard386405f2003-03-23 21:28:45 +00001363
bellard1f673132004-04-04 15:21:17 +00001364@item The x86 version of QEMU is also included. You can try weird things such as:
1365@example
1366qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1367@end example
bellard386405f2003-03-23 21:28:45 +00001368
bellard1f673132004-04-04 15:21:17 +00001369@end itemize
bellard386405f2003-03-23 21:28:45 +00001370
bellard1f673132004-04-04 15:21:17 +00001371@section Wine launch
bellard386405f2003-03-23 21:28:45 +00001372
bellard1f673132004-04-04 15:21:17 +00001373@itemize
bellard386405f2003-03-23 21:28:45 +00001374
bellard1f673132004-04-04 15:21:17 +00001375@item Ensure that you have a working QEMU with the x86 glibc
1376distribution (see previous section). In order to verify it, you must be
1377able to do:
bellard386405f2003-03-23 21:28:45 +00001378
bellard1f673132004-04-04 15:21:17 +00001379@example
1380qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1381@end example
bellard386405f2003-03-23 21:28:45 +00001382
bellard1f673132004-04-04 15:21:17 +00001383@item Download the binary x86 Wine install
1384(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
bellard386405f2003-03-23 21:28:45 +00001385
bellard1f673132004-04-04 15:21:17 +00001386@item Configure Wine on your account. Look at the provided script
1387@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
1388@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard386405f2003-03-23 21:28:45 +00001389
bellard1f673132004-04-04 15:21:17 +00001390@item Then you can try the example @file{putty.exe}:
bellard386405f2003-03-23 21:28:45 +00001391
bellard1f673132004-04-04 15:21:17 +00001392@example
1393qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1394@end example
bellard386405f2003-03-23 21:28:45 +00001395
bellard1f673132004-04-04 15:21:17 +00001396@end itemize
bellard386405f2003-03-23 21:28:45 +00001397
bellard1f673132004-04-04 15:21:17 +00001398@section Command line options
bellard386405f2003-03-23 21:28:45 +00001399
bellard1f673132004-04-04 15:21:17 +00001400@example
1401usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1402@end example
bellard386405f2003-03-23 21:28:45 +00001403
bellard1f673132004-04-04 15:21:17 +00001404@table @option
1405@item -h
1406Print the help
1407@item -L path
1408Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1409@item -s size
1410Set the x86 stack size in bytes (default=524288)
bellard386405f2003-03-23 21:28:45 +00001411@end table
1412
bellard1f673132004-04-04 15:21:17 +00001413Debug options:
bellard386405f2003-03-23 21:28:45 +00001414
bellard1f673132004-04-04 15:21:17 +00001415@table @option
1416@item -d
1417Activate log (logfile=/tmp/qemu.log)
1418@item -p pagesize
1419Act as if the host page size was 'pagesize' bytes
1420@end table
bellard386405f2003-03-23 21:28:45 +00001421
bellard15a34c62004-07-08 21:26:26 +00001422@node compilation
1423@chapter Compilation from the sources
1424
bellard7c3fc842005-02-10 21:46:47 +00001425@section Linux/Unix
bellard15a34c62004-07-08 21:26:26 +00001426
bellard7c3fc842005-02-10 21:46:47 +00001427@subsection Compilation
1428
1429First you must decompress the sources:
1430@example
1431cd /tmp
1432tar zxvf qemu-x.y.z.tar.gz
1433cd qemu-x.y.z
1434@end example
1435
1436Then you configure QEMU and build it (usually no options are needed):
1437@example
1438./configure
1439make
1440@end example
1441
1442Then type as root user:
1443@example
1444make install
1445@end example
1446to install QEMU in @file{/usr/local}.
1447
bellard7c3fc842005-02-10 21:46:47 +00001448@subsection Tested tool versions
1449
1450In order to compile QEMU succesfully, it is very important that you
1451have the right tools. The most important one is gcc. I cannot guaranty
1452that QEMU works if you do not use a tested gcc version. Look at
1453'configure' and 'Makefile' if you want to make a different gcc
1454version work.
1455
1456@example
1457host gcc binutils glibc linux distribution
1458----------------------------------------------------------------------
1459x86 3.2 2.13.2 2.1.3 2.4.18
1460 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3
1461 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9
1462
1463PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq
1464 3.2
1465
1466Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0
1467
1468Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0
1469
1470ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0
1471
1472[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
1473 for gcc version >= 3.3.
1474[2] Linux >= 2.4.20 is necessary for precise exception support
1475 (untested).
1476[3] 2.4.9-ac10-rmk2-np1-cerf2
1477
1478[4] gcc 2.95.x generates invalid code when using too many register
1479variables. You must use gcc 3.x on PowerPC.
1480@end example
bellard15a34c62004-07-08 21:26:26 +00001481
1482@section Windows
1483
1484@itemize
1485@item Install the current versions of MSYS and MinGW from
1486@url{http://www.mingw.org/}. You can find detailed installation
1487instructions in the download section and the FAQ.
1488
1489@item Download
1490the MinGW development library of SDL 1.2.x
1491(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
1492@url{http://www.libsdl.org}. Unpack it in a temporary place, and
1493unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
1494directory. Edit the @file{sdl-config} script so that it gives the
1495correct SDL directory when invoked.
1496
1497@item Extract the current version of QEMU.
1498
1499@item Start the MSYS shell (file @file{msys.bat}).
1500
1501@item Change to the QEMU directory. Launch @file{./configure} and
1502@file{make}. If you have problems using SDL, verify that
1503@file{sdl-config} can be launched from the MSYS command line.
1504
1505@item You can install QEMU in @file{Program Files/Qemu} by typing
1506@file{make install}. Don't forget to copy @file{SDL.dll} in
1507@file{Program Files/Qemu}.
1508
1509@end itemize
1510
1511@section Cross compilation for Windows with Linux
1512
1513@itemize
1514@item
1515Install the MinGW cross compilation tools available at
1516@url{http://www.mingw.org/}.
1517
1518@item
1519Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
1520unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
1521variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
1522the QEMU configuration script.
1523
1524@item
1525Configure QEMU for Windows cross compilation:
1526@example
1527./configure --enable-mingw32
1528@end example
1529If necessary, you can change the cross-prefix according to the prefix
1530choosen for the MinGW tools with --cross-prefix. You can also use
1531--prefix to set the Win32 install path.
1532
1533@item You can install QEMU in the installation directory by typing
1534@file{make install}. Don't forget to copy @file{SDL.dll} in the
1535installation directory.
1536
1537@end itemize
1538
1539Note: Currently, Wine does not seem able to launch
1540QEMU for Win32.
1541
1542@section Mac OS X
1543
1544The Mac OS X patches are not fully merged in QEMU, so you should look
1545at the QEMU mailing list archive to have all the necessary
1546information.
1547