Statistics
| Branch: | Revision:

root / qemu-doc.texi @ d7e5edca

History | View | Annotate | Download (68.6 kB)

1
\input texinfo @c -*- texinfo -*-
2
@c %**start of header
3
@setfilename qemu-doc.info
4

    
5
@documentlanguage en
6
@documentencoding UTF-8
7

    
8
@settitle QEMU Emulator User Documentation
9
@exampleindent 0
10
@paragraphindent 0
11
@c %**end of header
12

    
13
@ifinfo
14
@direntry
15
* QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
16
@end direntry
17
@end ifinfo
18

    
19
@iftex
20
@titlepage
21
@sp 7
22
@center @titlefont{QEMU Emulator}
23
@sp 1
24
@center @titlefont{User Documentation}
25
@sp 3
26
@end titlepage
27
@end iftex
28

    
29
@ifnottex
30
@node Top
31
@top
32

    
33
@menu
34
* Introduction::
35
* Installation::
36
* QEMU PC System emulator::
37
* QEMU System emulator for non PC targets::
38
* QEMU User space emulator::
39
* compilation:: Compilation from the sources
40
* Index::
41
@end menu
42
@end ifnottex
43

    
44
@contents
45

    
46
@node Introduction
47
@chapter Introduction
48

    
49
@menu
50
* intro_features:: Features
51
@end menu
52

    
53
@node intro_features
54
@section Features
55

    
56
QEMU is a FAST! processor emulator using dynamic translation to
57
achieve good emulation speed.
58

    
59
QEMU has two operating modes:
60

    
61
@itemize
62

    
63
@item
64
Full system emulation. In this mode, QEMU emulates a full system (for
65
example a PC), including one or several processors and various
66
peripherals. It can be used to launch different Operating Systems
67
without rebooting the PC or to debug system code.
68

    
69
@item
70
User mode emulation. In this mode, QEMU can launch
71
processes compiled for one CPU on another CPU. It can be used to
72
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
73
to ease cross-compilation and cross-debugging.
74

    
75
@end itemize
76

    
77
QEMU can run without an host kernel driver and yet gives acceptable
78
performance.
79

    
80
For system emulation, the following hardware targets are supported:
81
@itemize
82
@item PC (x86 or x86_64 processor)
83
@item ISA PC (old style PC without PCI bus)
84
@item PREP (PowerPC processor)
85
@item G3 Beige PowerMac (PowerPC processor)
86
@item Mac99 PowerMac (PowerPC processor, in progress)
87
@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
88
@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
89
@item Malta board (32-bit and 64-bit MIPS processors)
90
@item MIPS Magnum (64-bit MIPS processor)
91
@item ARM Integrator/CP (ARM)
92
@item ARM Versatile baseboard (ARM)
93
@item ARM RealView Emulation/Platform baseboard (ARM)
94
@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
95
@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
96
@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
97
@item Freescale MCF5208EVB (ColdFire V2).
98
@item Arnewsh MCF5206 evaluation board (ColdFire V2).
99
@item Palm Tungsten|E PDA (OMAP310 processor)
100
@item N800 and N810 tablets (OMAP2420 processor)
101
@item MusicPal (MV88W8618 ARM processor)
102
@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
103
@item Siemens SX1 smartphone (OMAP310 processor)
104
@item Syborg SVP base model (ARM Cortex-A8).
105
@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
106
@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
107
@end itemize
108

    
109
For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
110

    
111
@node Installation
112
@chapter Installation
113

    
114
If you want to compile QEMU yourself, see @ref{compilation}.
115

    
116
@menu
117
* install_linux::   Linux
118
* install_windows:: Windows
119
* install_mac::     Macintosh
120
@end menu
121

    
122
@node install_linux
123
@section Linux
124

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

    
128
@node install_windows
129
@section Windows
130

    
131
Download the experimental binary installer at
132
@url{http://www.free.oszoo.org/@/download.html}.
133

    
134
@node install_mac
135
@section Mac OS X
136

    
137
Download the experimental binary installer at
138
@url{http://www.free.oszoo.org/@/download.html}.
139

    
140
@node QEMU PC System emulator
141
@chapter QEMU PC System emulator
142

    
143
@menu
144
* pcsys_introduction:: Introduction
145
* pcsys_quickstart::   Quick Start
146
* sec_invocation::     Invocation
147
* pcsys_keys::         Keys
148
* pcsys_monitor::      QEMU Monitor
149
* disk_images::        Disk Images
150
* pcsys_network::      Network emulation
151
* direct_linux_boot::  Direct Linux Boot
152
* pcsys_usb::          USB emulation
153
* vnc_security::       VNC security
154
* gdb_usage::          GDB usage
155
* pcsys_os_specific::  Target OS specific information
156
@end menu
157

    
158
@node pcsys_introduction
159
@section Introduction
160

    
161
@c man begin DESCRIPTION
162

    
163
The QEMU PC System emulator simulates the
164
following peripherals:
165

    
166
@itemize @minus
167
@item
168
i440FX host PCI bridge and PIIX3 PCI to ISA bridge
169
@item
170
Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
171
extensions (hardware level, including all non standard modes).
172
@item
173
PS/2 mouse and keyboard
174
@item
175
2 PCI IDE interfaces with hard disk and CD-ROM support
176
@item
177
Floppy disk
178
@item
179
PCI and ISA network adapters
180
@item
181
Serial ports
182
@item
183
Creative SoundBlaster 16 sound card
184
@item
185
ENSONIQ AudioPCI ES1370 sound card
186
@item
187
Intel 82801AA AC97 Audio compatible sound card
188
@item
189
Adlib(OPL2) - Yamaha YM3812 compatible chip
190
@item
191
Gravis Ultrasound GF1 sound card
192
@item
193
CS4231A compatible sound card
194
@item
195
PCI UHCI USB controller and a virtual USB hub.
196
@end itemize
197

    
198
SMP is supported with up to 255 CPUs.
199

    
200
Note that adlib, gus and cs4231a are only available when QEMU was
201
configured with --audio-card-list option containing the name(s) of
202
required card(s).
203

    
204
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
205
VGA BIOS.
206

    
207
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
208

    
209
QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
210
by Tibor "TS" Schütz.
211

    
212
Not that, by default, GUS shares IRQ(7) with parallel ports and so
213
qemu must be told to not have parallel ports to have working GUS
214

    
215
@example
216
qemu dos.img -soundhw gus -parallel none
217
@end example
218

    
219
Alternatively:
220
@example
221
qemu dos.img -device gus,irq=5
222
@end example
223

    
224
Or some other unclaimed IRQ.
225

    
226
CS4231A is the chip used in Windows Sound System and GUSMAX products
227

    
228
@c man end
229

    
230
@node pcsys_quickstart
231
@section Quick Start
232

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

    
235
@example
236
qemu linux.img
237
@end example
238

    
239
Linux should boot and give you a prompt.
240

    
241
@node sec_invocation
242
@section Invocation
243

    
244
@example
245
@c man begin SYNOPSIS
246
usage: qemu [options] [@var{disk_image}]
247
@c man end
248
@end example
249

    
250
@c man begin OPTIONS
251
@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
252
targets do not need a disk image.
253

    
254
@include qemu-options.texi
255

    
256
@c man end
257

    
258
@node pcsys_keys
259
@section Keys
260

    
261
@c man begin OPTIONS
262

    
263
During the graphical emulation, you can use the following keys:
264
@table @key
265
@item Ctrl-Alt-f
266
Toggle full screen
267

    
268
@item Ctrl-Alt-u
269
Restore the screen's un-scaled dimensions
270

    
271
@item Ctrl-Alt-n
272
Switch to virtual console 'n'. Standard console mappings are:
273
@table @emph
274
@item 1
275
Target system display
276
@item 2
277
Monitor
278
@item 3
279
Serial port
280
@end table
281

    
282
@item Ctrl-Alt
283
Toggle mouse and keyboard grab.
284
@end table
285

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

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

    
292
@table @key
293
@item Ctrl-a h
294
@item Ctrl-a ?
295
Print this help
296
@item Ctrl-a x
297
Exit emulator
298
@item Ctrl-a s
299
Save disk data back to file (if -snapshot)
300
@item Ctrl-a t
301
Toggle console timestamps
302
@item Ctrl-a b
303
Send break (magic sysrq in Linux)
304
@item Ctrl-a c
305
Switch between console and monitor
306
@item Ctrl-a Ctrl-a
307
Send Ctrl-a
308
@end table
309
@c man end
310

    
311
@ignore
312

    
313
@c man begin SEEALSO
314
The HTML documentation of QEMU for more precise information and Linux
315
user mode emulator invocation.
316
@c man end
317

    
318
@c man begin AUTHOR
319
Fabrice Bellard
320
@c man end
321

    
322
@end ignore
323

    
324
@node pcsys_monitor
325
@section QEMU Monitor
326

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

    
330
@itemize @minus
331

    
332
@item
333
Remove or insert removable media images
334
(such as CD-ROM or floppies).
335

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

    
340
@item Inspect the VM state without an external debugger.
341

    
342
@end itemize
343

    
344
@subsection Commands
345

    
346
The following commands are available:
347

    
348
@include qemu-monitor.texi
349

    
350
@subsection Integer expressions
351

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

    
356
@node disk_images
357
@section Disk Images
358

    
359
Since version 0.6.1, QEMU supports many disk image formats, including
360
growable disk images (their size increase as non empty sectors are
361
written), compressed and encrypted disk images. Version 0.8.3 added
362
the new qcow2 disk image format which is essential to support VM
363
snapshots.
364

    
365
@menu
366
* disk_images_quickstart::    Quick start for disk image creation
367
* disk_images_snapshot_mode:: Snapshot mode
368
* vm_snapshots::              VM snapshots
369
* qemu_img_invocation::       qemu-img Invocation
370
* qemu_nbd_invocation::       qemu-nbd Invocation
371
* host_drives::               Using host drives
372
* disk_images_fat_images::    Virtual FAT disk images
373
* disk_images_nbd::           NBD access
374
@end menu
375

    
376
@node disk_images_quickstart
377
@subsection Quick start for disk image creation
378

    
379
You can create a disk image with the command:
380
@example
381
qemu-img create myimage.img mysize
382
@end example
383
where @var{myimage.img} is the disk image filename and @var{mysize} is its
384
size in kilobytes. You can add an @code{M} suffix to give the size in
385
megabytes and a @code{G} suffix for gigabytes.
386

    
387
See @ref{qemu_img_invocation} for more information.
388

    
389
@node disk_images_snapshot_mode
390
@subsection Snapshot mode
391

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

    
398
@node vm_snapshots
399
@subsection VM snapshots
400

    
401
VM snapshots are snapshots of the complete virtual machine including
402
CPU state, RAM, device state and the content of all the writable
403
disks. In order to use VM snapshots, you must have at least one non
404
removable and writable block device using the @code{qcow2} disk image
405
format. Normally this device is the first virtual hard drive.
406

    
407
Use the monitor command @code{savevm} to create a new VM snapshot or
408
replace an existing one. A human readable name can be assigned to each
409
snapshot in addition to its numerical ID.
410

    
411
Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
412
a VM snapshot. @code{info snapshots} lists the available snapshots
413
with their associated information:
414

    
415
@example
416
(qemu) info snapshots
417
Snapshot devices: hda
418
Snapshot list (from hda):
419
ID        TAG                 VM SIZE                DATE       VM CLOCK
420
1         start                   41M 2006-08-06 12:38:02   00:00:14.954
421
2                                 40M 2006-08-06 12:43:29   00:00:18.633
422
3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
423
@end example
424

    
425
A VM snapshot is made of a VM state info (its size is shown in
426
@code{info snapshots}) and a snapshot of every writable disk image.
427
The VM state info is stored in the first @code{qcow2} non removable
428
and writable block device. The disk image snapshots are stored in
429
every disk image. The size of a snapshot in a disk image is difficult
430
to evaluate and is not shown by @code{info snapshots} because the
431
associated disk sectors are shared among all the snapshots to save
432
disk space (otherwise each snapshot would need a full copy of all the
433
disk images).
434

    
435
When using the (unrelated) @code{-snapshot} option
436
(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
437
but they are deleted as soon as you exit QEMU.
438

    
439
VM snapshots currently have the following known limitations:
440
@itemize
441
@item
442
They cannot cope with removable devices if they are removed or
443
inserted after a snapshot is done.
444
@item
445
A few device drivers still have incomplete snapshot support so their
446
state is not saved or restored properly (in particular USB).
447
@end itemize
448

    
449
@node qemu_img_invocation
450
@subsection @code{qemu-img} Invocation
451

    
452
@include qemu-img.texi
453

    
454
@node qemu_nbd_invocation
455
@subsection @code{qemu-nbd} Invocation
456

    
457
@include qemu-nbd.texi
458

    
459
@node host_drives
460
@subsection Using host drives
461

    
462
In addition to disk image files, QEMU can directly access host
463
devices. We describe here the usage for QEMU version >= 0.8.3.
464

    
465
@subsubsection Linux
466

    
467
On Linux, you can directly use the host device filename instead of a
468
disk image filename provided you have enough privileges to access
469
it. For example, use @file{/dev/cdrom} to access to the CDROM or
470
@file{/dev/fd0} for the floppy.
471

    
472
@table @code
473
@item CD
474
You can specify a CDROM device even if no CDROM is loaded. QEMU has
475
specific code to detect CDROM insertion or removal. CDROM ejection by
476
the guest OS is supported. Currently only data CDs are supported.
477
@item Floppy
478
You can specify a floppy device even if no floppy is loaded. Floppy
479
removal is currently not detected accurately (if you change floppy
480
without doing floppy access while the floppy is not loaded, the guest
481
OS will think that the same floppy is loaded).
482
@item Hard disks
483
Hard disks can be used. Normally you must specify the whole disk
484
(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
485
see it as a partitioned disk. WARNING: unless you know what you do, it
486
is better to only make READ-ONLY accesses to the hard disk otherwise
487
you may corrupt your host data (use the @option{-snapshot} command
488
line option or modify the device permissions accordingly).
489
@end table
490

    
491
@subsubsection Windows
492

    
493
@table @code
494
@item CD
495
The preferred syntax is the drive letter (e.g. @file{d:}). The
496
alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
497
supported as an alias to the first CDROM drive.
498

    
499
Currently there is no specific code to handle removable media, so it
500
is better to use the @code{change} or @code{eject} monitor commands to
501
change or eject media.
502
@item Hard disks
503
Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
504
where @var{N} is the drive number (0 is the first hard disk).
505

    
506
WARNING: unless you know what you do, it is better to only make
507
READ-ONLY accesses to the hard disk otherwise you may corrupt your
508
host data (use the @option{-snapshot} command line so that the
509
modifications are written in a temporary file).
510
@end table
511

    
512

    
513
@subsubsection Mac OS X
514

    
515
@file{/dev/cdrom} is an alias to the first CDROM.
516

    
517
Currently there is no specific code to handle removable media, so it
518
is better to use the @code{change} or @code{eject} monitor commands to
519
change or eject media.
520

    
521
@node disk_images_fat_images
522
@subsection Virtual FAT disk images
523

    
524
QEMU can automatically create a virtual FAT disk image from a
525
directory tree. In order to use it, just type:
526

    
527
@example
528
qemu linux.img -hdb fat:/my_directory
529
@end example
530

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

    
535
Floppies can be emulated with the @code{:floppy:} option:
536

    
537
@example
538
qemu linux.img -fda fat:floppy:/my_directory
539
@end example
540

    
541
A read/write support is available for testing (beta stage) with the
542
@code{:rw:} option:
543

    
544
@example
545
qemu linux.img -fda fat:floppy:rw:/my_directory
546
@end example
547

    
548
What you should @emph{never} do:
549
@itemize
550
@item use non-ASCII filenames ;
551
@item use "-snapshot" together with ":rw:" ;
552
@item expect it to work when loadvm'ing ;
553
@item write to the FAT directory on the host system while accessing it with the guest system.
554
@end itemize
555

    
556
@node disk_images_nbd
557
@subsection NBD access
558

    
559
QEMU can access directly to block device exported using the Network Block Device
560
protocol.
561

    
562
@example
563
qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
564
@end example
565

    
566
If the NBD server is located on the same host, you can use an unix socket instead
567
of an inet socket:
568

    
569
@example
570
qemu linux.img -hdb nbd:unix:/tmp/my_socket
571
@end example
572

    
573
In this case, the block device must be exported using qemu-nbd:
574

    
575
@example
576
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
577
@end example
578

    
579
The use of qemu-nbd allows to share a disk between several guests:
580
@example
581
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
582
@end example
583

    
584
and then you can use it with two guests:
585
@example
586
qemu linux1.img -hdb nbd:unix:/tmp/my_socket
587
qemu linux2.img -hdb nbd:unix:/tmp/my_socket
588
@end example
589

    
590
@node pcsys_network
591
@section Network emulation
592

    
593
QEMU can simulate several network cards (PCI or ISA cards on the PC
594
target) and can connect them to an arbitrary number of Virtual Local
595
Area Networks (VLANs). Host TAP devices can be connected to any QEMU
596
VLAN. VLAN can be connected between separate instances of QEMU to
597
simulate large networks. For simpler usage, a non privileged user mode
598
network stack can replace the TAP device to have a basic network
599
connection.
600

    
601
@subsection VLANs
602

    
603
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
604
connection between several network devices. These devices can be for
605
example QEMU virtual Ethernet cards or virtual Host ethernet devices
606
(TAP devices).
607

    
608
@subsection Using TAP network interfaces
609

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

    
614
@subsubsection Linux host
615

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

    
623
See @ref{sec_invocation} to have examples of command lines using the
624
TAP network interfaces.
625

    
626
@subsubsection Windows host
627

    
628
There is a virtual ethernet driver for Windows 2000/XP systems, called
629
TAP-Win32. But it is not included in standard QEMU for Windows,
630
so you will need to get it separately. It is part of OpenVPN package,
631
so download OpenVPN from : @url{http://openvpn.net/}.
632

    
633
@subsection Using the user mode network stack
634

    
635
By using the option @option{-net user} (default configuration if no
636
@option{-net} option is specified), QEMU uses a completely user mode
637
network stack (you don't need root privilege to use the virtual
638
network). The virtual network configuration is the following:
639

    
640
@example
641

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

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

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

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

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

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

    
670
@subsection Connecting VLANs between QEMU instances
671

    
672
Using the @option{-net socket} option, it is possible to make VLANs
673
that span several QEMU instances. See @ref{sec_invocation} to have a
674
basic example.
675

    
676
@node direct_linux_boot
677
@section Direct Linux Boot
678

    
679
This section explains how to launch a Linux kernel inside QEMU without
680
having to make a full bootable image. It is very useful for fast Linux
681
kernel testing.
682

    
683
The syntax is:
684
@example
685
qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
686
@end example
687

    
688
Use @option{-kernel} to provide the Linux kernel image and
689
@option{-append} to give the kernel command line arguments. The
690
@option{-initrd} option can be used to provide an INITRD image.
691

    
692
When using the direct Linux boot, a disk image for the first hard disk
693
@file{hda} is required because its boot sector is used to launch the
694
Linux kernel.
695

    
696
If you do not need graphical output, you can disable it and redirect
697
the virtual serial port and the QEMU monitor to the console with the
698
@option{-nographic} option. The typical command line is:
699
@example
700
qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
701
     -append "root=/dev/hda console=ttyS0" -nographic
702
@end example
703

    
704
Use @key{Ctrl-a c} to switch between the serial console and the
705
monitor (@pxref{pcsys_keys}).
706

    
707
@node pcsys_usb
708
@section USB emulation
709

    
710
QEMU emulates a PCI UHCI USB controller. You can virtually plug
711
virtual USB devices or real host USB devices (experimental, works only
712
on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
713
as necessary to connect multiple USB devices.
714

    
715
@menu
716
* usb_devices::
717
* host_usb_devices::
718
@end menu
719
@node usb_devices
720
@subsection Connecting USB devices
721

    
722
USB devices can be connected with the @option{-usbdevice} commandline option
723
or the @code{usb_add} monitor command.  Available devices are:
724

    
725
@table @code
726
@item mouse
727
Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
728
@item tablet
729
Pointer device that uses absolute coordinates (like a touchscreen).
730
This means qemu is able to report the mouse position without having
731
to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
732
@item disk:@var{file}
733
Mass storage device based on @var{file} (@pxref{disk_images})
734
@item host:@var{bus.addr}
735
Pass through the host device identified by @var{bus.addr}
736
(Linux only)
737
@item host:@var{vendor_id:product_id}
738
Pass through the host device identified by @var{vendor_id:product_id}
739
(Linux only)
740
@item wacom-tablet
741
Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
742
above but it can be used with the tslib library because in addition to touch
743
coordinates it reports touch pressure.
744
@item keyboard
745
Standard USB keyboard.  Will override the PS/2 keyboard (if present).
746
@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
747
Serial converter. This emulates an FTDI FT232BM chip connected to host character
748
device @var{dev}. The available character devices are the same as for the
749
@code{-serial} option. The @code{vendorid} and @code{productid} options can be
750
used to override the default 0403:6001. For instance, 
751
@example
752
usb_add serial:productid=FA00:tcp:192.168.0.2:4444
753
@end example
754
will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
755
serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
756
@item braille
757
Braille device.  This will use BrlAPI to display the braille output on a real
758
or fake device.
759
@item net:@var{options}
760
Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
761
specifies NIC options as with @code{-net nic,}@var{options} (see description).
762
For instance, user-mode networking can be used with
763
@example
764
qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
765
@end example
766
Currently this cannot be used in machines that support PCI NICs.
767
@item bt[:@var{hci-type}]
768
Bluetooth dongle whose type is specified in the same format as with
769
the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
770
no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
771
This USB device implements the USB Transport Layer of HCI.  Example
772
usage:
773
@example
774
qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
775
@end example
776
@end table
777

    
778
@node host_usb_devices
779
@subsection Using host USB devices on a Linux host
780

    
781
WARNING: this is an experimental feature. QEMU will slow down when
782
using it. USB devices requiring real time streaming (i.e. USB Video
783
Cameras) are not supported yet.
784

    
785
@enumerate
786
@item If you use an early Linux 2.4 kernel, verify that no Linux driver
787
is actually using the USB device. A simple way to do that is simply to
788
disable the corresponding kernel module by renaming it from @file{mydriver.o}
789
to @file{mydriver.o.disabled}.
790

    
791
@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
792
@example
793
ls /proc/bus/usb
794
001  devices  drivers
795
@end example
796

    
797
@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:
798
@example
799
chown -R myuid /proc/bus/usb
800
@end example
801

    
802
@item Launch QEMU and do in the monitor:
803
@example
804
info usbhost
805
  Device 1.2, speed 480 Mb/s
806
    Class 00: USB device 1234:5678, USB DISK
807
@end example
808
You should see the list of the devices you can use (Never try to use
809
hubs, it won't work).
810

    
811
@item Add the device in QEMU by using:
812
@example
813
usb_add host:1234:5678
814
@end example
815

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

    
819
@item Now you can try to use the host USB device in QEMU.
820

    
821
@end enumerate
822

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

    
826
@node vnc_security
827
@section VNC security
828

    
829
The VNC server capability provides access to the graphical console
830
of the guest VM across the network. This has a number of security
831
considerations depending on the deployment scenarios.
832

    
833
@menu
834
* vnc_sec_none::
835
* vnc_sec_password::
836
* vnc_sec_certificate::
837
* vnc_sec_certificate_verify::
838
* vnc_sec_certificate_pw::
839
* vnc_sec_sasl::
840
* vnc_sec_certificate_sasl::
841
* vnc_generate_cert::
842
* vnc_setup_sasl::
843
@end menu
844
@node vnc_sec_none
845
@subsection Without passwords
846

    
847
The simplest VNC server setup does not include any form of authentication.
848
For this setup it is recommended to restrict it to listen on a UNIX domain
849
socket only. For example
850

    
851
@example
852
qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
853
@end example
854

    
855
This ensures that only users on local box with read/write access to that
856
path can access the VNC server. To securely access the VNC server from a
857
remote machine, a combination of netcat+ssh can be used to provide a secure
858
tunnel.
859

    
860
@node vnc_sec_password
861
@subsection With passwords
862

    
863
The VNC protocol has limited support for password based authentication. Since
864
the protocol limits passwords to 8 characters it should not be considered
865
to provide high security. The password can be fairly easily brute-forced by
866
a client making repeat connections. For this reason, a VNC server using password
867
authentication should be restricted to only listen on the loopback interface
868
or UNIX domain sockets. Password authentication is requested with the @code{password}
869
option, and then once QEMU is running the password is set with the monitor. Until
870
the monitor is used to set the password all clients will be rejected.
871

    
872
@example
873
qemu [...OPTIONS...] -vnc :1,password -monitor stdio
874
(qemu) change vnc password
875
Password: ********
876
(qemu)
877
@end example
878

    
879
@node vnc_sec_certificate
880
@subsection With x509 certificates
881

    
882
The QEMU VNC server also implements the VeNCrypt extension allowing use of
883
TLS for encryption of the session, and x509 certificates for authentication.
884
The use of x509 certificates is strongly recommended, because TLS on its
885
own is susceptible to man-in-the-middle attacks. Basic x509 certificate
886
support provides a secure session, but no authentication. This allows any
887
client to connect, and provides an encrypted session.
888

    
889
@example
890
qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
891
@end example
892

    
893
In the above example @code{/etc/pki/qemu} should contain at least three files,
894
@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
895
users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
896
NB the @code{server-key.pem} file should be protected with file mode 0600 to
897
only be readable by the user owning it.
898

    
899
@node vnc_sec_certificate_verify
900
@subsection With x509 certificates and client verification
901

    
902
Certificates can also provide a means to authenticate the client connecting.
903
The server will request that the client provide a certificate, which it will
904
then validate against the CA certificate. This is a good choice if deploying
905
in an environment with a private internal certificate authority.
906

    
907
@example
908
qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
909
@end example
910

    
911

    
912
@node vnc_sec_certificate_pw
913
@subsection With x509 certificates, client verification and passwords
914

    
915
Finally, the previous method can be combined with VNC password authentication
916
to provide two layers of authentication for clients.
917

    
918
@example
919
qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
920
(qemu) change vnc password
921
Password: ********
922
(qemu)
923
@end example
924

    
925

    
926
@node vnc_sec_sasl
927
@subsection With SASL authentication
928

    
929
The SASL authentication method is a VNC extension, that provides an
930
easily extendable, pluggable authentication method. This allows for
931
integration with a wide range of authentication mechanisms, such as
932
PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
933
The strength of the authentication depends on the exact mechanism
934
configured. If the chosen mechanism also provides a SSF layer, then
935
it will encrypt the datastream as well.
936

    
937
Refer to the later docs on how to choose the exact SASL mechanism
938
used for authentication, but assuming use of one supporting SSF,
939
then QEMU can be launched with:
940

    
941
@example
942
qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
943
@end example
944

    
945
@node vnc_sec_certificate_sasl
946
@subsection With x509 certificates and SASL authentication
947

    
948
If the desired SASL authentication mechanism does not supported
949
SSF layers, then it is strongly advised to run it in combination
950
with TLS and x509 certificates. This provides securely encrypted
951
data stream, avoiding risk of compromising of the security
952
credentials. This can be enabled, by combining the 'sasl' option
953
with the aforementioned TLS + x509 options:
954

    
955
@example
956
qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
957
@end example
958

    
959

    
960
@node vnc_generate_cert
961
@subsection Generating certificates for VNC
962

    
963
The GNU TLS packages provides a command called @code{certtool} which can
964
be used to generate certificates and keys in PEM format. At a minimum it
965
is neccessary to setup a certificate authority, and issue certificates to
966
each server. If using certificates for authentication, then each client
967
will also need to be issued a certificate. The recommendation is for the
968
server to keep its certificates in either @code{/etc/pki/qemu} or for
969
unprivileged users in @code{$HOME/.pki/qemu}.
970

    
971
@menu
972
* vnc_generate_ca::
973
* vnc_generate_server::
974
* vnc_generate_client::
975
@end menu
976
@node vnc_generate_ca
977
@subsubsection Setup the Certificate Authority
978

    
979
This step only needs to be performed once per organization / organizational
980
unit. First the CA needs a private key. This key must be kept VERY secret
981
and secure. If this key is compromised the entire trust chain of the certificates
982
issued with it is lost.
983

    
984
@example
985
# certtool --generate-privkey > ca-key.pem
986
@end example
987

    
988
A CA needs to have a public certificate. For simplicity it can be a self-signed
989
certificate, or one issue by a commercial certificate issuing authority. To
990
generate a self-signed certificate requires one core piece of information, the
991
name of the organization.
992

    
993
@example
994
# cat > ca.info <<EOF
995
cn = Name of your organization
996
ca
997
cert_signing_key
998
EOF
999
# certtool --generate-self-signed \
1000
           --load-privkey ca-key.pem
1001
           --template ca.info \
1002
           --outfile ca-cert.pem
1003
@end example
1004

    
1005
The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1006
TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1007

    
1008
@node vnc_generate_server
1009
@subsubsection Issuing server certificates
1010

    
1011
Each server (or host) needs to be issued with a key and certificate. When connecting
1012
the certificate is sent to the client which validates it against the CA certificate.
1013
The core piece of information for a server certificate is the hostname. This should
1014
be the fully qualified hostname that the client will connect with, since the client
1015
will typically also verify the hostname in the certificate. On the host holding the
1016
secure CA private key:
1017

    
1018
@example
1019
# cat > server.info <<EOF
1020
organization = Name  of your organization
1021
cn = server.foo.example.com
1022
tls_www_server
1023
encryption_key
1024
signing_key
1025
EOF
1026
# certtool --generate-privkey > server-key.pem
1027
# certtool --generate-certificate \
1028
           --load-ca-certificate ca-cert.pem \
1029
           --load-ca-privkey ca-key.pem \
1030
           --load-privkey server server-key.pem \
1031
           --template server.info \
1032
           --outfile server-cert.pem
1033
@end example
1034

    
1035
The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1036
to the server for which they were generated. The @code{server-key.pem} is security
1037
sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1038

    
1039
@node vnc_generate_client
1040
@subsubsection Issuing client certificates
1041

    
1042
If the QEMU VNC server is to use the @code{x509verify} option to validate client
1043
certificates as its authentication mechanism, each client also needs to be issued
1044
a certificate. The client certificate contains enough metadata to uniquely identify
1045
the client, typically organization, state, city, building, etc. On the host holding
1046
the secure CA private key:
1047

    
1048
@example
1049
# cat > client.info <<EOF
1050
country = GB
1051
state = London
1052
locality = London
1053
organiazation = Name of your organization
1054
cn = client.foo.example.com
1055
tls_www_client
1056
encryption_key
1057
signing_key
1058
EOF
1059
# certtool --generate-privkey > client-key.pem
1060
# certtool --generate-certificate \
1061
           --load-ca-certificate ca-cert.pem \
1062
           --load-ca-privkey ca-key.pem \
1063
           --load-privkey client-key.pem \
1064
           --template client.info \
1065
           --outfile client-cert.pem
1066
@end example
1067

    
1068
The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1069
copied to the client for which they were generated.
1070

    
1071

    
1072
@node vnc_setup_sasl
1073

    
1074
@subsection Configuring SASL mechanisms
1075

    
1076
The following documentation assumes use of the Cyrus SASL implementation on a
1077
Linux host, but the principals should apply to any other SASL impl. When SASL
1078
is enabled, the mechanism configuration will be loaded from system default
1079
SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1080
unprivileged user, an environment variable SASL_CONF_PATH can be used
1081
to make it search alternate locations for the service config.
1082

    
1083
The default configuration might contain
1084

    
1085
@example
1086
mech_list: digest-md5
1087
sasldb_path: /etc/qemu/passwd.db
1088
@end example
1089

    
1090
This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1091
Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1092
in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1093
command. While this mechanism is easy to configure and use, it is not
1094
considered secure by modern standards, so only suitable for developers /
1095
ad-hoc testing.
1096

    
1097
A more serious deployment might use Kerberos, which is done with the 'gssapi'
1098
mechanism
1099

    
1100
@example
1101
mech_list: gssapi
1102
keytab: /etc/qemu/krb5.tab
1103
@end example
1104

    
1105
For this to work the administrator of your KDC must generate a Kerberos
1106
principal for the server, with a name of  'qemu/somehost.example.com@@EXAMPLE.COM'
1107
replacing 'somehost.example.com' with the fully qualified host name of the
1108
machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
1109

    
1110
Other configurations will be left as an exercise for the reader. It should
1111
be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1112
encryption. For all other mechanisms, VNC should always be configured to
1113
use TLS and x509 certificates to protect security credentials from snooping.
1114

    
1115
@node gdb_usage
1116
@section GDB usage
1117

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

    
1121
In order to use gdb, launch qemu with the '-s' option. It will wait for a
1122
gdb connection:
1123
@example
1124
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1125
       -append "root=/dev/hda"
1126
Connected to host network interface: tun0
1127
Waiting gdb connection on port 1234
1128
@end example
1129

    
1130
Then launch gdb on the 'vmlinux' executable:
1131
@example
1132
> gdb vmlinux
1133
@end example
1134

    
1135
In gdb, connect to QEMU:
1136
@example
1137
(gdb) target remote localhost:1234
1138
@end example
1139

    
1140
Then you can use gdb normally. For example, type 'c' to launch the kernel:
1141
@example
1142
(gdb) c
1143
@end example
1144

    
1145
Here are some useful tips in order to use gdb on system code:
1146

    
1147
@enumerate
1148
@item
1149
Use @code{info reg} to display all the CPU registers.
1150
@item
1151
Use @code{x/10i $eip} to display the code at the PC position.
1152
@item
1153
Use @code{set architecture i8086} to dump 16 bit code. Then use
1154
@code{x/10i $cs*16+$eip} to dump the code at the PC position.
1155
@end enumerate
1156

    
1157
Advanced debugging options:
1158

    
1159
The default single stepping behavior is step with the IRQs and timer service routines off.  It is set this way because when gdb executes a single step it expects to advance beyond the current instruction.  With the IRQs and and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed.  Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB.  There are three commands you can query and set the single step behavior:
1160
@table @code
1161
@item maintenance packet qqemu.sstepbits
1162

    
1163
This will display the MASK bits used to control the single stepping IE:
1164
@example
1165
(gdb) maintenance packet qqemu.sstepbits
1166
sending: "qqemu.sstepbits"
1167
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1168
@end example
1169
@item maintenance packet qqemu.sstep
1170

    
1171
This will display the current value of the mask used when single stepping IE:
1172
@example
1173
(gdb) maintenance packet qqemu.sstep
1174
sending: "qqemu.sstep"
1175
received: "0x7"
1176
@end example
1177
@item maintenance packet Qqemu.sstep=HEX_VALUE
1178

    
1179
This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1180
@example
1181
(gdb) maintenance packet Qqemu.sstep=0x5
1182
sending: "qemu.sstep=0x5"
1183
received: "OK"
1184
@end example
1185
@end table
1186

    
1187
@node pcsys_os_specific
1188
@section Target OS specific information
1189

    
1190
@subsection Linux
1191

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

    
1196
When using a 2.6 guest Linux kernel, you should add the option
1197
@code{clock=pit} on the kernel command line because the 2.6 Linux
1198
kernels make very strict real time clock checks by default that QEMU
1199
cannot simulate exactly.
1200

    
1201
When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1202
not activated because QEMU is slower with this patch. The QEMU
1203
Accelerator Module is also much slower in this case. Earlier Fedora
1204
Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1205
patch by default. Newer kernels don't have it.
1206

    
1207
@subsection Windows
1208

    
1209
If you have a slow host, using Windows 95 is better as it gives the
1210
best speed. Windows 2000 is also a good choice.
1211

    
1212
@subsubsection SVGA graphic modes support
1213

    
1214
QEMU emulates a Cirrus Logic GD5446 Video
1215
card. All Windows versions starting from Windows 95 should recognize
1216
and use this graphic card. For optimal performances, use 16 bit color
1217
depth in the guest and the host OS.
1218

    
1219
If you are using Windows XP as guest OS and if you want to use high
1220
resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1221
1280x1024x16), then you should use the VESA VBE virtual graphic card
1222
(option @option{-std-vga}).
1223

    
1224
@subsubsection CPU usage reduction
1225

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

    
1232
@subsubsection Windows 2000 disk full problem
1233

    
1234
Windows 2000 has a bug which gives a disk full problem during its
1235
installation. When installing it, use the @option{-win2k-hack} QEMU
1236
option to enable a specific workaround. After Windows 2000 is
1237
installed, you no longer need this option (this option slows down the
1238
IDE transfers).
1239

    
1240
@subsubsection Windows 2000 shutdown
1241

    
1242
Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1243
can. It comes from the fact that Windows 2000 does not automatically
1244
use the APM driver provided by the BIOS.
1245

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

    
1253
@subsubsection Share a directory between Unix and Windows
1254

    
1255
See @ref{sec_invocation} about the help of the option @option{-smb}.
1256

    
1257
@subsubsection Windows XP security problem
1258

    
1259
Some releases of Windows XP install correctly but give a security
1260
error when booting:
1261
@example
1262
A problem is preventing Windows from accurately checking the
1263
license for this computer. Error code: 0x800703e6.
1264
@end example
1265

    
1266
The workaround is to install a service pack for XP after a boot in safe
1267
mode. Then reboot, and the problem should go away. Since there is no
1268
network while in safe mode, its recommended to download the full
1269
installation of SP1 or SP2 and transfer that via an ISO or using the
1270
vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1271

    
1272
@subsection MS-DOS and FreeDOS
1273

    
1274
@subsubsection CPU usage reduction
1275

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

    
1281
@node QEMU System emulator for non PC targets
1282
@chapter QEMU System emulator for non PC targets
1283

    
1284
QEMU is a generic emulator and it emulates many non PC
1285
machines. Most of the options are similar to the PC emulator. The
1286
differences are mentioned in the following sections.
1287

    
1288
@menu
1289
* QEMU PowerPC System emulator::
1290
* Sparc32 System emulator::
1291
* Sparc64 System emulator::
1292
* MIPS System emulator::
1293
* ARM System emulator::
1294
* ColdFire System emulator::
1295
@end menu
1296

    
1297
@node QEMU PowerPC System emulator
1298
@section QEMU PowerPC System emulator
1299

    
1300
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1301
or PowerMac PowerPC system.
1302

    
1303
QEMU emulates the following PowerMac peripherals:
1304

    
1305
@itemize @minus
1306
@item
1307
UniNorth or Grackle PCI Bridge
1308
@item
1309
PCI VGA compatible card with VESA Bochs Extensions
1310
@item
1311
2 PMAC IDE interfaces with hard disk and CD-ROM support
1312
@item
1313
NE2000 PCI adapters
1314
@item
1315
Non Volatile RAM
1316
@item
1317
VIA-CUDA with ADB keyboard and mouse.
1318
@end itemize
1319

    
1320
QEMU emulates the following PREP peripherals:
1321

    
1322
@itemize @minus
1323
@item
1324
PCI Bridge
1325
@item
1326
PCI VGA compatible card with VESA Bochs Extensions
1327
@item
1328
2 IDE interfaces with hard disk and CD-ROM support
1329
@item
1330
Floppy disk
1331
@item
1332
NE2000 network adapters
1333
@item
1334
Serial port
1335
@item
1336
PREP Non Volatile RAM
1337
@item
1338
PC compatible keyboard and mouse.
1339
@end itemize
1340

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

    
1344
Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
1345
for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1346
v2) portable firmware implementation. The goal is to implement a 100%
1347
IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1348

    
1349
@c man begin OPTIONS
1350

    
1351
The following options are specific to the PowerPC emulation:
1352

    
1353
@table @option
1354

    
1355
@item -g @var{W}x@var{H}[x@var{DEPTH}]
1356

    
1357
Set the initial VGA graphic mode. The default is 800x600x15.
1358

    
1359
@item -prom-env @var{string}
1360

    
1361
Set OpenBIOS variables in NVRAM, for example:
1362

    
1363
@example
1364
qemu-system-ppc -prom-env 'auto-boot?=false' \
1365
 -prom-env 'boot-device=hd:2,\yaboot' \
1366
 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1367
@end example
1368

    
1369
These variables are not used by Open Hack'Ware.
1370

    
1371
@end table
1372

    
1373
@c man end
1374

    
1375

    
1376
More information is available at
1377
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1378

    
1379
@node Sparc32 System emulator
1380
@section Sparc32 System emulator
1381

    
1382
Use the executable @file{qemu-system-sparc} to simulate the following
1383
Sun4m architecture machines:
1384
@itemize @minus
1385
@item
1386
SPARCstation 4
1387
@item
1388
SPARCstation 5
1389
@item
1390
SPARCstation 10
1391
@item
1392
SPARCstation 20
1393
@item
1394
SPARCserver 600MP
1395
@item
1396
SPARCstation LX
1397
@item
1398
SPARCstation Voyager
1399
@item
1400
SPARCclassic
1401
@item
1402
SPARCbook
1403
@end itemize
1404

    
1405
The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1406
but Linux limits the number of usable CPUs to 4.
1407

    
1408
It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1409
SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1410
emulators are not usable yet.
1411

    
1412
QEMU emulates the following sun4m/sun4c/sun4d peripherals:
1413

    
1414
@itemize @minus
1415
@item
1416
IOMMU or IO-UNITs
1417
@item
1418
TCX Frame buffer
1419
@item
1420
Lance (Am7990) Ethernet
1421
@item
1422
Non Volatile RAM M48T02/M48T08
1423
@item
1424
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1425
and power/reset logic
1426
@item
1427
ESP SCSI controller with hard disk and CD-ROM support
1428
@item
1429
Floppy drive (not on SS-600MP)
1430
@item
1431
CS4231 sound device (only on SS-5, not working yet)
1432
@end itemize
1433

    
1434
The number of peripherals is fixed in the architecture.  Maximum
1435
memory size depends on the machine type, for SS-5 it is 256MB and for
1436
others 2047MB.
1437

    
1438
Since version 0.8.2, QEMU uses OpenBIOS
1439
@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1440
firmware implementation. The goal is to implement a 100% IEEE
1441
1275-1994 (referred to as Open Firmware) compliant firmware.
1442

    
1443
A sample Linux 2.6 series kernel and ram disk image are available on
1444
the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1445
some kernel versions work. Please note that currently Solaris kernels
1446
don't work probably due to interface issues between OpenBIOS and
1447
Solaris.
1448

    
1449
@c man begin OPTIONS
1450

    
1451
The following options are specific to the Sparc32 emulation:
1452

    
1453
@table @option
1454

    
1455
@item -g @var{W}x@var{H}x[x@var{DEPTH}]
1456

    
1457
Set the initial TCX graphic mode. The default is 1024x768x8, currently
1458
the only other possible mode is 1024x768x24.
1459

    
1460
@item -prom-env @var{string}
1461

    
1462
Set OpenBIOS variables in NVRAM, for example:
1463

    
1464
@example
1465
qemu-system-sparc -prom-env 'auto-boot?=false' \
1466
 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1467
@end example
1468

    
1469
@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
1470

    
1471
Set the emulated machine type. Default is SS-5.
1472

    
1473
@end table
1474

    
1475
@c man end
1476

    
1477
@node Sparc64 System emulator
1478
@section Sparc64 System emulator
1479

    
1480
Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1481
(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1482
Niagara (T1) machine. The emulator is not usable for anything yet, but
1483
it can launch some kernels.
1484

    
1485
QEMU emulates the following peripherals:
1486

    
1487
@itemize @minus
1488
@item
1489
UltraSparc IIi APB PCI Bridge
1490
@item
1491
PCI VGA compatible card with VESA Bochs Extensions
1492
@item
1493
PS/2 mouse and keyboard
1494
@item
1495
Non Volatile RAM M48T59
1496
@item
1497
PC-compatible serial ports
1498
@item
1499
2 PCI IDE interfaces with hard disk and CD-ROM support
1500
@item
1501
Floppy disk
1502
@end itemize
1503

    
1504
@c man begin OPTIONS
1505

    
1506
The following options are specific to the Sparc64 emulation:
1507

    
1508
@table @option
1509

    
1510
@item -prom-env @var{string}
1511

    
1512
Set OpenBIOS variables in NVRAM, for example:
1513

    
1514
@example
1515
qemu-system-sparc64 -prom-env 'auto-boot?=false'
1516
@end example
1517

    
1518
@item -M [sun4u|sun4v|Niagara]
1519

    
1520
Set the emulated machine type. The default is sun4u.
1521

    
1522
@end table
1523

    
1524
@c man end
1525

    
1526
@node MIPS System emulator
1527
@section MIPS System emulator
1528

    
1529
Four executables cover simulation of 32 and 64-bit MIPS systems in
1530
both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1531
@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1532
Five different machine types are emulated:
1533

    
1534
@itemize @minus
1535
@item
1536
A generic ISA PC-like machine "mips"
1537
@item
1538
The MIPS Malta prototype board "malta"
1539
@item
1540
An ACER Pica "pica61". This machine needs the 64-bit emulator.
1541
@item
1542
MIPS emulator pseudo board "mipssim"
1543
@item
1544
A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1545
@end itemize
1546

    
1547
The generic emulation is supported by Debian 'Etch' and is able to
1548
install Debian into a virtual disk image. The following devices are
1549
emulated:
1550

    
1551
@itemize @minus
1552
@item
1553
A range of MIPS CPUs, default is the 24Kf
1554
@item
1555
PC style serial port
1556
@item
1557
PC style IDE disk
1558
@item
1559
NE2000 network card
1560
@end itemize
1561

    
1562
The Malta emulation supports the following devices:
1563

    
1564
@itemize @minus
1565
@item
1566
Core board with MIPS 24Kf CPU and Galileo system controller
1567
@item
1568
PIIX4 PCI/USB/SMbus controller
1569
@item
1570
The Multi-I/O chip's serial device
1571
@item
1572
PCI network cards (PCnet32 and others)
1573
@item
1574
Malta FPGA serial device
1575
@item
1576
Cirrus (default) or any other PCI VGA graphics card
1577
@end itemize
1578

    
1579
The ACER Pica emulation supports:
1580

    
1581
@itemize @minus
1582
@item
1583
MIPS R4000 CPU
1584
@item
1585
PC-style IRQ and DMA controllers
1586
@item
1587
PC Keyboard
1588
@item
1589
IDE controller
1590
@end itemize
1591

    
1592
The mipssim pseudo board emulation provides an environment similiar
1593
to what the proprietary MIPS emulator uses for running Linux.
1594
It supports:
1595

    
1596
@itemize @minus
1597
@item
1598
A range of MIPS CPUs, default is the 24Kf
1599
@item
1600
PC style serial port
1601
@item
1602
MIPSnet network emulation
1603
@end itemize
1604

    
1605
The MIPS Magnum R4000 emulation supports:
1606

    
1607
@itemize @minus
1608
@item
1609
MIPS R4000 CPU
1610
@item
1611
PC-style IRQ controller
1612
@item
1613
PC Keyboard
1614
@item
1615
SCSI controller
1616
@item
1617
G364 framebuffer
1618
@end itemize
1619

    
1620

    
1621
@node ARM System emulator
1622
@section ARM System emulator
1623

    
1624
Use the executable @file{qemu-system-arm} to simulate a ARM
1625
machine. The ARM Integrator/CP board is emulated with the following
1626
devices:
1627

    
1628
@itemize @minus
1629
@item
1630
ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1631
@item
1632
Two PL011 UARTs
1633
@item
1634
SMC 91c111 Ethernet adapter
1635
@item
1636
PL110 LCD controller
1637
@item
1638
PL050 KMI with PS/2 keyboard and mouse.
1639
@item
1640
PL181 MultiMedia Card Interface with SD card.
1641
@end itemize
1642

    
1643
The ARM Versatile baseboard is emulated with the following devices:
1644

    
1645
@itemize @minus
1646
@item
1647
ARM926E, ARM1136 or Cortex-A8 CPU
1648
@item
1649
PL190 Vectored Interrupt Controller
1650
@item
1651
Four PL011 UARTs
1652
@item
1653
SMC 91c111 Ethernet adapter
1654
@item
1655
PL110 LCD controller
1656
@item
1657
PL050 KMI with PS/2 keyboard and mouse.
1658
@item
1659
PCI host bridge.  Note the emulated PCI bridge only provides access to
1660
PCI memory space.  It does not provide access to PCI IO space.
1661
This means some devices (eg. ne2k_pci NIC) are not usable, and others
1662
(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1663
mapped control registers.
1664
@item
1665
PCI OHCI USB controller.
1666
@item
1667
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1668
@item
1669
PL181 MultiMedia Card Interface with SD card.
1670
@end itemize
1671

    
1672
Several variants of the ARM RealView baseboard are emulated,
1673
including the EB, PB-A8 and PBX-A9.  Due to interactions with the
1674
bootloader, only certain Linux kernel configurations work out
1675
of the box on these boards.
1676

    
1677
Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1678
enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
1679
should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1680
disabled and expect 1024M RAM.
1681

    
1682
The following devices are emuilated:
1683

    
1684
@itemize @minus
1685
@item
1686
ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1687
@item
1688
ARM AMBA Generic/Distributed Interrupt Controller
1689
@item
1690
Four PL011 UARTs
1691
@item
1692
SMC 91c111 or SMSC LAN9118 Ethernet adapter
1693
@item
1694
PL110 LCD controller
1695
@item
1696
PL050 KMI with PS/2 keyboard and mouse
1697
@item
1698
PCI host bridge
1699
@item
1700
PCI OHCI USB controller
1701
@item
1702
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1703
@item
1704
PL181 MultiMedia Card Interface with SD card.
1705
@end itemize
1706

    
1707
The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1708
and "Terrier") emulation includes the following peripherals:
1709

    
1710
@itemize @minus
1711
@item
1712
Intel PXA270 System-on-chip (ARM V5TE core)
1713
@item
1714
NAND Flash memory
1715
@item
1716
IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1717
@item
1718
On-chip OHCI USB controller
1719
@item
1720
On-chip LCD controller
1721
@item
1722
On-chip Real Time Clock
1723
@item
1724
TI ADS7846 touchscreen controller on SSP bus
1725
@item
1726
Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1727
@item
1728
GPIO-connected keyboard controller and LEDs
1729
@item
1730
Secure Digital card connected to PXA MMC/SD host
1731
@item
1732
Three on-chip UARTs
1733
@item
1734
WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1735
@end itemize
1736

    
1737
The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1738
following elements:
1739

    
1740
@itemize @minus
1741
@item
1742
Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1743
@item
1744
ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1745
@item
1746
On-chip LCD controller
1747
@item
1748
On-chip Real Time Clock
1749
@item
1750
TI TSC2102i touchscreen controller / analog-digital converter / Audio
1751
CODEC, connected through MicroWire and I@math{^2}S busses
1752
@item
1753
GPIO-connected matrix keypad
1754
@item
1755
Secure Digital card connected to OMAP MMC/SD host
1756
@item
1757
Three on-chip UARTs
1758
@end itemize
1759

    
1760
Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1761
emulation supports the following elements:
1762

    
1763
@itemize @minus
1764
@item
1765
Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1766
@item
1767
RAM and non-volatile OneNAND Flash memories
1768
@item
1769
Display connected to EPSON remote framebuffer chip and OMAP on-chip
1770
display controller and a LS041y3 MIPI DBI-C controller
1771
@item
1772
TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1773
driven through SPI bus
1774
@item
1775
National Semiconductor LM8323-controlled qwerty keyboard driven
1776
through I@math{^2}C bus
1777
@item
1778
Secure Digital card connected to OMAP MMC/SD host
1779
@item
1780
Three OMAP on-chip UARTs and on-chip STI debugging console
1781
@item
1782
A Bluetooth(R) transciever and HCI connected to an UART
1783
@item
1784
Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
1785
TUSB6010 chip - only USB host mode is supported
1786
@item
1787
TI TMP105 temperature sensor driven through I@math{^2}C bus
1788
@item
1789
TI TWL92230C power management companion with an RTC on I@math{^2}C bus
1790
@item
1791
Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
1792
through CBUS
1793
@end itemize
1794

    
1795
The Luminary Micro Stellaris LM3S811EVB emulation includes the following
1796
devices:
1797

    
1798
@itemize @minus
1799
@item
1800
Cortex-M3 CPU core.
1801
@item
1802
64k Flash and 8k SRAM.
1803
@item
1804
Timers, UARTs, ADC and I@math{^2}C interface.
1805
@item
1806
OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
1807
@end itemize
1808

    
1809
The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
1810
devices:
1811

    
1812
@itemize @minus
1813
@item
1814
Cortex-M3 CPU core.
1815
@item
1816
256k Flash and 64k SRAM.
1817
@item
1818
Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
1819
@item
1820
OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1821
@end itemize
1822

    
1823
The Freecom MusicPal internet radio emulation includes the following
1824
elements:
1825

    
1826
@itemize @minus
1827
@item
1828
Marvell MV88W8618 ARM core.
1829
@item
1830
32 MB RAM, 256 KB SRAM, 8 MB flash.
1831
@item
1832
Up to 2 16550 UARTs
1833
@item
1834
MV88W8xx8 Ethernet controller
1835
@item
1836
MV88W8618 audio controller, WM8750 CODEC and mixer
1837
@item
1838
128×64 display with brightness control
1839
@item
1840
2 buttons, 2 navigation wheels with button function
1841
@end itemize
1842

    
1843
The Siemens SX1 models v1 and v2 (default) basic emulation.
1844
The emulaton includes the following elements:
1845

    
1846
@itemize @minus
1847
@item
1848
Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1849
@item
1850
ROM and RAM memories (ROM firmware image can be loaded with -pflash)
1851
V1
1852
1 Flash of 16MB and 1 Flash of 8MB
1853
V2
1854
1 Flash of 32MB
1855
@item
1856
On-chip LCD controller
1857
@item
1858
On-chip Real Time Clock
1859
@item
1860
Secure Digital card connected to OMAP MMC/SD host
1861
@item
1862
Three on-chip UARTs
1863
@end itemize
1864

    
1865
The "Syborg" Symbian Virtual Platform base model includes the following
1866
elements:
1867

    
1868
@itemize @minus
1869
@item
1870
ARM Cortex-A8 CPU
1871
@item
1872
Interrupt controller
1873
@item
1874
Timer
1875
@item
1876
Real Time Clock
1877
@item
1878
Keyboard
1879
@item
1880
Framebuffer
1881
@item
1882
Touchscreen
1883
@item
1884
UARTs
1885
@end itemize
1886

    
1887
A Linux 2.6 test image is available on the QEMU web site. More
1888
information is available in the QEMU mailing-list archive.
1889

    
1890
@c man begin OPTIONS
1891

    
1892
The following options are specific to the ARM emulation:
1893

    
1894
@table @option
1895

    
1896
@item -semihosting
1897
Enable semihosting syscall emulation.
1898

    
1899
On ARM this implements the "Angel" interface.
1900

    
1901
Note that this allows guest direct access to the host filesystem,
1902
so should only be used with trusted guest OS.
1903

    
1904
@end table
1905

    
1906
@node ColdFire System emulator
1907
@section ColdFire System emulator
1908

    
1909
Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
1910
The emulator is able to boot a uClinux kernel.
1911

    
1912
The M5208EVB emulation includes the following devices:
1913

    
1914
@itemize @minus
1915
@item
1916
MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
1917
@item
1918
Three Two on-chip UARTs.
1919
@item
1920
Fast Ethernet Controller (FEC)
1921
@end itemize
1922

    
1923
The AN5206 emulation includes the following devices:
1924

    
1925
@itemize @minus
1926
@item
1927
MCF5206 ColdFire V2 Microprocessor.
1928
@item
1929
Two on-chip UARTs.
1930
@end itemize
1931

    
1932
@c man begin OPTIONS
1933

    
1934
The following options are specific to the ARM emulation:
1935

    
1936
@table @option
1937

    
1938
@item -semihosting
1939
Enable semihosting syscall emulation.
1940

    
1941
On M68K this implements the "ColdFire GDB" interface used by libgloss.
1942

    
1943
Note that this allows guest direct access to the host filesystem,
1944
so should only be used with trusted guest OS.
1945

    
1946
@end table
1947

    
1948
@node QEMU User space emulator
1949
@chapter QEMU User space emulator
1950

    
1951
@menu
1952
* Supported Operating Systems ::
1953
* Linux User space emulator::
1954
* Mac OS X/Darwin User space emulator ::
1955
* BSD User space emulator ::
1956
@end menu
1957

    
1958
@node Supported Operating Systems
1959
@section Supported Operating Systems
1960

    
1961
The following OS are supported in user space emulation:
1962

    
1963
@itemize @minus
1964
@item
1965
Linux (referred as qemu-linux-user)
1966
@item
1967
Mac OS X/Darwin (referred as qemu-darwin-user)
1968
@item
1969
BSD (referred as qemu-bsd-user)
1970
@end itemize
1971

    
1972
@node Linux User space emulator
1973
@section Linux User space emulator
1974

    
1975
@menu
1976
* Quick Start::
1977
* Wine launch::
1978
* Command line options::
1979
* Other binaries::
1980
@end menu
1981

    
1982
@node Quick Start
1983
@subsection Quick Start
1984

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

    
1988
@itemize
1989

    
1990
@item On x86, you can just try to launch any process by using the native
1991
libraries:
1992

    
1993
@example
1994
qemu-i386 -L / /bin/ls
1995
@end example
1996

    
1997
@code{-L /} tells that the x86 dynamic linker must be searched with a
1998
@file{/} prefix.
1999

    
2000
@item Since QEMU is also a linux process, you can launch qemu with
2001
qemu (NOTE: you can only do that if you compiled QEMU from the sources):
2002

    
2003
@example
2004
qemu-i386 -L / qemu-i386 -L / /bin/ls
2005
@end example
2006

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

    
2011
@example
2012
unset LD_LIBRARY_PATH
2013
@end example
2014

    
2015
Then you can launch the precompiled @file{ls} x86 executable:
2016

    
2017
@example
2018
qemu-i386 tests/i386/ls
2019
@end example
2020
You can look at @file{qemu-binfmt-conf.sh} so that
2021
QEMU is automatically launched by the Linux kernel when you try to
2022
launch x86 executables. It requires the @code{binfmt_misc} module in the
2023
Linux kernel.
2024

    
2025
@item The x86 version of QEMU is also included. You can try weird things such as:
2026
@example
2027
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2028
          /usr/local/qemu-i386/bin/ls-i386
2029
@end example
2030

    
2031
@end itemize
2032

    
2033
@node Wine launch
2034
@subsection Wine launch
2035

    
2036
@itemize
2037

    
2038
@item Ensure that you have a working QEMU with the x86 glibc
2039
distribution (see previous section). In order to verify it, you must be
2040
able to do:
2041

    
2042
@example
2043
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2044
@end example
2045

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

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

    
2053
@item Then you can try the example @file{putty.exe}:
2054

    
2055
@example
2056
qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2057
          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2058
@end example
2059

    
2060
@end itemize
2061

    
2062
@node Command line options
2063
@subsection Command line options
2064

    
2065
@example
2066
usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] program [arguments...]
2067
@end example
2068

    
2069
@table @option
2070
@item -h
2071
Print the help
2072
@item -L path
2073
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2074
@item -s size
2075
Set the x86 stack size in bytes (default=524288)
2076
@item -cpu model
2077
Select CPU model (-cpu ? for list and additional feature selection)
2078
@item -B offset
2079
Offset guest address by the specified number of bytes.  This is useful when
2080
the address region rewuired by guest applications is reserved on the host.
2081
Ths option is currently only supported on some hosts.
2082
@end table
2083

    
2084
Debug options:
2085

    
2086
@table @option
2087
@item -d
2088
Activate log (logfile=/tmp/qemu.log)
2089
@item -p pagesize
2090
Act as if the host page size was 'pagesize' bytes
2091
@item -g port
2092
Wait gdb connection to port
2093
@item -singlestep
2094
Run the emulation in single step mode.
2095
@end table
2096

    
2097
Environment variables:
2098

    
2099
@table @env
2100
@item QEMU_STRACE
2101
Print system calls and arguments similar to the 'strace' program
2102
(NOTE: the actual 'strace' program will not work because the user
2103
space emulator hasn't implemented ptrace).  At the moment this is
2104
incomplete.  All system calls that don't have a specific argument
2105
format are printed with information for six arguments.  Many
2106
flag-style arguments don't have decoders and will show up as numbers.
2107
@end table
2108

    
2109
@node Other binaries
2110
@subsection Other binaries
2111

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

    
2116
@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2117
(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2118
coldfire uClinux bFLT format binaries.
2119

    
2120
The binary format is detected automatically.
2121

    
2122
@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2123

    
2124
@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2125
(Sparc64 CPU, 32 bit ABI).
2126

    
2127
@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2128
SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2129

    
2130
@node Mac OS X/Darwin User space emulator
2131
@section Mac OS X/Darwin User space emulator
2132

    
2133
@menu
2134
* Mac OS X/Darwin Status::
2135
* Mac OS X/Darwin Quick Start::
2136
* Mac OS X/Darwin Command line options::
2137
@end menu
2138

    
2139
@node Mac OS X/Darwin Status
2140
@subsection Mac OS X/Darwin Status
2141

    
2142
@itemize @minus
2143
@item
2144
target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2145
@item
2146
target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2147
@item
2148
target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
2149
@item
2150
target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2151
@end itemize
2152

    
2153
[1] If you're host commpage can be executed by qemu.
2154

    
2155
@node Mac OS X/Darwin Quick Start
2156
@subsection Quick Start
2157

    
2158
In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2159
itself and all the target dynamic libraries used by it. If you don't have the FAT
2160
libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2161
CD or compile them by hand.
2162

    
2163
@itemize
2164

    
2165
@item On x86, you can just try to launch any process by using the native
2166
libraries:
2167

    
2168
@example
2169
qemu-i386 /bin/ls
2170
@end example
2171

    
2172
or to run the ppc version of the executable:
2173

    
2174
@example
2175
qemu-ppc /bin/ls
2176
@end example
2177

    
2178
@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2179
are installed:
2180

    
2181
@example
2182
qemu-i386 -L /opt/x86_root/ /bin/ls
2183
@end example
2184

    
2185
@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2186
@file{/opt/x86_root/usr/bin/dyld}.
2187

    
2188
@end itemize
2189

    
2190
@node Mac OS X/Darwin Command line options
2191
@subsection Command line options
2192

    
2193
@example
2194
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2195
@end example
2196

    
2197
@table @option
2198
@item -h
2199
Print the help
2200
@item -L path
2201
Set the library root path (default=/)
2202
@item -s size
2203
Set the stack size in bytes (default=524288)
2204
@end table
2205

    
2206
Debug options:
2207

    
2208
@table @option
2209
@item -d
2210
Activate log (logfile=/tmp/qemu.log)
2211
@item -p pagesize
2212
Act as if the host page size was 'pagesize' bytes
2213
@item -singlestep
2214
Run the emulation in single step mode.
2215
@end table
2216

    
2217
@node BSD User space emulator
2218
@section BSD User space emulator
2219

    
2220
@menu
2221
* BSD Status::
2222
* BSD Quick Start::
2223
* BSD Command line options::
2224
@end menu
2225

    
2226
@node BSD Status
2227
@subsection BSD Status
2228

    
2229
@itemize @minus
2230
@item
2231
target Sparc64 on Sparc64: Some trivial programs work.
2232
@end itemize
2233

    
2234
@node BSD Quick Start
2235
@subsection Quick Start
2236

    
2237
In order to launch a BSD process, QEMU needs the process executable
2238
itself and all the target dynamic libraries used by it.
2239

    
2240
@itemize
2241

    
2242
@item On Sparc64, you can just try to launch any process by using the native
2243
libraries:
2244

    
2245
@example
2246
qemu-sparc64 /bin/ls
2247
@end example
2248

    
2249
@end itemize
2250

    
2251
@node BSD Command line options
2252
@subsection Command line options
2253

    
2254
@example
2255
usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2256
@end example
2257

    
2258
@table @option
2259
@item -h
2260
Print the help
2261
@item -L path
2262
Set the library root path (default=/)
2263
@item -s size
2264
Set the stack size in bytes (default=524288)
2265
@item -bsd type
2266
Set the type of the emulated BSD Operating system. Valid values are
2267
FreeBSD, NetBSD and OpenBSD (default).
2268
@end table
2269

    
2270
Debug options:
2271

    
2272
@table @option
2273
@item -d
2274
Activate log (logfile=/tmp/qemu.log)
2275
@item -p pagesize
2276
Act as if the host page size was 'pagesize' bytes
2277
@item -singlestep
2278
Run the emulation in single step mode.
2279
@end table
2280

    
2281
@node compilation
2282
@chapter Compilation from the sources
2283

    
2284
@menu
2285
* Linux/Unix::
2286
* Windows::
2287
* Cross compilation for Windows with Linux::
2288
* Mac OS X::
2289
* Make targets::
2290
@end menu
2291

    
2292
@node Linux/Unix
2293
@section Linux/Unix
2294

    
2295
@subsection Compilation
2296

    
2297
First you must decompress the sources:
2298
@example
2299
cd /tmp
2300
tar zxvf qemu-x.y.z.tar.gz
2301
cd qemu-x.y.z
2302
@end example
2303

    
2304
Then you configure QEMU and build it (usually no options are needed):
2305
@example
2306
./configure
2307
make
2308
@end example
2309

    
2310
Then type as root user:
2311
@example
2312
make install
2313
@end example
2314
to install QEMU in @file{/usr/local}.
2315

    
2316
@node Windows
2317
@section Windows
2318

    
2319
@itemize
2320
@item Install the current versions of MSYS and MinGW from
2321
@url{http://www.mingw.org/}. You can find detailed installation
2322
instructions in the download section and the FAQ.
2323

    
2324
@item Download
2325
the MinGW development library of SDL 1.2.x
2326
(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2327
@url{http://www.libsdl.org}. Unpack it in a temporary place and
2328
edit the @file{sdl-config} script so that it gives the
2329
correct SDL directory when invoked.
2330

    
2331
@item Install the MinGW version of zlib and make sure
2332
@file{zlib.h} and @file{libz.dll.a} are in
2333
MingGW's default header and linker search paths.
2334

    
2335
@item Extract the current version of QEMU.
2336

    
2337
@item Start the MSYS shell (file @file{msys.bat}).
2338

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

    
2343
@item You can install QEMU in @file{Program Files/Qemu} by typing
2344
@file{make install}. Don't forget to copy @file{SDL.dll} in
2345
@file{Program Files/Qemu}.
2346

    
2347
@end itemize
2348

    
2349
@node Cross compilation for Windows with Linux
2350
@section Cross compilation for Windows with Linux
2351

    
2352
@itemize
2353
@item
2354
Install the MinGW cross compilation tools available at
2355
@url{http://www.mingw.org/}.
2356

    
2357
@item Download
2358
the MinGW development library of SDL 1.2.x
2359
(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2360
@url{http://www.libsdl.org}. Unpack it in a temporary place and
2361
edit the @file{sdl-config} script so that it gives the
2362
correct SDL directory when invoked.  Set up the @code{PATH} environment
2363
variable so that @file{sdl-config} can be launched by
2364
the QEMU configuration script.
2365

    
2366
@item Install the MinGW version of zlib and make sure
2367
@file{zlib.h} and @file{libz.dll.a} are in
2368
MingGW's default header and linker search paths.
2369

    
2370
@item
2371
Configure QEMU for Windows cross compilation:
2372
@example
2373
PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
2374
@end example
2375
The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
2376
MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
2377
We set the @code{PATH} environment variable to ensure the MingW version of @file{sdl-config} is used and
2378
use --cross-prefix to specify the name of the cross compiler.
2379
You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
2380

    
2381
Under Fedora Linux, you can run:
2382
@example
2383
yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
2384
@end example
2385
to get a suitable cross compilation environment.
2386

    
2387
@item You can install QEMU in the installation directory by typing
2388
@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
2389
installation directory.
2390

    
2391
@end itemize
2392

    
2393
Wine can be used to launch the resulting qemu.exe compiled for Win32.
2394

    
2395
@node Mac OS X
2396
@section Mac OS X
2397

    
2398
The Mac OS X patches are not fully merged in QEMU, so you should look
2399
at the QEMU mailing list archive to have all the necessary
2400
information.
2401

    
2402
@node Make targets
2403
@section Make targets
2404

    
2405
@table @code
2406

    
2407
@item make
2408
@item make all
2409
Make everything which is typically needed.
2410

    
2411
@item install
2412
TODO
2413

    
2414
@item install-doc
2415
TODO
2416

    
2417
@item make clean
2418
Remove most files which were built during make.
2419

    
2420
@item make distclean
2421
Remove everything which was built during make.
2422

    
2423
@item make dvi
2424
@item make html
2425
@item make info
2426
@item make pdf
2427
Create documentation in dvi, html, info or pdf format.
2428

    
2429
@item make cscope
2430
TODO
2431

    
2432
@item make defconfig
2433
(Re-)create some build configuration files.
2434
User made changes will be overwritten.
2435

    
2436
@item tar
2437
@item tarbin
2438
TODO
2439

    
2440
@end table
2441

    
2442
@node Index
2443
@chapter Index
2444
@printindex cp
2445

    
2446
@bye