Statistics
| Branch: | Revision:

root / qemu-doc.texi @ b756921a

History | View | Annotate | Download (34.5 kB)

1
\input texinfo @c -*- texinfo -*-
2

    
3
@iftex
4
@settitle QEMU CPU Emulator User Documentation
5
@titlepage
6
@sp 7
7
@center @titlefont{QEMU CPU Emulator User Documentation}
8
@sp 3
9
@end titlepage
10
@end iftex
11

    
12
@chapter Introduction
13

    
14
@section Features
15

    
16
QEMU is a FAST! processor emulator using dynamic translation to
17
achieve good emulation speed.
18

    
19
QEMU has two operating modes:
20

    
21
@itemize @minus
22

    
23
@item 
24
Full system emulation. In this mode, QEMU emulates a full system (for
25
example a PC), including a processor and various peripherials. It can
26
be used to launch different Operating Systems without rebooting the
27
PC or to debug system code.
28

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

    
35
@end itemize
36

    
37
QEMU can run without an host kernel driver and yet gives acceptable
38
performance. 
39

    
40
For system emulation, the following hardware targets are supported:
41
@itemize
42
@item PC (x86 processor)
43
@item PREP (PowerPC processor)
44
@item PowerMac (PowerPC processor, in progress)
45
@item Sun4m (Sparc processor, in progress)
46
@end itemize
47

    
48
For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
49

    
50
@chapter Installation
51

    
52
If you want to compile QEMU yourself, see @ref{compilation}.
53

    
54
@section Linux
55

    
56
If a precompiled package is available for your distribution - you just
57
have to install it. Otherwise, see @ref{compilation}.
58

    
59
@section Windows
60

    
61
Download the experimental binary installer at
62
@url{http://www.freeoszoo.org/download.php}.
63

    
64
@section Mac OS X
65

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

    
69
@chapter QEMU PC System emulator invocation
70

    
71
@section Introduction
72

    
73
@c man begin DESCRIPTION
74

    
75
The QEMU System emulator simulates the
76
following PC peripherials:
77

    
78
@itemize @minus
79
@item 
80
i440FX host PCI bridge and PIIX3 PCI to ISA bridge
81
@item
82
Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
83
extensions (hardware level, including all non standard modes).
84
@item
85
PS/2 mouse and keyboard
86
@item 
87
2 PCI IDE interfaces with hard disk and CD-ROM support
88
@item
89
Floppy disk
90
@item 
91
NE2000 PCI network adapters
92
@item
93
Serial ports
94
@item
95
Soundblaster 16 card
96
@end itemize
97

    
98
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
99
VGA BIOS.
100

    
101
@c man end
102

    
103
@section Quick Start
104

    
105
Download and uncompress the linux image (@file{linux.img}) and type:
106

    
107
@example
108
qemu linux.img
109
@end example
110

    
111
Linux should boot and give you a prompt.
112

    
113
@section Invocation
114

    
115
@example
116
@c man begin SYNOPSIS
117
usage: qemu [options] [disk_image]
118
@c man end
119
@end example
120

    
121
@c man begin OPTIONS
122
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
123

    
124
General options:
125
@table @option
126
@item -fda file
127
@item -fdb file
128
Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
129
use the host floppy by using @file{/dev/fd0} as filename.
130

    
131
@item -hda file
132
@item -hdb file
133
@item -hdc file
134
@item -hdd file
135
Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
136

    
137
@item -cdrom file
138
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
139
@option{-cdrom} at the same time). You can use the host CD-ROM by
140
using @file{/dev/cdrom} as filename.
141

    
142
@item -boot [a|c|d]
143
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
144
the default.
145

    
146
@item -snapshot
147
Write to temporary files instead of disk image files. In this case,
148
the raw disk image you use is not written back. You can however force
149
the write back by pressing @key{C-a s} (@xref{disk_images}). 
150

    
151
@item -m megs
152
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
153

    
154
@item -nographic
155

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

    
162
@item -k language
163

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

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

    
176
The default is @code{en-us}.
177

    
178
@item -enable-audio
179

    
180
The SB16 emulation is disabled by default as it may give problems with
181
Windows. You can enable it manually with this option.
182

    
183
@item -localtime
184
Set the real time clock to local time (the default is to UTC
185
time). This option is needed to have correct date in MS-DOS or
186
Windows.
187

    
188
@item -full-screen
189
Start in full screen.
190

    
191
@item -pidfile file
192
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
193
from a script.
194

    
195
@end table
196

    
197
Network options:
198

    
199
@table @option
200

    
201
@item -n script      
202
Set TUN/TAP network init script [default=/etc/qemu-ifup]. This script
203
is launched to configure the host network interface (usually tun0)
204
corresponding to the virtual NE2000 card.
205

    
206
@item -macaddr addr   
207

    
208
Set the mac address of the first interface (the format is
209
aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each
210
new network interface.
211

    
212
@item -tun-fd fd
213
Assumes @var{fd} talks to a tap/tun host network interface and use
214
it. Read @url{http://bellard.org/qemu/tetrinet.html} to have an
215
example of its use.
216

    
217
@item -user-net 
218
Use the user mode network stack. This is the default if no tun/tap
219
network init script is found.
220

    
221
@item -tftp prefix
222
When using the user mode network stack, activate a built-in TFTP
223
server. All filenames beginning with @var{prefix} can be downloaded
224
from the host to the guest using a TFTP client. The TFTP client on the
225
guest must be configured in binary mode (use the command @code{bin} of
226
the Unix TFTP client). The host IP address on the guest is as usual
227
10.0.2.2.
228

    
229
@item -smb dir
230
When using the user mode network stack, activate a built-in SMB
231
server so that Windows OSes can access to the host files in @file{dir}
232
transparently.
233

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

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

    
243
Note that a SAMBA server must be installed on the host OS in
244
@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
245
2.2.7a from the Red Hat 9.
246

    
247
@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
248

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

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

    
258
@example
259
# on the host
260
qemu -redir tcp:6001::6000 [...]
261
# this host xterm should open in the guest X11 server
262
xterm -display :1
263
@end example
264

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

    
268
@example
269
# on the host
270
qemu -redir tcp:5555::23 [...]
271
telnet localhost 5555
272
@end example
273

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

    
277
@item -dummy-net 
278
Use the dummy network stack: no packet will be received by the network
279
cards.
280

    
281
@end table
282

    
283
Linux boot specific. When using this options, you can use a given
284
Linux kernel without installing it in the disk image. It can be useful
285
for easier testing of various kernels.
286

    
287
@table @option
288

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

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

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

    
298
@end table
299

    
300
Debug/Expert options:
301
@table @option
302

    
303
@item -serial dev
304
Redirect the virtual serial port to host device @var{dev}. Available
305
devices are:
306
@table @code
307
@item vc
308
Virtual console
309
@item pty
310
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
311
@item null
312
void device
313
@item stdio
314
[Unix only] standard input/output
315
@end table
316
The default device is @code{vc} in graphical mode and @code{stdio} in
317
non graphical mode.
318

    
319
This option can be used several times to simulate up to 4 serials
320
ports.
321

    
322
@item -monitor dev
323
Redirect the monitor to host device @var{dev} (same devices as the
324
serial port).
325
The default device is @code{vc} in graphical mode and @code{stdio} in
326
non graphical mode.
327

    
328
@item -s
329
Wait gdb connection to port 1234 (@xref{gdb_usage}). 
330
@item -p port
331
Change gdb connection port.
332
@item -S
333
Do not start CPU at startup (you must type 'c' in the monitor).
334
@item -d             
335
Output log in /tmp/qemu.log
336
@item -hdachs c,h,s,[,t]
337
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
338
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
339
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
340
all thoses parameters. This option is useful for old MS-DOS disk
341
images.
342

    
343
@item -isa
344
Simulate an ISA-only system (default is PCI system).
345
@item -std-vga
346
Simulate a standard VGA card with Bochs VBE extensions (default is
347
Cirrus Logic GD5446 PCI VGA)
348
@item -loadvm file
349
Start right away with a saved state (@code{loadvm} in monitor)
350
@end table
351

    
352
@c man end
353

    
354
@section Keys
355

    
356
@c man begin OPTIONS
357

    
358
During the graphical emulation, you can use the following keys:
359
@table @key
360
@item Ctrl-Alt-f
361
Toggle full screen
362

    
363
@item Ctrl-Alt-n
364
Switch to virtual console 'n'. Standard console mappings are:
365
@table @emph
366
@item 1
367
Target system display
368
@item 2
369
Monitor
370
@item 3
371
Serial port
372
@end table
373

    
374
@item Ctrl-Alt
375
Toggle mouse and keyboard grab.
376
@end table
377

    
378
In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
379
@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
380

    
381
During emulation, if you are using the @option{-nographic} option, use
382
@key{Ctrl-a h} to get terminal commands:
383

    
384
@table @key
385
@item Ctrl-a h
386
Print this help
387
@item Ctrl-a x    
388
Exit emulatior
389
@item Ctrl-a s    
390
Save disk data back to file (if -snapshot)
391
@item Ctrl-a b
392
Send break (magic sysrq in Linux)
393
@item Ctrl-a c
394
Switch between console and monitor
395
@item Ctrl-a Ctrl-a
396
Send Ctrl-a
397
@end table
398
@c man end
399

    
400
@ignore
401

    
402
@setfilename qemu 
403
@settitle QEMU System Emulator
404

    
405
@c man begin SEEALSO
406
The HTML documentation of QEMU for more precise information and Linux
407
user mode emulator invocation.
408
@c man end
409

    
410
@c man begin AUTHOR
411
Fabrice Bellard
412
@c man end
413

    
414
@end ignore
415

    
416
@end ignore
417

    
418
@section QEMU Monitor
419

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

    
423
@itemize @minus
424

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

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

    
433
@item Inspect the VM state without an external debugger.
434

    
435
@end itemize
436

    
437
@subsection Commands
438

    
439
The following commands are available:
440

    
441
@table @option
442

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

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

    
449
@item info subcommand 
450
show various information about the system state
451

    
452
@table @option
453
@item info network
454
show the network state
455
@item info block
456
show the block devices
457
@item info registers
458
show the cpu registers
459
@item info history
460
show the command line history
461
@end table
462

    
463
@item q or quit
464
Quit the emulator.
465

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

    
469
@item change device filename
470
Change a removable media.
471

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

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

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

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

    
484
@item stop
485
Stop emulation.
486

    
487
@item c or cont
488
Resume emulation.
489

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

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

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

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

    
502
@table @var
503
@item count 
504
is the number of items to be dumped.
505

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

    
510
@item size
511
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
512
@code{h} or @code{w} can be specified with the @code{i} format to
513
respectively select 16 or 32 bit code instruction size.
514

    
515
@end table
516

    
517
Examples: 
518
@itemize
519
@item
520
Dump 10 instructions at the current instruction pointer:
521
@example 
522
(qemu) x/10i $eip
523
0x90107063:  ret
524
0x90107064:  sti
525
0x90107065:  lea    0x0(%esi,1),%esi
526
0x90107069:  lea    0x0(%edi,1),%edi
527
0x90107070:  ret
528
0x90107071:  jmp    0x90107080
529
0x90107073:  nop
530
0x90107074:  nop
531
0x90107075:  nop
532
0x90107076:  nop
533
@end example
534

    
535
@item
536
Dump 80 16 bit values at the start of the video memory.
537
@example 
538
(qemu) xp/80hx 0xb8000
539
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
540
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
541
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
542
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
543
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
544
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
545
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
546
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
547
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
548
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
549
@end example
550
@end itemize
551

    
552
@item p or print/fmt expr
553

    
554
Print expression value. Only the @var{format} part of @var{fmt} is
555
used.
556

    
557
@item sendkey keys
558

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

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

    
568
@item system_reset
569

    
570
Reset the system.
571

    
572
@end table
573

    
574
@subsection Integer expressions
575

    
576
The monitor understands integers expressions for every integer
577
argument. You can use register names to get the value of specifics
578
CPU registers by prefixing them with @emph{$}.
579

    
580
@node disk_images
581
@section Disk Images
582

    
583
Since version 0.6.1, QEMU supports many disk image formats, including
584
growable disk images (their size increase as non empty sectors are
585
written), compressed and encrypted disk images.
586

    
587
@subsection Quick start for disk image creation
588

    
589
You can create a disk image with the command:
590
@example
591
qemu-img create myimage.img mysize
592
@end example
593
where @var{myimage.img} is the disk image filename and @var{mysize} is its
594
size in kilobytes. You can add an @code{M} suffix to give the size in
595
megabytes and a @code{G} suffix for gigabytes.
596

    
597
@xref{qemu_img_invocation} for more information.
598

    
599
@subsection Snapshot mode
600

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

    
607
@node qemu_img_invocation
608
@subsection @code{qemu-img} Invocation
609

    
610
@include qemu-img.texi
611

    
612
@section Network emulation
613

    
614
QEMU simulates up to 6 networks cards (NE2000 boards). Each card can
615
be connected to a specific host network interface.
616

    
617
@subsection Using tun/tap network interface
618

    
619
This is the standard way to emulate network. QEMU adds a virtual
620
network device on your host (called @code{tun0}), and you can then
621
configure it as if it was a real ethernet card.
622

    
623
As an example, you can download the @file{linux-test-xxx.tar.gz}
624
archive and copy the script @file{qemu-ifup} in @file{/etc} and
625
configure properly @code{sudo} so that the command @code{ifconfig}
626
contained in @file{qemu-ifup} can be executed as root. You must verify
627
that your host kernel supports the TUN/TAP network interfaces: the
628
device @file{/dev/net/tun} must be present.
629

    
630
See @ref{direct_linux_boot} to have an example of network use with a
631
Linux distribution.
632

    
633
@subsection Using the user mode network stack
634

    
635
By using the option @option{-user-net} or if you have no tun/tap init
636
script, QEMU uses a completely user mode network stack (you don't need
637
root priviledge to use the virtual network). The virtual network
638
configuration is the following:
639

    
640
@example
641

    
642
QEMU Virtual Machine    <------>  Firewall/DHCP server <-----> Internet
643
     (10.0.2.x)            |          (10.0.2.2)
644
                           |
645
                           ---->  DNS server (10.0.2.3)
646
                           |     
647
                           ---->  SMB server (10.0.2.4)
648
@end example
649

    
650
The QEMU VM behaves as if it was behind a firewall which blocks all
651
incoming connections. You can use a DHCP client to automatically
652
configure the network in the QEMU VM.
653

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

    
658
Note that @code{ping} is not supported reliably to the internet as it
659
would require root priviledges. It means you can only ping the local
660
router (10.0.2.2).
661

    
662
When using the built-in TFTP server, the router is also the TFTP
663
server.
664

    
665
When using the @option{-redir} option, TCP or UDP connections can be
666
redirected from the host to the guest. It allows for example to
667
redirect X11, telnet or SSH connections.
668

    
669
@node direct_linux_boot
670
@section Direct Linux Boot
671

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

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

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

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

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

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

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

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

    
781
Then enable X11 connections on your PC from the emulated Linux: 
782
@example
783
xhost +172.20.0.2
784
@end example
785

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

    
789
@end enumerate
790

    
791
NOTES:
792
@enumerate
793
@item 
794
A 2.5.74 kernel is also included in the archive. Just
795
replace the bzImage in qemu.sh to try it.
796

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

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

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

    
813
@end enumerate
814

    
815
@node gdb_usage
816
@section GDB usage
817

    
818
QEMU has a primitive support to work with gdb, so that you can do
819
'Ctrl-C' while the virtual machine is running and inspect its state.
820

    
821
In order to use gdb, launch qemu with the '-s' option. It will wait for a
822
gdb connection:
823
@example
824
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
825
Connected to host network interface: tun0
826
Waiting gdb connection on port 1234
827
@end example
828

    
829
Then launch gdb on the 'vmlinux' executable:
830
@example
831
> gdb vmlinux
832
@end example
833

    
834
In gdb, connect to QEMU:
835
@example
836
(gdb) target remote localhost:1234
837
@end example
838

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

    
844
Here are some useful tips in order to use gdb on system code:
845

    
846
@enumerate
847
@item
848
Use @code{info reg} to display all the CPU registers.
849
@item
850
Use @code{x/10i $eip} to display the code at the PC position.
851
@item
852
Use @code{set architecture i8086} to dump 16 bit code. Then use
853
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
854
@end enumerate
855

    
856
@section Target OS specific information
857

    
858
@subsection Linux
859

    
860
To have access to SVGA graphic modes under X11, use the @code{vesa} or
861
the @code{cirrus} X11 driver. For optimal performances, use 16 bit
862
color depth in the guest and the host OS.
863

    
864
When using a 2.6 guest Linux kernel, you should add the option
865
@code{clock=pit} on the kernel command line because the 2.6 Linux
866
kernels make very strict real time clock checks by default that QEMU
867
cannot simulate exactly.
868

    
869
When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
870
not activated because QEMU is slower with this patch. The QEMU
871
Accelerator Module is also much slower in this case. Earlier Fedora
872
Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
873
patch by default. Newer kernels don't have it.
874

    
875
@subsection Windows
876

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

    
880
@subsubsection SVGA graphic modes support
881

    
882
QEMU emulates a Cirrus Logic GD5446 Video
883
card. All Windows versions starting from Windows 95 should recognize
884
and use this graphic card. For optimal performances, use 16 bit color
885
depth in the guest and the host OS.
886

    
887
@subsubsection CPU usage reduction
888

    
889
Windows 9x does not correctly use the CPU HLT
890
instruction. The result is that it takes host CPU cycles even when
891
idle. You can install the utility from
892
@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
893
problem. Note that no such tool is needed for NT, 2000 or XP.
894

    
895
@subsubsection Windows 2000 disk full problems
896

    
897
Currently (release 0.6.0) QEMU has a bug which gives a @code{disk
898
full} error during installation of some releases of Windows 2000. The
899
workaround is to stop QEMU as soon as you notice that your disk image
900
size is growing too fast (monitor it with @code{ls -ls}). Then
901
relaunch QEMU to continue the installation. If you still experience
902
the problem, relaunch QEMU again.
903

    
904
Future QEMU releases are likely to correct this bug.
905

    
906
@subsubsection Windows XP security problems
907

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

    
917
Future QEMU releases are likely to correct this bug.
918

    
919
@subsection MS-DOS and FreeDOS
920

    
921
@subsubsection CPU usage reduction
922

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

    
928
@chapter QEMU PowerPC System emulator invocation
929

    
930
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
931
or PowerMac PowerPC system.
932

    
933
QEMU emulates the following PowerMac peripherials:
934

    
935
@itemize @minus
936
@item 
937
UniNorth PCI Bridge 
938
@item
939
PCI VGA compatible card with VESA Bochs Extensions
940
@item 
941
2 PMAC IDE interfaces with hard disk and CD-ROM support
942
@item 
943
NE2000 PCI adapters
944
@item
945
Non Volatile RAM
946
@item
947
VIA-CUDA with ADB keyboard and mouse.
948
@end itemize
949

    
950
QEMU emulates the following PREP peripherials:
951

    
952
@itemize @minus
953
@item 
954
PCI Bridge
955
@item
956
PCI VGA compatible card with VESA Bochs Extensions
957
@item 
958
2 IDE interfaces with hard disk and CD-ROM support
959
@item
960
Floppy disk
961
@item 
962
NE2000 network adapters
963
@item
964
Serial port
965
@item
966
PREP Non Volatile RAM
967
@item
968
PC compatible keyboard and mouse.
969
@end itemize
970

    
971
QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
972
@url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}.
973

    
974
You can read the qemu PC system emulation chapter to have more
975
informations about QEMU usage.
976

    
977
@c man begin OPTIONS
978

    
979
The following options are specific to the PowerPC emulation:
980

    
981
@table @option
982

    
983
@item -prep
984
Simulate a PREP system (default is PowerMAC)
985

    
986
@item -g WxH[xDEPTH]  
987

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

    
990
@end table
991

    
992
@c man end 
993

    
994

    
995
More information is available at
996
@url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
997

    
998
@chapter Sparc System emulator invocation
999

    
1000
Use the executable @file{qemu-system-sparc} to simulate a JavaStation
1001
(sun4m architecture). The emulation is far from complete.
1002

    
1003
QEMU emulates the following sun4m peripherials:
1004

    
1005
@itemize @minus
1006
@item 
1007
IOMMU
1008
@item
1009
TCX Frame buffer
1010
@item 
1011
Lance (Am7990) Ethernet
1012
@item
1013
Non Volatile RAM M48T08
1014
@item
1015
Slave I/O: timers, interrupt controllers, Zilog serial ports
1016
@end itemize
1017

    
1018
QEMU uses the Proll, a PROM replacement available at
1019
@url{http://people.redhat.com/zaitcev/linux/}.
1020

    
1021
A sample Linux kernel and ram disk image are available on the QEMU web
1022
site.
1023

    
1024
@chapter QEMU User space emulator invocation
1025

    
1026
@section Quick Start
1027

    
1028
In order to launch a Linux process, QEMU needs the process executable
1029
itself and all the target (x86) dynamic libraries used by it. 
1030

    
1031
@itemize
1032

    
1033
@item On x86, you can just try to launch any process by using the native
1034
libraries:
1035

    
1036
@example 
1037
qemu-i386 -L / /bin/ls
1038
@end example
1039

    
1040
@code{-L /} tells that the x86 dynamic linker must be searched with a
1041
@file{/} prefix.
1042

    
1043
@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):
1044

    
1045
@example 
1046
qemu-i386 -L / qemu-i386 -L / /bin/ls
1047
@end example
1048

    
1049
@item On non x86 CPUs, you need first to download at least an x86 glibc
1050
(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1051
@code{LD_LIBRARY_PATH} is not set:
1052

    
1053
@example
1054
unset LD_LIBRARY_PATH 
1055
@end example
1056

    
1057
Then you can launch the precompiled @file{ls} x86 executable:
1058

    
1059
@example
1060
qemu-i386 tests/i386/ls
1061
@end example
1062
You can look at @file{qemu-binfmt-conf.sh} so that
1063
QEMU is automatically launched by the Linux kernel when you try to
1064
launch x86 executables. It requires the @code{binfmt_misc} module in the
1065
Linux kernel.
1066

    
1067
@item The x86 version of QEMU is also included. You can try weird things such as:
1068
@example
1069
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1070
@end example
1071

    
1072
@end itemize
1073

    
1074
@section Wine launch
1075

    
1076
@itemize
1077

    
1078
@item Ensure that you have a working QEMU with the x86 glibc
1079
distribution (see previous section). In order to verify it, you must be
1080
able to do:
1081

    
1082
@example
1083
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1084
@end example
1085

    
1086
@item Download the binary x86 Wine install
1087
(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). 
1088

    
1089
@item Configure Wine on your account. Look at the provided script
1090
@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
1091
@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
1092

    
1093
@item Then you can try the example @file{putty.exe}:
1094

    
1095
@example
1096
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1097
@end example
1098

    
1099
@end itemize
1100

    
1101
@section Command line options
1102

    
1103
@example
1104
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1105
@end example
1106

    
1107
@table @option
1108
@item -h
1109
Print the help
1110
@item -L path   
1111
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1112
@item -s size
1113
Set the x86 stack size in bytes (default=524288)
1114
@end table
1115

    
1116
Debug options:
1117

    
1118
@table @option
1119
@item -d
1120
Activate log (logfile=/tmp/qemu.log)
1121
@item -p pagesize
1122
Act as if the host page size was 'pagesize' bytes
1123
@end table
1124

    
1125
@node compilation
1126
@chapter Compilation from the sources
1127

    
1128
@section Linux/Unix
1129

    
1130
@subsection Compilation
1131

    
1132
First you must decompress the sources:
1133
@example
1134
cd /tmp
1135
tar zxvf qemu-x.y.z.tar.gz
1136
cd qemu-x.y.z
1137
@end example
1138

    
1139
Then you configure QEMU and build it (usually no options are needed):
1140
@example
1141
./configure
1142
make
1143
@end example
1144

    
1145
Then type as root user:
1146
@example
1147
make install
1148
@end example
1149
to install QEMU in @file{/usr/local}.
1150

    
1151
@subsection Tested tool versions
1152

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

    
1159
@example
1160
host      gcc      binutils      glibc    linux       distribution
1161
----------------------------------------------------------------------
1162
x86       3.2      2.13.2        2.1.3    2.4.18
1163
          2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
1164
          3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
1165

    
1166
PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
1167
          3.2
1168

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

    
1171
Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
1172

    
1173
ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
1174

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

    
1181
[4] gcc 2.95.x generates invalid code when using too many register
1182
variables. You must use gcc 3.x on PowerPC.
1183
@end example
1184

    
1185
@section Windows
1186

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

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

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

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

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

    
1212
@end itemize
1213

    
1214
@section Cross compilation for Windows with Linux
1215

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

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

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

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

    
1240
@end itemize
1241

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

    
1245
@section Mac OS X
1246

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