Statistics
| Branch: | Revision:

root / qemu-doc.texi @ 75818250

History | View | Annotate | Download (89.9 kB)

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

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

    
19
@ifnottex
20
@node Top
21
@top
22

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

    
34
@contents
35

    
36
@node Introduction
37
@chapter Introduction
38

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

    
43
@node intro_features
44
@section Features
45

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

    
49
QEMU has two operating modes:
50

    
51
@itemize @minus
52

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

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

    
65
@end itemize
66

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

    
70
For system emulation, the following hardware targets are supported:
71
@itemize
72
@item PC (x86 or x86_64 processor)
73
@item ISA PC (old style PC without PCI bus)
74
@item PREP (PowerPC processor)
75
@item G3 BW PowerMac (PowerPC processor)
76
@item Mac99 PowerMac (PowerPC processor, in progress)
77
@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
78
@item Sun4u (64-bit Sparc processor, in progress)
79
@item Malta board (32-bit and 64-bit MIPS processors)
80
@item MIPS Magnum (64-bit MIPS processor)
81
@item ARM Integrator/CP (ARM)
82
@item ARM Versatile baseboard (ARM)
83
@item ARM RealView Emulation baseboard (ARM)
84
@item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
85
@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
86
@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
87
@item Freescale MCF5208EVB (ColdFire V2).
88
@item Arnewsh MCF5206 evaluation board (ColdFire V2).
89
@item Palm Tungsten|E PDA (OMAP310 processor)
90
@item N800 and N810 tablets (OMAP2420 processor)
91
@item MusicPal (MV88W8618 ARM processor)
92
@end itemize
93

    
94
For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
95

    
96
@node Installation
97
@chapter Installation
98

    
99
If you want to compile QEMU yourself, see @ref{compilation}.
100

    
101
@menu
102
* install_linux::   Linux
103
* install_windows:: Windows
104
* install_mac::     Macintosh
105
@end menu
106

    
107
@node install_linux
108
@section Linux
109

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

    
113
@node install_windows
114
@section Windows
115

    
116
Download the experimental binary installer at
117
@url{http://www.free.oszoo.org/@/download.html}.
118

    
119
@node install_mac
120
@section Mac OS X
121

    
122
Download the experimental binary installer at
123
@url{http://www.free.oszoo.org/@/download.html}.
124

    
125
@node QEMU PC System emulator
126
@chapter QEMU PC System emulator
127

    
128
@menu
129
* pcsys_introduction:: Introduction
130
* pcsys_quickstart::   Quick Start
131
* sec_invocation::     Invocation
132
* pcsys_keys::         Keys
133
* pcsys_monitor::      QEMU Monitor
134
* disk_images::        Disk Images
135
* pcsys_network::      Network emulation
136
* direct_linux_boot::  Direct Linux Boot
137
* pcsys_usb::          USB emulation
138
* vnc_security::       VNC security
139
* gdb_usage::          GDB usage
140
* pcsys_os_specific::  Target OS specific information
141
@end menu
142

    
143
@node pcsys_introduction
144
@section Introduction
145

    
146
@c man begin DESCRIPTION
147

    
148
The QEMU PC System emulator simulates the
149
following peripherals:
150

    
151
@itemize @minus
152
@item
153
i440FX host PCI bridge and PIIX3 PCI to ISA bridge
154
@item
155
Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
156
extensions (hardware level, including all non standard modes).
157
@item
158
PS/2 mouse and keyboard
159
@item
160
2 PCI IDE interfaces with hard disk and CD-ROM support
161
@item
162
Floppy disk
163
@item
164
PCI/ISA PCI network adapters
165
@item
166
Serial ports
167
@item
168
Creative SoundBlaster 16 sound card
169
@item
170
ENSONIQ AudioPCI ES1370 sound card
171
@item
172
Intel 82801AA AC97 Audio compatible sound card
173
@item
174
Adlib(OPL2) - Yamaha YM3812 compatible chip
175
@item
176
Gravis Ultrasound GF1 sound card
177
@item
178
CS4231A compatible sound card
179
@item
180
PCI UHCI USB controller and a virtual USB hub.
181
@end itemize
182

    
183
SMP is supported with up to 255 CPUs.
184

    
185
Note that adlib, ac97, gus and cs4231a are only available when QEMU
186
was configured with --audio-card-list option containing the name(s) of
187
required card(s).
188

    
189
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
190
VGA BIOS.
191

    
192
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
193

    
194
QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
195
by Tibor "TS" Sch?tz.
196

    
197
CS4231A is the chip used in Windows Sound System and GUSMAX products
198

    
199
@c man end
200

    
201
@node pcsys_quickstart
202
@section Quick Start
203

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

    
206
@example
207
qemu linux.img
208
@end example
209

    
210
Linux should boot and give you a prompt.
211

    
212
@node sec_invocation
213
@section Invocation
214

    
215
@example
216
@c man begin SYNOPSIS
217
usage: qemu [options] [@var{disk_image}]
218
@c man end
219
@end example
220

    
221
@c man begin OPTIONS
222
@var{disk_image} is a raw hard disk image for IDE hard disk 0.
223

    
224
General options:
225
@table @option
226
@item -M @var{machine}
227
Select the emulated @var{machine} (@code{-M ?} for list)
228

    
229
@item -fda @var{file}
230
@item -fdb @var{file}
231
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
232
use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
233

    
234
@item -hda @var{file}
235
@item -hdb @var{file}
236
@item -hdc @var{file}
237
@item -hdd @var{file}
238
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
239

    
240
@item -cdrom @var{file}
241
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
242
@option{-cdrom} at the same time). You can use the host CD-ROM by
243
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
244

    
245
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
246

    
247
Define a new drive. Valid options are:
248

    
249
@table @code
250
@item file=@var{file}
251
This option defines which disk image (@pxref{disk_images}) to use with
252
this drive. If the filename contains comma, you must double it
253
(for instance, "file=my,,file" to use file "my,file").
254
@item if=@var{interface}
255
This option defines on which type on interface the drive is connected.
256
Available types are: ide, scsi, sd, mtd, floppy, pflash.
257
@item bus=@var{bus},unit=@var{unit}
258
These options define where is connected the drive by defining the bus number and
259
the unit id.
260
@item index=@var{index}
261
This option defines where is connected the drive by using an index in the list
262
of available connectors of a given interface type.
263
@item media=@var{media}
264
This option defines the type of the media: disk or cdrom.
265
@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
266
These options have the same definition as they have in @option{-hdachs}.
267
@item snapshot=@var{snapshot}
268
@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
269
@item cache=@var{cache}
270
@var{cache} is "on" or "off" and allows to disable host cache to access data.
271
@item format=@var{format}
272
Specify which disk @var{format} will be used rather than detecting
273
the format.  Can be used to specifiy format=raw to avoid interpreting
274
an untrusted format header.
275
@end table
276

    
277
Instead of @option{-cdrom} you can use:
278
@example
279
qemu -drive file=file,index=2,media=cdrom
280
@end example
281

    
282
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
283
use:
284
@example
285
qemu -drive file=file,index=0,media=disk
286
qemu -drive file=file,index=1,media=disk
287
qemu -drive file=file,index=2,media=disk
288
qemu -drive file=file,index=3,media=disk
289
@end example
290

    
291
You can connect a CDROM to the slave of ide0:
292
@example
293
qemu -drive file=file,if=ide,index=1,media=cdrom
294
@end example
295

    
296
If you don't specify the "file=" argument, you define an empty drive:
297
@example
298
qemu -drive if=ide,index=1,media=cdrom
299
@end example
300

    
301
You can connect a SCSI disk with unit ID 6 on the bus #0:
302
@example
303
qemu -drive file=file,if=scsi,bus=0,unit=6
304
@end example
305

    
306
Instead of @option{-fda}, @option{-fdb}, you can use:
307
@example
308
qemu -drive file=file,index=0,if=floppy
309
qemu -drive file=file,index=1,if=floppy
310
@end example
311

    
312
By default, @var{interface} is "ide" and @var{index} is automatically
313
incremented:
314
@example
315
qemu -drive file=a -drive file=b"
316
@end example
317
is interpreted like:
318
@example
319
qemu -hda a -hdb b
320
@end example
321

    
322
@item -boot [a|c|d|n]
323
Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
324
is the default.
325

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

    
331
@item -no-fd-bootchk
332
Disable boot signature checking for floppy disks in Bochs BIOS. It may
333
be needed to boot from old floppy disks.
334

    
335
@item -m @var{megs}
336
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
337
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
338
gigabytes respectively.
339

    
340
@item -smp @var{n}
341
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
342
CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
343
to 4.
344

    
345
@item -audio-help
346

    
347
Will show the audio subsystem help: list of drivers, tunable
348
parameters.
349

    
350
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
351

    
352
Enable audio and selected sound hardware. Use ? to print all
353
available sound hardware.
354

    
355
@example
356
qemu -soundhw sb16,adlib hda
357
qemu -soundhw es1370 hda
358
qemu -soundhw ac97 hda
359
qemu -soundhw all hda
360
qemu -soundhw ?
361
@end example
362

    
363
Note that Linux's i810_audio OSS kernel (for AC97) module might
364
require manually specifying clocking.
365

    
366
@example
367
modprobe i810_audio clocking=48000
368
@end example
369

    
370
@item -localtime
371
Set the real time clock to local time (the default is to UTC
372
time). This option is needed to have correct date in MS-DOS or
373
Windows.
374

    
375
@item -startdate @var{date}
376
Set the initial date of the real time clock. Valid format for
377
@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
378
@code{2006-06-17}. The default value is @code{now}.
379

    
380
@item -pidfile @var{file}
381
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
382
from a script.
383

    
384
@item -daemonize
385
Daemonize the QEMU process after initialization.  QEMU will not detach from
386
standard IO until it is ready to receive connections on any of its devices.
387
This option is a useful way for external programs to launch QEMU without having
388
to cope with initialization race conditions.
389

    
390
@item -win2k-hack
391
Use it when installing Windows 2000 to avoid a disk full bug. After
392
Windows 2000 is installed, you no longer need this option (this option
393
slows down the IDE transfers).
394

    
395
@item -option-rom @var{file}
396
Load the contents of @var{file} as an option ROM.
397
This option is useful to load things like EtherBoot.
398

    
399
@item -name @var{name}
400
Sets the @var{name} of the guest.
401
This name will be display in the SDL window caption.
402
The @var{name} will also be used for the VNC server.
403

    
404
@end table
405

    
406
Display options:
407
@table @option
408

    
409
@item -nographic
410

    
411
Normally, QEMU uses SDL to display the VGA output. With this option,
412
you can totally disable graphical output so that QEMU is a simple
413
command line application. The emulated serial port is redirected on
414
the console. Therefore, you can still use QEMU to debug a Linux kernel
415
with a serial console.
416

    
417
@item -curses
418

    
419
Normally, QEMU uses SDL to display the VGA output.  With this option,
420
QEMU can display the VGA output when in text mode using a 
421
curses/ncurses interface.  Nothing is displayed in graphical mode.
422

    
423
@item -no-frame
424

    
425
Do not use decorations for SDL windows and start them using the whole
426
available screen space. This makes the using QEMU in a dedicated desktop
427
workspace more convenient.
428

    
429
@item -no-quit
430

    
431
Disable SDL window close capability.
432

    
433
@item -full-screen
434
Start in full screen.
435

    
436
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
437

    
438
Normally, QEMU uses SDL to display the VGA output.  With this option,
439
you can have QEMU listen on VNC display @var{display} and redirect the VGA
440
display over the VNC session.  It is very useful to enable the usb
441
tablet device when using this option (option @option{-usbdevice
442
tablet}). When using the VNC display, you must use the @option{-k}
443
parameter to set the keyboard layout if you are not using en-us. Valid
444
syntax for the @var{display} is
445

    
446
@table @code
447

    
448
@item @var{host}:@var{d}
449

    
450
TCP connections will only be allowed from @var{host} on display @var{d}.
451
By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
452
be omitted in which case the server will accept connections from any host.
453

    
454
@item @code{unix}:@var{path}
455

    
456
Connections will be allowed over UNIX domain sockets where @var{path} is the
457
location of a unix socket to listen for connections on.
458

    
459
@item none
460

    
461
VNC is initialized but not started. The monitor @code{change} command
462
can be used to later start the VNC server.
463

    
464
@end table
465

    
466
Following the @var{display} value there may be one or more @var{option} flags
467
separated by commas. Valid options are
468

    
469
@table @code
470

    
471
@item reverse
472

    
473
Connect to a listening VNC client via a ``reverse'' connection. The
474
client is specified by the @var{display}. For reverse network
475
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
476
is a TCP port number, not a display number.
477

    
478
@item password
479

    
480
Require that password based authentication is used for client connections.
481
The password must be set separately using the @code{change} command in the
482
@ref{pcsys_monitor}
483

    
484
@item tls
485

    
486
Require that client use TLS when communicating with the VNC server. This
487
uses anonymous TLS credentials so is susceptible to a man-in-the-middle
488
attack. It is recommended that this option be combined with either the
489
@var{x509} or @var{x509verify} options.
490

    
491
@item x509=@var{/path/to/certificate/dir}
492

    
493
Valid if @option{tls} is specified. Require that x509 credentials are used
494
for negotiating the TLS session. The server will send its x509 certificate
495
to the client. It is recommended that a password be set on the VNC server
496
to provide authentication of the client when this is used. The path following
497
this option specifies where the x509 certificates are to be loaded from.
498
See the @ref{vnc_security} section for details on generating certificates.
499

    
500
@item x509verify=@var{/path/to/certificate/dir}
501

    
502
Valid if @option{tls} is specified. Require that x509 credentials are used
503
for negotiating the TLS session. The server will send its x509 certificate
504
to the client, and request that the client send its own x509 certificate.
505
The server will validate the client's certificate against the CA certificate,
506
and reject clients when validation fails. If the certificate authority is
507
trusted, this is a sufficient authentication mechanism. You may still wish
508
to set a password on the VNC server as a second authentication layer. The
509
path following this option specifies where the x509 certificates are to
510
be loaded from. See the @ref{vnc_security} section for details on generating
511
certificates.
512

    
513
@end table
514

    
515
@item -k @var{language}
516

    
517
Use keyboard layout @var{language} (for example @code{fr} for
518
French). This option is only needed where it is not easy to get raw PC
519
keycodes (e.g. on Macs, with some X11 servers or with a VNC
520
display). You don't normally need to use it on PC/Linux or PC/Windows
521
hosts.
522

    
523
The available layouts are:
524
@example
525
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
526
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
527
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
528
@end example
529

    
530
The default is @code{en-us}.
531

    
532
@end table
533

    
534
USB options:
535
@table @option
536

    
537
@item -usb
538
Enable the USB driver (will be the default soon)
539

    
540
@item -usbdevice @var{devname}
541
Add the USB device @var{devname}. @xref{usb_devices}.
542

    
543
@table @code
544

    
545
@item mouse
546
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
547

    
548
@item tablet
549
Pointer device that uses absolute coordinates (like a touchscreen). This
550
means qemu is able to report the mouse position without having to grab the
551
mouse. Also overrides the PS/2 mouse emulation when activated.
552

    
553
@item disk:file
554
Mass storage device based on file
555

    
556
@item host:bus.addr
557
Pass through the host device identified by bus.addr (Linux only).
558

    
559
@item host:vendor_id:product_id
560
Pass through the host device identified by vendor_id:product_id (Linux only).
561

    
562
@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
563
Serial converter to host character device @var{dev}, see @code{-serial} for the
564
available devices.
565

    
566
@item braille
567
Braille device.  This will use BrlAPI to display the braille output on a real
568
or fake device.
569

    
570
@end table
571

    
572
@end table
573

    
574
Network options:
575

    
576
@table @option
577

    
578
@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
579
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
580
= 0 is the default). The NIC is an ne2k_pci by default on the PC
581
target. Optionally, the MAC address can be changed. If no
582
@option{-net} option is specified, a single NIC is created.
583
Qemu can emulate several different models of network card.
584
Valid values for @var{type} are
585
@code{i82551}, @code{i82557b}, @code{i82559er},
586
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
587
@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
588
Not all devices are supported on all targets.  Use -net nic,model=?
589
for a list of available devices for your target.
590

    
591
@item -net user[,vlan=@var{n}][,hostname=@var{name}]
592
Use the user mode network stack which requires no administrator
593
privilege to run.  @option{hostname=name} can be used to specify the client
594
hostname reported by the builtin DHCP server.
595

    
596
@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}]
597
Connect the host TAP network interface @var{name} to VLAN @var{n} and
598
use the network script @var{file} to configure it. The default
599
network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
600
disable script execution. If @var{name} is not
601
provided, the OS automatically provides one. @option{fd}=@var{h} can be
602
used to specify the handle of an already opened host TAP interface. Example:
603

    
604
@example
605
qemu linux.img -net nic -net tap
606
@end example
607

    
608
More complicated example (two NICs, each one connected to a TAP device)
609
@example
610
qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
611
               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
612
@end example
613

    
614

    
615
@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
616

    
617
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
618
machine using a TCP socket connection. If @option{listen} is
619
specified, QEMU waits for incoming connections on @var{port}
620
(@var{host} is optional). @option{connect} is used to connect to
621
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
622
specifies an already opened TCP socket.
623

    
624
Example:
625
@example
626
# launch a first QEMU instance
627
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
628
               -net socket,listen=:1234
629
# connect the VLAN 0 of this instance to the VLAN 0
630
# of the first instance
631
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
632
               -net socket,connect=127.0.0.1:1234
633
@end example
634

    
635
@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
636

    
637
Create a VLAN @var{n} shared with another QEMU virtual
638
machines using a UDP multicast socket, effectively making a bus for
639
every QEMU with same multicast address @var{maddr} and @var{port}.
640
NOTES:
641
@enumerate
642
@item
643
Several QEMU can be running on different hosts and share same bus (assuming
644
correct multicast setup for these hosts).
645
@item
646
mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
647
@url{http://user-mode-linux.sf.net}.
648
@item
649
Use @option{fd=h} to specify an already opened UDP multicast socket.
650
@end enumerate
651

    
652
Example:
653
@example
654
# launch one QEMU instance
655
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
656
               -net socket,mcast=230.0.0.1:1234
657
# launch another QEMU instance on same "bus"
658
qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
659
               -net socket,mcast=230.0.0.1:1234
660
# launch yet another QEMU instance on same "bus"
661
qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
662
               -net socket,mcast=230.0.0.1:1234
663
@end example
664

    
665
Example (User Mode Linux compat.):
666
@example
667
# launch QEMU instance (note mcast address selected
668
# is UML's default)
669
qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
670
               -net socket,mcast=239.192.168.1:1102
671
# launch UML
672
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
673
@end example
674

    
675
@item -net none
676
Indicate that no network devices should be configured. It is used to
677
override the default configuration (@option{-net nic -net user}) which
678
is activated if no @option{-net} options are provided.
679

    
680
@item -tftp @var{dir}
681
When using the user mode network stack, activate a built-in TFTP
682
server. The files in @var{dir} will be exposed as the root of a TFTP server.
683
The TFTP client on the guest must be configured in binary mode (use the command
684
@code{bin} of the Unix TFTP client). The host IP address on the guest is as
685
usual 10.0.2.2.
686

    
687
@item -bootp @var{file}
688
When using the user mode network stack, broadcast @var{file} as the BOOTP
689
filename.  In conjunction with @option{-tftp}, this can be used to network boot
690
a guest from a local directory.
691

    
692
Example (using pxelinux):
693
@example
694
qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
695
@end example
696

    
697
@item -smb @var{dir}
698
When using the user mode network stack, activate a built-in SMB
699
server so that Windows OSes can access to the host files in @file{@var{dir}}
700
transparently.
701

    
702
In the guest Windows OS, the line:
703
@example
704
10.0.2.4 smbserver
705
@end example
706
must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
707
or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
708

    
709
Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
710

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

    
715
@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
716

    
717
When using the user mode network stack, redirect incoming TCP or UDP
718
connections to the host port @var{host-port} to the guest
719
@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
720
is not specified, its value is 10.0.2.15 (default address given by the
721
built-in DHCP server).
722

    
723
For example, to redirect host X11 connection from screen 1 to guest
724
screen 0, use the following:
725

    
726
@example
727
# on the host
728
qemu -redir tcp:6001::6000 [...]
729
# this host xterm should open in the guest X11 server
730
xterm -display :1
731
@end example
732

    
733
To redirect telnet connections from host port 5555 to telnet port on
734
the guest, use the following:
735

    
736
@example
737
# on the host
738
qemu -redir tcp:5555::23 [...]
739
telnet localhost 5555
740
@end example
741

    
742
Then when you use on the host @code{telnet localhost 5555}, you
743
connect to the guest telnet server.
744

    
745
@end table
746

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

    
751
@table @option
752

    
753
@item -kernel @var{bzImage}
754
Use @var{bzImage} as kernel image.
755

    
756
@item -append @var{cmdline}
757
Use @var{cmdline} as kernel command line
758

    
759
@item -initrd @var{file}
760
Use @var{file} as initial ram disk.
761

    
762
@end table
763

    
764
Debug/Expert options:
765
@table @option
766

    
767
@item -serial @var{dev}
768
Redirect the virtual serial port to host character device
769
@var{dev}. The default device is @code{vc} in graphical mode and
770
@code{stdio} in non graphical mode.
771

    
772
This option can be used several times to simulate up to 4 serials
773
ports.
774

    
775
Use @code{-serial none} to disable all serial ports.
776

    
777
Available character devices are:
778
@table @code
779
@item vc[:WxH]
780
Virtual console. Optionally, a width and height can be given in pixel with
781
@example
782
vc:800x600
783
@end example
784
It is also possible to specify width or height in characters:
785
@example
786
vc:80Cx24C
787
@end example
788
@item pty
789
[Linux only] Pseudo TTY (a new PTY is automatically allocated)
790
@item none
791
No device is allocated.
792
@item null
793
void device
794
@item /dev/XXX
795
[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
796
parameters are set according to the emulated ones.
797
@item /dev/parport@var{N}
798
[Linux only, parallel port only] Use host parallel port
799
@var{N}. Currently SPP and EPP parallel port features can be used.
800
@item file:@var{filename}
801
Write output to @var{filename}. No character can be read.
802
@item stdio
803
[Unix only] standard input/output
804
@item pipe:@var{filename}
805
name pipe @var{filename}
806
@item COM@var{n}
807
[Windows only] Use host serial port @var{n}
808
@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
809
This implements UDP Net Console.
810
When @var{remote_host} or @var{src_ip} are not specified
811
they default to @code{0.0.0.0}.
812
When not using a specified @var{src_port} a random port is automatically chosen.
813

    
814
If you just want a simple readonly console you can use @code{netcat} or
815
@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
816
@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
817
will appear in the netconsole session.
818

    
819
If you plan to send characters back via netconsole or you want to stop
820
and start qemu a lot of times, you should have qemu use the same
821
source port each time by using something like @code{-serial
822
udp::4555@@:4556} to qemu. Another approach is to use a patched
823
version of netcat which can listen to a TCP port and send and receive
824
characters via udp.  If you have a patched version of netcat which
825
activates telnet remote echo and single char transfer, then you can
826
use the following options to step up a netcat redirector to allow
827
telnet on port 5555 to access the qemu port.
828
@table @code
829
@item Qemu Options:
830
-serial udp::4555@@:4556
831
@item netcat options:
832
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
833
@item telnet options:
834
localhost 5555
835
@end table
836

    
837

    
838
@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
839
The TCP Net Console has two modes of operation.  It can send the serial
840
I/O to a location or wait for a connection from a location.  By default
841
the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
842
the @var{server} option QEMU will wait for a client socket application
843
to connect to the port before continuing, unless the @code{nowait}
844
option was specified.  The @code{nodelay} option disables the Nagle buffering
845
algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
846
one TCP connection at a time is accepted. You can use @code{telnet} to
847
connect to the corresponding character device.
848
@table @code
849
@item Example to send tcp console to 192.168.0.2 port 4444
850
-serial tcp:192.168.0.2:4444
851
@item Example to listen and wait on port 4444 for connection
852
-serial tcp::4444,server
853
@item Example to not wait and listen on ip 192.168.0.100 port 4444
854
-serial tcp:192.168.0.100:4444,server,nowait
855
@end table
856

    
857
@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
858
The telnet protocol is used instead of raw tcp sockets.  The options
859
work the same as if you had specified @code{-serial tcp}.  The
860
difference is that the port acts like a telnet server or client using
861
telnet option negotiation.  This will also allow you to send the
862
MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
863
sequence.  Typically in unix telnet you do it with Control-] and then
864
type "send break" followed by pressing the enter key.
865

    
866
@item unix:@var{path}[,server][,nowait]
867
A unix domain socket is used instead of a tcp socket.  The option works the
868
same as if you had specified @code{-serial tcp} except the unix domain socket
869
@var{path} is used for connections.
870

    
871
@item mon:@var{dev_string}
872
This is a special option to allow the monitor to be multiplexed onto
873
another serial port.  The monitor is accessed with key sequence of
874
@key{Control-a} and then pressing @key{c}. See monitor access
875
@ref{pcsys_keys} in the -nographic section for more keys.
876
@var{dev_string} should be any one of the serial devices specified
877
above.  An example to multiplex the monitor onto a telnet server
878
listening on port 4444 would be:
879
@table @code
880
@item -serial mon:telnet::4444,server,nowait
881
@end table
882

    
883
@item braille
884
Braille device.  This will use BrlAPI to display the braille output on a real
885
or fake device.
886

    
887
@end table
888

    
889
@item -parallel @var{dev}
890
Redirect the virtual parallel port to host device @var{dev} (same
891
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
892
be used to use hardware devices connected on the corresponding host
893
parallel port.
894

    
895
This option can be used several times to simulate up to 3 parallel
896
ports.
897

    
898
Use @code{-parallel none} to disable all parallel ports.
899

    
900
@item -monitor @var{dev}
901
Redirect the monitor to host device @var{dev} (same devices as the
902
serial port).
903
The default device is @code{vc} in graphical mode and @code{stdio} in
904
non graphical mode.
905

    
906
@item -echr numeric_ascii_value
907
Change the escape character used for switching to the monitor when using
908
monitor and serial sharing.  The default is @code{0x01} when using the
909
@code{-nographic} option.  @code{0x01} is equal to pressing
910
@code{Control-a}.  You can select a different character from the ascii
911
control keys where 1 through 26 map to Control-a through Control-z.  For
912
instance you could use the either of the following to change the escape
913
character to Control-t.
914
@table @code
915
@item -echr 0x14
916
@item -echr 20
917
@end table
918

    
919
@item -s
920
Wait gdb connection to port 1234 (@pxref{gdb_usage}).
921
@item -p @var{port}
922
Change gdb connection port.  @var{port} can be either a decimal number
923
to specify a TCP port, or a host device (same devices as the serial port).
924
@item -S
925
Do not start CPU at startup (you must type 'c' in the monitor).
926
@item -d
927
Output log in /tmp/qemu.log
928
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
929
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
930
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
931
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
932
all those parameters. This option is useful for old MS-DOS disk
933
images.
934

    
935
@item -L path
936
Set the directory for the BIOS, VGA BIOS and keymaps.
937

    
938
@item -std-vga
939
Simulate a standard VGA card with Bochs VBE extensions (default is
940
Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
941
VBE extensions (e.g. Windows XP) and if you want to use high
942
resolution modes (>= 1280x1024x16) then you should use this option.
943

    
944
@item -no-acpi
945
Disable ACPI (Advanced Configuration and Power Interface) support. Use
946
it if your guest OS complains about ACPI problems (PC target machine
947
only).
948

    
949
@item -no-reboot
950
Exit instead of rebooting.
951

    
952
@item -no-shutdown
953
Don't exit QEMU on guest shutdown, but instead only stop the emulation.
954
This allows for instance switching to monitor to commit changes to the
955
disk image.
956

    
957
@item -loadvm file
958
Start right away with a saved state (@code{loadvm} in monitor)
959

    
960
@item -semihosting
961
Enable semihosting syscall emulation (ARM and M68K target machines only).
962

    
963
On ARM this implements the "Angel" interface.
964
On M68K this implements the "ColdFire GDB" interface used by libgloss.
965

    
966
Note that this allows guest direct access to the host filesystem,
967
so should only be used with trusted guest OS.
968

    
969
@item -icount [N|auto]
970
Enable virtual instruction counter.  The virtual cpu will execute one
971
instruction every 2^N ns of virtual time.  If @code{auto} is specified
972
then the virtual cpu speed will be automatically adjusted to keep virtual
973
time within a few seconds of real time.
974

    
975
Note that while this option can give deterministic behavior, it does not
976
provide cycle accurate emulation.  Modern CPUs contain superscalar out of
977
order cores with complex cache hierarchies.  The number of instructions
978
executed often has little or no correlation with actual performance.
979
@end table
980

    
981
@c man end
982

    
983
@node pcsys_keys
984
@section Keys
985

    
986
@c man begin OPTIONS
987

    
988
During the graphical emulation, you can use the following keys:
989
@table @key
990
@item Ctrl-Alt-f
991
Toggle full screen
992

    
993
@item Ctrl-Alt-n
994
Switch to virtual console 'n'. Standard console mappings are:
995
@table @emph
996
@item 1
997
Target system display
998
@item 2
999
Monitor
1000
@item 3
1001
Serial port
1002
@end table
1003

    
1004
@item Ctrl-Alt
1005
Toggle mouse and keyboard grab.
1006
@end table
1007

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

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

    
1014
@table @key
1015
@item Ctrl-a h
1016
Print this help
1017
@item Ctrl-a x
1018
Exit emulator
1019
@item Ctrl-a s
1020
Save disk data back to file (if -snapshot)
1021
@item Ctrl-a t
1022
toggle console timestamps
1023
@item Ctrl-a b
1024
Send break (magic sysrq in Linux)
1025
@item Ctrl-a c
1026
Switch between console and monitor
1027
@item Ctrl-a Ctrl-a
1028
Send Ctrl-a
1029
@end table
1030
@c man end
1031

    
1032
@ignore
1033

    
1034
@c man begin SEEALSO
1035
The HTML documentation of QEMU for more precise information and Linux
1036
user mode emulator invocation.
1037
@c man end
1038

    
1039
@c man begin AUTHOR
1040
Fabrice Bellard
1041
@c man end
1042

    
1043
@end ignore
1044

    
1045
@node pcsys_monitor
1046
@section QEMU Monitor
1047

    
1048
The QEMU monitor is used to give complex commands to the QEMU
1049
emulator. You can use it to:
1050

    
1051
@itemize @minus
1052

    
1053
@item
1054
Remove or insert removable media images
1055
(such as CD-ROM or floppies).
1056

    
1057
@item
1058
Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
1059
from a disk file.
1060

    
1061
@item Inspect the VM state without an external debugger.
1062

    
1063
@end itemize
1064

    
1065
@subsection Commands
1066

    
1067
The following commands are available:
1068

    
1069
@table @option
1070

    
1071
@item help or ? [@var{cmd}]
1072
Show the help for all commands or just for command @var{cmd}.
1073

    
1074
@item commit
1075
Commit changes to the disk images (if -snapshot is used).
1076

    
1077
@item info @var{subcommand}
1078
Show various information about the system state.
1079

    
1080
@table @option
1081
@item info network
1082
show the various VLANs and the associated devices
1083
@item info block
1084
show the block devices
1085
@item info registers
1086
show the cpu registers
1087
@item info history
1088
show the command line history
1089
@item info pci
1090
show emulated PCI device
1091
@item info usb
1092
show USB devices plugged on the virtual USB hub
1093
@item info usbhost
1094
show all USB host devices
1095
@item info capture
1096
show information about active capturing
1097
@item info snapshots
1098
show list of VM snapshots
1099
@item info mice
1100
show which guest mouse is receiving events
1101
@end table
1102

    
1103
@item q or quit
1104
Quit the emulator.
1105

    
1106
@item eject [-f] @var{device}
1107
Eject a removable medium (use -f to force it).
1108

    
1109
@item change @var{device} @var{setting}
1110

    
1111
Change the configuration of a device.
1112

    
1113
@table @option
1114
@item change @var{diskdevice} @var{filename}
1115
Change the medium for a removable disk device to point to @var{filename}. eg
1116

    
1117
@example
1118
(qemu) change ide1-cd0 /path/to/some.iso
1119
@end example
1120

    
1121
@item change vnc @var{display},@var{options}
1122
Change the configuration of the VNC server. The valid syntax for @var{display}
1123
and @var{options} are described at @ref{sec_invocation}. eg
1124

    
1125
@example
1126
(qemu) change vnc localhost:1
1127
@end example
1128

    
1129
@item change vnc password
1130

    
1131
Change the password associated with the VNC server. The monitor will prompt for
1132
the new password to be entered. VNC passwords are only significant upto 8 letters.
1133
eg.
1134

    
1135
@example
1136
(qemu) change vnc password
1137
Password: ********
1138
@end example
1139

    
1140
@end table
1141

    
1142
@item screendump @var{filename}
1143
Save screen into PPM image @var{filename}.
1144

    
1145
@item mouse_move @var{dx} @var{dy} [@var{dz}]
1146
Move the active mouse to the specified coordinates @var{dx} @var{dy}
1147
with optional scroll axis @var{dz}.
1148

    
1149
@item mouse_button @var{val}
1150
Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1151

    
1152
@item mouse_set @var{index}
1153
Set which mouse device receives events at given @var{index}, index
1154
can be obtained with
1155
@example
1156
info mice
1157
@end example
1158

    
1159
@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
1160
Capture audio into @var{filename}. Using sample rate @var{frequency}
1161
bits per sample @var{bits} and number of channels @var{channels}.
1162

    
1163
Defaults:
1164
@itemize @minus
1165
@item Sample rate = 44100 Hz - CD quality
1166
@item Bits = 16
1167
@item Number of channels = 2 - Stereo
1168
@end itemize
1169

    
1170
@item stopcapture @var{index}
1171
Stop capture with a given @var{index}, index can be obtained with
1172
@example
1173
info capture
1174
@end example
1175

    
1176
@item log @var{item1}[,...]
1177
Activate logging of the specified items to @file{/tmp/qemu.log}.
1178

    
1179
@item savevm [@var{tag}|@var{id}]
1180
Create a snapshot of the whole virtual machine. If @var{tag} is
1181
provided, it is used as human readable identifier. If there is already
1182
a snapshot with the same tag or ID, it is replaced. More info at
1183
@ref{vm_snapshots}.
1184

    
1185
@item loadvm @var{tag}|@var{id}
1186
Set the whole virtual machine to the snapshot identified by the tag
1187
@var{tag} or the unique snapshot ID @var{id}.
1188

    
1189
@item delvm @var{tag}|@var{id}
1190
Delete the snapshot identified by @var{tag} or @var{id}.
1191

    
1192
@item stop
1193
Stop emulation.
1194

    
1195
@item c or cont
1196
Resume emulation.
1197

    
1198
@item gdbserver [@var{port}]
1199
Start gdbserver session (default @var{port}=1234)
1200

    
1201
@item x/fmt @var{addr}
1202
Virtual memory dump starting at @var{addr}.
1203

    
1204
@item xp /@var{fmt} @var{addr}
1205
Physical memory dump starting at @var{addr}.
1206

    
1207
@var{fmt} is a format which tells the command how to format the
1208
data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1209

    
1210
@table @var
1211
@item count
1212
is the number of items to be dumped.
1213

    
1214
@item format
1215
can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
1216
c (char) or i (asm instruction).
1217

    
1218
@item size
1219
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1220
@code{h} or @code{w} can be specified with the @code{i} format to
1221
respectively select 16 or 32 bit code instruction size.
1222

    
1223
@end table
1224

    
1225
Examples:
1226
@itemize
1227
@item
1228
Dump 10 instructions at the current instruction pointer:
1229
@example
1230
(qemu) x/10i $eip
1231
0x90107063:  ret
1232
0x90107064:  sti
1233
0x90107065:  lea    0x0(%esi,1),%esi
1234
0x90107069:  lea    0x0(%edi,1),%edi
1235
0x90107070:  ret
1236
0x90107071:  jmp    0x90107080
1237
0x90107073:  nop
1238
0x90107074:  nop
1239
0x90107075:  nop
1240
0x90107076:  nop
1241
@end example
1242

    
1243
@item
1244
Dump 80 16 bit values at the start of the video memory.
1245
@smallexample
1246
(qemu) xp/80hx 0xb8000
1247
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
1248
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
1249
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
1250
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
1251
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
1252
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
1253
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1254
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1255
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1256
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1257
@end smallexample
1258
@end itemize
1259

    
1260
@item p or print/@var{fmt} @var{expr}
1261

    
1262
Print expression value. Only the @var{format} part of @var{fmt} is
1263
used.
1264

    
1265
@item sendkey @var{keys}
1266

    
1267
Send @var{keys} to the emulator. Use @code{-} to press several keys
1268
simultaneously. Example:
1269
@example
1270
sendkey ctrl-alt-f1
1271
@end example
1272

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

    
1276
@item system_reset
1277

    
1278
Reset the system.
1279

    
1280
@item boot_set @var{bootdevicelist}
1281

    
1282
Define new values for the boot device list. Those values will override
1283
the values specified on the command line through the @code{-boot} option.
1284

    
1285
The values that can be specified here depend on the machine type, but are
1286
the same that can be specified in the @code{-boot} command line option.
1287

    
1288
@item usb_add @var{devname}
1289

    
1290
Add the USB device @var{devname}.  For details of available devices see
1291
@ref{usb_devices}
1292

    
1293
@item usb_del @var{devname}
1294

    
1295
Remove the USB device @var{devname} from the QEMU virtual USB
1296
hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1297
command @code{info usb} to see the devices you can remove.
1298

    
1299
@end table
1300

    
1301
@subsection Integer expressions
1302

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

    
1307
@node disk_images
1308
@section Disk Images
1309

    
1310
Since version 0.6.1, QEMU supports many disk image formats, including
1311
growable disk images (their size increase as non empty sectors are
1312
written), compressed and encrypted disk images. Version 0.8.3 added
1313
the new qcow2 disk image format which is essential to support VM
1314
snapshots.
1315

    
1316
@menu
1317
* disk_images_quickstart::    Quick start for disk image creation
1318
* disk_images_snapshot_mode:: Snapshot mode
1319
* vm_snapshots::              VM snapshots
1320
* qemu_img_invocation::       qemu-img Invocation
1321
* qemu_nbd_invocation::       qemu-nbd Invocation
1322
* host_drives::               Using host drives
1323
* disk_images_fat_images::    Virtual FAT disk images
1324
* disk_images_nbd::           NBD access
1325
@end menu
1326

    
1327
@node disk_images_quickstart
1328
@subsection Quick start for disk image creation
1329

    
1330
You can create a disk image with the command:
1331
@example
1332
qemu-img create myimage.img mysize
1333
@end example
1334
where @var{myimage.img} is the disk image filename and @var{mysize} is its
1335
size in kilobytes. You can add an @code{M} suffix to give the size in
1336
megabytes and a @code{G} suffix for gigabytes.
1337

    
1338
See @ref{qemu_img_invocation} for more information.
1339

    
1340
@node disk_images_snapshot_mode
1341
@subsection Snapshot mode
1342

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

    
1349
@node vm_snapshots
1350
@subsection VM snapshots
1351

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

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

    
1362
Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1363
a VM snapshot. @code{info snapshots} lists the available snapshots
1364
with their associated information:
1365

    
1366
@example
1367
(qemu) info snapshots
1368
Snapshot devices: hda
1369
Snapshot list (from hda):
1370
ID        TAG                 VM SIZE                DATE       VM CLOCK
1371
1         start                   41M 2006-08-06 12:38:02   00:00:14.954
1372
2                                 40M 2006-08-06 12:43:29   00:00:18.633
1373
3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
1374
@end example
1375

    
1376
A VM snapshot is made of a VM state info (its size is shown in
1377
@code{info snapshots}) and a snapshot of every writable disk image.
1378
The VM state info is stored in the first @code{qcow2} non removable
1379
and writable block device. The disk image snapshots are stored in
1380
every disk image. The size of a snapshot in a disk image is difficult
1381
to evaluate and is not shown by @code{info snapshots} because the
1382
associated disk sectors are shared among all the snapshots to save
1383
disk space (otherwise each snapshot would need a full copy of all the
1384
disk images).
1385

    
1386
When using the (unrelated) @code{-snapshot} option
1387
(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1388
but they are deleted as soon as you exit QEMU.
1389

    
1390
VM snapshots currently have the following known limitations:
1391
@itemize
1392
@item
1393
They cannot cope with removable devices if they are removed or
1394
inserted after a snapshot is done.
1395
@item
1396
A few device drivers still have incomplete snapshot support so their
1397
state is not saved or restored properly (in particular USB).
1398
@end itemize
1399

    
1400
@node qemu_img_invocation
1401
@subsection @code{qemu-img} Invocation
1402

    
1403
@include qemu-img.texi
1404

    
1405
@node qemu_nbd_invocation
1406
@subsection @code{qemu-nbd} Invocation
1407

    
1408
@include qemu-nbd.texi
1409

    
1410
@node host_drives
1411
@subsection Using host drives
1412

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

    
1416
@subsubsection Linux
1417

    
1418
On Linux, you can directly use the host device filename instead of a
1419
disk image filename provided you have enough privileges to access
1420
it. For example, use @file{/dev/cdrom} to access to the CDROM or
1421
@file{/dev/fd0} for the floppy.
1422

    
1423
@table @code
1424
@item CD
1425
You can specify a CDROM device even if no CDROM is loaded. QEMU has
1426
specific code to detect CDROM insertion or removal. CDROM ejection by
1427
the guest OS is supported. Currently only data CDs are supported.
1428
@item Floppy
1429
You can specify a floppy device even if no floppy is loaded. Floppy
1430
removal is currently not detected accurately (if you change floppy
1431
without doing floppy access while the floppy is not loaded, the guest
1432
OS will think that the same floppy is loaded).
1433
@item Hard disks
1434
Hard disks can be used. Normally you must specify the whole disk
1435
(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1436
see it as a partitioned disk. WARNING: unless you know what you do, it
1437
is better to only make READ-ONLY accesses to the hard disk otherwise
1438
you may corrupt your host data (use the @option{-snapshot} command
1439
line option or modify the device permissions accordingly).
1440
@end table
1441

    
1442
@subsubsection Windows
1443

    
1444
@table @code
1445
@item CD
1446
The preferred syntax is the drive letter (e.g. @file{d:}). The
1447
alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1448
supported as an alias to the first CDROM drive.
1449

    
1450
Currently there is no specific code to handle removable media, so it
1451
is better to use the @code{change} or @code{eject} monitor commands to
1452
change or eject media.
1453
@item Hard disks
1454
Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
1455
where @var{N} is the drive number (0 is the first hard disk).
1456

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

    
1463

    
1464
@subsubsection Mac OS X
1465

    
1466
@file{/dev/cdrom} is an alias to the first CDROM.
1467

    
1468
Currently there is no specific code to handle removable media, so it
1469
is better to use the @code{change} or @code{eject} monitor commands to
1470
change or eject media.
1471

    
1472
@node disk_images_fat_images
1473
@subsection Virtual FAT disk images
1474

    
1475
QEMU can automatically create a virtual FAT disk image from a
1476
directory tree. In order to use it, just type:
1477

    
1478
@example
1479
qemu linux.img -hdb fat:/my_directory
1480
@end example
1481

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

    
1486
Floppies can be emulated with the @code{:floppy:} option:
1487

    
1488
@example
1489
qemu linux.img -fda fat:floppy:/my_directory
1490
@end example
1491

    
1492
A read/write support is available for testing (beta stage) with the
1493
@code{:rw:} option:
1494

    
1495
@example
1496
qemu linux.img -fda fat:floppy:rw:/my_directory
1497
@end example
1498

    
1499
What you should @emph{never} do:
1500
@itemize
1501
@item use non-ASCII filenames ;
1502
@item use "-snapshot" together with ":rw:" ;
1503
@item expect it to work when loadvm'ing ;
1504
@item write to the FAT directory on the host system while accessing it with the guest system.
1505
@end itemize
1506

    
1507
@node disk_images_nbd
1508
@subsection NBD access
1509

    
1510
QEMU can access directly to block device exported using the Network Block Device
1511
protocol.
1512

    
1513
@example
1514
qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
1515
@end example
1516

    
1517
If the NBD server is located on the same host, you can use an unix socket instead
1518
of an inet socket:
1519

    
1520
@example
1521
qemu linux.img -hdb nbd:unix:/tmp/my_socket
1522
@end example
1523

    
1524
In this case, the block device must be exported using qemu-nbd:
1525

    
1526
@example
1527
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
1528
@end example
1529

    
1530
The use of qemu-nbd allows to share a disk between several guests:
1531
@example
1532
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
1533
@end example
1534

    
1535
and then you can use it with two guests:
1536
@example
1537
qemu linux1.img -hdb nbd:unix:/tmp/my_socket
1538
qemu linux2.img -hdb nbd:unix:/tmp/my_socket
1539
@end example
1540

    
1541
@node pcsys_network
1542
@section Network emulation
1543

    
1544
QEMU can simulate several network cards (PCI or ISA cards on the PC
1545
target) and can connect them to an arbitrary number of Virtual Local
1546
Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1547
VLAN. VLAN can be connected between separate instances of QEMU to
1548
simulate large networks. For simpler usage, a non privileged user mode
1549
network stack can replace the TAP device to have a basic network
1550
connection.
1551

    
1552
@subsection VLANs
1553

    
1554
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1555
connection between several network devices. These devices can be for
1556
example QEMU virtual Ethernet cards or virtual Host ethernet devices
1557
(TAP devices).
1558

    
1559
@subsection Using TAP network interfaces
1560

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

    
1565
@subsubsection Linux host
1566

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

    
1574
See @ref{sec_invocation} to have examples of command lines using the
1575
TAP network interfaces.
1576

    
1577
@subsubsection Windows host
1578

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

    
1584
@subsection Using the user mode network stack
1585

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

    
1591
@example
1592

    
1593
         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
1594
                           |          (10.0.2.2)
1595
                           |
1596
                           ---->  DNS server (10.0.2.3)
1597
                           |
1598
                           ---->  SMB server (10.0.2.4)
1599
@end example
1600

    
1601
The QEMU VM behaves as if it was behind a firewall which blocks all
1602
incoming connections. You can use a DHCP client to automatically
1603
configure the network in the QEMU VM. The DHCP server assign addresses
1604
to the hosts starting from 10.0.2.15.
1605

    
1606
In order to check that the user mode network is working, you can ping
1607
the address 10.0.2.2 and verify that you got an address in the range
1608
10.0.2.x from the QEMU virtual DHCP server.
1609

    
1610
Note that @code{ping} is not supported reliably to the internet as it
1611
would require root privileges. It means you can only ping the local
1612
router (10.0.2.2).
1613

    
1614
When using the built-in TFTP server, the router is also the TFTP
1615
server.
1616

    
1617
When using the @option{-redir} option, TCP or UDP connections can be
1618
redirected from the host to the guest. It allows for example to
1619
redirect X11, telnet or SSH connections.
1620

    
1621
@subsection Connecting VLANs between QEMU instances
1622

    
1623
Using the @option{-net socket} option, it is possible to make VLANs
1624
that span several QEMU instances. See @ref{sec_invocation} to have a
1625
basic example.
1626

    
1627
@node direct_linux_boot
1628
@section Direct Linux Boot
1629

    
1630
This section explains how to launch a Linux kernel inside QEMU without
1631
having to make a full bootable image. It is very useful for fast Linux
1632
kernel testing.
1633

    
1634
The syntax is:
1635
@example
1636
qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1637
@end example
1638

    
1639
Use @option{-kernel} to provide the Linux kernel image and
1640
@option{-append} to give the kernel command line arguments. The
1641
@option{-initrd} option can be used to provide an INITRD image.
1642

    
1643
When using the direct Linux boot, a disk image for the first hard disk
1644
@file{hda} is required because its boot sector is used to launch the
1645
Linux kernel.
1646

    
1647
If you do not need graphical output, you can disable it and redirect
1648
the virtual serial port and the QEMU monitor to the console with the
1649
@option{-nographic} option. The typical command line is:
1650
@example
1651
qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1652
     -append "root=/dev/hda console=ttyS0" -nographic
1653
@end example
1654

    
1655
Use @key{Ctrl-a c} to switch between the serial console and the
1656
monitor (@pxref{pcsys_keys}).
1657

    
1658
@node pcsys_usb
1659
@section USB emulation
1660

    
1661
QEMU emulates a PCI UHCI USB controller. You can virtually plug
1662
virtual USB devices or real host USB devices (experimental, works only
1663
on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1664
as necessary to connect multiple USB devices.
1665

    
1666
@menu
1667
* usb_devices::
1668
* host_usb_devices::
1669
@end menu
1670
@node usb_devices
1671
@subsection Connecting USB devices
1672

    
1673
USB devices can be connected with the @option{-usbdevice} commandline option
1674
or the @code{usb_add} monitor command.  Available devices are:
1675

    
1676
@table @code
1677
@item mouse
1678
Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1679
@item tablet
1680
Pointer device that uses absolute coordinates (like a touchscreen).
1681
This means qemu is able to report the mouse position without having
1682
to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1683
@item disk:@var{file}
1684
Mass storage device based on @var{file} (@pxref{disk_images})
1685
@item host:@var{bus.addr}
1686
Pass through the host device identified by @var{bus.addr}
1687
(Linux only)
1688
@item host:@var{vendor_id:product_id}
1689
Pass through the host device identified by @var{vendor_id:product_id}
1690
(Linux only)
1691
@item wacom-tablet
1692
Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1693
above but it can be used with the tslib library because in addition to touch
1694
coordinates it reports touch pressure.
1695
@item keyboard
1696
Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1697
@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1698
Serial converter. This emulates an FTDI FT232BM chip connected to host character
1699
device @var{dev}. The available character devices are the same as for the
1700
@code{-serial} option. The @code{vendorid} and @code{productid} options can be
1701
used to override the default 0403:6001. For instance, 
1702
@example
1703
usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1704
@end example
1705
will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1706
serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
1707
@item braille
1708
Braille device.  This will use BrlAPI to display the braille output on a real
1709
or fake device.
1710
@end table
1711

    
1712
@node host_usb_devices
1713
@subsection Using host USB devices on a Linux host
1714

    
1715
WARNING: this is an experimental feature. QEMU will slow down when
1716
using it. USB devices requiring real time streaming (i.e. USB Video
1717
Cameras) are not supported yet.
1718

    
1719
@enumerate
1720
@item If you use an early Linux 2.4 kernel, verify that no Linux driver
1721
is actually using the USB device. A simple way to do that is simply to
1722
disable the corresponding kernel module by renaming it from @file{mydriver.o}
1723
to @file{mydriver.o.disabled}.
1724

    
1725
@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1726
@example
1727
ls /proc/bus/usb
1728
001  devices  drivers
1729
@end example
1730

    
1731
@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:
1732
@example
1733
chown -R myuid /proc/bus/usb
1734
@end example
1735

    
1736
@item Launch QEMU and do in the monitor:
1737
@example
1738
info usbhost
1739
  Device 1.2, speed 480 Mb/s
1740
    Class 00: USB device 1234:5678, USB DISK
1741
@end example
1742
You should see the list of the devices you can use (Never try to use
1743
hubs, it won't work).
1744

    
1745
@item Add the device in QEMU by using:
1746
@example
1747
usb_add host:1234:5678
1748
@end example
1749

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

    
1753
@item Now you can try to use the host USB device in QEMU.
1754

    
1755
@end enumerate
1756

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

    
1760
@node vnc_security
1761
@section VNC security
1762

    
1763
The VNC server capability provides access to the graphical console
1764
of the guest VM across the network. This has a number of security
1765
considerations depending on the deployment scenarios.
1766

    
1767
@menu
1768
* vnc_sec_none::
1769
* vnc_sec_password::
1770
* vnc_sec_certificate::
1771
* vnc_sec_certificate_verify::
1772
* vnc_sec_certificate_pw::
1773
* vnc_generate_cert::
1774
@end menu
1775
@node vnc_sec_none
1776
@subsection Without passwords
1777

    
1778
The simplest VNC server setup does not include any form of authentication.
1779
For this setup it is recommended to restrict it to listen on a UNIX domain
1780
socket only. For example
1781

    
1782
@example
1783
qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1784
@end example
1785

    
1786
This ensures that only users on local box with read/write access to that
1787
path can access the VNC server. To securely access the VNC server from a
1788
remote machine, a combination of netcat+ssh can be used to provide a secure
1789
tunnel.
1790

    
1791
@node vnc_sec_password
1792
@subsection With passwords
1793

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

    
1803
@example
1804
qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1805
(qemu) change vnc password
1806
Password: ********
1807
(qemu)
1808
@end example
1809

    
1810
@node vnc_sec_certificate
1811
@subsection With x509 certificates
1812

    
1813
The QEMU VNC server also implements the VeNCrypt extension allowing use of
1814
TLS for encryption of the session, and x509 certificates for authentication.
1815
The use of x509 certificates is strongly recommended, because TLS on its
1816
own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1817
support provides a secure session, but no authentication. This allows any
1818
client to connect, and provides an encrypted session.
1819

    
1820
@example
1821
qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1822
@end example
1823

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

    
1830
@node vnc_sec_certificate_verify
1831
@subsection With x509 certificates and client verification
1832

    
1833
Certificates can also provide a means to authenticate the client connecting.
1834
The server will request that the client provide a certificate, which it will
1835
then validate against the CA certificate. This is a good choice if deploying
1836
in an environment with a private internal certificate authority.
1837

    
1838
@example
1839
qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1840
@end example
1841

    
1842

    
1843
@node vnc_sec_certificate_pw
1844
@subsection With x509 certificates, client verification and passwords
1845

    
1846
Finally, the previous method can be combined with VNC password authentication
1847
to provide two layers of authentication for clients.
1848

    
1849
@example
1850
qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1851
(qemu) change vnc password
1852
Password: ********
1853
(qemu)
1854
@end example
1855

    
1856
@node vnc_generate_cert
1857
@subsection Generating certificates for VNC
1858

    
1859
The GNU TLS packages provides a command called @code{certtool} which can
1860
be used to generate certificates and keys in PEM format. At a minimum it
1861
is neccessary to setup a certificate authority, and issue certificates to
1862
each server. If using certificates for authentication, then each client
1863
will also need to be issued a certificate. The recommendation is for the
1864
server to keep its certificates in either @code{/etc/pki/qemu} or for
1865
unprivileged users in @code{$HOME/.pki/qemu}.
1866

    
1867
@menu
1868
* vnc_generate_ca::
1869
* vnc_generate_server::
1870
* vnc_generate_client::
1871
@end menu
1872
@node vnc_generate_ca
1873
@subsubsection Setup the Certificate Authority
1874

    
1875
This step only needs to be performed once per organization / organizational
1876
unit. First the CA needs a private key. This key must be kept VERY secret
1877
and secure. If this key is compromised the entire trust chain of the certificates
1878
issued with it is lost.
1879

    
1880
@example
1881
# certtool --generate-privkey > ca-key.pem
1882
@end example
1883

    
1884
A CA needs to have a public certificate. For simplicity it can be a self-signed
1885
certificate, or one issue by a commercial certificate issuing authority. To
1886
generate a self-signed certificate requires one core piece of information, the
1887
name of the organization.
1888

    
1889
@example
1890
# cat > ca.info <<EOF
1891
cn = Name of your organization
1892
ca
1893
cert_signing_key
1894
EOF
1895
# certtool --generate-self-signed \
1896
           --load-privkey ca-key.pem
1897
           --template ca.info \
1898
           --outfile ca-cert.pem
1899
@end example
1900

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

    
1904
@node vnc_generate_server
1905
@subsubsection Issuing server certificates
1906

    
1907
Each server (or host) needs to be issued with a key and certificate. When connecting
1908
the certificate is sent to the client which validates it against the CA certificate.
1909
The core piece of information for a server certificate is the hostname. This should
1910
be the fully qualified hostname that the client will connect with, since the client
1911
will typically also verify the hostname in the certificate. On the host holding the
1912
secure CA private key:
1913

    
1914
@example
1915
# cat > server.info <<EOF
1916
organization = Name  of your organization
1917
cn = server.foo.example.com
1918
tls_www_server
1919
encryption_key
1920
signing_key
1921
EOF
1922
# certtool --generate-privkey > server-key.pem
1923
# certtool --generate-certificate \
1924
           --load-ca-certificate ca-cert.pem \
1925
           --load-ca-privkey ca-key.pem \
1926
           --load-privkey server server-key.pem \
1927
           --template server.info \
1928
           --outfile server-cert.pem
1929
@end example
1930

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

    
1935
@node vnc_generate_client
1936
@subsubsection Issuing client certificates
1937

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

    
1944
@example
1945
# cat > client.info <<EOF
1946
country = GB
1947
state = London
1948
locality = London
1949
organiazation = Name of your organization
1950
cn = client.foo.example.com
1951
tls_www_client
1952
encryption_key
1953
signing_key
1954
EOF
1955
# certtool --generate-privkey > client-key.pem
1956
# certtool --generate-certificate \
1957
           --load-ca-certificate ca-cert.pem \
1958
           --load-ca-privkey ca-key.pem \
1959
           --load-privkey client-key.pem \
1960
           --template client.info \
1961
           --outfile client-cert.pem
1962
@end example
1963

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

    
1967
@node gdb_usage
1968
@section GDB usage
1969

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

    
1973
In order to use gdb, launch qemu with the '-s' option. It will wait for a
1974
gdb connection:
1975
@example
1976
> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1977
       -append "root=/dev/hda"
1978
Connected to host network interface: tun0
1979
Waiting gdb connection on port 1234
1980
@end example
1981

    
1982
Then launch gdb on the 'vmlinux' executable:
1983
@example
1984
> gdb vmlinux
1985
@end example
1986

    
1987
In gdb, connect to QEMU:
1988
@example
1989
(gdb) target remote localhost:1234
1990
@end example
1991

    
1992
Then you can use gdb normally. For example, type 'c' to launch the kernel:
1993
@example
1994
(gdb) c
1995
@end example
1996

    
1997
Here are some useful tips in order to use gdb on system code:
1998

    
1999
@enumerate
2000
@item
2001
Use @code{info reg} to display all the CPU registers.
2002
@item
2003
Use @code{x/10i $eip} to display the code at the PC position.
2004
@item
2005
Use @code{set architecture i8086} to dump 16 bit code. Then use
2006
@code{x/10i $cs*16+$eip} to dump the code at the PC position.
2007
@end enumerate
2008

    
2009
Advanced debugging options:
2010

    
2011
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:
2012
@table @code
2013
@item maintenance packet qqemu.sstepbits
2014

    
2015
This will display the MASK bits used to control the single stepping IE:
2016
@example
2017
(gdb) maintenance packet qqemu.sstepbits
2018
sending: "qqemu.sstepbits"
2019
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
2020
@end example
2021
@item maintenance packet qqemu.sstep
2022

    
2023
This will display the current value of the mask used when single stepping IE:
2024
@example
2025
(gdb) maintenance packet qqemu.sstep
2026
sending: "qqemu.sstep"
2027
received: "0x7"
2028
@end example
2029
@item maintenance packet Qqemu.sstep=HEX_VALUE
2030

    
2031
This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
2032
@example
2033
(gdb) maintenance packet Qqemu.sstep=0x5
2034
sending: "qemu.sstep=0x5"
2035
received: "OK"
2036
@end example
2037
@end table
2038

    
2039
@node pcsys_os_specific
2040
@section Target OS specific information
2041

    
2042
@subsection Linux
2043

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

    
2048
When using a 2.6 guest Linux kernel, you should add the option
2049
@code{clock=pit} on the kernel command line because the 2.6 Linux
2050
kernels make very strict real time clock checks by default that QEMU
2051
cannot simulate exactly.
2052

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

    
2059
@subsection Windows
2060

    
2061
If you have a slow host, using Windows 95 is better as it gives the
2062
best speed. Windows 2000 is also a good choice.
2063

    
2064
@subsubsection SVGA graphic modes support
2065

    
2066
QEMU emulates a Cirrus Logic GD5446 Video
2067
card. All Windows versions starting from Windows 95 should recognize
2068
and use this graphic card. For optimal performances, use 16 bit color
2069
depth in the guest and the host OS.
2070

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

    
2076
@subsubsection CPU usage reduction
2077

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

    
2084
@subsubsection Windows 2000 disk full problem
2085

    
2086
Windows 2000 has a bug which gives a disk full problem during its
2087
installation. When installing it, use the @option{-win2k-hack} QEMU
2088
option to enable a specific workaround. After Windows 2000 is
2089
installed, you no longer need this option (this option slows down the
2090
IDE transfers).
2091

    
2092
@subsubsection Windows 2000 shutdown
2093

    
2094
Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2095
can. It comes from the fact that Windows 2000 does not automatically
2096
use the APM driver provided by the BIOS.
2097

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

    
2105
@subsubsection Share a directory between Unix and Windows
2106

    
2107
See @ref{sec_invocation} about the help of the option @option{-smb}.
2108

    
2109
@subsubsection Windows XP security problem
2110

    
2111
Some releases of Windows XP install correctly but give a security
2112
error when booting:
2113
@example
2114
A problem is preventing Windows from accurately checking the
2115
license for this computer. Error code: 0x800703e6.
2116
@end example
2117

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

    
2124
@subsection MS-DOS and FreeDOS
2125

    
2126
@subsubsection CPU usage reduction
2127

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

    
2133
@node QEMU System emulator for non PC targets
2134
@chapter QEMU System emulator for non PC targets
2135

    
2136
QEMU is a generic emulator and it emulates many non PC
2137
machines. Most of the options are similar to the PC emulator. The
2138
differences are mentioned in the following sections.
2139

    
2140
@menu
2141
* QEMU PowerPC System emulator::
2142
* Sparc32 System emulator::
2143
* Sparc64 System emulator::
2144
* MIPS System emulator::
2145
* ARM System emulator::
2146
* ColdFire System emulator::
2147
@end menu
2148

    
2149
@node QEMU PowerPC System emulator
2150
@section QEMU PowerPC System emulator
2151

    
2152
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
2153
or PowerMac PowerPC system.
2154

    
2155
QEMU emulates the following PowerMac peripherals:
2156

    
2157
@itemize @minus
2158
@item
2159
UniNorth PCI Bridge
2160
@item
2161
PCI VGA compatible card with VESA Bochs Extensions
2162
@item
2163
2 PMAC IDE interfaces with hard disk and CD-ROM support
2164
@item
2165
NE2000 PCI adapters
2166
@item
2167
Non Volatile RAM
2168
@item
2169
VIA-CUDA with ADB keyboard and mouse.
2170
@end itemize
2171

    
2172
QEMU emulates the following PREP peripherals:
2173

    
2174
@itemize @minus
2175
@item
2176
PCI Bridge
2177
@item
2178
PCI VGA compatible card with VESA Bochs Extensions
2179
@item
2180
2 IDE interfaces with hard disk and CD-ROM support
2181
@item
2182
Floppy disk
2183
@item
2184
NE2000 network adapters
2185
@item
2186
Serial port
2187
@item
2188
PREP Non Volatile RAM
2189
@item
2190
PC compatible keyboard and mouse.
2191
@end itemize
2192

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

    
2196
@c man begin OPTIONS
2197

    
2198
The following options are specific to the PowerPC emulation:
2199

    
2200
@table @option
2201

    
2202
@item -g WxH[xDEPTH]
2203

    
2204
Set the initial VGA graphic mode. The default is 800x600x15.
2205

    
2206
@end table
2207

    
2208
@c man end
2209

    
2210

    
2211
More information is available at
2212
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
2213

    
2214
@node Sparc32 System emulator
2215
@section Sparc32 System emulator
2216

    
2217
Use the executable @file{qemu-system-sparc} to simulate a SPARCstation
2218
5, SPARCstation 10, SPARCstation 20, SPARCserver 600MP (sun4m
2219
architecture), SPARCstation 2 (sun4c architecture), SPARCserver 1000,
2220
or SPARCcenter 2000 (sun4d architecture). The emulation is somewhat
2221
complete.  SMP up to 16 CPUs is supported, but Linux limits the number
2222
of usable CPUs to 4.
2223

    
2224
QEMU emulates the following sun4m/sun4d peripherals:
2225

    
2226
@itemize @minus
2227
@item
2228
IOMMU or IO-UNITs
2229
@item
2230
TCX Frame buffer
2231
@item
2232
Lance (Am7990) Ethernet
2233
@item
2234
Non Volatile RAM M48T08
2235
@item
2236
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2237
and power/reset logic
2238
@item
2239
ESP SCSI controller with hard disk and CD-ROM support
2240
@item
2241
Floppy drive (not on SS-600MP)
2242
@item
2243
CS4231 sound device (only on SS-5, not working yet)
2244
@end itemize
2245

    
2246
The number of peripherals is fixed in the architecture.  Maximum
2247
memory size depends on the machine type, for SS-5 it is 256MB and for
2248
others 2047MB.
2249

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

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

    
2259
@c man begin OPTIONS
2260

    
2261
The following options are specific to the Sparc32 emulation:
2262

    
2263
@table @option
2264

    
2265
@item -g WxHx[xDEPTH]
2266

    
2267
Set the initial TCX graphic mode. The default is 1024x768x8, currently
2268
the only other possible mode is 1024x768x24.
2269

    
2270
@item -prom-env string
2271

    
2272
Set OpenBIOS variables in NVRAM, for example:
2273

    
2274
@example
2275
qemu-system-sparc -prom-env 'auto-boot?=false' \
2276
 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2277
@end example
2278

    
2279
@item -M [SS-5|SS-10|SS-20|SS-600MP|SS-2|SS-1000|SS-2000]
2280

    
2281
Set the emulated machine type. Default is SS-5.
2282

    
2283
@end table
2284

    
2285
@c man end
2286

    
2287
@node Sparc64 System emulator
2288
@section Sparc64 System emulator
2289

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

    
2293
QEMU emulates the following sun4u peripherals:
2294

    
2295
@itemize @minus
2296
@item
2297
UltraSparc IIi APB PCI Bridge
2298
@item
2299
PCI VGA compatible card with VESA Bochs Extensions
2300
@item
2301
Non Volatile RAM M48T59
2302
@item
2303
PC-compatible serial ports
2304
@end itemize
2305

    
2306
@node MIPS System emulator
2307
@section MIPS System emulator
2308

    
2309
Four executables cover simulation of 32 and 64-bit MIPS systems in
2310
both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2311
@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2312
Five different machine types are emulated:
2313

    
2314
@itemize @minus
2315
@item
2316
A generic ISA PC-like machine "mips"
2317
@item
2318
The MIPS Malta prototype board "malta"
2319
@item
2320
An ACER Pica "pica61". This machine needs the 64-bit emulator.
2321
@item
2322
MIPS emulator pseudo board "mipssim"
2323
@item
2324
A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2325
@end itemize
2326

    
2327
The generic emulation is supported by Debian 'Etch' and is able to
2328
install Debian into a virtual disk image. The following devices are
2329
emulated:
2330

    
2331
@itemize @minus
2332
@item
2333
A range of MIPS CPUs, default is the 24Kf
2334
@item
2335
PC style serial port
2336
@item
2337
PC style IDE disk
2338
@item
2339
NE2000 network card
2340
@end itemize
2341

    
2342
The Malta emulation supports the following devices:
2343

    
2344
@itemize @minus
2345
@item
2346
Core board with MIPS 24Kf CPU and Galileo system controller
2347
@item
2348
PIIX4 PCI/USB/SMbus controller
2349
@item
2350
The Multi-I/O chip's serial device
2351
@item
2352
PCnet32 PCI network card
2353
@item
2354
Malta FPGA serial device
2355
@item
2356
Cirrus VGA graphics card
2357
@end itemize
2358

    
2359
The ACER Pica emulation supports:
2360

    
2361
@itemize @minus
2362
@item
2363
MIPS R4000 CPU
2364
@item
2365
PC-style IRQ and DMA controllers
2366
@item
2367
PC Keyboard
2368
@item
2369
IDE controller
2370
@end itemize
2371

    
2372
The mipssim pseudo board emulation provides an environment similiar
2373
to what the proprietary MIPS emulator uses for running Linux.
2374
It supports:
2375

    
2376
@itemize @minus
2377
@item
2378
A range of MIPS CPUs, default is the 24Kf
2379
@item
2380
PC style serial port
2381
@item
2382
MIPSnet network emulation
2383
@end itemize
2384

    
2385
The MIPS Magnum R4000 emulation supports:
2386

    
2387
@itemize @minus
2388
@item
2389
MIPS R4000 CPU
2390
@item
2391
PC-style IRQ controller
2392
@item
2393
PC Keyboard
2394
@item
2395
SCSI controller
2396
@item
2397
G364 framebuffer
2398
@end itemize
2399

    
2400

    
2401
@node ARM System emulator
2402
@section ARM System emulator
2403

    
2404
Use the executable @file{qemu-system-arm} to simulate a ARM
2405
machine. The ARM Integrator/CP board is emulated with the following
2406
devices:
2407

    
2408
@itemize @minus
2409
@item
2410
ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2411
@item
2412
Two PL011 UARTs
2413
@item
2414
SMC 91c111 Ethernet adapter
2415
@item
2416
PL110 LCD controller
2417
@item
2418
PL050 KMI with PS/2 keyboard and mouse.
2419
@item
2420
PL181 MultiMedia Card Interface with SD card.
2421
@end itemize
2422

    
2423
The ARM Versatile baseboard is emulated with the following devices:
2424

    
2425
@itemize @minus
2426
@item
2427
ARM926E, ARM1136 or Cortex-A8 CPU
2428
@item
2429
PL190 Vectored Interrupt Controller
2430
@item
2431
Four PL011 UARTs
2432
@item
2433
SMC 91c111 Ethernet adapter
2434
@item
2435
PL110 LCD controller
2436
@item
2437
PL050 KMI with PS/2 keyboard and mouse.
2438
@item
2439
PCI host bridge.  Note the emulated PCI bridge only provides access to
2440
PCI memory space.  It does not provide access to PCI IO space.
2441
This means some devices (eg. ne2k_pci NIC) are not usable, and others
2442
(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2443
mapped control registers.
2444
@item
2445
PCI OHCI USB controller.
2446
@item
2447
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2448
@item
2449
PL181 MultiMedia Card Interface with SD card.
2450
@end itemize
2451

    
2452
The ARM RealView Emulation baseboard is emulated with the following devices:
2453

    
2454
@itemize @minus
2455
@item
2456
ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
2457
@item
2458
ARM AMBA Generic/Distributed Interrupt Controller
2459
@item
2460
Four PL011 UARTs
2461
@item
2462
SMC 91c111 Ethernet adapter
2463
@item
2464
PL110 LCD controller
2465
@item
2466
PL050 KMI with PS/2 keyboard and mouse
2467
@item
2468
PCI host bridge
2469
@item
2470
PCI OHCI USB controller
2471
@item
2472
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2473
@item
2474
PL181 MultiMedia Card Interface with SD card.
2475
@end itemize
2476

    
2477
The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2478
and "Terrier") emulation includes the following peripherals:
2479

    
2480
@itemize @minus
2481
@item
2482
Intel PXA270 System-on-chip (ARM V5TE core)
2483
@item
2484
NAND Flash memory
2485
@item
2486
IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2487
@item
2488
On-chip OHCI USB controller
2489
@item
2490
On-chip LCD controller
2491
@item
2492
On-chip Real Time Clock
2493
@item
2494
TI ADS7846 touchscreen controller on SSP bus
2495
@item
2496
Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2497
@item
2498
GPIO-connected keyboard controller and LEDs
2499
@item
2500
Secure Digital card connected to PXA MMC/SD host
2501
@item
2502
Three on-chip UARTs
2503
@item
2504
WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2505
@end itemize
2506

    
2507
The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2508
following elements:
2509

    
2510
@itemize @minus
2511
@item
2512
Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2513
@item
2514
ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2515
@item
2516
On-chip LCD controller
2517
@item
2518
On-chip Real Time Clock
2519
@item
2520
TI TSC2102i touchscreen controller / analog-digital converter / Audio
2521
CODEC, connected through MicroWire and I@math{^2}S busses
2522
@item
2523
GPIO-connected matrix keypad
2524
@item
2525
Secure Digital card connected to OMAP MMC/SD host
2526
@item
2527
Three on-chip UARTs
2528
@end itemize
2529

    
2530
Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2531
emulation supports the following elements:
2532

    
2533
@itemize @minus
2534
@item
2535
Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2536
@item
2537
RAM and non-volatile OneNAND Flash memories
2538
@item
2539
Display connected to EPSON remote framebuffer chip and OMAP on-chip
2540
display controller and a LS041y3 MIPI DBI-C controller
2541
@item
2542
TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2543
driven through SPI bus
2544
@item
2545
National Semiconductor LM8323-controlled qwerty keyboard driven
2546
through I@math{^2}C bus
2547
@item
2548
Secure Digital card connected to OMAP MMC/SD host
2549
@item
2550
Three OMAP on-chip UARTs and on-chip STI debugging console
2551
@item
2552
Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2553
TUSB6010 chip - only USB host mode is supported
2554
@item
2555
TI TMP105 temperature sensor driven through I@math{^2}C bus
2556
@item
2557
TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2558
@item
2559
Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2560
through CBUS
2561
@end itemize
2562

    
2563
The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2564
devices:
2565

    
2566
@itemize @minus
2567
@item
2568
Cortex-M3 CPU core.
2569
@item
2570
64k Flash and 8k SRAM.
2571
@item
2572
Timers, UARTs, ADC and I@math{^2}C interface.
2573
@item
2574
OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2575
@end itemize
2576

    
2577
The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2578
devices:
2579

    
2580
@itemize @minus
2581
@item
2582
Cortex-M3 CPU core.
2583
@item
2584
256k Flash and 64k SRAM.
2585
@item
2586
Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2587
@item
2588
OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2589
@end itemize
2590

    
2591
The Freecom MusicPal internet radio emulation includes the following
2592
elements:
2593

    
2594
@itemize @minus
2595
@item
2596
Marvell MV88W8618 ARM core.
2597
@item
2598
32 MB RAM, 256 KB SRAM, 8 MB flash.
2599
@item
2600
Up to 2 16550 UARTs
2601
@item
2602
MV88W8xx8 Ethernet controller
2603
@item
2604
MV88W8618 audio controller, WM8750 CODEC and mixer
2605
@item
2606
128?64 display with brightness control
2607
@item
2608
2 buttons, 2 navigation wheels with button function
2609
@end itemize
2610

    
2611
A Linux 2.6 test image is available on the QEMU web site. More
2612
information is available in the QEMU mailing-list archive.
2613

    
2614
@node ColdFire System emulator
2615
@section ColdFire System emulator
2616

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

    
2620
The M5208EVB emulation includes the following devices:
2621

    
2622
@itemize @minus
2623
@item
2624
MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2625
@item
2626
Three Two on-chip UARTs.
2627
@item
2628
Fast Ethernet Controller (FEC)
2629
@end itemize
2630

    
2631
The AN5206 emulation includes the following devices:
2632

    
2633
@itemize @minus
2634
@item
2635
MCF5206 ColdFire V2 Microprocessor.
2636
@item
2637
Two on-chip UARTs.
2638
@end itemize
2639

    
2640
@node QEMU User space emulator
2641
@chapter QEMU User space emulator
2642

    
2643
@menu
2644
* Supported Operating Systems ::
2645
* Linux User space emulator::
2646
* Mac OS X/Darwin User space emulator ::
2647
@end menu
2648

    
2649
@node Supported Operating Systems
2650
@section Supported Operating Systems
2651

    
2652
The following OS are supported in user space emulation:
2653

    
2654
@itemize @minus
2655
@item
2656
Linux (referred as qemu-linux-user)
2657
@item
2658
Mac OS X/Darwin (referred as qemu-darwin-user)
2659
@end itemize
2660

    
2661
@node Linux User space emulator
2662
@section Linux User space emulator
2663

    
2664
@menu
2665
* Quick Start::
2666
* Wine launch::
2667
* Command line options::
2668
* Other binaries::
2669
@end menu
2670

    
2671
@node Quick Start
2672
@subsection Quick Start
2673

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

    
2677
@itemize
2678

    
2679
@item On x86, you can just try to launch any process by using the native
2680
libraries:
2681

    
2682
@example
2683
qemu-i386 -L / /bin/ls
2684
@end example
2685

    
2686
@code{-L /} tells that the x86 dynamic linker must be searched with a
2687
@file{/} prefix.
2688

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

    
2692
@example
2693
qemu-i386 -L / qemu-i386 -L / /bin/ls
2694
@end example
2695

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

    
2700
@example
2701
unset LD_LIBRARY_PATH
2702
@end example
2703

    
2704
Then you can launch the precompiled @file{ls} x86 executable:
2705

    
2706
@example
2707
qemu-i386 tests/i386/ls
2708
@end example
2709
You can look at @file{qemu-binfmt-conf.sh} so that
2710
QEMU is automatically launched by the Linux kernel when you try to
2711
launch x86 executables. It requires the @code{binfmt_misc} module in the
2712
Linux kernel.
2713

    
2714
@item The x86 version of QEMU is also included. You can try weird things such as:
2715
@example
2716
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2717
          /usr/local/qemu-i386/bin/ls-i386
2718
@end example
2719

    
2720
@end itemize
2721

    
2722
@node Wine launch
2723
@subsection Wine launch
2724

    
2725
@itemize
2726

    
2727
@item Ensure that you have a working QEMU with the x86 glibc
2728
distribution (see previous section). In order to verify it, you must be
2729
able to do:
2730

    
2731
@example
2732
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2733
@end example
2734

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

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

    
2742
@item Then you can try the example @file{putty.exe}:
2743

    
2744
@example
2745
qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2746
          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2747
@end example
2748

    
2749
@end itemize
2750

    
2751
@node Command line options
2752
@subsection Command line options
2753

    
2754
@example
2755
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2756
@end example
2757

    
2758
@table @option
2759
@item -h
2760
Print the help
2761
@item -L path
2762
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2763
@item -s size
2764
Set the x86 stack size in bytes (default=524288)
2765
@end table
2766

    
2767
Debug options:
2768

    
2769
@table @option
2770
@item -d
2771
Activate log (logfile=/tmp/qemu.log)
2772
@item -p pagesize
2773
Act as if the host page size was 'pagesize' bytes
2774
@end table
2775

    
2776
Environment variables:
2777

    
2778
@table @env
2779
@item QEMU_STRACE
2780
Print system calls and arguments similar to the 'strace' program
2781
(NOTE: the actual 'strace' program will not work because the user
2782
space emulator hasn't implemented ptrace).  At the moment this is
2783
incomplete.  All system calls that don't have a specific argument
2784
format are printed with information for six arguments.  Many
2785
flag-style arguments don't have decoders and will show up as numbers.
2786
@end table
2787

    
2788
@node Other binaries
2789
@subsection Other binaries
2790

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

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

    
2799
The binary format is detected automatically.
2800

    
2801
@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2802
(Sparc64 CPU, 32 bit ABI).
2803

    
2804
@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2805
SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2806

    
2807
@node Mac OS X/Darwin User space emulator
2808
@section Mac OS X/Darwin User space emulator
2809

    
2810
@menu
2811
* Mac OS X/Darwin Status::
2812
* Mac OS X/Darwin Quick Start::
2813
* Mac OS X/Darwin Command line options::
2814
@end menu
2815

    
2816
@node Mac OS X/Darwin Status
2817
@subsection Mac OS X/Darwin Status
2818

    
2819
@itemize @minus
2820
@item
2821
target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2822
@item
2823
target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2824
@item
2825
target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
2826
@item
2827
target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2828
@end itemize
2829

    
2830
[1] If you're host commpage can be executed by qemu.
2831

    
2832
@node Mac OS X/Darwin Quick Start
2833
@subsection Quick Start
2834

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

    
2840
@itemize
2841

    
2842
@item On x86, you can just try to launch any process by using the native
2843
libraries:
2844

    
2845
@example
2846
qemu-i386 /bin/ls
2847
@end example
2848

    
2849
or to run the ppc version of the executable:
2850

    
2851
@example
2852
qemu-ppc /bin/ls
2853
@end example
2854

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

    
2858
@example
2859
qemu-i386 -L /opt/x86_root/ /bin/ls
2860
@end example
2861

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

    
2865
@end itemize
2866

    
2867
@node Mac OS X/Darwin Command line options
2868
@subsection Command line options
2869

    
2870
@example
2871
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2872
@end example
2873

    
2874
@table @option
2875
@item -h
2876
Print the help
2877
@item -L path
2878
Set the library root path (default=/)
2879
@item -s size
2880
Set the stack size in bytes (default=524288)
2881
@end table
2882

    
2883
Debug options:
2884

    
2885
@table @option
2886
@item -d
2887
Activate log (logfile=/tmp/qemu.log)
2888
@item -p pagesize
2889
Act as if the host page size was 'pagesize' bytes
2890
@end table
2891

    
2892
@node compilation
2893
@chapter Compilation from the sources
2894

    
2895
@menu
2896
* Linux/Unix::
2897
* Windows::
2898
* Cross compilation for Windows with Linux::
2899
* Mac OS X::
2900
@end menu
2901

    
2902
@node Linux/Unix
2903
@section Linux/Unix
2904

    
2905
@subsection Compilation
2906

    
2907
First you must decompress the sources:
2908
@example
2909
cd /tmp
2910
tar zxvf qemu-x.y.z.tar.gz
2911
cd qemu-x.y.z
2912
@end example
2913

    
2914
Then you configure QEMU and build it (usually no options are needed):
2915
@example
2916
./configure
2917
make
2918
@end example
2919

    
2920
Then type as root user:
2921
@example
2922
make install
2923
@end example
2924
to install QEMU in @file{/usr/local}.
2925

    
2926
@subsection GCC version
2927

    
2928
In order to compile QEMU successfully, it is very important that you
2929
have the right tools. The most important one is gcc. On most hosts and
2930
in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
2931
Linux distribution includes a gcc 4.x compiler, you can usually
2932
install an older version (it is invoked by @code{gcc32} or
2933
@code{gcc34}). The QEMU configure script automatically probes for
2934
these older versions so that usually you don't have to do anything.
2935

    
2936
@node Windows
2937
@section Windows
2938

    
2939
@itemize
2940
@item Install the current versions of MSYS and MinGW from
2941
@url{http://www.mingw.org/}. You can find detailed installation
2942
instructions in the download section and the FAQ.
2943

    
2944
@item Download
2945
the MinGW development library of SDL 1.2.x
2946
(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2947
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
2948
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2949
directory. Edit the @file{sdl-config} script so that it gives the
2950
correct SDL directory when invoked.
2951

    
2952
@item Extract the current version of QEMU.
2953

    
2954
@item Start the MSYS shell (file @file{msys.bat}).
2955

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

    
2960
@item You can install QEMU in @file{Program Files/Qemu} by typing
2961
@file{make install}. Don't forget to copy @file{SDL.dll} in
2962
@file{Program Files/Qemu}.
2963

    
2964
@end itemize
2965

    
2966
@node Cross compilation for Windows with Linux
2967
@section Cross compilation for Windows with Linux
2968

    
2969
@itemize
2970
@item
2971
Install the MinGW cross compilation tools available at
2972
@url{http://www.mingw.org/}.
2973

    
2974
@item
2975
Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
2976
unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
2977
variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
2978
the QEMU configuration script.
2979

    
2980
@item
2981
Configure QEMU for Windows cross compilation:
2982
@example
2983
./configure --enable-mingw32
2984
@end example
2985
If necessary, you can change the cross-prefix according to the prefix
2986
chosen for the MinGW tools with --cross-prefix. You can also use
2987
--prefix to set the Win32 install path.
2988

    
2989
@item You can install QEMU in the installation directory by typing
2990
@file{make install}. Don't forget to copy @file{SDL.dll} in the
2991
installation directory.
2992

    
2993
@end itemize
2994

    
2995
Note: Currently, Wine does not seem able to launch
2996
QEMU for Win32.
2997

    
2998
@node Mac OS X
2999
@section Mac OS X
3000

    
3001
The Mac OS X patches are not fully merged in QEMU, so you should look
3002
at the QEMU mailing list archive to have all the necessary
3003
information.
3004

    
3005
@node Index
3006
@chapter Index
3007
@printindex cp
3008

    
3009
@bye