qemu-doc.texi 46.2 KB
Newer Older
bellard's avatar
bellard committed
1
2
\input texinfo @c -*- texinfo -*-

bellard's avatar
updated    
bellard committed
3
@iftex
bellard's avatar
bellard committed
4
@settitle QEMU CPU Emulator User Documentation
bellard's avatar
bellard committed
5
6
@titlepage
@sp 7
bellard's avatar
bellard committed
7
@center @titlefont{QEMU CPU Emulator User Documentation}
bellard's avatar
bellard committed
8
9
@sp 3
@end titlepage
bellard's avatar
updated    
bellard committed
10
@end iftex
bellard's avatar
bellard committed
11
12
13

@chapter Introduction

bellard's avatar
update    
bellard committed
14
@section Features
bellard's avatar
bellard committed
15

bellard's avatar
bellard committed
16
17
QEMU is a FAST! processor emulator using dynamic translation to
achieve good emulation speed.
bellard's avatar
update    
bellard committed
18
19

QEMU has two operating modes:
bellard's avatar
updated    
bellard committed
20
21
22
23

@itemize @minus

@item 
bellard's avatar
bellard committed
24
Full system emulation. In this mode, QEMU emulates a full system (for
bellard's avatar
bellard committed
25
26
27
example a PC), including one or several processors and various
peripherals. It can be used to launch different Operating Systems
without rebooting the PC or to debug system code.
bellard's avatar
update    
bellard committed
28

bellard's avatar
updated    
bellard committed
29
@item 
bellard's avatar
bellard committed
30
31
32
33
User mode emulation (Linux host only). In this mode, QEMU can launch
Linux processes compiled for one CPU on another CPU. It can be used to
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
to ease cross-compilation and cross-debugging.
bellard's avatar
update    
bellard committed
34
35
36

@end itemize

bellard's avatar
update    
bellard committed
37
QEMU can run without an host kernel driver and yet gives acceptable
38
performance. 
bellard's avatar
update    
bellard committed
39

bellard's avatar
update    
bellard committed
40
41
For system emulation, the following hardware targets are supported:
@itemize
bellard's avatar
update    
bellard committed
42
@item PC (x86 or x86_64 processor)
bellard's avatar
bellard committed
43
@item ISA PC (old style PC without PCI bus)
bellard's avatar
update    
bellard committed
44
@item PREP (PowerPC processor)
bellard's avatar
update    
bellard committed
45
46
@item G3 BW PowerMac (PowerPC processor)
@item Mac99 PowerMac (PowerPC processor, in progress)
bellard's avatar
bellard committed
47
48
@item Sun4m (32-bit Sparc processor)
@item Sun4u (64-bit Sparc processor, in progress)
bellard's avatar
bellard committed
49
50
@item Malta board (32-bit MIPS processor)
@item ARM Integrator/CP (ARM1026E processor)
bellard's avatar
update    
bellard committed
51
@end itemize
bellard's avatar
bellard committed
52

bellard's avatar
bellard committed
53
For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported.
bellard's avatar
updated    
bellard committed
54

bellard's avatar
update    
bellard committed
55
56
@chapter Installation

bellard's avatar
bellard committed
57
58
If you want to compile QEMU yourself, see @ref{compilation}.

bellard's avatar
bellard committed
59
60
@section Linux

bellard's avatar
update    
bellard committed
61
62
If a precompiled package is available for your distribution - you just
have to install it. Otherwise, see @ref{compilation}.
bellard's avatar
update    
bellard committed
63

bellard's avatar
bellard committed
64
@section Windows
bellard's avatar
update    
bellard committed
65

bellard's avatar
bellard committed
66
67
Download the experimental binary installer at
@url{http://www.freeoszoo.org/download.php}.
68

bellard's avatar
bellard committed
69
@section Mac OS X
70

bellard's avatar
bellard committed
71
72
Download the experimental binary installer at
@url{http://www.freeoszoo.org/download.php}.
bellard's avatar
update    
bellard committed
73

bellard's avatar
bellard committed
74
@chapter QEMU PC System emulator
bellard's avatar
update    
bellard committed
75

bellard's avatar
updated    
bellard committed
76
77
78
79
@section Introduction

@c man begin DESCRIPTION

bellard's avatar
bellard committed
80
81
The QEMU PC System emulator simulates the
following peripherals:
bellard's avatar
updated    
bellard committed
82
83

@itemize @minus
bellard's avatar
bellard committed
84
85
@item 
i440FX host PCI bridge and PIIX3 PCI to ISA bridge
bellard's avatar
updated    
bellard committed
86
@item
bellard's avatar
bellard committed
87
88
Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
extensions (hardware level, including all non standard modes).
bellard's avatar
updated    
bellard committed
89
90
91
@item
PS/2 mouse and keyboard
@item 
bellard's avatar
bellard committed
92
2 PCI IDE interfaces with hard disk and CD-ROM support
bellard's avatar
bellard committed
93
94
@item
Floppy disk
bellard's avatar
updated    
bellard committed
95
@item 
bellard's avatar
bellard committed
96
NE2000 PCI network adapters
bellard's avatar
updated    
bellard committed
97
@item
bellard's avatar
update    
bellard committed
98
99
Serial ports
@item
bellard's avatar
bellard committed
100
101
102
103
104
Creative SoundBlaster 16 sound card
@item
ENSONIQ AudioPCI ES1370 sound card
@item
Adlib(OPL2) - Yamaha YM3812 compatible chip
bellard's avatar
bellard committed
105
106
@item
PCI UHCI USB controller and a virtual USB hub.
bellard's avatar
updated    
bellard committed
107
108
@end itemize

bellard's avatar
bellard committed
109
110
SMP is supported with up to 255 CPUs.

bellard's avatar
bellard committed
111
112
113
Note that adlib is only available when QEMU was configured with
-enable-adlib

bellard's avatar
bellard committed
114
115
116
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
VGA BIOS.

bellard's avatar
bellard committed
117
118
QEMU uses YM3812 emulation by Tatsuyuki Satoh.

bellard's avatar
updated    
bellard committed
119
120
@c man end

bellard's avatar
update    
bellard committed
121
122
@section Quick Start

bellard's avatar
update    
bellard committed
123
Download and uncompress the linux image (@file{linux.img}) and type:
bellard's avatar
updated    
bellard committed
124
125

@example
bellard's avatar
update    
bellard committed
126
qemu linux.img
bellard's avatar
updated    
bellard committed
127
128
129
130
@end example

Linux should boot and give you a prompt.

bellard's avatar
update    
bellard committed
131
@node sec_invocation
bellard's avatar
update    
bellard committed
132
133
134
@section Invocation

@example
bellard's avatar
updated    
bellard committed
135
136
137
@c man begin SYNOPSIS
usage: qemu [options] [disk_image]
@c man end
bellard's avatar
update    
bellard committed
138
139
@end example

bellard's avatar
updated    
bellard committed
140
@c man begin OPTIONS
bellard's avatar
update    
bellard committed
141
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
bellard's avatar
update    
bellard committed
142
143
144

General options:
@table @option
145
146
147
@item -M machine
Select the emulated machine (@code{-M ?} for list)

bellard's avatar
update    
bellard committed
148
149
@item -fda file
@item -fdb file
bellard's avatar
update    
bellard committed
150
151
Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
use the host floppy by using @file{/dev/fd0} as filename.
bellard's avatar
update    
bellard committed
152

bellard's avatar
update    
bellard committed
153
154
@item -hda file
@item -hdb file
bellard's avatar
update    
bellard committed
155
156
@item -hdc file
@item -hdd file
bellard's avatar
update    
bellard committed
157
Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
bellard's avatar
bellard committed
158

bellard's avatar
update    
bellard committed
159
160
@item -cdrom file
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
bellard's avatar
update    
bellard committed
161
162
@option{-cdrom} at the same time). You can use the host CD-ROM by
using @file{/dev/cdrom} as filename.
bellard's avatar
update    
bellard committed
163

bellard's avatar
bellard committed
164
165
@item -boot [a|c|d]
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
bellard's avatar
update    
bellard committed
166
the default.
bellard's avatar
bellard committed
167

bellard's avatar
update    
bellard committed
168
@item -snapshot
bellard's avatar
bellard committed
169
170
171
Write to temporary files instead of disk image files. In this case,
the raw disk image you use is not written back. You can however force
the write back by pressing @key{C-a s} (@xref{disk_images}). 
bellard's avatar
update    
bellard committed
172
173

@item -m megs
bellard's avatar
bellard committed
174
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
bellard's avatar
update    
bellard committed
175

bellard's avatar
bellard committed
176
177
178
179
@item -smp n
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
CPUs are supported.

bellard's avatar
updated    
bellard committed
180
181
182
183
184
185
186
187
@item -nographic

Normally, QEMU uses SDL to display the VGA output. With this option,
you can totally disable graphical output so that QEMU is a simple
command line application. The emulated serial port is redirected on
the console. Therefore, you can still use QEMU to debug a Linux kernel
with a serial console.

188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
@item -k language

Use keyboard layout @var{language} (for example @code{fr} for
French). This option is only needed where it is not easy to get raw PC
keycodes (e.g. on Macs or with some X11 servers). You don't need to
use it on PC/Linux or PC/Windows hosts.

The available layouts are:
@example
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
@end example

The default is @code{en-us}.

204
205
206
207
208
@item -audio-help

Will show the audio subsystem help: list of drivers, tunable
parameters.

209
@item -soundhw card1,card2,... or -soundhw all
210
211
212
213
214
215
216

Enable audio and selected sound hardware. Use ? to print all
available sound hardware.

@example
qemu -soundhw sb16,adlib hda
qemu -soundhw es1370 hda
217
qemu -soundhw all hda
218
219
qemu -soundhw ?
@end example
bellard's avatar
update    
bellard committed
220

bellard's avatar
bellard committed
221
222
223
224
225
@item -localtime
Set the real time clock to local time (the default is to UTC
time). This option is needed to have correct date in MS-DOS or
Windows.

bellard's avatar
bellard committed
226
227
228
@item -full-screen
Start in full screen.

bellard's avatar
bellard committed
229
230
231
232
@item -pidfile file
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
from a script.

bellard's avatar
update    
bellard committed
233
234
235
236
237
@item -win2k-hack
Use it when installing Windows 2000 to avoid a disk full bug. After
Windows 2000 is installed, you no longer need this option (this option
slows down the IDE transfers).

bellard's avatar
updated    
bellard committed
238
239
@end table

bellard's avatar
bellard committed
240
241
242
243
244
245
246
247
248
249
250
USB options:
@table @option

@item -usb
Enable the USB driver (will be the default soon)

@item -usbdevice devname
Add the USB device @var{devname}. See the monitor command
@code{usb_add} to have more information.
@end table

bellard's avatar
bellard committed
251
252
253
254
Network options:

@table @option

bellard's avatar
update    
bellard committed
255
256
257
258
259
260
261
@item -net nic[,vlan=n][,macaddr=addr]
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
= 0 is the default). The NIC is currently an NE2000 on the PC
target. Optionally, the MAC address can be changed. If no
@option{-net} option is specified, a single NIC is created.

@item -net user[,vlan=n]
bellard's avatar
update    
bellard committed
262
Use the user mode network stack which requires no administrator
bellard's avatar
update    
bellard committed
263
264
265
266
267
268
269
270
271
priviledge to run. This is the default if no @option{-net} option is
specified.

@item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
Connect the host TAP network interface @var{name} to VLAN @var{n} and
use the network script @var{file} to configure it. The default
network script is @file{/etc/qemu-ifup}. If @var{name} is not
provided, the OS automatically provides one.  @option{fd=h} can be
used to specify the handle of an already opened host TAP interface. Example:
bellard's avatar
bellard committed
272

bellard's avatar
update    
bellard committed
273
274
275
276
277
278
279
280
281
@example
qemu linux.img -net nic -net tap
@end example

More complicated example (two NICs, each one connected to a TAP device)
@example
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
@end example
bellard's avatar
bellard committed
282
283


bellard's avatar
update    
bellard committed
284
@item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
bellard's avatar
bellard committed
285

bellard's avatar
update    
bellard committed
286
287
288
289
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
machine using a TCP socket connection. If @option{listen} is
specified, QEMU waits for incoming connections on @var{port}
(@var{host} is optional). @option{connect} is used to connect to
290
291
another QEMU instance using the @option{listen} option. @option{fd=h}
specifies an already opened TCP socket.
bellard's avatar
bellard committed
292

bellard's avatar
update    
bellard committed
293
294
295
Example:
@example
# launch a first QEMU instance
bellard's avatar
update    
bellard committed
296
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,listen=:1234
bellard's avatar
update    
bellard committed
297
# connect the VLAN 0 of this instance to the VLAN 0 of the first instance
bellard's avatar
update    
bellard committed
298
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,connect=127.0.0.1:1234
bellard's avatar
update    
bellard committed
299
@end example
bellard's avatar
update    
bellard committed
300

301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
@item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]

Create a VLAN @var{n} shared with another QEMU virtual
machines using a UDP multicast socket, effectively making a bus for 
every QEMU with same multicast address @var{maddr} and @var{port}.
NOTES:
@enumerate
@item 
Several QEMU can be running on different hosts and share same bus (assuming 
correct multicast setup for these hosts).
@item
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
@url{http://user-mode-linux.sf.net}.
@item Use @option{fd=h} to specify an already opened UDP multicast socket.
@end enumerate

Example:
@example
# launch one QEMU instance
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=230.0.0.1:1234
# launch another QEMU instance on same "bus"
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,mcast=230.0.0.1:1234
# launch yet another QEMU instance on same "bus"
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 -net socket,mcast=230.0.0.1:1234
@end example

Example (User Mode Linux compat.):
@example
# launch QEMU instance (note mcast address selected is UML's default)
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=239.192.168.1:1102
# launch UML
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example

bellard's avatar
update    
bellard committed
335
336
337
338
@item -net none
Indicate that no network devices should be configured. It is used to
override the default configuration which is activated if no
@option{-net} options are provided.
bellard's avatar
update    
bellard committed
339

bellard's avatar
bellard committed
340
341
342
343
344
345
346
347
@item -tftp prefix
When using the user mode network stack, activate a built-in TFTP
server. All filenames beginning with @var{prefix} can be downloaded
from the host to the guest using a TFTP client. The TFTP client on the
guest must be configured in binary mode (use the command @code{bin} of
the Unix TFTP client). The host IP address on the guest is as usual
10.0.2.2.

bellard's avatar
update    
bellard committed
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
@item -smb dir
When using the user mode network stack, activate a built-in SMB
server so that Windows OSes can access to the host files in @file{dir}
transparently.

In the guest Windows OS, the line:
@example
10.0.2.4 smbserver
@end example
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).

Then @file{dir} can be accessed in @file{\\smbserver\qemu}.

Note that a SAMBA server must be installed on the host OS in
@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
bellard's avatar
update    
bellard committed
364
2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
bellard's avatar
update    
bellard committed
365

bellard's avatar
bellard committed
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
@item -redir [tcp|udp]:host-port:[guest-host]:guest-port

When using the user mode network stack, redirect incoming TCP or UDP
connections to the host port @var{host-port} to the guest
@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
is not specified, its value is 10.0.2.15 (default address given by the
built-in DHCP server).

For example, to redirect host X11 connection from screen 1 to guest
screen 0, use the following:

@example
# on the host
qemu -redir tcp:6001::6000 [...]
# this host xterm should open in the guest X11 server
xterm -display :1
@end example

To redirect telnet connections from host port 5555 to telnet port on
the guest, use the following:

@example
# on the host
qemu -redir tcp:5555::23 [...]
telnet localhost 5555
@end example

Then when you use on the host @code{telnet localhost 5555}, you
connect to the guest telnet server.

bellard's avatar
bellard committed
396
397
@end table

bellard's avatar
update    
bellard committed
398
Linux boot specific: When using these options, you can use a given
bellard's avatar
bellard committed
399
400
401
Linux kernel without installing it in the disk image. It can be useful
for easier testing of various kernels.

bellard's avatar
updated    
bellard committed
402
403
404
405
406
407
408
409
410
411
412
@table @option

@item -kernel bzImage 
Use @var{bzImage} as kernel image.

@item -append cmdline 
Use @var{cmdline} as kernel command line

@item -initrd file
Use @var{file} as initial ram disk.

bellard's avatar
update    
bellard committed
413
414
@end table

bellard's avatar
bellard committed
415
Debug/Expert options:
bellard's avatar
update    
bellard committed
416
@table @option
bellard's avatar
update    
bellard committed
417
418
419
420
421
422
423
424
425
426
427

@item -serial dev
Redirect the virtual serial port to host device @var{dev}. Available
devices are:
@table @code
@item vc
Virtual console
@item pty
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
@item null
void device
bellard's avatar
bellard committed
428
@item /dev/XXX
bellard's avatar
bellard committed
429
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
bellard's avatar
bellard committed
430
parameters are set according to the emulated ones.
bellard's avatar
bellard committed
431
432
433
@item /dev/parportN
[Linux only, parallel port only] Use host parallel port
@var{N}. Currently only SPP parallel port features can be used.
bellard's avatar
bellard committed
434
435
@item file:filename
Write output to filename. No character can be read.
bellard's avatar
update    
bellard committed
436
437
@item stdio
[Unix only] standard input/output
bellard's avatar
bellard committed
438
439
@item pipe:filename
[Unix only] name pipe @var{filename}
bellard's avatar
update    
bellard committed
440
441
442
443
@end table
The default device is @code{vc} in graphical mode and @code{stdio} in
non graphical mode.

bellard's avatar
update    
bellard committed
444
445
446
This option can be used several times to simulate up to 4 serials
ports.

bellard's avatar
bellard committed
447
448
449
450
451
452
453
454
455
@item -parallel dev
Redirect the virtual parallel port to host device @var{dev} (same
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
be used to use hardware devices connected on the corresponding host
parallel port.

This option can be used several times to simulate up to 3 parallel
ports.

bellard's avatar
update    
bellard committed
456
457
458
459
460
461
@item -monitor dev
Redirect the monitor to host device @var{dev} (same devices as the
serial port).
The default device is @code{vc} in graphical mode and @code{stdio} in
non graphical mode.

bellard's avatar
update    
bellard committed
462
@item -s
bellard's avatar
updated    
bellard committed
463
Wait gdb connection to port 1234 (@xref{gdb_usage}). 
bellard's avatar
update    
bellard committed
464
465
@item -p port
Change gdb connection port.
bellard's avatar
update    
bellard committed
466
467
@item -S
Do not start CPU at startup (you must type 'c' in the monitor).
bellard's avatar
update    
bellard committed
468
@item -d             
bellard's avatar
update    
bellard committed
469
Output log in /tmp/qemu.log
bellard's avatar
bellard committed
470
471
472
473
474
475
@item -hdachs c,h,s,[,t]
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
all thoses parameters. This option is useful for old MS-DOS disk
images.
bellard's avatar
update    
bellard committed
476

bellard's avatar
bellard committed
477
478
479
@item -std-vga
Simulate a standard VGA card with Bochs VBE extensions (default is
Cirrus Logic GD5446 PCI VGA)
bellard's avatar
bellard committed
480
481
@item -loadvm file
Start right away with a saved state (@code{loadvm} in monitor)
bellard's avatar
update    
bellard committed
482
483
@end table

bellard's avatar
update    
bellard committed
484
485
486
487
488
489
@c man end

@section Keys

@c man begin OPTIONS

bellard's avatar
update    
bellard committed
490
491
During the graphical emulation, you can use the following keys:
@table @key
bellard's avatar
update    
bellard committed
492
@item Ctrl-Alt-f
bellard's avatar
update    
bellard committed
493
Toggle full screen
bellard's avatar
update    
bellard committed
494

bellard's avatar
update    
bellard committed
495
@item Ctrl-Alt-n
bellard's avatar
update    
bellard committed
496
497
498
499
500
501
502
503
Switch to virtual console 'n'. Standard console mappings are:
@table @emph
@item 1
Target system display
@item 2
Monitor
@item 3
Serial port
bellard's avatar
update    
bellard committed
504
505
@end table

bellard's avatar
update    
bellard committed
506
@item Ctrl-Alt
bellard's avatar
update    
bellard committed
507
508
509
Toggle mouse and keyboard grab.
@end table

bellard's avatar
update    
bellard committed
510
511
512
In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.

bellard's avatar
update    
bellard committed
513
514
During emulation, if you are using the @option{-nographic} option, use
@key{Ctrl-a h} to get terminal commands:
bellard's avatar
update    
bellard committed
515
516

@table @key
bellard's avatar
update    
bellard committed
517
@item Ctrl-a h
bellard's avatar
update    
bellard committed
518
Print this help
bellard's avatar
update    
bellard committed
519
@item Ctrl-a x    
bellard's avatar
update    
bellard committed
520
Exit emulatior
bellard's avatar
update    
bellard committed
521
@item Ctrl-a s    
bellard's avatar
bellard committed
522
Save disk data back to file (if -snapshot)
bellard's avatar
update    
bellard committed
523
@item Ctrl-a b
bellard's avatar
bellard committed
524
Send break (magic sysrq in Linux)
bellard's avatar
update    
bellard committed
525
@item Ctrl-a c
bellard's avatar
bellard committed
526
Switch between console and monitor
bellard's avatar
update    
bellard committed
527
528
@item Ctrl-a Ctrl-a
Send Ctrl-a
bellard's avatar
update    
bellard committed
529
@end table
bellard's avatar
updated    
bellard committed
530
531
532
533
534
535
536
@c man end

@ignore

@setfilename qemu 
@settitle QEMU System Emulator

bellard's avatar
bellard committed
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
@c man begin SEEALSO
The HTML documentation of QEMU for more precise information and Linux
user mode emulator invocation.
@c man end

@c man begin AUTHOR
Fabrice Bellard
@c man end

@end ignore

@end ignore

@section QEMU Monitor

The QEMU monitor is used to give complex commands to the QEMU
emulator. You can use it to:

@itemize @minus

@item
Remove or insert removable medias images
(such as CD-ROM or floppies)

@item 
Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
from a disk file.

@item Inspect the VM state without an external debugger.

@end itemize

@subsection Commands

The following commands are available:

@table @option

@item help or ? [cmd]
Show the help for all commands or just for command @var{cmd}.

@item commit  
Commit changes to the disk images (if -snapshot is used)

@item info subcommand 
show various information about the system state

@table @option
@item info network
bellard's avatar
update    
bellard committed
586
show the various VLANs and the associated devices
bellard's avatar
bellard committed
587
588
589
590
591
592
@item info block
show the block devices
@item info registers
show the cpu registers
@item info history
show the command line history
bellard's avatar
bellard committed
593
594
595
596
597
598
@item info pci
show emulated PCI device
@item info usb
show USB devices plugged on the virtual USB hub
@item info usbhost
show all USB host devices
bellard's avatar
bellard committed
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
@end table

@item q or quit
Quit the emulator.

@item eject [-f] device
Eject a removable media (use -f to force it).

@item change device filename
Change a removable media.

@item screendump filename
Save screen into PPM image @var{filename}.

@item log item1[,...]
Activate logging of the specified items to @file{/tmp/qemu.log}.

@item savevm filename
Save the whole virtual machine state to @var{filename}.

@item loadvm filename
Restore the whole virtual machine state from @var{filename}.

@item stop
Stop emulation.

@item c or cont
Resume emulation.

@item gdbserver [port]
Start gdbserver session (default port=1234)

@item x/fmt addr
Virtual memory dump starting at @var{addr}.

@item xp /fmt addr
Physical memory dump starting at @var{addr}.

@var{fmt} is a format which tells the command how to format the
data. Its syntax is: @option{/@{count@}@{format@}@{size@}}

@table @var
@item count 
is the number of items to be dumped.

@item format
can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
c (char) or i (asm instruction).

@item size
bellard's avatar
update    
bellard committed
649
650
651
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
@code{h} or @code{w} can be specified with the @code{i} format to
respectively select 16 or 32 bit code instruction size.
bellard's avatar
bellard committed
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693

@end table

Examples: 
@itemize
@item
Dump 10 instructions at the current instruction pointer:
@example 
(qemu) x/10i $eip
0x90107063:  ret
0x90107064:  sti
0x90107065:  lea    0x0(%esi,1),%esi
0x90107069:  lea    0x0(%edi,1),%edi
0x90107070:  ret
0x90107071:  jmp    0x90107080
0x90107073:  nop
0x90107074:  nop
0x90107075:  nop
0x90107076:  nop
@end example

@item
Dump 80 16 bit values at the start of the video memory.
@example 
(qemu) xp/80hx 0xb8000
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
@end example
@end itemize

@item p or print/fmt expr

Print expression value. Only the @var{format} part of @var{fmt} is
used.
bellard's avatar
updated    
bellard committed
694

bellard's avatar
bellard committed
695
696
697
698
699
700
701
702
703
704
705
@item sendkey keys

Send @var{keys} to the emulator. Use @code{-} to press several keys
simultaneously. Example:
@example
sendkey ctrl-alt-f1
@end example

This command is useful to send keys that your graphical user interface
intercepts at low level, such as @code{ctrl-alt-f1} in X Window.

bellard's avatar
bellard committed
706
707
708
709
@item system_reset

Reset the system.

bellard's avatar
bellard committed
710
711
712
713
714
715
716
717
718
719
720
721
722
@item usb_add devname

Plug the USB device devname to the QEMU virtual USB hub. @var{devname}
is either a virtual device name (for example @code{mouse}) or a host
USB device identifier. Host USB device identifiers have the following
syntax: @code{host:bus.addr} or @code{host:vendor_id:product_id}.

@item usb_del devname

Remove the USB device @var{devname} from the QEMU virtual USB
hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
command @code{info usb} to see the devices you can remove.

bellard's avatar
bellard committed
723
@end table
bellard's avatar
updated    
bellard committed
724

bellard's avatar
bellard committed
725
726
727
728
729
@subsection Integer expressions

The monitor understands integers expressions for every integer
argument. You can use register names to get the value of specifics
CPU registers by prefixing them with @emph{$}.
bellard's avatar
update    
bellard committed
730

bellard's avatar
bellard committed
731
732
733
@node disk_images
@section Disk Images

734
735
736
Since version 0.6.1, QEMU supports many disk image formats, including
growable disk images (their size increase as non empty sectors are
written), compressed and encrypted disk images.
bellard's avatar
bellard committed
737

738
739
740
@subsection Quick start for disk image creation

You can create a disk image with the command:
bellard's avatar
bellard committed
741
@example
742
qemu-img create myimage.img mysize
bellard's avatar
bellard committed
743
@end example
744
745
746
747
748
where @var{myimage.img} is the disk image filename and @var{mysize} is its
size in kilobytes. You can add an @code{M} suffix to give the size in
megabytes and a @code{G} suffix for gigabytes.

@xref{qemu_img_invocation} for more information.
bellard's avatar
bellard committed
749
750
751
752
753
754

@subsection Snapshot mode

If you use the option @option{-snapshot}, all disk images are
considered as read only. When sectors in written, they are written in
a temporary file created in @file{/tmp}. You can however force the
755
756
write back to the raw disk images by using the @code{commit} monitor
command (or @key{C-a s} in the serial console).
bellard's avatar
bellard committed
757

758
759
@node qemu_img_invocation
@subsection @code{qemu-img} Invocation
bellard's avatar
bellard committed
760

761
@include qemu-img.texi
bellard's avatar
bellard committed
762

bellard's avatar
update    
bellard committed
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
@subsection Virtual FAT disk images

QEMU can automatically create a virtual FAT disk image from a
directory tree. In order to use it, just type:

@example 
qemu linux.img -hdb fat:/my_directory
@end example

Then you access access to all the files in the @file{/my_directory}
directory without having to copy them in a disk image or to export
them via SAMBA or NFS. The default access is @emph{read-only}.

Floppies can be emulated with the @code{:floppy:} option:

@example 
qemu linux.img -fda fat:floppy:/my_directory
@end example

A read/write support is available for testing (beta stage) with the
@code{:rw:} option:

@example 
qemu linux.img -fda fat:floppy:rw:/my_directory
@end example

What you should @emph{never} do:
@itemize
@item use non-ASCII filenames ;
@item use "-snapshot" together with ":rw:" ;
bellard's avatar
bellard committed
793
794
@item expect it to work when loadvm'ing ;
@item write to the FAT directory on the host system while accessing it with the guest system.
bellard's avatar
update    
bellard committed
795
796
@end itemize

bellard's avatar
update    
bellard committed
797
798
@section Network emulation

bellard's avatar
update    
bellard committed
799
800
801
802
803
804
805
806
807
QEMU can simulate several networks cards (NE2000 boards on the PC
target) and can connect them to an arbitrary number of Virtual Local
Area Networks (VLANs). Host TAP devices can be connected to any QEMU
VLAN. VLAN can be connected between separate instances of QEMU to
simulate large networks. For simpler usage, a non priviledged user mode
network stack can replace the TAP device to have a basic network
connection.

@subsection VLANs
bellard's avatar
update    
bellard committed
808

bellard's avatar
update    
bellard committed
809
810
811
812
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
connection between several network devices. These devices can be for
example QEMU virtual Ethernet cards or virtual Host ethernet devices
(TAP devices).
bellard's avatar
update    
bellard committed
813

bellard's avatar
update    
bellard committed
814
815
816
817
818
@subsection Using TAP network interfaces

This is the standard way to connect QEMU to a real network. QEMU adds
a virtual network device on your host (called @code{tapN}), and you
can then configure it as if it was a real ethernet card.
bellard's avatar
update    
bellard committed
819
820
821
822
823

As an example, you can download the @file{linux-test-xxx.tar.gz}
archive and copy the script @file{qemu-ifup} in @file{/etc} and
configure properly @code{sudo} so that the command @code{ifconfig}
contained in @file{qemu-ifup} can be executed as root. You must verify
bellard's avatar
update    
bellard committed
824
that your host kernel supports the TAP network interfaces: the
bellard's avatar
update    
bellard committed
825
826
827
device @file{/dev/net/tun} must be present.

See @ref{direct_linux_boot} to have an example of network use with a
bellard's avatar
update    
bellard committed
828
829
Linux distribution and @ref{sec_invocation} to have examples of
command lines using the TAP network interfaces.
bellard's avatar
update    
bellard committed
830
831
832

@subsection Using the user mode network stack

bellard's avatar
update    
bellard committed
833
834
835
836
By using the option @option{-net user} (default configuration if no
@option{-net} option is specified), QEMU uses a completely user mode
network stack (you don't need root priviledge to use the virtual
network). The virtual network configuration is the following:
bellard's avatar
update    
bellard committed
837
838
839

@example

bellard's avatar
update    
bellard committed
840
841
         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
                           |          (10.0.2.2)
bellard's avatar
update    
bellard committed
842
                           |
bellard's avatar
update    
bellard committed
843
844
845
                           ---->  DNS server (10.0.2.3)
                           |     
                           ---->  SMB server (10.0.2.4)
bellard's avatar
update    
bellard committed
846
847
848
849
@end example

The QEMU VM behaves as if it was behind a firewall which blocks all
incoming connections. You can use a DHCP client to automatically
bellard's avatar
update    
bellard committed
850
851
configure the network in the QEMU VM. The DHCP server assign addresses
to the hosts starting from 10.0.2.15.
bellard's avatar
update    
bellard committed
852
853
854
855
856

In order to check that the user mode network is working, you can ping
the address 10.0.2.2 and verify that you got an address in the range
10.0.2.x from the QEMU virtual DHCP server.

bellard's avatar
update    
bellard committed
857
858
859
860
Note that @code{ping} is not supported reliably to the internet as it
would require root priviledges. It means you can only ping the local
router (10.0.2.2).

bellard's avatar
bellard committed
861
862
863
864
865
866
When using the built-in TFTP server, the router is also the TFTP
server.

When using the @option{-redir} option, TCP or UDP connections can be
redirected from the host to the guest. It allows for example to
redirect X11, telnet or SSH connections.
bellard's avatar
bellard committed
867

bellard's avatar
update    
bellard committed
868
869
870
871
872
873
@subsection Connecting VLANs between QEMU instances

Using the @option{-net socket} option, it is possible to make VLANs
that span several QEMU instances. See @ref{sec_invocation} to have a
basic example.

bellard's avatar
update    
bellard committed
874
875
@node direct_linux_boot
@section Direct Linux Boot
bellard's avatar
bellard committed
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019

This section explains how to launch a Linux kernel inside QEMU without
having to make a full bootable image. It is very useful for fast Linux
kernel testing. The QEMU network configuration is also explained.

@enumerate
@item
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
kernel and a disk image. 

@item Optional: If you want network support (for example to launch X11 examples), you
must copy the script @file{qemu-ifup} in @file{/etc} and configure
properly @code{sudo} so that the command @code{ifconfig} contained in
@file{qemu-ifup} can be executed as root. You must verify that your host
kernel supports the TUN/TAP network interfaces: the device
@file{/dev/net/tun} must be present.

When network is enabled, there is a virtual network connection between
the host kernel and the emulated kernel. The emulated kernel is seen
from the host kernel at IP address 172.20.0.2 and the host kernel is
seen from the emulated kernel at IP address 172.20.0.1.

@item Launch @code{qemu.sh}. You should have the following output:

@example
> ./qemu.sh 
Connected to host network interface: tun0
Linux 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
BIOS-provided physical RAM map:
 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
32MB LOWMEM available.
On node 0 totalpages: 8192
zone(0): 4096 pages.
zone(1): 4096 pages.
zone(2): 0 pages.
Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
ide_setup: ide2=noprobe
ide_setup: ide3=noprobe
ide_setup: ide4=noprobe
ide_setup: ide5=noprobe
Initializing CPU#0
Detected 2399.621 MHz processor.
Console: colour EGA 80x25
Calibrating delay loop... 4744.80 BogoMIPS
Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
CPU: Intel Pentium Pro stepping 03
Checking 'hlt' instruction... OK.
POSIX conformance testing by UNIFIX
Linux NET4.0 for Linux 2.4
Based upon Swansea University Computer Society NET3.039
Initializing RT netlink socket
apm: BIOS not found.
Starting kswapd
Journalled Block Device driver loaded
Detected PS/2 Mouse Port.
pty: 256 Unix98 ptys configured
Serial driver version 5.05c (2001-07-08) with no serial options enabled
ttyS00 at 0x03f8 (irq = 4) is a 16450
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
Last modified Nov 1, 2000 by Paul Gortmaker
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
eth0: NE2000 found at 0x300, using IRQ 9.
RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
hda: QEMU HARDDISK, ATA DISK drive
ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
hda: attached ide-disk driver.
hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
Partition check:
 hda:
Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
NET4: Linux TCP/IP 1.0 for NET4.0
IP Protocols: ICMP, UDP, TCP, IGMP
IP: routing cache hash table of 512 buckets, 4Kbytes
TCP: Hash tables configured (established 2048 bind 4096)
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
VFS: Mounted root (ext2 filesystem).
Freeing unused kernel memory: 64k freed
 
Linux 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
 
QEMU Linux test distribution (based on Redhat 9)
 
Type 'exit' to halt the system
 
sh-2.05b# 
@end example

@item
Then you can play with the kernel inside the virtual serial console. You
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
about the keys you can type inside the virtual serial console. In
particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
the Magic SysRq key.

@item 
If the network is enabled, launch the script @file{/etc/linuxrc} in the
emulator (don't forget the leading dot):
@example
. /etc/linuxrc
@end example

Then enable X11 connections on your PC from the emulated Linux: 
@example
xhost +172.20.0.2
@end example

You can now launch @file{xterm} or @file{xlogo} and verify that you have
a real Virtual Linux system !

@end enumerate

NOTES:
@enumerate
@item 
A 2.5.74 kernel is also included in the archive. Just
replace the bzImage in qemu.sh to try it.

@item 
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
qemu. qemu will automatically exit when the Linux shutdown is done.

@item 
You can boot slightly faster by disabling the probe of non present IDE
interfaces. To do so, add the following options on the kernel command
line:
@example
ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
@end example

@item 
The example disk image is a modified version of the one made by Kevin
Lawton for the plex86 Project (@url{www.plex86.org}).

@end enumerate

bellard's avatar
bellard committed
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
@section USB emulation

QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
to it. You can virtually plug to the hub virtual USB devices or real
host USB devices (experimental, works only on Linux hosts).

@subsection Using virtual USB devices

A virtual USB mouse device is available for testing in QEMU.

You can try it with the following monitor commands:

@example
# add the mouse device
(qemu) usb_add mouse 

# show the virtual USB devices plugged on the QEMU Virtual USB hub
(qemu) info usb
  Device 0.3, speed 12 Mb/s

# after some time you can try to remove the mouse
(qemu) usb_del 0.3
@end example

The option @option{-usbdevice} is similar to the monitor command
@code{usb_add}.

@subsection Using host USB devices on a Linux host

WARNING: this is an experimental feature. QEMU will slow down when
using it. USB devices requiring real time streaming (i.e. USB Video
Cameras) are not supported yet.

@enumerate
@item If you use an early Linux 2.4 kernel, verify that no Linux driver 
is actually using the USB device. A simple way to do that is simply to
disable the corresponding kernel module by renaming it from @file{mydriver.o}
to @file{mydriver.o.disabled}.

@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
@example
ls /proc/bus/usb
001  devices  drivers
@end example

@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:
@example
chown -R myuid /proc/bus/usb
@end example

@item Launch QEMU and do in the monitor:
@example 
info usbhost
  Device 1.2, speed 480 Mb/s
    Class 00: USB device 1234:5678, USB DISK
@end example
You should see the list of the devices you can use (Never try to use
hubs, it won't work).

@item Add the device in QEMU by using:
@example 
usb_add host:1234:5678
@end example

Normally the guest OS should report that a new USB device is
plugged. You can use the option @option{-usbdevice} to do the same.

@item Now you can try to use the host USB device in QEMU.

@end enumerate

When relaunching QEMU, you may have to unplug and plug again the USB
device to make it work again (this is a bug).

bellard's avatar
updated    
bellard committed
1094
@node gdb_usage
bellard's avatar
bellard committed
1095
1096
1097
@section GDB usage

QEMU has a primitive support to work with gdb, so that you can do
bellard's avatar
updated    
bellard committed
1098
'Ctrl-C' while the virtual machine is running and inspect its state.
bellard's avatar
bellard committed
1099

bellard's avatar
update    
bellard committed
1100
In order to use gdb, launch qemu with the '-s' option. It will wait for a
bellard's avatar
bellard committed
1101
1102
gdb connection:
@example
bellard's avatar
update    
bellard committed
1103
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
bellard's avatar
bellard committed
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
Connected to host network interface: tun0
Waiting gdb connection on port 1234
@end example

Then launch gdb on the 'vmlinux' executable:
@example
> gdb vmlinux
@end example

In gdb, connect to QEMU:
@example
bellard's avatar
update    
bellard committed
1115
(gdb) target remote localhost:1234
bellard's avatar
bellard committed
1116
1117
1118
1119
1120
1121
1122
@end example

Then you can use gdb normally. For example, type 'c' to launch the kernel:
@example
(gdb) c
@end example

bellard's avatar
updated    
bellard committed
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
Here are some useful tips in order to use gdb on system code:

@enumerate
@item
Use @code{info reg} to display all the CPU registers.
@item
Use @code{x/10i $eip} to display the code at the PC position.
@item
Use @code{set architecture i8086} to dump 16 bit code. Then use
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
@end enumerate

bellard's avatar
update    
bellard committed
1135
1136
1137
1138
@section Target OS specific information

@subsection Linux

bellard's avatar
bellard committed
1139
1140
1141
To have access to SVGA graphic modes under X11, use the @code{vesa} or
the @code{cirrus} X11 driver. For optimal performances, use 16 bit
color depth in the guest and the host OS.
bellard's avatar
update    
bellard committed
1142

bellard's avatar
update    
bellard committed
1143
1144
1145
1146
1147
When using a 2.6 guest Linux kernel, you should add the option
@code{clock=pit} on the kernel command line because the 2.6 Linux
kernels make very strict real time clock checks by default that QEMU
cannot simulate exactly.

bellard's avatar
update    
bellard committed
1148
1149
1150
1151
1152
1153
When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
not activated because QEMU is slower with this patch. The QEMU
Accelerator Module is also much slower in this case. Earlier Fedora
Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
patch by default. Newer kernels don't have it.

bellard's avatar
update    
bellard committed
1154
1155
1156
1157
1158
@subsection Windows

If you have a slow host, using Windows 95 is better as it gives the
best speed. Windows 2000 is also a good choice.

bellard's avatar
update    
bellard committed
1159
1160
1161
@subsubsection SVGA graphic modes support

QEMU emulates a Cirrus Logic GD5446 Video
bellard's avatar
bellard committed
1162
1163
1164
card. All Windows versions starting from Windows 95 should recognize
and use this graphic card. For optimal performances, use 16 bit color
depth in the guest and the host OS.
bellard's avatar
update    
bellard committed
1165

bellard's avatar
update    
bellard committed
1166
1167
1168
@subsubsection CPU usage reduction

Windows 9x does not correctly use the CPU HLT
bellard's avatar
bellard committed
1169
1170
1171
1172
instruction. The result is that it takes host CPU cycles even when
idle. You can install the utility from
@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
problem. Note that no such tool is needed for NT, 2000 or XP.
bellard's avatar
update    
bellard committed
1173

bellard's avatar
update    
bellard committed
1174
@subsubsection Windows 2000 disk full problem
bellard's avatar
update    
bellard committed
1175

bellard's avatar
update    
bellard committed
1176
1177
1178
1179
1180
Windows 2000 has a bug which gives a disk full problem during its
installation. When installing it, use the @option{-win2k-hack} QEMU
option to enable a specific workaround. After Windows 2000 is
installed, you no longer need this option (this option slows down the
IDE transfers).
bellard's avatar
update    
bellard committed
1181

bellard's avatar
update    
bellard committed
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
@subsubsection Windows 2000 shutdown

Windows 2000 cannot automatically shutdown in QEMU although Windows 98
can. It comes from the fact that Windows 2000 does not automatically
use the APM driver provided by the BIOS.

In order to correct that, do the following (thanks to Struan
Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
Add/Troubleshoot a device => Add a new device & Next => No, select the
hardware from a list & Next => NT Apm/Legacy Support & Next => Next
(again) a few times. Now the driver is installed and Windows 2000 now
correctly instructs QEMU to shutdown at the appropriate moment. 

@subsubsection Share a directory between Unix and Windows

See @ref{sec_invocation} about the help of the option @option{-smb}.

bellard's avatar
update    
bellard committed
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
@subsubsection Windows XP security problems

Some releases of Windows XP install correctly but give a security
error when booting:
@example
A problem is preventing Windows from accurately checking the
license for this computer. Error code: 0x800703e6.
@end example
The only known workaround is to boot in Safe mode
without networking support. 

Future QEMU releases are likely to correct this bug.

bellard's avatar
update    
bellard committed
1212
1213
1214
1215
1216
1217
1218
1219
1220
@subsection MS-DOS and FreeDOS

@subsubsection CPU usage reduction

DOS does not correctly use the CPU HLT instruction. The result is that
it takes host CPU cycles even when idle. You can install the utility
from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
problem.

bellard's avatar
bellard committed
1221
1222
1223
1224
1225
1226
1227
@chapter QEMU System emulator for non PC targets

QEMU is a generic emulator and it emulates many non PC
machines. Most of the options are similar to the PC emulator. The
differences are mentionned in the following sections.

@section QEMU PowerPC System emulator
bellard's avatar
update    
bellard committed
1228

bellard's avatar
bellard committed
1229
1230
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
or PowerMac PowerPC system.
bellard's avatar
update    
bellard committed
1231

bellard's avatar
typos    
bellard committed
1232
QEMU emulates the following PowerMac peripherals:
bellard's avatar
update    
bellard committed
1233

bellard's avatar
bellard committed
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
@itemize @minus
@item 
UniNorth PCI Bridge 
@item
PCI VGA compatible card with VESA Bochs Extensions
@item 
2 PMAC IDE interfaces with hard disk and CD-ROM support
@item 
NE2000 PCI adapters
@item
Non Volatile RAM
@item
VIA-CUDA with ADB keyboard and mouse.
bellard's avatar
update    
bellard committed
1247
1248
@end itemize

bellard's avatar
typos    
bellard committed
1249
QEMU emulates the following PREP peripherals:
bellard's avatar
update    
bellard committed
1250
1251
1252

@itemize @minus
@item 
bellard's avatar
bellard committed
1253
1254
1255
1256
PCI Bridge
@item
PCI VGA compatible card with VESA Bochs Extensions
@item 
bellard's avatar
update    
bellard committed
1257
1258
1259
1260
2 IDE interfaces with hard disk and CD-ROM support
@item
Floppy disk
@item 
bellard's avatar
bellard committed
1261
NE2000 network adapters
bellard's avatar
update    
bellard committed
1262
1263
1264
1265
@item
Serial port
@item
PREP Non Volatile RAM
bellard's avatar
bellard committed
1266
1267
@item
PC compatible keyboard and mouse.
bellard's avatar
update    
bellard committed
1268
1269
@end itemize

bellard's avatar
bellard committed
1270
QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
bellard's avatar
bellard committed
1271
@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
bellard's avatar
update    
bellard committed
1272

bellard's avatar
bellard committed
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
@c man begin OPTIONS

The following options are specific to the PowerPC emulation:

@table @option

@item -g WxH[xDEPTH]  

Set the initial VGA graphic mode. The default is 800x600x15.

@end table

@c man end 


bellard's avatar
update    
bellard committed
1288
More information is available at
bellard's avatar
bellard committed
1289
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
bellard's avatar
update    
bellard committed
1290

bellard's avatar
bellard committed
1291
@section Sparc32 System emulator invocation
bellard's avatar
bellard committed
1292
1293

Use the executable @file{qemu-system-sparc} to simulate a JavaStation
bellard's avatar
bellard committed
1294
(sun4m architecture). The emulation is somewhat complete.
bellard's avatar
bellard committed
1295

bellard's avatar
typos    
bellard committed
1296
QEMU emulates the following sun4m peripherals:
bellard's avatar
bellard committed
1297
1298

@itemize @minus
bellard's avatar
bellard committed
1299
@item
bellard's avatar
bellard committed
1300
1301
1302
1303
1304
1305
1306
1307
IOMMU
@item
TCX Frame buffer
@item 
Lance (Am7990) Ethernet
@item
Non Volatile RAM M48T08
@item
bellard's avatar
bellard committed
1308
1309
1310
1311
1312
1313
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
and power/reset logic
@item
ESP SCSI controller with hard disk and CD-ROM support
@item
Floppy drive
bellard's avatar
bellard committed
1314
1315
@end itemize

bellard's avatar
bellard committed
1316
1317
The number of peripherals is fixed in the architecture.

bellard's avatar
bellard committed
1318
QEMU uses the Proll, a PROM replacement available at
bellard's avatar
bellard committed
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
@url{http://people.redhat.com/zaitcev/linux/}. The required
QEMU-specific patches are included with the sources.

A sample Linux 2.6 series kernel and ram disk image are available on
the QEMU web site. Please note that currently neither Linux 2.4
series, NetBSD, nor OpenBSD kernels work.

@c man begin OPTIONS

The following options are specific to the Sparc emulation:

@table @option

@item -g WxH

Set the initial TCX graphic mode. The default is 1024x768.

@end table

@c man end 

bellard's avatar
bellard committed
1340
@section Sparc64 System emulator invocation
bellard's avatar
bellard committed
1341

bellard's avatar
bellard committed
1342
1343
Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
The emulator is not usable for anything yet.
bellard's avatar
bellard committed
1344

bellard's avatar
bellard committed
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
QEMU emulates the following sun4u peripherals:

@itemize @minus
@item
UltraSparc IIi APB PCI Bridge 
@item
PCI VGA compatible card with VESA Bochs Extensions
@item
Non Volatile RAM M48T59
@item
PC-compatible serial ports
@end itemize

bellard's avatar
bellard committed
1358
@section MIPS System emulator invocation
bellard's avatar
update    
bellard committed
1359
1360

Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
bellard's avatar
bellard committed
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
The emulator is able to boot a Linux kernel and to run a Linux Debian
installation from NFS. The following devices are emulated:

@itemize @minus
@item 
MIPS R4K CPU
@item
PC style serial port
@item
NE2000 network card
@end itemize

More information is available in the QEMU mailing-list archive.

@section ARM System emulator invocation

Use the executable @file{qemu-system-arm} to simulate a ARM
machine. The ARM Integrator/CP board is emulated with the following
devices:

@itemize @minus
@item
ARM1026E CPU
@item
Two PL011 UARTs
@item 
SMC 91c111 Ethernet adapter
@end itemize

A Linux 2.6 test image is available on the QEMU web site. More
information is available in the QEMU mailing-list archive.
bellard's avatar
update    
bellard committed
1392

bellard's avatar
bellard committed
1393
@chapter QEMU Linux User space emulator 
bellard's avatar
bellard committed
1394

bellard's avatar
bellard committed
1395
@section Quick Start
bellard's avatar
update    
bellard committed
1396

bellard's avatar
bellard committed
1397
1398
In order to launch a Linux process, QEMU needs the process executable
itself and all the target (x86) dynamic libraries used by it. 
bellard's avatar
bellard committed
1399

bellard's avatar
bellard committed
1400
@itemize
bellard's avatar
bellard committed
1401

bellard's avatar
bellard committed
1402
1403
@item On x86, you can just try to launch any process by using the native
libraries:
bellard's avatar
bellard committed
1404

bellard's avatar
bellard committed
1405
1406
1407
@example 
qemu-i386 -L / /bin/ls
@end example
bellard's avatar
bellard committed
1408

bellard's avatar
bellard committed
1409
1410
@code{-L /} tells that the x86 dynamic linker must be searched with a
@file{/} prefix.
bellard's avatar
bellard committed
1411

bellard's avatar
bellard committed
1412
@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):
bellard's avatar
bellard committed
1413

bellard's avatar
bellard committed
1414
1415
1416
@example 
qemu-i386 -L / qemu-i386 -L / /bin/ls
@end example
bellard's avatar
bellard committed
1417

bellard's avatar
bellard committed
1418
1419
1420
@item On non x86 CPUs, you need first to download at least an x86 glibc
(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
@code{LD_LIBRARY_PATH} is not set:
bellard's avatar
update    
bellard committed
1421

bellard's avatar
bellard committed
1422
1423
1424
@example
unset LD_LIBRARY_PATH 
@end example
bellard's avatar
update    
bellard committed
1425

bellard's avatar
bellard committed
1426
Then you can launch the precompiled @file{ls} x86 executable:
bellard's avatar
update    
bellard committed
1427

bellard's avatar
bellard committed
1428
1429
1430
1431
1432
1433
1434
@example
qemu-i386 tests/i386/ls
@end example
You can look at @file{qemu-binfmt-conf.sh} so that
QEMU is automatically launched by the Linux kernel when you try to
launch x86 executables. It requires the @code{binfmt_misc} module in the
Linux kernel.
bellard's avatar
update    
bellard committed
1435

bellard's avatar
bellard committed
1436
1437
1438
1439
@item The x86 version of QEMU is also included. You can try weird things such as:
@example
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
@end example
bellard's avatar
update    
bellard committed
1440

bellard's avatar
bellard committed
1441
@end itemize
bellard's avatar
update    
bellard committed
1442

bellard's avatar
bellard committed
1443
@section Wine launch
bellard's avatar
update    
bellard committed
1444

bellard's avatar
bellard committed
1445
@itemize
bellard's avatar
bellard committed
1446

bellard's avatar
bellard committed
1447
1448
1449
@item Ensure that you have a working QEMU with the x86 glibc
distribution (see previous section). In order to verify it, you must be
able to do:
bellard's avatar
bellard committed
1450

bellard's avatar
bellard committed
1451
1452
1453
@example
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
@end example
bellard's avatar
bellard committed
1454

bellard's avatar
bellard committed
1455
1456
@item Download the binary x86 Wine install
(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). 
bellard's avatar
bellard committed
1457

bellard's avatar
bellard committed
1458
1459
1460
@item Configure Wine on your account. Look at the provided script
@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
bellard's avatar
bellard committed
1461

bellard's avatar
bellard committed
1462
@item Then you can try the example @file{putty.exe}:
bellard's avatar
bellard committed
1463

bellard's avatar
bellard committed
1464
1465
1466
@example
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
@end example
bellard's avatar
bellard committed
1467

bellard's avatar
bellard committed
1468
@end itemize
bellard's avatar
update    
bellard committed
1469

bellard's avatar
bellard committed
1470
@section Command line options
bellard's avatar
update    
bellard committed
1471

bellard's avatar
bellard committed
1472
1473
1474
@example
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
@end example
bellard's avatar
update    
bellard committed
1475

bellard's avatar
bellard committed
1476
1477
1478
1479
1480
1481
1482
@table @option
@item -h
Print the help
@item -L path   
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
@item -s size
Set the x86 stack size in bytes (default=524288)
bellard's avatar
bellard committed
1483
1484
@end table

bellard's avatar
bellard committed
1485
Debug options:
bellard's avatar
bellard committed
1486

bellard's avatar
bellard committed
1487
1488
1489
1490
1491
1492
@table @option
@item -d
Activate log (logfile=/tmp/qemu.log)
@item -p pagesize
Act as if the host page size was 'pagesize' bytes
@end table
bellard's avatar
bellard committed
1493

bellard's avatar
bellard committed
1494
1495
1496
@node compilation
@chapter Compilation from the sources

bellard's avatar
update    
bellard committed
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
@section Linux/Unix

@subsection Compilation

First you must decompress the sources:
@example
cd /tmp
tar zxvf qemu-x.y.z.tar.gz
cd qemu-x.y.z
@end example

Then you configure QEMU and build it (usually no options are needed):
@example
./configure
make
@end example

Then type as root user:
@example
make install
@end example
to install QEMU in @file{/usr/local}.

@subsection Tested tool versions

In order to compile QEMU succesfully, it is very important that you
have the right tools. The most important one is gcc. I cannot guaranty
that QEMU works if you do not use a tested gcc version. Look at
'configure' and 'Makefile' if you want to make a different gcc
version work.

@example
host      gcc      binutils      glibc    linux       distribution
----------------------------------------------------------------------
x86       3.2      2.13.2        2.1.3    2.4.18
          2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
          3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9

PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
          3.2

Alpha     3.3 [1]  2.14.90.0.4   2.2.5    2.2.20 [2]  Debian 3.0

Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0

ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0

[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
    for gcc version >= 3.3.
[2] Linux >= 2.4.20 is necessary for precise exception support
    (untested).
[3] 2.4.9-ac10-rmk2-np1-cerf2

[4] gcc 2.95.x generates invalid code when using too many register
variables. You must use gcc 3.x on PowerPC.
@end example
bellard's avatar
bellard committed
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619

@section Windows

@itemize
@item Install the current versions of MSYS and MinGW from
@url{http://www.mingw.org/}. You can find detailed installation
instructions in the download section and the FAQ.

@item Download 
the MinGW development library of SDL 1.2.x
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
directory. Edit the @file{sdl-config} script so that it gives the
correct SDL directory when invoked.

@item Extract the current version of QEMU.
 
@item Start the MSYS shell (file @file{msys.bat}).

@item Change to the QEMU directory. Launch @file{./configure} and 
@file{make}.  If you have problems using SDL, verify that
@file{sdl-config} can be launched from the MSYS command line.

@item You can install QEMU in @file{Program Files/Qemu} by typing 
@file{make install}. Don't forget to copy @file{SDL.dll} in
@file{Program Files/Qemu}.

@end itemize

@section Cross compilation for Windows with Linux

@itemize
@item
Install the MinGW cross compilation tools available at
@url{http://www.mingw.org/}.

@item 
Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
the QEMU configuration script.

@item 
Configure QEMU for Windows cross compilation:
@example
./configure --enable-mingw32
@end example
If necessary, you can change the cross-prefix according to the prefix
choosen for the MinGW tools with --cross-prefix. You can also use
--prefix to set the Win32 install path.

@item You can install QEMU in the installation directory by typing 
@file{make install}. Don't forget to copy @file{SDL.dll} in the
installation directory. 

@end itemize

Note: Currently, Wine does not seem able to launch
QEMU for Win32.

@section Mac OS X

The Mac OS X patches are not fully merged in QEMU, so you should look
at the QEMU mailing list archive to have all the necessary
information.