Statistics
| Branch: | Revision:

root / qemu-doc.texi @ a03a6053

History | View | Annotate | Download (46.6 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 one or several processors and various
26
peripherals. It can be used to launch different Operating Systems
27
without rebooting the PC or to debug system code.
28

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

    
35
@end itemize
36

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

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

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

    
55
@chapter Installation
56

    
57
If you want to compile QEMU yourself, see @ref{compilation}.
58

    
59
@section Linux
60

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

    
64
@section Windows
65

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

    
69
@section Mac OS X
70

    
71
Download the experimental binary installer at
72
@url{http://www.free.oszoo.org/download.html}.
73

    
74
@chapter QEMU PC System emulator
75

    
76
@section Introduction
77

    
78
@c man begin DESCRIPTION
79

    
80
The QEMU PC System emulator simulates the
81
following peripherals:
82

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

    
109
SMP is supported with up to 255 CPUs.
110

    
111
Note that adlib is only available when QEMU was configured with
112
-enable-adlib
113

    
114
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
115
VGA BIOS.
116

    
117
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
118

    
119
@c man end
120

    
121
@section Quick Start
122

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

    
125
@example
126
qemu linux.img
127
@end example
128

    
129
Linux should boot and give you a prompt.
130

    
131
@node sec_invocation
132
@section Invocation
133

    
134
@example
135
@c man begin SYNOPSIS
136
usage: qemu [options] [disk_image]
137
@c man end
138
@end example
139

    
140
@c man begin OPTIONS
141
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
142

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

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

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

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

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

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

    
173
@item -m megs
174
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
175

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

    
180
@item -nographic
181

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

    
188
@item -k language
189

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

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

    
202
The default is @code{en-us}.
203

    
204
@item -audio-help
205

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

    
209
@item -soundhw card1,card2,... or -soundhw all
210

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

    
214
@example
215
qemu -soundhw sb16,adlib hda
216
qemu -soundhw es1370 hda
217
qemu -soundhw all hda
218
qemu -soundhw ?
219
@end example
220

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

    
226
@item -full-screen
227
Start in full screen.
228

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

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

    
238
@end table
239

    
240
USB options:
241
@table @option
242

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

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

    
251
Network options:
252

    
253
@table @option
254

    
255
@item -net nic[,vlan=n][,macaddr=addr][,model=type]
256
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
257
= 0 is the default). The NIC is currently an NE2000 on the PC
258
target. Optionally, the MAC address can be changed. If no
259
@option{-net} option is specified, a single NIC is created.
260
Qemu can emulate several different models of network card.  Valid values for
261
@var{type} are @code{ne2k_pci}, @code{ne2k_isa}, @code{rtl8139},
262
@code{smc91c111} and @code{lance}.  Not all devices are supported on all
263
targets.
264

    
265
@item -net user[,vlan=n][,hostname=name]
266
Use the user mode network stack which requires no administrator
267
priviledge to run.  @option{hostname=name} can be used to specify the client
268
hostname reported by the builtin DHCP server.
269

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

    
277
@example
278
qemu linux.img -net nic -net tap
279
@end example
280

    
281
More complicated example (two NICs, each one connected to a TAP device)
282
@example
283
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
284
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
285
@end example
286

    
287

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

    
290
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
291
machine using a TCP socket connection. If @option{listen} is
292
specified, QEMU waits for incoming connections on @var{port}
293
(@var{host} is optional). @option{connect} is used to connect to
294
another QEMU instance using the @option{listen} option. @option{fd=h}
295
specifies an already opened TCP socket.
296

    
297
Example:
298
@example
299
# launch a first QEMU instance
300
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,listen=:1234
301
# connect the VLAN 0 of this instance to the VLAN 0 of the first instance
302
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,connect=127.0.0.1:1234
303
@end example
304

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

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

    
321
Example:
322
@example
323
# launch one QEMU instance
324
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=230.0.0.1:1234
325
# launch another QEMU instance on same "bus"
326
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,mcast=230.0.0.1:1234
327
# launch yet another QEMU instance on same "bus"
328
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 -net socket,mcast=230.0.0.1:1234
329
@end example
330

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

    
339
@item -net none
340
Indicate that no network devices should be configured. It is used to
341
override the default configuration (@option{-net nic -net user}) which
342
is activated if no @option{-net} options are provided.
343

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

    
352
@item -smb dir
353
When using the user mode network stack, activate a built-in SMB
354
server so that Windows OSes can access to the host files in @file{dir}
355
transparently.
356

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

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

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

    
370
@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
371

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

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

    
381
@example
382
# on the host
383
qemu -redir tcp:6001::6000 [...]
384
# this host xterm should open in the guest X11 server
385
xterm -display :1
386
@end example
387

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

    
391
@example
392
# on the host
393
qemu -redir tcp:5555::23 [...]
394
telnet localhost 5555
395
@end example
396

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

    
400
@end table
401

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

    
406
@table @option
407

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

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

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

    
417
@end table
418

    
419
Debug/Expert options:
420
@table @option
421

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

    
448
This option can be used several times to simulate up to 4 serials
449
ports.
450

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

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

    
460
@item -monitor dev
461
Redirect the monitor to host device @var{dev} (same devices as the
462
serial port).
463
The default device is @code{vc} in graphical mode and @code{stdio} in
464
non graphical mode.
465

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

    
481
@item -std-vga
482
Simulate a standard VGA card with Bochs VBE extensions (default is
483
Cirrus Logic GD5446 PCI VGA)
484
@item -loadvm file
485
Start right away with a saved state (@code{loadvm} in monitor)
486
@end table
487

    
488
@c man end
489

    
490
@section Keys
491

    
492
@c man begin OPTIONS
493

    
494
During the graphical emulation, you can use the following keys:
495
@table @key
496
@item Ctrl-Alt-f
497
Toggle full screen
498

    
499
@item Ctrl-Alt-n
500
Switch to virtual console 'n'. Standard console mappings are:
501
@table @emph
502
@item 1
503
Target system display
504
@item 2
505
Monitor
506
@item 3
507
Serial port
508
@end table
509

    
510
@item Ctrl-Alt
511
Toggle mouse and keyboard grab.
512
@end table
513

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

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

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

    
536
@ignore
537

    
538
@setfilename qemu 
539
@settitle QEMU System Emulator
540

    
541
@c man begin SEEALSO
542
The HTML documentation of QEMU for more precise information and Linux
543
user mode emulator invocation.
544
@c man end
545

    
546
@c man begin AUTHOR
547
Fabrice Bellard
548
@c man end
549

    
550
@end ignore
551

    
552
@end ignore
553

    
554
@section QEMU Monitor
555

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

    
559
@itemize @minus
560

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

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

    
569
@item Inspect the VM state without an external debugger.
570

    
571
@end itemize
572

    
573
@subsection Commands
574

    
575
The following commands are available:
576

    
577
@table @option
578

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

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

    
585
@item info subcommand 
586
show various information about the system state
587

    
588
@table @option
589
@item info network
590
show the various VLANs and the associated devices
591
@item info block
592
show the block devices
593
@item info registers
594
show the cpu registers
595
@item info history
596
show the command line history
597
@item info pci
598
show emulated PCI device
599
@item info usb
600
show USB devices plugged on the virtual USB hub
601
@item info usbhost
602
show all USB host devices
603
@end table
604

    
605
@item q or quit
606
Quit the emulator.
607

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

    
611
@item change device filename
612
Change a removable media.
613

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

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

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

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

    
626
@item stop
627
Stop emulation.
628

    
629
@item c or cont
630
Resume emulation.
631

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

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

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

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

    
644
@table @var
645
@item count 
646
is the number of items to be dumped.
647

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

    
652
@item size
653
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
654
@code{h} or @code{w} can be specified with the @code{i} format to
655
respectively select 16 or 32 bit code instruction size.
656

    
657
@end table
658

    
659
Examples: 
660
@itemize
661
@item
662
Dump 10 instructions at the current instruction pointer:
663
@example 
664
(qemu) x/10i $eip
665
0x90107063:  ret
666
0x90107064:  sti
667
0x90107065:  lea    0x0(%esi,1),%esi
668
0x90107069:  lea    0x0(%edi,1),%edi
669
0x90107070:  ret
670
0x90107071:  jmp    0x90107080
671
0x90107073:  nop
672
0x90107074:  nop
673
0x90107075:  nop
674
0x90107076:  nop
675
@end example
676

    
677
@item
678
Dump 80 16 bit values at the start of the video memory.
679
@example 
680
(qemu) xp/80hx 0xb8000
681
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
682
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
683
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
684
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
685
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
686
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
687
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
688
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
689
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
690
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
691
@end example
692
@end itemize
693

    
694
@item p or print/fmt expr
695

    
696
Print expression value. Only the @var{format} part of @var{fmt} is
697
used.
698

    
699
@item sendkey keys
700

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

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

    
710
@item system_reset
711

    
712
Reset the system.
713

    
714
@item usb_add devname
715

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

    
721
@item usb_del devname
722

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

    
727
@end table
728

    
729
@subsection Integer expressions
730

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

    
735
@node disk_images
736
@section Disk Images
737

    
738
Since version 0.6.1, QEMU supports many disk image formats, including
739
growable disk images (their size increase as non empty sectors are
740
written), compressed and encrypted disk images.
741

    
742
@subsection Quick start for disk image creation
743

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

    
752
@xref{qemu_img_invocation} for more information.
753

    
754
@subsection Snapshot mode
755

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

    
762
@node qemu_img_invocation
763
@subsection @code{qemu-img} Invocation
764

    
765
@include qemu-img.texi
766

    
767
@subsection Virtual FAT disk images
768

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

    
772
@example 
773
qemu linux.img -hdb fat:/my_directory
774
@end example
775

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

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

    
782
@example 
783
qemu linux.img -fda fat:floppy:/my_directory
784
@end example
785

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

    
789
@example 
790
qemu linux.img -fda fat:floppy:rw:/my_directory
791
@end example
792

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

    
801
@section Network emulation
802

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

    
811
@subsection VLANs
812

    
813
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
814
connection between several network devices. These devices can be for
815
example QEMU virtual Ethernet cards or virtual Host ethernet devices
816
(TAP devices).
817

    
818
@subsection Using TAP network interfaces
819

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

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

    
831
See @ref{direct_linux_boot} to have an example of network use with a
832
Linux distribution and @ref{sec_invocation} to have examples of
833
command lines using the TAP network interfaces.
834

    
835
@subsection Using the user mode network stack
836

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

    
842
@example
843

    
844
         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
845
                           |          (10.0.2.2)
846
                           |
847
                           ---->  DNS server (10.0.2.3)
848
                           |     
849
                           ---->  SMB server (10.0.2.4)
850
@end example
851

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

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

    
861
Note that @code{ping} is not supported reliably to the internet as it
862
would require root priviledges. It means you can only ping the local
863
router (10.0.2.2).
864

    
865
When using the built-in TFTP server, the router is also the TFTP
866
server.
867

    
868
When using the @option{-redir} option, TCP or UDP connections can be
869
redirected from the host to the guest. It allows for example to
870
redirect X11, telnet or SSH connections.
871

    
872
@subsection Connecting VLANs between QEMU instances
873

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

    
878
@node direct_linux_boot
879
@section Direct Linux Boot
880

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

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

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

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

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

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

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

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

    
990
Then enable X11 connections on your PC from the emulated Linux: 
991
@example
992
xhost +172.20.0.2
993
@end example
994

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

    
998
@end enumerate
999

    
1000
NOTES:
1001
@enumerate
1002
@item 
1003
A 2.5.74 kernel is also included in the archive. Just
1004
replace the bzImage in qemu.sh to try it.
1005

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

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

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

    
1022
@end enumerate
1023

    
1024
@section USB emulation
1025

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

    
1030
@subsection Using virtual USB devices
1031

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

    
1034
You can try it with the following monitor commands:
1035

    
1036
@example
1037
# add the mouse device
1038
(qemu) usb_add mouse 
1039

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

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

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

    
1051
@subsection Using host USB devices on a Linux host
1052

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

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

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

    
1069
@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:
1070
@example
1071
chown -R myuid /proc/bus/usb
1072
@end example
1073

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

    
1083
@item Add the device in QEMU by using:
1084
@example 
1085
usb_add host:1234:5678
1086
@end example
1087

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

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

    
1093
@end enumerate
1094

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

    
1098
@node gdb_usage
1099
@section GDB usage
1100

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

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

    
1112
Then launch gdb on the 'vmlinux' executable:
1113
@example
1114
> gdb vmlinux
1115
@end example
1116

    
1117
In gdb, connect to QEMU:
1118
@example
1119
(gdb) target remote localhost:1234
1120
@end example
1121

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

    
1127
Here are some useful tips in order to use gdb on system code:
1128

    
1129
@enumerate
1130
@item
1131
Use @code{info reg} to display all the CPU registers.
1132
@item
1133
Use @code{x/10i $eip} to display the code at the PC position.
1134
@item
1135
Use @code{set architecture i8086} to dump 16 bit code. Then use
1136
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
1137
@end enumerate
1138

    
1139
@section Target OS specific information
1140

    
1141
@subsection Linux
1142

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

    
1147
When using a 2.6 guest Linux kernel, you should add the option
1148
@code{clock=pit} on the kernel command line because the 2.6 Linux
1149
kernels make very strict real time clock checks by default that QEMU
1150
cannot simulate exactly.
1151

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

    
1158
@subsection Windows
1159

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

    
1163
@subsubsection SVGA graphic modes support
1164

    
1165
QEMU emulates a Cirrus Logic GD5446 Video
1166
card. All Windows versions starting from Windows 95 should recognize
1167
and use this graphic card. For optimal performances, use 16 bit color
1168
depth in the guest and the host OS.
1169

    
1170
@subsubsection CPU usage reduction
1171

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

    
1178
@subsubsection Windows 2000 disk full problem
1179

    
1180
Windows 2000 has a bug which gives a disk full problem during its
1181
installation. When installing it, use the @option{-win2k-hack} QEMU
1182
option to enable a specific workaround. After Windows 2000 is
1183
installed, you no longer need this option (this option slows down the
1184
IDE transfers).
1185

    
1186
@subsubsection Windows 2000 shutdown
1187

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

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

    
1199
@subsubsection Share a directory between Unix and Windows
1200

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

    
1203
@subsubsection Windows XP security problems
1204

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

    
1214
Future QEMU releases are likely to correct this bug.
1215

    
1216
@subsection MS-DOS and FreeDOS
1217

    
1218
@subsubsection CPU usage reduction
1219

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

    
1225
@chapter QEMU System emulator for non PC targets
1226

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

    
1231
@section QEMU PowerPC System emulator
1232

    
1233
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1234
or PowerMac PowerPC system.
1235

    
1236
QEMU emulates the following PowerMac peripherals:
1237

    
1238
@itemize @minus
1239
@item 
1240
UniNorth PCI Bridge 
1241
@item
1242
PCI VGA compatible card with VESA Bochs Extensions
1243
@item 
1244
2 PMAC IDE interfaces with hard disk and CD-ROM support
1245
@item 
1246
NE2000 PCI adapters
1247
@item
1248
Non Volatile RAM
1249
@item
1250
VIA-CUDA with ADB keyboard and mouse.
1251
@end itemize
1252

    
1253
QEMU emulates the following PREP peripherals:
1254

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

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

    
1277
@c man begin OPTIONS
1278

    
1279
The following options are specific to the PowerPC emulation:
1280

    
1281
@table @option
1282

    
1283
@item -g WxH[xDEPTH]  
1284

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

    
1287
@end table
1288

    
1289
@c man end 
1290

    
1291

    
1292
More information is available at
1293
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1294

    
1295
@section Sparc32 System emulator invocation
1296

    
1297
Use the executable @file{qemu-system-sparc} to simulate a JavaStation
1298
(sun4m architecture). The emulation is somewhat complete.
1299

    
1300
QEMU emulates the following sun4m peripherals:
1301

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

    
1320
The number of peripherals is fixed in the architecture.
1321

    
1322
QEMU uses the Proll, a PROM replacement available at
1323
@url{http://people.redhat.com/zaitcev/linux/}. The required
1324
QEMU-specific patches are included with the sources.
1325

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

    
1330
@c man begin OPTIONS
1331

    
1332
The following options are specific to the Sparc emulation:
1333

    
1334
@table @option
1335

    
1336
@item -g WxH
1337

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

    
1340
@end table
1341

    
1342
@c man end 
1343

    
1344
@section Sparc64 System emulator invocation
1345

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

    
1349
QEMU emulates the following sun4u peripherals:
1350

    
1351
@itemize @minus
1352
@item
1353
UltraSparc IIi APB PCI Bridge 
1354
@item
1355
PCI VGA compatible card with VESA Bochs Extensions
1356
@item
1357
Non Volatile RAM M48T59
1358
@item
1359
PC-compatible serial ports
1360
@end itemize
1361

    
1362
@section MIPS System emulator invocation
1363

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

    
1368
@itemize @minus
1369
@item 
1370
MIPS R4K CPU
1371
@item
1372
PC style serial port
1373
@item
1374
NE2000 network card
1375
@end itemize
1376

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

    
1379
@section ARM System emulator invocation
1380

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

    
1385
@itemize @minus
1386
@item
1387
ARM926E or ARM1026E CPU
1388
@item
1389
Two PL011 UARTs
1390
@item 
1391
SMC 91c111 Ethernet adapter
1392
@end itemize
1393

    
1394
A Linux 2.6 test image is available on the QEMU web site. More
1395
information is available in the QEMU mailing-list archive.
1396

    
1397
@chapter QEMU Linux User space emulator 
1398

    
1399
@section Quick Start
1400

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

    
1404
@itemize
1405

    
1406
@item On x86, you can just try to launch any process by using the native
1407
libraries:
1408

    
1409
@example 
1410
qemu-i386 -L / /bin/ls
1411
@end example
1412

    
1413
@code{-L /} tells that the x86 dynamic linker must be searched with a
1414
@file{/} prefix.
1415

    
1416
@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):
1417

    
1418
@example 
1419
qemu-i386 -L / qemu-i386 -L / /bin/ls
1420
@end example
1421

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

    
1426
@example
1427
unset LD_LIBRARY_PATH 
1428
@end example
1429

    
1430
Then you can launch the precompiled @file{ls} x86 executable:
1431

    
1432
@example
1433
qemu-i386 tests/i386/ls
1434
@end example
1435
You can look at @file{qemu-binfmt-conf.sh} so that
1436
QEMU is automatically launched by the Linux kernel when you try to
1437
launch x86 executables. It requires the @code{binfmt_misc} module in the
1438
Linux kernel.
1439

    
1440
@item The x86 version of QEMU is also included. You can try weird things such as:
1441
@example
1442
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1443
@end example
1444

    
1445
@end itemize
1446

    
1447
@section Wine launch
1448

    
1449
@itemize
1450

    
1451
@item Ensure that you have a working QEMU with the x86 glibc
1452
distribution (see previous section). In order to verify it, you must be
1453
able to do:
1454

    
1455
@example
1456
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1457
@end example
1458

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

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

    
1466
@item Then you can try the example @file{putty.exe}:
1467

    
1468
@example
1469
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1470
@end example
1471

    
1472
@end itemize
1473

    
1474
@section Command line options
1475

    
1476
@example
1477
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1478
@end example
1479

    
1480
@table @option
1481
@item -h
1482
Print the help
1483
@item -L path   
1484
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1485
@item -s size
1486
Set the x86 stack size in bytes (default=524288)
1487
@end table
1488

    
1489
Debug options:
1490

    
1491
@table @option
1492
@item -d
1493
Activate log (logfile=/tmp/qemu.log)
1494
@item -p pagesize
1495
Act as if the host page size was 'pagesize' bytes
1496
@end table
1497

    
1498
@node compilation
1499
@chapter Compilation from the sources
1500

    
1501
@section Linux/Unix
1502

    
1503
@subsection Compilation
1504

    
1505
First you must decompress the sources:
1506
@example
1507
cd /tmp
1508
tar zxvf qemu-x.y.z.tar.gz
1509
cd qemu-x.y.z
1510
@end example
1511

    
1512
Then you configure QEMU and build it (usually no options are needed):
1513
@example
1514
./configure
1515
make
1516
@end example
1517

    
1518
Then type as root user:
1519
@example
1520
make install
1521
@end example
1522
to install QEMU in @file{/usr/local}.
1523

    
1524
@subsection Tested tool versions
1525

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

    
1532
@example
1533
host      gcc      binutils      glibc    linux       distribution
1534
----------------------------------------------------------------------
1535
x86       3.2      2.13.2        2.1.3    2.4.18
1536
          2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
1537
          3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
1538

    
1539
PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
1540
          3.2
1541

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

    
1544
Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
1545

    
1546
ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
1547

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

    
1554
[4] gcc 2.95.x generates invalid code when using too many register
1555
variables. You must use gcc 3.x on PowerPC.
1556
@end example
1557

    
1558
@section Windows
1559

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

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

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

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

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

    
1585
@end itemize
1586

    
1587
@section Cross compilation for Windows with Linux
1588

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

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

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

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

    
1613
@end itemize
1614

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

    
1618
@section Mac OS X
1619

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