Statistics
| Branch: | Revision:

root / qemu-doc.texi @ 1f673135

History | View | Annotate | Download (24.4 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
As QEMU requires no host kernel driver to run, it is very safe and
38
easy to use.
39

    
40
For system emulation, only the x86 PC emulator is currently
41
usable. The PowerPC system emulator is being developped.
42

    
43
For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
44

    
45
@chapter Installation
46

    
47
@section Linux
48

    
49
If you want to compile QEMU, please read the @file{README} which gives
50
the related information. Otherwise just download the binary
51
distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in
52
@file{/}:
53

    
54
@example
55
su
56
cd /
57
tar zxvf /tmp/qemu-XXX-i386.tar.gz
58
@end example
59

    
60
@section Windows
61
w
62
@itemize
63
@item Install the current versions of MSYS and MinGW from
64
@url{http://www.mingw.org/}. You can find detailed installation
65
instructions in the download section and the FAQ.
66

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

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

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

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

    
87
@end itemize
88

    
89
@section Cross compilation for Windows with Linux
90

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

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

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

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

    
115
@end itemize
116

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

    
120
@section Mac OS X
121

    
122
Mac OS X is currently not supported.
123

    
124
@chapter QEMU System emulator invocation
125

    
126
@section Introduction
127

    
128
@c man begin DESCRIPTION
129

    
130
The QEMU System emulator simulates a complete PC. 
131

    
132
In order to meet specific user needs, two versions of QEMU are
133
available:
134

    
135
@enumerate
136

    
137
@item 
138
@code{qemu-fast} uses the host Memory Management Unit (MMU) to simulate 
139
the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB
140
address space cannot be used and some memory mapped peripherials
141
cannot be emulated accurately yet. Therefore, a specific Linux kernel
142
must be used (@xref{linux_compile}).
143

    
144
@item 
145
@code{qemu} uses a software MMU. It is about @emph{two times 
146
slower} but gives a more accurate emulation. 
147

    
148
@end enumerate
149

    
150
QEMU emulates the following PC peripherials:
151

    
152
@itemize @minus
153
@item
154
VGA (hardware level, including all non standard modes)
155
@item
156
PS/2 mouse and keyboard
157
@item 
158
2 IDE interfaces with hard disk and CD-ROM support
159
@item
160
Floppy disk
161
@item 
162
up to 6 NE2000 network adapters
163
@item
164
Serial port
165
@item 
166
Soundblaster 16 card
167
@end itemize
168

    
169
@c man end
170

    
171
@section Quick Start
172

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

    
175
@example
176
qemu linux.img
177
@end example
178

    
179
Linux should boot and give you a prompt.
180

    
181
@section Invocation
182

    
183
@example
184
@c man begin SYNOPSIS
185
usage: qemu [options] [disk_image]
186
@c man end
187
@end example
188

    
189
@c man begin OPTIONS
190
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
191

    
192
General options:
193
@table @option
194
@item -fda file
195
@item -fdb file
196
Use @var{file} as floppy disk 0/1 image (@xref{disk_images}).
197

    
198
@item -hda file
199
@item -hdb file
200
@item -hdc file
201
@item -hdd file
202
Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
203

    
204
@item -cdrom file
205
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
206
@option{-cdrom} at the same time).
207

    
208
@item -boot [a|c|d]
209
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
210
the default.
211

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

    
217
@item -m megs
218
Set virtual RAM size to @var{megs} megabytes.
219

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

    
223
@item -nographic
224

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

    
231
@end table
232

    
233
Network options:
234

    
235
@table @option
236

    
237
@item -n script      
238
Set network init script [default=/etc/qemu-ifup]. This script is
239
launched to configure the host network interface (usually tun0)
240
corresponding to the virtual NE2000 card.
241

    
242
@item nics n
243
Simulate @var{n} network interfaces (default=1).
244

    
245
@item -macaddr addr   
246

    
247
Set the mac address of the first interface (the format is
248
aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each
249
new network interface.
250

    
251
@item -tun-fd fd1,...
252
Assumes @var{fd} talks to tap/tun and use it. Read
253
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
254
use.
255

    
256
@end table
257

    
258
Linux boot specific. When using this options, you can use a given
259
Linux kernel without installing it in the disk image. It can be useful
260
for easier testing of various kernels.
261

    
262
@table @option
263

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

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

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

    
273
@end table
274

    
275
Debug options:
276
@table @option
277
@item -s
278
Wait gdb connection to port 1234 (@xref{gdb_usage}). 
279
@item -p port
280
Change gdb connection port.
281
@item -d             
282
Output log in /tmp/qemu.log
283
@end table
284

    
285
During emulation, if you are using the serial console, use @key{C-a h}
286
to get terminal commands:
287

    
288
@table @key
289
@item C-a h
290
Print this help
291
@item C-a x    
292
Exit emulatior
293
@item C-a s    
294
Save disk data back to file (if -snapshot)
295
@item C-a b
296
Send break (magic sysrq in Linux)
297
@item C-a c
298
Switch between console and monitor
299
@item C-a C-a
300
Send C-a
301
@end table
302
@c man end
303

    
304
@ignore
305

    
306
@setfilename qemu 
307
@settitle QEMU System Emulator
308

    
309
@c man begin SEEALSO
310
The HTML documentation of QEMU for more precise information and Linux
311
user mode emulator invocation.
312
@c man end
313

    
314
@c man begin AUTHOR
315
Fabrice Bellard
316
@c man end
317

    
318
@end ignore
319

    
320
@end ignore
321

    
322

    
323
@section QEMU Monitor
324

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

    
328
@itemize @minus
329

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

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

    
338
@item Inspect the VM state without an external debugger.
339

    
340
@end itemize
341

    
342
@subsection Commands
343

    
344
The following commands are available:
345

    
346
@table @option
347

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

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

    
354
@item info subcommand 
355
show various information about the system state
356

    
357
@table @option
358
@item info network
359
show the network state
360
@item info block
361
show the block devices
362
@item info registers
363
show the cpu registers
364
@item info history
365
show the command line history
366
@end table
367

    
368
@item q or quit
369
Quit the emulator.
370

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

    
374
@item change device filename
375
Change a removable media.
376

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

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

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

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

    
389
@item stop
390
Stop emulation.
391

    
392
@item c or cont
393
Resume emulation.
394

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

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

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

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

    
407
@table @var
408
@item count 
409
is the number of items to be dumped.
410

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

    
415
@item size
416
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits)
417

    
418
@end table
419

    
420
Examples: 
421
@itemize
422
@item
423
Dump 10 instructions at the current instruction pointer:
424
@example 
425
(qemu) x/10i $eip
426
0x90107063:  ret
427
0x90107064:  sti
428
0x90107065:  lea    0x0(%esi,1),%esi
429
0x90107069:  lea    0x0(%edi,1),%edi
430
0x90107070:  ret
431
0x90107071:  jmp    0x90107080
432
0x90107073:  nop
433
0x90107074:  nop
434
0x90107075:  nop
435
0x90107076:  nop
436
@end example
437

    
438
@item
439
Dump 80 16 bit values at the start of the video memory.
440
@example 
441
(qemu) xp/80hx 0xb8000
442
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
443
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
444
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
445
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
446
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
447
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
448
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
449
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
450
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
451
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
452
@end example
453
@end itemize
454

    
455
@item p or print/fmt expr
456

    
457
Print expression value. Only the @var{format} part of @var{fmt} is
458
used.
459

    
460
@end table
461

    
462
@subsection Integer expressions
463

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

    
468
@node disk_images
469
@section Disk Images
470

    
471
@subsection Raw disk images
472

    
473
The disk images can simply be raw images of the hard disk. You can
474
create them with the command:
475
@example
476
dd if=/dev/zero of=myimage bs=1024 count=mysize
477
@end example
478
where @var{myimage} is the image filename and @var{mysize} is its size
479
in kilobytes.
480

    
481
@subsection Snapshot mode
482

    
483
If you use the option @option{-snapshot}, all disk images are
484
considered as read only. When sectors in written, they are written in
485
a temporary file created in @file{/tmp}. You can however force the
486
write back to the raw disk images by pressing @key{C-a s}.
487

    
488
NOTE: The snapshot mode only works with raw disk images.
489

    
490
@subsection Copy On Write disk images
491

    
492
QEMU also supports user mode Linux
493
(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
494
disk images. The COW disk images are much smaller than normal images
495
as they store only modified sectors. They also permit the use of the
496
same disk image template for many users.
497

    
498
To create a COW disk images, use the command:
499

    
500
@example
501
qemu-mkcow -f myrawimage.bin mycowimage.cow
502
@end example
503

    
504
@file{myrawimage.bin} is a raw image you want to use as original disk
505
image. It will never be written to.
506

    
507
@file{mycowimage.cow} is the COW disk image which is created by
508
@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
509
options. You must not modify the original raw disk image if you use
510
COW images, as COW images only store the modified sectors from the raw
511
disk image. QEMU stores the original raw disk image name and its
512
modified time in the COW disk image so that chances of mistakes are
513
reduced.
514

    
515
If the raw disk image is not read-only, by pressing @key{C-a s} you
516
can flush the COW disk image back into the raw disk image, as in
517
snapshot mode.
518

    
519
COW disk images can also be created without a corresponding raw disk
520
image. It is useful to have a big initial virtual disk image without
521
using much disk space. Use:
522

    
523
@example
524
qemu-mkcow mycowimage.cow 1024
525
@end example
526

    
527
to create a 1 gigabyte empty COW disk image.
528

    
529
NOTES: 
530
@enumerate
531
@item
532
COW disk images must be created on file systems supporting
533
@emph{holes} such as ext2 or ext3.
534
@item 
535
Since holes are used, the displayed size of the COW disk image is not
536
the real one. To know it, use the @code{ls -ls} command.
537
@end enumerate
538

    
539
@section Direct Linux Boot and Network emulation
540

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

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

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

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

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

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

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

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

    
650
Then enable X11 connections on your PC from the emulated Linux: 
651
@example
652
xhost +172.20.0.2
653
@end example
654

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

    
658
@end enumerate
659

    
660
NOTES:
661
@enumerate
662
@item 
663
A 2.5.74 kernel is also included in the archive. Just
664
replace the bzImage in qemu.sh to try it.
665

    
666
@item 
667
qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
668
default) containing all the simulated PC memory. If possible, try to use
669
a temporary directory using the tmpfs filesystem to avoid too many
670
unnecessary disk accesses.
671

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

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

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

    
688
@end enumerate
689

    
690
@node linux_compile
691
@section Linux Kernel Compilation
692

    
693
You can use any linux kernel with QEMU. However, if you want to use
694
@code{qemu-fast} to get maximum performances, you must use a modified
695
guest kernel. If you are using a 2.6 guest kernel, you can use
696
directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty
697
Russel available in the QEMU source archive. Otherwise, you can make the
698
following changes @emph{by hand} to the Linux kernel:
699

    
700
@enumerate
701
@item
702
The kernel must be mapped at 0x90000000 (the default is
703
0xc0000000). You must modify only two lines in the kernel source:
704

    
705
In @file{include/asm/page.h}, replace
706
@example
707
#define __PAGE_OFFSET           (0xc0000000)
708
@end example
709
by
710
@example
711
#define __PAGE_OFFSET           (0x90000000)
712
@end example
713

    
714
And in @file{arch/i386/vmlinux.lds}, replace
715
@example
716
  . = 0xc0000000 + 0x100000;
717
@end example
718
by 
719
@example
720
  . = 0x90000000 + 0x100000;
721
@end example
722

    
723
@item
724
If you want to enable SMP (Symmetric Multi-Processing) support, you
725
must make the following change in @file{include/asm/fixmap.h}. Replace
726
@example
727
#define FIXADDR_TOP	(0xffffX000UL)
728
@end example
729
by 
730
@example
731
#define FIXADDR_TOP	(0xa7ffX000UL)
732
@end example
733
(X is 'e' or 'f' depending on the kernel version). Although you can
734
use an SMP kernel with QEMU, it only supports one CPU.
735

    
736
@item
737
If you are not using a 2.6 kernel as host kernel but if you use a target
738
2.6 kernel, you must also ensure that the 'HZ' define is set to 100
739
(1000 is the default) as QEMU cannot currently emulate timers at
740
frequencies greater than 100 Hz on host Linux systems < 2.6. In
741
@file{include/asm/param.h}, replace:
742

    
743
@example
744
# define HZ		1000		/* Internal kernel timer frequency */
745
@end example
746
by
747
@example
748
# define HZ		100		/* Internal kernel timer frequency */
749
@end example
750

    
751
@end enumerate
752

    
753
The file config-2.x.x gives the configuration of the example kernels.
754

    
755
Just type
756
@example
757
make bzImage
758
@end example
759

    
760
As you would do to make a real kernel. Then you can use with QEMU
761
exactly the same kernel as you would boot on your PC (in
762
@file{arch/i386/boot/bzImage}).
763

    
764
@node gdb_usage
765
@section GDB usage
766

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

    
770
In order to use gdb, launch qemu with the '-s' option. It will wait for a
771
gdb connection:
772
@example
773
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
774
Connected to host network interface: tun0
775
Waiting gdb connection on port 1234
776
@end example
777

    
778
Then launch gdb on the 'vmlinux' executable:
779
@example
780
> gdb vmlinux
781
@end example
782

    
783
In gdb, connect to QEMU:
784
@example
785
(gdb) target remote localhost:1234
786
@end example
787

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

    
793
Here are some useful tips in order to use gdb on system code:
794

    
795
@enumerate
796
@item
797
Use @code{info reg} to display all the CPU registers.
798
@item
799
Use @code{x/10i $eip} to display the code at the PC position.
800
@item
801
Use @code{set architecture i8086} to dump 16 bit code. Then use
802
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
803
@end enumerate
804

    
805
@chapter QEMU User space emulator invocation
806

    
807
@section Quick Start
808

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

    
812
@itemize
813

    
814
@item On x86, you can just try to launch any process by using the native
815
libraries:
816

    
817
@example 
818
qemu-i386 -L / /bin/ls
819
@end example
820

    
821
@code{-L /} tells that the x86 dynamic linker must be searched with a
822
@file{/} prefix.
823

    
824
@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):
825

    
826
@example 
827
qemu-i386 -L / qemu-i386 -L / /bin/ls
828
@end example
829

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

    
834
@example
835
unset LD_LIBRARY_PATH 
836
@end example
837

    
838
Then you can launch the precompiled @file{ls} x86 executable:
839

    
840
@example
841
qemu-i386 tests/i386/ls
842
@end example
843
You can look at @file{qemu-binfmt-conf.sh} so that
844
QEMU is automatically launched by the Linux kernel when you try to
845
launch x86 executables. It requires the @code{binfmt_misc} module in the
846
Linux kernel.
847

    
848
@item The x86 version of QEMU is also included. You can try weird things such as:
849
@example
850
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
851
@end example
852

    
853
@end itemize
854

    
855
@section Wine launch
856

    
857
@itemize
858

    
859
@item Ensure that you have a working QEMU with the x86 glibc
860
distribution (see previous section). In order to verify it, you must be
861
able to do:
862

    
863
@example
864
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
865
@end example
866

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

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

    
874
@item Then you can try the example @file{putty.exe}:
875

    
876
@example
877
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
878
@end example
879

    
880
@end itemize
881

    
882
@section Command line options
883

    
884
@example
885
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
886
@end example
887

    
888
@table @option
889
@item -h
890
Print the help
891
@item -L path   
892
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
893
@item -s size
894
Set the x86 stack size in bytes (default=524288)
895
@end table
896

    
897
Debug options:
898

    
899
@table @option
900
@item -d
901
Activate log (logfile=/tmp/qemu.log)
902
@item -p pagesize
903
Act as if the host page size was 'pagesize' bytes
904
@end table
905