Statistics
| Branch: | Revision:

root / qemu-doc.texi @ 0986ac3b

History | View | Annotate | Download (50.7 kB)

1
\input texinfo @c -*- texinfo -*-
2
@c %**start of header
3
@setfilename qemu-doc.info
4
@settitle QEMU CPU Emulator User Documentation
5
@exampleindent 0
6
@paragraphindent 0
7
@c %**end of header
8

    
9
@iftex
10
@titlepage
11
@sp 7
12
@center @titlefont{QEMU CPU Emulator}
13
@sp 1
14
@center @titlefont{User Documentation}
15
@sp 3
16
@end titlepage
17
@end iftex
18

    
19
@ifnottex
20
@node Top
21
@top
22

    
23
@menu
24
* Introduction::
25
* Installation::
26
* QEMU PC System emulator::
27
* QEMU System emulator for non PC targets::
28
* QEMU Linux User space emulator::
29
* compilation:: Compilation from the sources
30
* Index::
31
@end menu
32
@end ifnottex
33

    
34
@contents
35

    
36
@node Introduction
37
@chapter Introduction
38

    
39
@menu
40
* intro_features:: Features
41
@end menu
42

    
43
@node intro_features
44
@section Features
45

    
46
QEMU is a FAST! processor emulator using dynamic translation to
47
achieve good emulation speed.
48

    
49
QEMU has two operating modes:
50

    
51
@itemize @minus
52

    
53
@item 
54
Full system emulation. In this mode, QEMU emulates a full system (for
55
example a PC), including one or several processors and various
56
peripherals. It can be used to launch different Operating Systems
57
without rebooting the PC or to debug system code.
58

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

    
65
@end itemize
66

    
67
QEMU can run without an host kernel driver and yet gives acceptable
68
performance. 
69

    
70
For system emulation, the following hardware targets are supported:
71
@itemize
72
@item PC (x86 or x86_64 processor)
73
@item ISA PC (old style PC without PCI bus)
74
@item PREP (PowerPC processor)
75
@item G3 BW PowerMac (PowerPC processor)
76
@item Mac99 PowerMac (PowerPC processor, in progress)
77
@item Sun4m (32-bit Sparc processor)
78
@item Sun4u (64-bit Sparc processor, in progress)
79
@item Malta board (32-bit MIPS processor)
80
@item ARM Integrator/CP (ARM926E or 1026E processor)
81
@item ARM Versatile baseboard (ARM926E)
82
@end itemize
83

    
84
For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported.
85

    
86
@node Installation
87
@chapter Installation
88

    
89
If you want to compile QEMU yourself, see @ref{compilation}.
90

    
91
@menu
92
* install_linux::   Linux
93
* install_windows:: Windows
94
* install_mac::     Macintosh
95
@end menu
96

    
97
@node install_linux
98
@section Linux
99

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

    
103
@node install_windows
104
@section Windows
105

    
106
Download the experimental binary installer at
107
@url{http://www.free.oszoo.org/@/download.html}.
108

    
109
@node install_mac
110
@section Mac OS X
111

    
112
Download the experimental binary installer at
113
@url{http://www.free.oszoo.org/@/download.html}.
114

    
115
@node QEMU PC System emulator
116
@chapter QEMU PC System emulator
117

    
118
@menu
119
* pcsys_introduction:: Introduction
120
* pcsys_quickstart::   Quick Start
121
* sec_invocation::     Invocation
122
* pcsys_keys::         Keys
123
* pcsys_monitor::      QEMU Monitor
124
* disk_images::        Disk Images
125
* pcsys_network::      Network emulation
126
* direct_linux_boot::  Direct Linux Boot
127
* pcsys_usb::          USB emulation
128
* gdb_usage::          GDB usage
129
* pcsys_os_specific::  Target OS specific information
130
@end menu
131

    
132
@node pcsys_introduction
133
@section Introduction
134

    
135
@c man begin DESCRIPTION
136

    
137
The QEMU PC System emulator simulates the
138
following peripherals:
139

    
140
@itemize @minus
141
@item 
142
i440FX host PCI bridge and PIIX3 PCI to ISA bridge
143
@item
144
Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
145
extensions (hardware level, including all non standard modes).
146
@item
147
PS/2 mouse and keyboard
148
@item 
149
2 PCI IDE interfaces with hard disk and CD-ROM support
150
@item
151
Floppy disk
152
@item 
153
NE2000 PCI network adapters
154
@item
155
Serial ports
156
@item
157
Creative SoundBlaster 16 sound card
158
@item
159
ENSONIQ AudioPCI ES1370 sound card
160
@item
161
Adlib(OPL2) - Yamaha YM3812 compatible chip
162
@item
163
PCI UHCI USB controller and a virtual USB hub.
164
@end itemize
165

    
166
SMP is supported with up to 255 CPUs.
167

    
168
Note that adlib is only available when QEMU was configured with
169
-enable-adlib
170

    
171
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
172
VGA BIOS.
173

    
174
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
175

    
176
@c man end
177

    
178
@node pcsys_quickstart
179
@section Quick Start
180

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

    
183
@example
184
qemu linux.img
185
@end example
186

    
187
Linux should boot and give you a prompt.
188

    
189
@node sec_invocation
190
@section Invocation
191

    
192
@example
193
@c man begin SYNOPSIS
194
usage: qemu [options] [disk_image]
195
@c man end
196
@end example
197

    
198
@c man begin OPTIONS
199
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
200

    
201
General options:
202
@table @option
203
@item -M machine
204
Select the emulated machine (@code{-M ?} for list)
205

    
206
@item -fda file
207
@item -fdb file
208
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
209
use the host floppy by using @file{/dev/fd0} as filename.
210

    
211
@item -hda file
212
@item -hdb file
213
@item -hdc file
214
@item -hdd file
215
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
216

    
217
@item -cdrom file
218
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
219
@option{-cdrom} at the same time). You can use the host CD-ROM by
220
using @file{/dev/cdrom} as filename.
221

    
222
@item -boot [a|c|d]
223
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
224
the default.
225

    
226
@item -snapshot
227
Write to temporary files instead of disk image files. In this case,
228
the raw disk image you use is not written back. You can however force
229
the write back by pressing @key{C-a s} (@pxref{disk_images}). 
230

    
231
@item -m megs
232
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
233

    
234
@item -smp n
235
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
236
CPUs are supported.
237

    
238
@item -nographic
239

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

    
246
@item -vnc d
247

    
248
Normally, QEMU uses SDL to display the VGA output.  With this option,
249
you can have QEMU listen on VNC display d and redirect the VGA display
250
over the VNC session.  It is very useful to enable the usb tablet device
251
when using this option (option @option{-usbdevice tablet}).
252

    
253
@item -k language
254

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

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

    
267
The default is @code{en-us}.
268

    
269
@item -audio-help
270

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

    
274
@item -soundhw card1,card2,... or -soundhw all
275

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

    
279
@example
280
qemu -soundhw sb16,adlib hda
281
qemu -soundhw es1370 hda
282
qemu -soundhw all hda
283
qemu -soundhw ?
284
@end example
285

    
286
@item -localtime
287
Set the real time clock to local time (the default is to UTC
288
time). This option is needed to have correct date in MS-DOS or
289
Windows.
290

    
291
@item -full-screen
292
Start in full screen.
293

    
294
@item -pidfile file
295
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
296
from a script.
297

    
298
@item -win2k-hack
299
Use it when installing Windows 2000 to avoid a disk full bug. After
300
Windows 2000 is installed, you no longer need this option (this option
301
slows down the IDE transfers).
302

    
303
@end table
304

    
305
USB options:
306
@table @option
307

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

    
311
@item -usbdevice devname
312
Add the USB device @var{devname}. @xref{usb_devices}.
313
@end table
314

    
315
Network options:
316

    
317
@table @option
318

    
319
@item -net nic[,vlan=n][,macaddr=addr][,model=type]
320
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
321
= 0 is the default). The NIC is currently an NE2000 on the PC
322
target. Optionally, the MAC address can be changed. If no
323
@option{-net} option is specified, a single NIC is created.
324
Qemu can emulate several different models of network card.  Valid values for
325
@var{type} are @code{ne2k_pci}, @code{ne2k_isa}, @code{rtl8139},
326
@code{smc91c111} and @code{lance}.  Not all devices are supported on all
327
targets.
328

    
329
@item -net user[,vlan=n][,hostname=name]
330
Use the user mode network stack which requires no administrator
331
priviledge to run.  @option{hostname=name} can be used to specify the client
332
hostname reported by the builtin DHCP server.
333

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

    
341
@example
342
qemu linux.img -net nic -net tap
343
@end example
344

    
345
More complicated example (two NICs, each one connected to a TAP device)
346
@example
347
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
348
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
349
@end example
350

    
351

    
352
@item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
353

    
354
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
355
machine using a TCP socket connection. If @option{listen} is
356
specified, QEMU waits for incoming connections on @var{port}
357
(@var{host} is optional). @option{connect} is used to connect to
358
another QEMU instance using the @option{listen} option. @option{fd=h}
359
specifies an already opened TCP socket.
360

    
361
Example:
362
@example
363
# launch a first QEMU instance
364
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
365
               -net socket,listen=:1234
366
# connect the VLAN 0 of this instance to the VLAN 0
367
# of the first instance
368
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
369
               -net socket,connect=127.0.0.1:1234
370
@end example
371

    
372
@item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]
373

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

    
388
Example:
389
@example
390
# launch one QEMU instance
391
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
392
               -net socket,mcast=230.0.0.1:1234
393
# launch another QEMU instance on same "bus"
394
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
395
               -net socket,mcast=230.0.0.1:1234
396
# launch yet another QEMU instance on same "bus"
397
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
398
               -net socket,mcast=230.0.0.1:1234
399
@end example
400

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

    
411
@item -net none
412
Indicate that no network devices should be configured. It is used to
413
override the default configuration (@option{-net nic -net user}) which
414
is activated if no @option{-net} options are provided.
415

    
416
@item -tftp prefix
417
When using the user mode network stack, activate a built-in TFTP
418
server. All filenames beginning with @var{prefix} can be downloaded
419
from the host to the guest using a TFTP client. The TFTP client on the
420
guest must be configured in binary mode (use the command @code{bin} of
421
the Unix TFTP client). The host IP address on the guest is as usual
422
10.0.2.2.
423

    
424
@item -smb dir
425
When using the user mode network stack, activate a built-in SMB
426
server so that Windows OSes can access to the host files in @file{dir}
427
transparently.
428

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

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

    
438
Note that a SAMBA server must be installed on the host OS in
439
@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
440
2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
441

    
442
@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
443

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

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

    
453
@example
454
# on the host
455
qemu -redir tcp:6001::6000 [...]
456
# this host xterm should open in the guest X11 server
457
xterm -display :1
458
@end example
459

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

    
463
@example
464
# on the host
465
qemu -redir tcp:5555::23 [...]
466
telnet localhost 5555
467
@end example
468

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

    
472
@end table
473

    
474
Linux boot specific: When using these options, you can use a given
475
Linux kernel without installing it in the disk image. It can be useful
476
for easier testing of various kernels.
477

    
478
@table @option
479

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

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

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

    
489
@end table
490

    
491
Debug/Expert options:
492
@table @option
493

    
494
@item -serial dev
495
Redirect the virtual serial port to host device @var{dev}. Available
496
devices are:
497
@table @code
498
@item vc
499
Virtual console
500
@item pty
501
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
502
@item null
503
void device
504
@item /dev/XXX
505
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
506
parameters are set according to the emulated ones.
507
@item /dev/parportN
508
[Linux only, parallel port only] Use host parallel port
509
@var{N}. Currently only SPP parallel port features can be used.
510
@item file:filename
511
Write output to filename. No character can be read.
512
@item stdio
513
[Unix only] standard input/output
514
@item pipe:filename
515
[Unix only] name pipe @var{filename}
516
@end table
517
The default device is @code{vc} in graphical mode and @code{stdio} in
518
non graphical mode.
519

    
520
This option can be used several times to simulate up to 4 serials
521
ports.
522

    
523
@item -parallel dev
524
Redirect the virtual parallel port to host device @var{dev} (same
525
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
526
be used to use hardware devices connected on the corresponding host
527
parallel port.
528

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

    
532
@item -monitor dev
533
Redirect the monitor to host device @var{dev} (same devices as the
534
serial port).
535
The default device is @code{vc} in graphical mode and @code{stdio} in
536
non graphical mode.
537

    
538
@item -s
539
Wait gdb connection to port 1234 (@pxref{gdb_usage}). 
540
@item -p port
541
Change gdb connection port.
542
@item -S
543
Do not start CPU at startup (you must type 'c' in the monitor).
544
@item -d             
545
Output log in /tmp/qemu.log
546
@item -hdachs c,h,s,[,t]
547
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
548
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
549
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
550
all thoses parameters. This option is useful for old MS-DOS disk
551
images.
552

    
553
@item -std-vga
554
Simulate a standard VGA card with Bochs VBE extensions (default is
555
Cirrus Logic GD5446 PCI VGA)
556
@item -loadvm file
557
Start right away with a saved state (@code{loadvm} in monitor)
558
@end table
559

    
560
@c man end
561

    
562
@node pcsys_keys
563
@section Keys
564

    
565
@c man begin OPTIONS
566

    
567
During the graphical emulation, you can use the following keys:
568
@table @key
569
@item Ctrl-Alt-f
570
Toggle full screen
571

    
572
@item Ctrl-Alt-n
573
Switch to virtual console 'n'. Standard console mappings are:
574
@table @emph
575
@item 1
576
Target system display
577
@item 2
578
Monitor
579
@item 3
580
Serial port
581
@end table
582

    
583
@item Ctrl-Alt
584
Toggle mouse and keyboard grab.
585
@end table
586

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

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

    
593
@table @key
594
@item Ctrl-a h
595
Print this help
596
@item Ctrl-a x    
597
Exit emulatior
598
@item Ctrl-a s    
599
Save disk data back to file (if -snapshot)
600
@item Ctrl-a b
601
Send break (magic sysrq in Linux)
602
@item Ctrl-a c
603
Switch between console and monitor
604
@item Ctrl-a Ctrl-a
605
Send Ctrl-a
606
@end table
607
@c man end
608

    
609
@ignore
610

    
611
@c man begin SEEALSO
612
The HTML documentation of QEMU for more precise information and Linux
613
user mode emulator invocation.
614
@c man end
615

    
616
@c man begin AUTHOR
617
Fabrice Bellard
618
@c man end
619

    
620
@end ignore
621

    
622
@node pcsys_monitor
623
@section QEMU Monitor
624

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

    
628
@itemize @minus
629

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

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

    
638
@item Inspect the VM state without an external debugger.
639

    
640
@end itemize
641

    
642
@subsection Commands
643

    
644
The following commands are available:
645

    
646
@table @option
647

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

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

    
654
@item info subcommand 
655
show various information about the system state
656

    
657
@table @option
658
@item info network
659
show the various VLANs and the associated devices
660
@item info block
661
show the block devices
662
@item info registers
663
show the cpu registers
664
@item info history
665
show the command line history
666
@item info pci
667
show emulated PCI device
668
@item info usb
669
show USB devices plugged on the virtual USB hub
670
@item info usbhost
671
show all USB host devices
672
@end table
673

    
674
@item q or quit
675
Quit the emulator.
676

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

    
680
@item change device filename
681
Change a removable media.
682

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

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

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

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

    
695
@item stop
696
Stop emulation.
697

    
698
@item c or cont
699
Resume emulation.
700

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

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

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

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

    
713
@table @var
714
@item count 
715
is the number of items to be dumped.
716

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

    
721
@item size
722
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
723
@code{h} or @code{w} can be specified with the @code{i} format to
724
respectively select 16 or 32 bit code instruction size.
725

    
726
@end table
727

    
728
Examples: 
729
@itemize
730
@item
731
Dump 10 instructions at the current instruction pointer:
732
@example 
733
(qemu) x/10i $eip
734
0x90107063:  ret
735
0x90107064:  sti
736
0x90107065:  lea    0x0(%esi,1),%esi
737
0x90107069:  lea    0x0(%edi,1),%edi
738
0x90107070:  ret
739
0x90107071:  jmp    0x90107080
740
0x90107073:  nop
741
0x90107074:  nop
742
0x90107075:  nop
743
0x90107076:  nop
744
@end example
745

    
746
@item
747
Dump 80 16 bit values at the start of the video memory.
748
@smallexample 
749
(qemu) xp/80hx 0xb8000
750
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
751
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
752
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
753
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
754
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
755
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
756
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
757
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
758
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
759
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
760
@end smallexample
761
@end itemize
762

    
763
@item p or print/fmt expr
764

    
765
Print expression value. Only the @var{format} part of @var{fmt} is
766
used.
767

    
768
@item sendkey keys
769

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

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

    
779
@item system_reset
780

    
781
Reset the system.
782

    
783
@item usb_add devname
784

    
785
Add the USB device @var{devname}.  For details of available devices see
786
@ref{usb_devices}
787

    
788
@item usb_del devname
789

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

    
794
@end table
795

    
796
@subsection Integer expressions
797

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

    
802
@node disk_images
803
@section Disk Images
804

    
805
Since version 0.6.1, QEMU supports many disk image formats, including
806
growable disk images (their size increase as non empty sectors are
807
written), compressed and encrypted disk images.
808

    
809
@menu
810
* disk_images_quickstart::    Quick start for disk image creation
811
* disk_images_snapshot_mode:: Snapshot mode
812
* qemu_img_invocation::       qemu-img Invocation
813
* disk_images_fat_images::    Virtual FAT disk images
814
@end menu
815

    
816
@node disk_images_quickstart
817
@subsection Quick start for disk image creation
818

    
819
You can create a disk image with the command:
820
@example
821
qemu-img create myimage.img mysize
822
@end example
823
where @var{myimage.img} is the disk image filename and @var{mysize} is its
824
size in kilobytes. You can add an @code{M} suffix to give the size in
825
megabytes and a @code{G} suffix for gigabytes.
826

    
827
See @ref{qemu_img_invocation} for more information.
828

    
829
@node disk_images_snapshot_mode
830
@subsection Snapshot mode
831

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

    
838
@node qemu_img_invocation
839
@subsection @code{qemu-img} Invocation
840

    
841
@include qemu-img.texi
842

    
843
@node disk_images_fat_images
844
@subsection Virtual FAT disk images
845

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

    
849
@example 
850
qemu linux.img -hdb fat:/my_directory
851
@end example
852

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

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

    
859
@example 
860
qemu linux.img -fda fat:floppy:/my_directory
861
@end example
862

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

    
866
@example 
867
qemu linux.img -fda fat:floppy:rw:/my_directory
868
@end example
869

    
870
What you should @emph{never} do:
871
@itemize
872
@item use non-ASCII filenames ;
873
@item use "-snapshot" together with ":rw:" ;
874
@item expect it to work when loadvm'ing ;
875
@item write to the FAT directory on the host system while accessing it with the guest system.
876
@end itemize
877

    
878
@node pcsys_network
879
@section Network emulation
880

    
881
QEMU can simulate several networks cards (NE2000 boards on the PC
882
target) and can connect them to an arbitrary number of Virtual Local
883
Area Networks (VLANs). Host TAP devices can be connected to any QEMU
884
VLAN. VLAN can be connected between separate instances of QEMU to
885
simulate large networks. For simpler usage, a non priviledged user mode
886
network stack can replace the TAP device to have a basic network
887
connection.
888

    
889
@subsection VLANs
890

    
891
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
892
connection between several network devices. These devices can be for
893
example QEMU virtual Ethernet cards or virtual Host ethernet devices
894
(TAP devices).
895

    
896
@subsection Using TAP network interfaces
897

    
898
This is the standard way to connect QEMU to a real network. QEMU adds
899
a virtual network device on your host (called @code{tapN}), and you
900
can then configure it as if it was a real ethernet card.
901

    
902
As an example, you can download the @file{linux-test-xxx.tar.gz}
903
archive and copy the script @file{qemu-ifup} in @file{/etc} and
904
configure properly @code{sudo} so that the command @code{ifconfig}
905
contained in @file{qemu-ifup} can be executed as root. You must verify
906
that your host kernel supports the TAP network interfaces: the
907
device @file{/dev/net/tun} must be present.
908

    
909
See @ref{direct_linux_boot} to have an example of network use with a
910
Linux distribution and @ref{sec_invocation} to have examples of
911
command lines using the TAP network interfaces.
912

    
913
@subsection Using the user mode network stack
914

    
915
By using the option @option{-net user} (default configuration if no
916
@option{-net} option is specified), QEMU uses a completely user mode
917
network stack (you don't need root priviledge to use the virtual
918
network). The virtual network configuration is the following:
919

    
920
@example
921

    
922
         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
923
                           |          (10.0.2.2)
924
                           |
925
                           ---->  DNS server (10.0.2.3)
926
                           |     
927
                           ---->  SMB server (10.0.2.4)
928
@end example
929

    
930
The QEMU VM behaves as if it was behind a firewall which blocks all
931
incoming connections. You can use a DHCP client to automatically
932
configure the network in the QEMU VM. The DHCP server assign addresses
933
to the hosts starting from 10.0.2.15.
934

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

    
939
Note that @code{ping} is not supported reliably to the internet as it
940
would require root priviledges. It means you can only ping the local
941
router (10.0.2.2).
942

    
943
When using the built-in TFTP server, the router is also the TFTP
944
server.
945

    
946
When using the @option{-redir} option, TCP or UDP connections can be
947
redirected from the host to the guest. It allows for example to
948
redirect X11, telnet or SSH connections.
949

    
950
@subsection Connecting VLANs between QEMU instances
951

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

    
956
@node direct_linux_boot
957
@section Direct Linux Boot
958

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

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

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

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

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

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

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

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

    
1068
Then enable X11 connections on your PC from the emulated Linux: 
1069
@example
1070
xhost +172.20.0.2
1071
@end example
1072

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

    
1076
@end enumerate
1077

    
1078
NOTES:
1079
@enumerate
1080
@item 
1081
A 2.5.74 kernel is also included in the archive. Just
1082
replace the bzImage in qemu.sh to try it.
1083

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

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

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

    
1100
@end enumerate
1101

    
1102
@node pcsys_usb
1103
@section USB emulation
1104

    
1105
QEMU emulates a PCI UHCI USB controller. You can virtually plug
1106
virtual USB devices or real host USB devices (experimental, works only
1107
on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1108
as neccessary to connect multiple USB devices.
1109

    
1110
@menu
1111
* usb_devices::
1112
* host_usb_devices::
1113
@end menu
1114
@node usb_devices
1115
@subsection Connecting USB devices
1116

    
1117
USB devices can be connected with the @option{-usbdevice} commandline option
1118
or the @code{usb_add} monitor command.  Available devices are:
1119

    
1120
@table @var
1121
@item @code{mouse}
1122
Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1123
@item @code{tablet}
1124
Pointer device that uses abolsute coordinates (like a touchscreen).
1125
This means qemu is able to report the mouse position without having
1126
to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1127
@item @code{disk:file}
1128
Mass storage device based on @var{file} (@pxref{disk_images})
1129
@item @code{host:bus.addr}
1130
Pass through the host device identified by @var{bus.addr}
1131
(Linux only)
1132
@item @code{host:vendor_id:product_id}
1133
Pass through the host device identified by @var{vendor_id:product_id}
1134
(Linux only)
1135
@end table
1136

    
1137
@node host_usb_devices
1138
@subsection Using host USB devices on a Linux host
1139

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

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

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

    
1156
@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1157
@example
1158
chown -R myuid /proc/bus/usb
1159
@end example
1160

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

    
1170
@item Add the device in QEMU by using:
1171
@example 
1172
usb_add host:1234:5678
1173
@end example
1174

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

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

    
1180
@end enumerate
1181

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

    
1185
@node gdb_usage
1186
@section GDB usage
1187

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

    
1191
In order to use gdb, launch qemu with the '-s' option. It will wait for a
1192
gdb connection:
1193
@example
1194
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1195
       -append "root=/dev/hda"
1196
Connected to host network interface: tun0
1197
Waiting gdb connection on port 1234
1198
@end example
1199

    
1200
Then launch gdb on the 'vmlinux' executable:
1201
@example
1202
> gdb vmlinux
1203
@end example
1204

    
1205
In gdb, connect to QEMU:
1206
@example
1207
(gdb) target remote localhost:1234
1208
@end example
1209

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

    
1215
Here are some useful tips in order to use gdb on system code:
1216

    
1217
@enumerate
1218
@item
1219
Use @code{info reg} to display all the CPU registers.
1220
@item
1221
Use @code{x/10i $eip} to display the code at the PC position.
1222
@item
1223
Use @code{set architecture i8086} to dump 16 bit code. Then use
1224
@code{x/10i $cs*16+$eip} to dump the code at the PC position.
1225
@end enumerate
1226

    
1227
@node pcsys_os_specific
1228
@section Target OS specific information
1229

    
1230
@subsection Linux
1231

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

    
1236
When using a 2.6 guest Linux kernel, you should add the option
1237
@code{clock=pit} on the kernel command line because the 2.6 Linux
1238
kernels make very strict real time clock checks by default that QEMU
1239
cannot simulate exactly.
1240

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

    
1247
@subsection Windows
1248

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

    
1252
@subsubsection SVGA graphic modes support
1253

    
1254
QEMU emulates a Cirrus Logic GD5446 Video
1255
card. All Windows versions starting from Windows 95 should recognize
1256
and use this graphic card. For optimal performances, use 16 bit color
1257
depth in the guest and the host OS.
1258

    
1259
@subsubsection CPU usage reduction
1260

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

    
1267
@subsubsection Windows 2000 disk full problem
1268

    
1269
Windows 2000 has a bug which gives a disk full problem during its
1270
installation. When installing it, use the @option{-win2k-hack} QEMU
1271
option to enable a specific workaround. After Windows 2000 is
1272
installed, you no longer need this option (this option slows down the
1273
IDE transfers).
1274

    
1275
@subsubsection Windows 2000 shutdown
1276

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

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

    
1288
@subsubsection Share a directory between Unix and Windows
1289

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

    
1292
@subsubsection Windows XP security problems
1293

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

    
1303
Future QEMU releases are likely to correct this bug.
1304

    
1305
@subsection MS-DOS and FreeDOS
1306

    
1307
@subsubsection CPU usage reduction
1308

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

    
1314
@node QEMU System emulator for non PC targets
1315
@chapter QEMU System emulator for non PC targets
1316

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

    
1321
@menu
1322
* QEMU PowerPC System emulator::
1323
* Sparc32 System emulator invocation::
1324
* Sparc64 System emulator invocation::
1325
* MIPS System emulator invocation::
1326
* ARM System emulator invocation::
1327
@end menu
1328

    
1329
@node QEMU PowerPC System emulator
1330
@section QEMU PowerPC System emulator
1331

    
1332
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1333
or PowerMac PowerPC system.
1334

    
1335
QEMU emulates the following PowerMac peripherals:
1336

    
1337
@itemize @minus
1338
@item 
1339
UniNorth PCI Bridge 
1340
@item
1341
PCI VGA compatible card with VESA Bochs Extensions
1342
@item 
1343
2 PMAC IDE interfaces with hard disk and CD-ROM support
1344
@item 
1345
NE2000 PCI adapters
1346
@item
1347
Non Volatile RAM
1348
@item
1349
VIA-CUDA with ADB keyboard and mouse.
1350
@end itemize
1351

    
1352
QEMU emulates the following PREP peripherals:
1353

    
1354
@itemize @minus
1355
@item 
1356
PCI Bridge
1357
@item
1358
PCI VGA compatible card with VESA Bochs Extensions
1359
@item 
1360
2 IDE interfaces with hard disk and CD-ROM support
1361
@item
1362
Floppy disk
1363
@item 
1364
NE2000 network adapters
1365
@item
1366
Serial port
1367
@item
1368
PREP Non Volatile RAM
1369
@item
1370
PC compatible keyboard and mouse.
1371
@end itemize
1372

    
1373
QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1374
@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1375

    
1376
@c man begin OPTIONS
1377

    
1378
The following options are specific to the PowerPC emulation:
1379

    
1380
@table @option
1381

    
1382
@item -g WxH[xDEPTH]  
1383

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

    
1386
@end table
1387

    
1388
@c man end 
1389

    
1390

    
1391
More information is available at
1392
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1393

    
1394
@node Sparc32 System emulator invocation
1395
@section Sparc32 System emulator invocation
1396

    
1397
Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5
1398
(sun4m architecture). The emulation is somewhat complete.
1399

    
1400
QEMU emulates the following sun4m peripherals:
1401

    
1402
@itemize @minus
1403
@item
1404
IOMMU
1405
@item
1406
TCX Frame buffer
1407
@item 
1408
Lance (Am7990) Ethernet
1409
@item
1410
Non Volatile RAM M48T08
1411
@item
1412
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1413
and power/reset logic
1414
@item
1415
ESP SCSI controller with hard disk and CD-ROM support
1416
@item
1417
Floppy drive
1418
@end itemize
1419

    
1420
The number of peripherals is fixed in the architecture.
1421

    
1422
Since version 0.8.1, QEMU uses OpenBIOS
1423
@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1424
firmware implementation. The goal is to implement a 100% IEEE
1425
1275-1994 (referred to as Open Firmware) compliant firmware.
1426

    
1427
A sample Linux 2.6 series kernel and ram disk image are available on
1428
the QEMU web site. Please note that currently NetBSD, OpenBSD or
1429
Solaris kernels don't work.
1430

    
1431
@c man begin OPTIONS
1432

    
1433
The following options are specific to the Sparc emulation:
1434

    
1435
@table @option
1436

    
1437
@item -g WxH
1438

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

    
1441
@end table
1442

    
1443
@c man end 
1444

    
1445
@node Sparc64 System emulator invocation
1446
@section Sparc64 System emulator invocation
1447

    
1448
Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
1449
The emulator is not usable for anything yet.
1450

    
1451
QEMU emulates the following sun4u peripherals:
1452

    
1453
@itemize @minus
1454
@item
1455
UltraSparc IIi APB PCI Bridge 
1456
@item
1457
PCI VGA compatible card with VESA Bochs Extensions
1458
@item
1459
Non Volatile RAM M48T59
1460
@item
1461
PC-compatible serial ports
1462
@end itemize
1463

    
1464
@node MIPS System emulator invocation
1465
@section MIPS System emulator invocation
1466

    
1467
Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
1468
The emulator is able to boot a Linux kernel and to run a Linux Debian
1469
installation from NFS. The following devices are emulated:
1470

    
1471
@itemize @minus
1472
@item 
1473
MIPS R4K CPU
1474
@item
1475
PC style serial port
1476
@item
1477
NE2000 network card
1478
@end itemize
1479

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

    
1482
@node ARM System emulator invocation
1483
@section ARM System emulator invocation
1484

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

    
1489
@itemize @minus
1490
@item
1491
ARM926E or ARM1026E CPU
1492
@item
1493
Two PL011 UARTs
1494
@item 
1495
SMC 91c111 Ethernet adapter
1496
@item
1497
PL110 LCD controller
1498
@item
1499
PL050 KMI with PS/2 keyboard and mouse.
1500
@end itemize
1501

    
1502
The ARM Versatile baseboard is emulated with the following devices:
1503

    
1504
@itemize @minus
1505
@item
1506
ARM926E CPU
1507
@item
1508
PL190 Vectored Interrupt Controller
1509
@item
1510
Four PL011 UARTs
1511
@item 
1512
SMC 91c111 Ethernet adapter
1513
@item
1514
PL110 LCD controller
1515
@item
1516
PL050 KMI with PS/2 keyboard and mouse.
1517
@item
1518
PCI host bridge.  Note the emulated PCI bridge only provides access to
1519
PCI memory space.  It does not provide access to PCI IO space.
1520
This means some devices (eg. ne2k_pci NIC) are not useable, and others
1521
(eg. rtl8139 NIC) are only useable when the guest drivers use the memory
1522
mapped control registers.
1523
@end itemize
1524

    
1525
A Linux 2.6 test image is available on the QEMU web site. More
1526
information is available in the QEMU mailing-list archive.
1527

    
1528
@node QEMU Linux User space emulator 
1529
@chapter QEMU Linux User space emulator 
1530

    
1531
@menu
1532
* Quick Start::
1533
* Wine launch::
1534
* Command line options::
1535
* Other binaries::
1536
@end menu
1537

    
1538
@node Quick Start
1539
@section Quick Start
1540

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

    
1544
@itemize
1545

    
1546
@item On x86, you can just try to launch any process by using the native
1547
libraries:
1548

    
1549
@example 
1550
qemu-i386 -L / /bin/ls
1551
@end example
1552

    
1553
@code{-L /} tells that the x86 dynamic linker must be searched with a
1554
@file{/} prefix.
1555

    
1556
@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):
1557

    
1558
@example 
1559
qemu-i386 -L / qemu-i386 -L / /bin/ls
1560
@end example
1561

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

    
1566
@example
1567
unset LD_LIBRARY_PATH 
1568
@end example
1569

    
1570
Then you can launch the precompiled @file{ls} x86 executable:
1571

    
1572
@example
1573
qemu-i386 tests/i386/ls
1574
@end example
1575
You can look at @file{qemu-binfmt-conf.sh} so that
1576
QEMU is automatically launched by the Linux kernel when you try to
1577
launch x86 executables. It requires the @code{binfmt_misc} module in the
1578
Linux kernel.
1579

    
1580
@item The x86 version of QEMU is also included. You can try weird things such as:
1581
@example
1582
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
1583
          /usr/local/qemu-i386/bin/ls-i386
1584
@end example
1585

    
1586
@end itemize
1587

    
1588
@node Wine launch
1589
@section Wine launch
1590

    
1591
@itemize
1592

    
1593
@item Ensure that you have a working QEMU with the x86 glibc
1594
distribution (see previous section). In order to verify it, you must be
1595
able to do:
1596

    
1597
@example
1598
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1599
@end example
1600

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

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

    
1608
@item Then you can try the example @file{putty.exe}:
1609

    
1610
@example
1611
qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
1612
          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1613
@end example
1614

    
1615
@end itemize
1616

    
1617
@node Command line options
1618
@section Command line options
1619

    
1620
@example
1621
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1622
@end example
1623

    
1624
@table @option
1625
@item -h
1626
Print the help
1627
@item -L path   
1628
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1629
@item -s size
1630
Set the x86 stack size in bytes (default=524288)
1631
@end table
1632

    
1633
Debug options:
1634

    
1635
@table @option
1636
@item -d
1637
Activate log (logfile=/tmp/qemu.log)
1638
@item -p pagesize
1639
Act as if the host page size was 'pagesize' bytes
1640
@end table
1641

    
1642
@node Other binaries
1643
@section Other binaries
1644

    
1645
@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
1646
binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
1647
configurations), and arm-uclinux bFLT format binaries.
1648

    
1649
The binary format is detected automatically.
1650

    
1651
@node compilation
1652
@chapter Compilation from the sources
1653

    
1654
@menu
1655
* Linux/Unix::
1656
* Windows::
1657
* Cross compilation for Windows with Linux::
1658
* Mac OS X::
1659
@end menu
1660

    
1661
@node Linux/Unix
1662
@section Linux/Unix
1663

    
1664
@subsection Compilation
1665

    
1666
First you must decompress the sources:
1667
@example
1668
cd /tmp
1669
tar zxvf qemu-x.y.z.tar.gz
1670
cd qemu-x.y.z
1671
@end example
1672

    
1673
Then you configure QEMU and build it (usually no options are needed):
1674
@example
1675
./configure
1676
make
1677
@end example
1678

    
1679
Then type as root user:
1680
@example
1681
make install
1682
@end example
1683
to install QEMU in @file{/usr/local}.
1684

    
1685
@subsection Tested tool versions
1686

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

    
1693
@example
1694
host      gcc      binutils      glibc    linux       distribution
1695
----------------------------------------------------------------------
1696
x86       3.2      2.13.2        2.1.3    2.4.18
1697
          2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
1698
          3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
1699

    
1700
PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
1701
          3.2
1702

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

    
1705
Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
1706

    
1707
ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
1708

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

    
1715
[4] gcc 2.95.x generates invalid code when using too many register
1716
variables. You must use gcc 3.x on PowerPC.
1717
@end example
1718

    
1719
@node Windows
1720
@section Windows
1721

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

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

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

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

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

    
1747
@end itemize
1748

    
1749
@node Cross compilation for Windows with Linux
1750
@section Cross compilation for Windows with Linux
1751

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

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

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

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

    
1776
@end itemize
1777

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

    
1781
@node Mac OS X
1782
@section Mac OS X
1783

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

    
1788
@node Index
1789
@chapter Index
1790
@printindex cp
1791

    
1792
@bye