]> git.proxmox.com Git - mirror_qemu.git/blob - qemu-doc.texi
base memory size in cmos
[mirror_qemu.git] / qemu-doc.texi
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