]> git.proxmox.com Git - qemu.git/blame - qemu-doc.texi
global s/fflush(logfile)/qemu_log_flush()/ (Eduardo Habkost)
[qemu.git] / qemu-doc.texi
CommitLineData
386405f7 1\input texinfo @c -*- texinfo -*-
debc7065
FB
2@c %**start of header
3@setfilename qemu-doc.info
8f40c388 4@settitle QEMU Emulator User Documentation
debc7065
FB
5@exampleindent 0
6@paragraphindent 0
7@c %**end of header
386405f7 8
0806e3f6 9@iftex
386405f7
FB
10@titlepage
11@sp 7
8f40c388 12@center @titlefont{QEMU Emulator}
debc7065
FB
13@sp 1
14@center @titlefont{User Documentation}
386405f7
FB
15@sp 3
16@end titlepage
0806e3f6 17@end iftex
386405f7 18
debc7065
FB
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::
83195237 28* QEMU User space emulator::
debc7065
FB
29* compilation:: Compilation from the sources
30* Index::
31@end menu
32@end ifnottex
33
34@contents
35
36@node Introduction
386405f7
FB
37@chapter Introduction
38
debc7065
FB
39@menu
40* intro_features:: Features
41@end menu
42
43@node intro_features
322d0c66 44@section Features
386405f7 45
1f673135
FB
46QEMU is a FAST! processor emulator using dynamic translation to
47achieve good emulation speed.
1eb20527
FB
48
49QEMU has two operating modes:
0806e3f6
FB
50
51@itemize @minus
52
5fafdf24 53@item
1f673135 54Full system emulation. In this mode, QEMU emulates a full system (for
3f9f3aa1
FB
55example a PC), including one or several processors and various
56peripherals. It can be used to launch different Operating Systems
57without rebooting the PC or to debug system code.
1eb20527 58
5fafdf24 59@item
83195237
FB
60User mode emulation. In this mode, QEMU can launch
61processes compiled for one CPU on another CPU. It can be used to
1f673135
FB
62launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63to ease cross-compilation and cross-debugging.
1eb20527
FB
64
65@end itemize
66
7c3fc84d 67QEMU can run without an host kernel driver and yet gives acceptable
5fafdf24 68performance.
322d0c66 69
52c00a5f
FB
70For system emulation, the following hardware targets are supported:
71@itemize
9d0a8e6f 72@item PC (x86 or x86_64 processor)
3f9f3aa1 73@item ISA PC (old style PC without PCI bus)
52c00a5f 74@item PREP (PowerPC processor)
d45952a0 75@item G3 Beige PowerMac (PowerPC processor)
9d0a8e6f 76@item Mac99 PowerMac (PowerPC processor, in progress)
ee76f82e 77@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
c7ba218d 78@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
d9aedc32 79@item Malta board (32-bit and 64-bit MIPS processors)
88cb0a02 80@item MIPS Magnum (64-bit MIPS processor)
9ee6e8bb
PB
81@item ARM Integrator/CP (ARM)
82@item ARM Versatile baseboard (ARM)
83@item ARM RealView Emulation baseboard (ARM)
ef4c3856 84@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
9ee6e8bb
PB
85@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
86@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
707e011b 87@item Freescale MCF5208EVB (ColdFire V2).
209a4e69 88@item Arnewsh MCF5206 evaluation board (ColdFire V2).
02645926 89@item Palm Tungsten|E PDA (OMAP310 processor)
c30bb264 90@item N800 and N810 tablets (OMAP2420 processor)
57cd6e97 91@item MusicPal (MV88W8618 ARM processor)
ef4c3856
AZ
92@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
93@item Siemens SX1 smartphone (OMAP310 processor)
52c00a5f 94@end itemize
386405f7 95
d9aedc32 96For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
0806e3f6 97
debc7065 98@node Installation
5b9f457a
FB
99@chapter Installation
100
15a34c63
FB
101If you want to compile QEMU yourself, see @ref{compilation}.
102
debc7065
FB
103@menu
104* install_linux:: Linux
105* install_windows:: Windows
106* install_mac:: Macintosh
107@end menu
108
109@node install_linux
1f673135
FB
110@section Linux
111
7c3fc84d
FB
112If a precompiled package is available for your distribution - you just
113have to install it. Otherwise, see @ref{compilation}.
5b9f457a 114
debc7065 115@node install_windows
1f673135 116@section Windows
8cd0ac2f 117
15a34c63 118Download the experimental binary installer at
debc7065 119@url{http://www.free.oszoo.org/@/download.html}.
d691f669 120
debc7065 121@node install_mac
1f673135 122@section Mac OS X
d691f669 123
15a34c63 124Download the experimental binary installer at
debc7065 125@url{http://www.free.oszoo.org/@/download.html}.
df0f11a0 126
debc7065 127@node QEMU PC System emulator
3f9f3aa1 128@chapter QEMU PC System emulator
1eb20527 129
debc7065
FB
130@menu
131* pcsys_introduction:: Introduction
132* pcsys_quickstart:: Quick Start
133* sec_invocation:: Invocation
134* pcsys_keys:: Keys
135* pcsys_monitor:: QEMU Monitor
136* disk_images:: Disk Images
137* pcsys_network:: Network emulation
138* direct_linux_boot:: Direct Linux Boot
139* pcsys_usb:: USB emulation
f858dcae 140* vnc_security:: VNC security
debc7065
FB
141* gdb_usage:: GDB usage
142* pcsys_os_specific:: Target OS specific information
143@end menu
144
145@node pcsys_introduction
0806e3f6
FB
146@section Introduction
147
148@c man begin DESCRIPTION
149
3f9f3aa1
FB
150The QEMU PC System emulator simulates the
151following peripherals:
0806e3f6
FB
152
153@itemize @minus
5fafdf24 154@item
15a34c63 155i440FX host PCI bridge and PIIX3 PCI to ISA bridge
0806e3f6 156@item
15a34c63
FB
157Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
158extensions (hardware level, including all non standard modes).
0806e3f6
FB
159@item
160PS/2 mouse and keyboard
5fafdf24 161@item
15a34c63 1622 PCI IDE interfaces with hard disk and CD-ROM support
1f673135
FB
163@item
164Floppy disk
5fafdf24 165@item
c4a7060c 166PCI/ISA PCI network adapters
0806e3f6 167@item
05d5818c
FB
168Serial ports
169@item
c0fe3827
FB
170Creative SoundBlaster 16 sound card
171@item
172ENSONIQ AudioPCI ES1370 sound card
173@item
e5c9a13e
AZ
174Intel 82801AA AC97 Audio compatible sound card
175@item
c0fe3827 176Adlib(OPL2) - Yamaha YM3812 compatible chip
b389dbfb 177@item
26463dbc
AZ
178Gravis Ultrasound GF1 sound card
179@item
cc53d26d 180CS4231A compatible sound card
181@item
b389dbfb 182PCI UHCI USB controller and a virtual USB hub.
0806e3f6
FB
183@end itemize
184
3f9f3aa1
FB
185SMP is supported with up to 255 CPUs.
186
1d1f8c33 187Note that adlib, gus and cs4231a are only available when QEMU was
188configured with --audio-card-list option containing the name(s) of
e5178e8d 189required card(s).
c0fe3827 190
15a34c63
FB
191QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
192VGA BIOS.
193
c0fe3827
FB
194QEMU uses YM3812 emulation by Tatsuyuki Satoh.
195
26463dbc
AZ
196QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
197by Tibor "TS" Schütz.
423d65f4 198
cc53d26d 199CS4231A is the chip used in Windows Sound System and GUSMAX products
200
0806e3f6
FB
201@c man end
202
debc7065 203@node pcsys_quickstart
1eb20527
FB
204@section Quick Start
205
285dc330 206Download and uncompress the linux image (@file{linux.img}) and type:
0806e3f6
FB
207
208@example
285dc330 209qemu linux.img
0806e3f6
FB
210@end example
211
212Linux should boot and give you a prompt.
213
6cc721cf 214@node sec_invocation
ec410fc9
FB
215@section Invocation
216
217@example
0806e3f6 218@c man begin SYNOPSIS
89dfe898 219usage: qemu [options] [@var{disk_image}]
0806e3f6 220@c man end
ec410fc9
FB
221@end example
222
0806e3f6 223@c man begin OPTIONS
9d4520d0 224@var{disk_image} is a raw hard disk image for IDE hard disk 0.
ec410fc9
FB
225
226General options:
227@table @option
89dfe898
TS
228@item -M @var{machine}
229Select the emulated @var{machine} (@code{-M ?} for list)
3dbbdc25 230
89dfe898
TS
231@item -fda @var{file}
232@item -fdb @var{file}
debc7065 233Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
19cb3738 234use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
2be3bc02 235
89dfe898
TS
236@item -hda @var{file}
237@item -hdb @var{file}
238@item -hdc @var{file}
239@item -hdd @var{file}
debc7065 240Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
1f47a922 241
89dfe898
TS
242@item -cdrom @var{file}
243Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
be3edd95 244@option{-cdrom} at the same time). You can use the host CD-ROM by
19cb3738 245using @file{/dev/cdrom} as filename (@pxref{host_drives}).
181f1558 246
e0e7ada1
AZ
247@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
248
249Define a new drive. Valid options are:
250
251@table @code
252@item file=@var{file}
253This option defines which disk image (@pxref{disk_images}) to use with
609497ab
AZ
254this drive. If the filename contains comma, you must double it
255(for instance, "file=my,,file" to use file "my,file").
e0e7ada1
AZ
256@item if=@var{interface}
257This option defines on which type on interface the drive is connected.
6e02c38d 258Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
e0e7ada1
AZ
259@item bus=@var{bus},unit=@var{unit}
260These options define where is connected the drive by defining the bus number and
261the unit id.
262@item index=@var{index}
263This option defines where is connected the drive by using an index in the list
264of available connectors of a given interface type.
265@item media=@var{media}
266This option defines the type of the media: disk or cdrom.
267@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
268These options have the same definition as they have in @option{-hdachs}.
269@item snapshot=@var{snapshot}
270@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
33f00271 271@item cache=@var{cache}
9f7965c7 272@var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.
1e72d3b7
AJ
273@item format=@var{format}
274Specify which disk @var{format} will be used rather than detecting
275the format. Can be used to specifiy format=raw to avoid interpreting
276an untrusted format header.
fa879c64
AL
277@item serial=@var{serial}
278This option specifies the serial number to assign to the device.
e0e7ada1
AZ
279@end table
280
9f7965c7
AL
281By default, writethrough caching is used for all block device. This means that
282the host page cache will be used to read and write data but write notification
283will be sent to the guest only when the data has been reported as written by
284the storage subsystem.
285
286Writeback caching will report data writes as completed as soon as the data is
287present in the host page cache. This is safe as long as you trust your host.
288If your host crashes or loses power, then the guest may experience data
289corruption. When using the @option{-snapshot} option, writeback caching is
290used by default.
291
292The host page can be avoided entirely with @option{cache=none}. This will
293attempt to do disk IO directly to the guests memory. QEMU may still perform
294an internal copy of the data.
295
4dc822d7
AL
296Some block drivers perform badly with @option{cache=writethrough}, most notably,
297qcow2. If performance is more important than correctness,
298@option{cache=writeback} should be used with qcow2. By default, if no explicit
299caching is specified for a qcow2 disk image, @option{cache=writeback} will be
300used. For all other disk types, @option{cache=writethrough} is the default.
301
e0e7ada1
AZ
302Instead of @option{-cdrom} you can use:
303@example
304qemu -drive file=file,index=2,media=cdrom
305@end example
306
307Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
308use:
309@example
310qemu -drive file=file,index=0,media=disk
311qemu -drive file=file,index=1,media=disk
312qemu -drive file=file,index=2,media=disk
313qemu -drive file=file,index=3,media=disk
314@end example
315
316You can connect a CDROM to the slave of ide0:
317@example
318qemu -drive file=file,if=ide,index=1,media=cdrom
319@end example
320
321If you don't specify the "file=" argument, you define an empty drive:
322@example
323qemu -drive if=ide,index=1,media=cdrom
324@end example
325
326You can connect a SCSI disk with unit ID 6 on the bus #0:
327@example
328qemu -drive file=file,if=scsi,bus=0,unit=6
329@end example
330
331Instead of @option{-fda}, @option{-fdb}, you can use:
332@example
333qemu -drive file=file,index=0,if=floppy
334qemu -drive file=file,index=1,if=floppy
335@end example
336
337By default, @var{interface} is "ide" and @var{index} is automatically
338incremented:
339@example
340qemu -drive file=a -drive file=b"
341@end example
342is interpreted like:
343@example
344qemu -hda a -hdb b
345@end example
346
eec85c2a
TS
347@item -boot [a|c|d|n]
348Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
349is the default.
1f47a922 350
181f1558 351@item -snapshot
1f47a922
FB
352Write to temporary files instead of disk image files. In this case,
353the raw disk image you use is not written back. You can however force
42550fde 354the write back by pressing @key{C-a s} (@pxref{disk_images}).
ec410fc9 355
52ca8d6a
FB
356@item -no-fd-bootchk
357Disable boot signature checking for floppy disks in Bochs BIOS. It may
358be needed to boot from old floppy disks.
359
89dfe898 360@item -m @var{megs}
00f82b8a
AJ
361Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
362a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
363gigabytes respectively.
ec410fc9 364
34a3d239
BS
365@item -cpu @var{model}
366Select CPU model (-cpu ? for list and additional feature selection)
367
89dfe898 368@item -smp @var{n}
3f9f3aa1 369Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
a785e42e
BS
370CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
371to 4.
3f9f3aa1 372
1d14ffa9
FB
373@item -audio-help
374
375Will show the audio subsystem help: list of drivers, tunable
376parameters.
377
89dfe898 378@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
1d14ffa9
FB
379
380Enable audio and selected sound hardware. Use ? to print all
381available sound hardware.
382
383@example
9b3469cc 384qemu -soundhw sb16,adlib disk.img
385qemu -soundhw es1370 disk.img
386qemu -soundhw ac97 disk.img
387qemu -soundhw all disk.img
1d14ffa9
FB
388qemu -soundhw ?
389@end example
a8c490cd 390
e5c9a13e
AZ
391Note that Linux's i810_audio OSS kernel (for AC97) module might
392require manually specifying clocking.
393
394@example
395modprobe i810_audio clocking=48000
396@end example
397
15a34c63
FB
398@item -localtime
399Set the real time clock to local time (the default is to UTC
400time). This option is needed to have correct date in MS-DOS or
401Windows.
402
89dfe898 403@item -startdate @var{date}
1addc7c5 404Set the initial date of the real time clock. Valid formats for
7e0af5d0
FB
405@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
406@code{2006-06-17}. The default value is @code{now}.
407
89dfe898 408@item -pidfile @var{file}
f7cce898
FB
409Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
410from a script.
411
71e3ceb8
TS
412@item -daemonize
413Daemonize the QEMU process after initialization. QEMU will not detach from
414standard IO until it is ready to receive connections on any of its devices.
415This option is a useful way for external programs to launch QEMU without having
416to cope with initialization race conditions.
417
9d0a8e6f
FB
418@item -win2k-hack
419Use it when installing Windows 2000 to avoid a disk full bug. After
420Windows 2000 is installed, you no longer need this option (this option
421slows down the IDE transfers).
422
73822ec8
AL
423@item -rtc-td-hack
424Use it if you experience time drift problem in Windows with ACPI HAL.
425This option will try to figure out how many timer interrupts were not
426processed by the Windows guest and will re-inject them.
427
89dfe898
TS
428@item -option-rom @var{file}
429Load the contents of @var{file} as an option ROM.
430This option is useful to load things like EtherBoot.
9ae02555 431
89dfe898
TS
432@item -name @var{name}
433Sets the @var{name} of the guest.
1addc7c5 434This name will be displayed in the SDL window caption.
89dfe898 435The @var{name} will also be used for the VNC server.
c35734b2 436
0806e3f6
FB
437@end table
438
f858dcae
TS
439Display options:
440@table @option
441
442@item -nographic
443
444Normally, QEMU uses SDL to display the VGA output. With this option,
445you can totally disable graphical output so that QEMU is a simple
446command line application. The emulated serial port is redirected on
447the console. Therefore, you can still use QEMU to debug a Linux kernel
448with a serial console.
449
052caf70
AJ
450@item -curses
451
452Normally, QEMU uses SDL to display the VGA output. With this option,
453QEMU can display the VGA output when in text mode using a
454curses/ncurses interface. Nothing is displayed in graphical mode.
455
f858dcae
TS
456@item -no-frame
457
458Do not use decorations for SDL windows and start them using the whole
459available screen space. This makes the using QEMU in a dedicated desktop
460workspace more convenient.
461
99aa9e4c
AJ
462@item -no-quit
463
464Disable SDL window close capability.
465
f858dcae
TS
466@item -full-screen
467Start in full screen.
468
89dfe898 469@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
f858dcae
TS
470
471Normally, QEMU uses SDL to display the VGA output. With this option,
472you can have QEMU listen on VNC display @var{display} and redirect the VGA
473display over the VNC session. It is very useful to enable the usb
474tablet device when using this option (option @option{-usbdevice
475tablet}). When using the VNC display, you must use the @option{-k}
476parameter to set the keyboard layout if you are not using en-us. Valid
477syntax for the @var{display} is
478
479@table @code
480
3aa3eea3 481@item @var{host}:@var{d}
f858dcae 482
3aa3eea3
AZ
483TCP connections will only be allowed from @var{host} on display @var{d}.
484By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
485be omitted in which case the server will accept connections from any host.
f858dcae 486
3aa3eea3 487@item @code{unix}:@var{path}
f858dcae
TS
488
489Connections will be allowed over UNIX domain sockets where @var{path} is the
490location of a unix socket to listen for connections on.
491
89dfe898 492@item none
f858dcae 493
3aa3eea3
AZ
494VNC is initialized but not started. The monitor @code{change} command
495can be used to later start the VNC server.
f858dcae
TS
496
497@end table
498
499Following the @var{display} value there may be one or more @var{option} flags
500separated by commas. Valid options are
501
502@table @code
503
3aa3eea3
AZ
504@item reverse
505
506Connect to a listening VNC client via a ``reverse'' connection. The
507client is specified by the @var{display}. For reverse network
508connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
509is a TCP port number, not a display number.
510
89dfe898 511@item password
f858dcae
TS
512
513Require that password based authentication is used for client connections.
514The password must be set separately using the @code{change} command in the
515@ref{pcsys_monitor}
516
89dfe898 517@item tls
f858dcae
TS
518
519Require that client use TLS when communicating with the VNC server. This
520uses anonymous TLS credentials so is susceptible to a man-in-the-middle
521attack. It is recommended that this option be combined with either the
522@var{x509} or @var{x509verify} options.
523
89dfe898 524@item x509=@var{/path/to/certificate/dir}
f858dcae 525
89dfe898 526Valid if @option{tls} is specified. Require that x509 credentials are used
f858dcae
TS
527for negotiating the TLS session. The server will send its x509 certificate
528to the client. It is recommended that a password be set on the VNC server
529to provide authentication of the client when this is used. The path following
530this option specifies where the x509 certificates are to be loaded from.
531See the @ref{vnc_security} section for details on generating certificates.
532
89dfe898 533@item x509verify=@var{/path/to/certificate/dir}
f858dcae 534
89dfe898 535Valid if @option{tls} is specified. Require that x509 credentials are used
f858dcae
TS
536for negotiating the TLS session. The server will send its x509 certificate
537to the client, and request that the client send its own x509 certificate.
538The server will validate the client's certificate against the CA certificate,
539and reject clients when validation fails. If the certificate authority is
540trusted, this is a sufficient authentication mechanism. You may still wish
541to set a password on the VNC server as a second authentication layer. The
542path following this option specifies where the x509 certificates are to
543be loaded from. See the @ref{vnc_security} section for details on generating
544certificates.
545
546@end table
547
89dfe898 548@item -k @var{language}
f858dcae
TS
549
550Use keyboard layout @var{language} (for example @code{fr} for
551French). This option is only needed where it is not easy to get raw PC
552keycodes (e.g. on Macs, with some X11 servers or with a VNC
553display). You don't normally need to use it on PC/Linux or PC/Windows
554hosts.
555
556The available layouts are:
557@example
558ar de-ch es fo fr-ca hu ja mk no pt-br sv
559da en-gb et fr fr-ch is lt nl pl ru th
560de en-us fi fr-be hr it lv nl-be pt sl tr
561@end example
562
563The default is @code{en-us}.
564
565@end table
566
b389dbfb
FB
567USB options:
568@table @option
569
570@item -usb
571Enable the USB driver (will be the default soon)
572
89dfe898 573@item -usbdevice @var{devname}
0aff66b5 574Add the USB device @var{devname}. @xref{usb_devices}.
8fccda83
TS
575
576@table @code
577
578@item mouse
579Virtual Mouse. This will override the PS/2 mouse emulation when activated.
580
581@item tablet
582Pointer device that uses absolute coordinates (like a touchscreen). This
583means qemu is able to report the mouse position without having to grab the
584mouse. Also overrides the PS/2 mouse emulation when activated.
585
334c0241
AJ
586@item disk:[format=@var{format}]:file
587Mass storage device based on file. The optional @var{format} argument
588will be used rather than detecting the format. Can be used to specifiy
589format=raw to avoid interpreting an untrusted format header.
8fccda83
TS
590
591@item host:bus.addr
592Pass through the host device identified by bus.addr (Linux only).
593
594@item host:vendor_id:product_id
595Pass through the host device identified by vendor_id:product_id (Linux only).
596
db380c06
AZ
597@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
598Serial converter to host character device @var{dev}, see @code{-serial} for the
599available devices.
600
2e4d9fb1
AJ
601@item braille
602Braille device. This will use BrlAPI to display the braille output on a real
603or fake device.
604
9ad97e65 605@item net:options
6c9f886c
AZ
606Network adapter that supports CDC ethernet and RNDIS protocols.
607
8fccda83
TS
608@end table
609
b389dbfb
FB
610@end table
611
1f673135
FB
612Network options:
613
614@table @option
615
7a9f6e4a 616@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}][,name=@var{name}]
41d03949 617Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
c4a7060c 618= 0 is the default). The NIC is an ne2k_pci by default on the PC
7a9f6e4a
AL
619target. Optionally, the MAC address can be changed to @var{addr}
620and a @var{name} can be assigned for use in monitor commands. If no
41d03949 621@option{-net} option is specified, a single NIC is created.
549444e1
AZ
622Qemu can emulate several different models of network card.
623Valid values for @var{type} are
624@code{i82551}, @code{i82557b}, @code{i82559er},
625@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
9ad97e65 626@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
c4a7060c
BS
627Not all devices are supported on all targets. Use -net nic,model=?
628for a list of available devices for your target.
41d03949 629
7a9f6e4a 630@item -net user[,vlan=@var{n}][,hostname=@var{name}][,name=@var{name}]
7e89463d 631Use the user mode network stack which requires no administrator
4be456f1 632privilege to run. @option{hostname=name} can be used to specify the client
115defd1 633hostname reported by the builtin DHCP server.
41d03949 634
7a9f6e4a 635@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
030370a2
AJ
636Connect the host TAP network interface @var{name} to VLAN @var{n}, use
637the network script @var{file} to configure it and the network script
638@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
639automatically provides one. @option{fd}=@var{h} can be used to specify
640the handle of an already opened host TAP interface. The default network
641configure script is @file{/etc/qemu-ifup} and the default network
642deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
643or @option{downscript=no} to disable script execution. Example:
1f673135 644
41d03949
FB
645@example
646qemu linux.img -net nic -net tap
647@end example
648
649More complicated example (two NICs, each one connected to a TAP device)
650@example
651qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
652 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
653@end example
3f1a88f4 654
3f1a88f4 655
7a9f6e4a 656@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1f673135 657
41d03949
FB
658Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
659machine using a TCP socket connection. If @option{listen} is
660specified, QEMU waits for incoming connections on @var{port}
661(@var{host} is optional). @option{connect} is used to connect to
89dfe898 662another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
3d830459 663specifies an already opened TCP socket.
1f673135 664
41d03949
FB
665Example:
666@example
667# launch a first QEMU instance
debc7065
FB
668qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
669 -net socket,listen=:1234
670# connect the VLAN 0 of this instance to the VLAN 0
671# of the first instance
672qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
673 -net socket,connect=127.0.0.1:1234
41d03949 674@end example
52c00a5f 675
7a9f6e4a 676@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
3d830459
FB
677
678Create a VLAN @var{n} shared with another QEMU virtual
5fafdf24 679machines using a UDP multicast socket, effectively making a bus for
3d830459
FB
680every QEMU with same multicast address @var{maddr} and @var{port}.
681NOTES:
682@enumerate
5fafdf24
TS
683@item
684Several QEMU can be running on different hosts and share same bus (assuming
3d830459
FB
685correct multicast setup for these hosts).
686@item
687mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
688@url{http://user-mode-linux.sf.net}.
4be456f1
TS
689@item
690Use @option{fd=h} to specify an already opened UDP multicast socket.
3d830459
FB
691@end enumerate
692
693Example:
694@example
695# launch one QEMU instance
debc7065
FB
696qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
697 -net socket,mcast=230.0.0.1:1234
3d830459 698# launch another QEMU instance on same "bus"
debc7065
FB
699qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
700 -net socket,mcast=230.0.0.1:1234
3d830459 701# launch yet another QEMU instance on same "bus"
debc7065
FB
702qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
703 -net socket,mcast=230.0.0.1:1234
3d830459
FB
704@end example
705
706Example (User Mode Linux compat.):
707@example
debc7065
FB
708# launch QEMU instance (note mcast address selected
709# is UML's default)
710qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
711 -net socket,mcast=239.192.168.1:1102
3d830459
FB
712# launch UML
713/path/to/linux ubd0=/path/to/root_fs eth0=mcast
714@end example
8a16d273 715
7a9f6e4a 716@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
8a16d273
TS
717Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
718listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
719and MODE @var{octalmode} to change default ownership and permissions for
720communication port. This option is available only if QEMU has been compiled
721with vde support enabled.
722
723Example:
724@example
725# launch vde switch
726vde_switch -F -sock /tmp/myswitch
727# launch QEMU instance
728qemu linux.img -net nic -net vde,sock=/tmp/myswitch
729@end example
3d830459 730
41d03949
FB
731@item -net none
732Indicate that no network devices should be configured. It is used to
039af320
FB
733override the default configuration (@option{-net nic -net user}) which
734is activated if no @option{-net} options are provided.
52c00a5f 735
89dfe898 736@item -tftp @var{dir}
9bf05444 737When using the user mode network stack, activate a built-in TFTP
0db1137d
TS
738server. The files in @var{dir} will be exposed as the root of a TFTP server.
739The TFTP client on the guest must be configured in binary mode (use the command
740@code{bin} of the Unix TFTP client). The host IP address on the guest is as
741usual 10.0.2.2.
9bf05444 742
89dfe898 743@item -bootp @var{file}
47d5d01a
TS
744When using the user mode network stack, broadcast @var{file} as the BOOTP
745filename. In conjunction with @option{-tftp}, this can be used to network boot
746a guest from a local directory.
747
748Example (using pxelinux):
749@example
750qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
751@end example
752
89dfe898 753@item -smb @var{dir}
2518bd0d 754When using the user mode network stack, activate a built-in SMB
89dfe898 755server so that Windows OSes can access to the host files in @file{@var{dir}}
2518bd0d
FB
756transparently.
757
758In the guest Windows OS, the line:
759@example
76010.0.2.4 smbserver
761@end example
762must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
763or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
764
89dfe898 765Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2518bd0d
FB
766
767Note that a SAMBA server must be installed on the host OS in
366dfc52 768@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
6cc721cf 7692.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
2518bd0d 770
89dfe898 771@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
9bf05444
FB
772
773When using the user mode network stack, redirect incoming TCP or UDP
774connections to the host port @var{host-port} to the guest
775@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
776is not specified, its value is 10.0.2.15 (default address given by the
777built-in DHCP server).
778
779For example, to redirect host X11 connection from screen 1 to guest
780screen 0, use the following:
781
782@example
783# on the host
784qemu -redir tcp:6001::6000 [...]
785# this host xterm should open in the guest X11 server
786xterm -display :1
787@end example
788
789To redirect telnet connections from host port 5555 to telnet port on
790the guest, use the following:
791
792@example
793# on the host
794qemu -redir tcp:5555::23 [...]
795telnet localhost 5555
796@end example
797
798Then when you use on the host @code{telnet localhost 5555}, you
799connect to the guest telnet server.
800
1f673135
FB
801@end table
802
2d564691
AZ
803Bluetooth(R) options:
804@table @option
805
806@item -bt hci[...]
807Defines the function of the corresponding Bluetooth HCI. -bt options
808are matched with the HCIs present in the chosen machine type. For
809example when emulating a machine with only one HCI built into it, only
810the first @code{-bt hci[...]} option is valid and defines the HCI's
811logic. The Transport Layer is decided by the machine type. Currently
812the machines @code{n800} and @code{n810} have one HCI and all other
813machines have none.
814
815@anchor{bt-hcis}
816The following three types are recognized:
817
818@table @code
819@item -bt hci,null
820(default) The corresponding Bluetooth HCI assumes no internal logic
821and will not respond to any HCI commands or emit events.
822
823@item -bt hci,host[:@var{id}]
824(@code{bluez} only) The corresponding HCI passes commands / events
825to / from the physical HCI identified by the name @var{id} (default:
826@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
827capable systems like Linux.
828
829@item -bt hci[,vlan=@var{n}]
830Add a virtual, standard HCI that will participate in the Bluetooth
831scatternet @var{n} (default @code{0}). Similarly to @option{-net}
832VLANs, devices inside a bluetooth network @var{n} can only communicate
833with other devices in the same network (scatternet).
834@end table
835
836@item -bt vhci[,vlan=@var{n}]
837(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
838to the host bluetooth stack instead of to the emulated target. This
839allows the host and target machines to participate in a common scatternet
840and communicate. Requires the Linux @code{vhci} driver installed. Can
841be used as following:
842
843@example
844qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
845@end example
846
847@item -bt device:@var{dev}[,vlan=@var{n}]
848Emulate a bluetooth device @var{dev} and place it in network @var{n}
849(default @code{0}). QEMU can only emulate one type of bluetooth devices
850currently:
851
852@table @code
853@item keyboard
854Virtual wireless keyboard implementing the HIDP bluetooth profile.
855@end table
856
857@end table
858
41d03949 859Linux boot specific: When using these options, you can use a given
1f673135
FB
860Linux kernel without installing it in the disk image. It can be useful
861for easier testing of various kernels.
862
0806e3f6
FB
863@table @option
864
89dfe898 865@item -kernel @var{bzImage}
0806e3f6
FB
866Use @var{bzImage} as kernel image.
867
89dfe898 868@item -append @var{cmdline}
0806e3f6
FB
869Use @var{cmdline} as kernel command line
870
89dfe898 871@item -initrd @var{file}
0806e3f6
FB
872Use @var{file} as initial ram disk.
873
ec410fc9
FB
874@end table
875
15a34c63 876Debug/Expert options:
ec410fc9 877@table @option
a0a821a4 878
89dfe898 879@item -serial @var{dev}
0bab00f3
FB
880Redirect the virtual serial port to host character device
881@var{dev}. The default device is @code{vc} in graphical mode and
882@code{stdio} in non graphical mode.
883
884This option can be used several times to simulate up to 4 serials
885ports.
886
c03b0f0f
FB
887Use @code{-serial none} to disable all serial ports.
888
0bab00f3 889Available character devices are:
a0a821a4 890@table @code
af3a9031
TS
891@item vc[:WxH]
892Virtual console. Optionally, a width and height can be given in pixel with
893@example
894vc:800x600
895@end example
896It is also possible to specify width or height in characters:
897@example
898vc:80Cx24C
899@end example
a0a821a4
FB
900@item pty
901[Linux only] Pseudo TTY (a new PTY is automatically allocated)
c03b0f0f
FB
902@item none
903No device is allocated.
a0a821a4
FB
904@item null
905void device
f8d179e3 906@item /dev/XXX
e57a8c0e 907[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
f8d179e3 908parameters are set according to the emulated ones.
89dfe898 909@item /dev/parport@var{N}
e57a8c0e 910[Linux only, parallel port only] Use host parallel port
5867c88a 911@var{N}. Currently SPP and EPP parallel port features can be used.
89dfe898
TS
912@item file:@var{filename}
913Write output to @var{filename}. No character can be read.
a0a821a4
FB
914@item stdio
915[Unix only] standard input/output
89dfe898 916@item pipe:@var{filename}
0bab00f3 917name pipe @var{filename}
89dfe898 918@item COM@var{n}
0bab00f3 919[Windows only] Use host serial port @var{n}
89dfe898
TS
920@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
921This implements UDP Net Console.
922When @var{remote_host} or @var{src_ip} are not specified
923they default to @code{0.0.0.0}.
924When not using a specified @var{src_port} a random port is automatically chosen.
951f1351
FB
925
926If you just want a simple readonly console you can use @code{netcat} or
927@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
928@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
929will appear in the netconsole session.
0bab00f3
FB
930
931If you plan to send characters back via netconsole or you want to stop
932and start qemu a lot of times, you should have qemu use the same
933source port each time by using something like @code{-serial
951f1351 934udp::4555@@:4556} to qemu. Another approach is to use a patched
0bab00f3
FB
935version of netcat which can listen to a TCP port and send and receive
936characters via udp. If you have a patched version of netcat which
937activates telnet remote echo and single char transfer, then you can
938use the following options to step up a netcat redirector to allow
939telnet on port 5555 to access the qemu port.
940@table @code
951f1351
FB
941@item Qemu Options:
942-serial udp::4555@@:4556
943@item netcat options:
944-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
945@item telnet options:
946localhost 5555
947@end table
948
949
89dfe898 950@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
951f1351
FB
951The TCP Net Console has two modes of operation. It can send the serial
952I/O to a location or wait for a connection from a location. By default
953the TCP Net Console is sent to @var{host} at the @var{port}. If you use
f542086d
FB
954the @var{server} option QEMU will wait for a client socket application
955to connect to the port before continuing, unless the @code{nowait}
f7499989 956option was specified. The @code{nodelay} option disables the Nagle buffering
4be456f1 957algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
951f1351
FB
958one TCP connection at a time is accepted. You can use @code{telnet} to
959connect to the corresponding character device.
960@table @code
961@item Example to send tcp console to 192.168.0.2 port 4444
962-serial tcp:192.168.0.2:4444
963@item Example to listen and wait on port 4444 for connection
964-serial tcp::4444,server
965@item Example to not wait and listen on ip 192.168.0.100 port 4444
966-serial tcp:192.168.0.100:4444,server,nowait
a0a821a4 967@end table
a0a821a4 968
89dfe898 969@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
951f1351
FB
970The telnet protocol is used instead of raw tcp sockets. The options
971work the same as if you had specified @code{-serial tcp}. The
972difference is that the port acts like a telnet server or client using
973telnet option negotiation. This will also allow you to send the
974MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
975sequence. Typically in unix telnet you do it with Control-] and then
976type "send break" followed by pressing the enter key.
0bab00f3 977
89dfe898 978@item unix:@var{path}[,server][,nowait]
ffd843bc
TS
979A unix domain socket is used instead of a tcp socket. The option works the
980same as if you had specified @code{-serial tcp} except the unix domain socket
981@var{path} is used for connections.
982
89dfe898 983@item mon:@var{dev_string}
20d8a3ed
TS
984This is a special option to allow the monitor to be multiplexed onto
985another serial port. The monitor is accessed with key sequence of
986@key{Control-a} and then pressing @key{c}. See monitor access
987@ref{pcsys_keys} in the -nographic section for more keys.
988@var{dev_string} should be any one of the serial devices specified
989above. An example to multiplex the monitor onto a telnet server
990listening on port 4444 would be:
991@table @code
992@item -serial mon:telnet::4444,server,nowait
993@end table
994
2e4d9fb1
AJ
995@item braille
996Braille device. This will use BrlAPI to display the braille output on a real
997or fake device.
998
0bab00f3 999@end table
05d5818c 1000
89dfe898 1001@item -parallel @var{dev}
e57a8c0e
FB
1002Redirect the virtual parallel port to host device @var{dev} (same
1003devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1004be used to use hardware devices connected on the corresponding host
1005parallel port.
1006
1007This option can be used several times to simulate up to 3 parallel
1008ports.
1009
c03b0f0f
FB
1010Use @code{-parallel none} to disable all parallel ports.
1011
89dfe898 1012@item -monitor @var{dev}
a0a821a4
FB
1013Redirect the monitor to host device @var{dev} (same devices as the
1014serial port).
1015The default device is @code{vc} in graphical mode and @code{stdio} in
1016non graphical mode.
1017
20d8a3ed
TS
1018@item -echr numeric_ascii_value
1019Change the escape character used for switching to the monitor when using
1020monitor and serial sharing. The default is @code{0x01} when using the
1021@code{-nographic} option. @code{0x01} is equal to pressing
1022@code{Control-a}. You can select a different character from the ascii
1023control keys where 1 through 26 map to Control-a through Control-z. For
1024instance you could use the either of the following to change the escape
1025character to Control-t.
1026@table @code
1027@item -echr 0x14
1028@item -echr 20
1029@end table
1030
ec410fc9 1031@item -s
5fafdf24 1032Wait gdb connection to port 1234 (@pxref{gdb_usage}).
89dfe898 1033@item -p @var{port}
4046d913
PB
1034Change gdb connection port. @var{port} can be either a decimal number
1035to specify a TCP port, or a host device (same devices as the serial port).
52c00a5f
FB
1036@item -S
1037Do not start CPU at startup (you must type 'c' in the monitor).
3b46e624 1038@item -d
9d4520d0 1039Output log in /tmp/qemu.log
89dfe898 1040@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
46d4767d
FB
1041Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1042@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1043translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
4be456f1 1044all those parameters. This option is useful for old MS-DOS disk
46d4767d 1045images.
7c3fc84d 1046
87b47350
FB
1047@item -L path
1048Set the directory for the BIOS, VGA BIOS and keymaps.
1049
3893c124 1050@item -vga @var{type}
1051Select type of VGA card to emulate. Valid values for @var{type} are
1052@table @code
1053@item cirrus
1054Cirrus Logic GD5446 Video card. All Windows versions starting from
1055Windows 95 should recognize and use this graphic card. For optimal
1056performances, use 16 bit color depth in the guest and the host OS.
1057(This one is the default)
1058@item std
1059Standard VGA card with Bochs VBE extensions. If your guest OS
1060supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1061to use high resolution modes (>= 1280x1024x16) then you should use
1062this option.
1063@item vmware
1064VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1065recent XFree86/XOrg server or Windows guest with a driver for this
1066card.
1067@end table
3cb0853a 1068
3c656346
FB
1069@item -no-acpi
1070Disable ACPI (Advanced Configuration and Power Interface) support. Use
1071it if your guest OS complains about ACPI problems (PC target machine
1072only).
1073
d1beab82
FB
1074@item -no-reboot
1075Exit instead of rebooting.
1076
99aa9e4c
AJ
1077@item -no-shutdown
1078Don't exit QEMU on guest shutdown, but instead only stop the emulation.
1079This allows for instance switching to monitor to commit changes to the
1080disk image.
1081
d63d307f
FB
1082@item -loadvm file
1083Start right away with a saved state (@code{loadvm} in monitor)
8e71621f
PB
1084
1085@item -semihosting
a87295e8
PB
1086Enable semihosting syscall emulation (ARM and M68K target machines only).
1087
1088On ARM this implements the "Angel" interface.
1089On M68K this implements the "ColdFire GDB" interface used by libgloss.
1090
8e71621f
PB
1091Note that this allows guest direct access to the host filesystem,
1092so should only be used with trusted guest OS.
2e70f6ef
PB
1093
1094@item -icount [N|auto]
1095Enable virtual instruction counter. The virtual cpu will execute one
1096instruction every 2^N ns of virtual time. If @code{auto} is specified
1097then the virtual cpu speed will be automatically adjusted to keep virtual
1098time within a few seconds of real time.
1099
1100Note that while this option can give deterministic behavior, it does not
1101provide cycle accurate emulation. Modern CPUs contain superscalar out of
dd5d6fe9 1102order cores with complex cache hierarchies. The number of instructions
2e70f6ef 1103executed often has little or no correlation with actual performance.
ec410fc9
FB
1104@end table
1105
3e11db9a
FB
1106@c man end
1107
debc7065 1108@node pcsys_keys
3e11db9a
FB
1109@section Keys
1110
1111@c man begin OPTIONS
1112
a1b74fe8
FB
1113During the graphical emulation, you can use the following keys:
1114@table @key
f9859310 1115@item Ctrl-Alt-f
a1b74fe8 1116Toggle full screen
a0a821a4 1117
f9859310 1118@item Ctrl-Alt-n
a0a821a4
FB
1119Switch to virtual console 'n'. Standard console mappings are:
1120@table @emph
1121@item 1
1122Target system display
1123@item 2
1124Monitor
1125@item 3
1126Serial port
a1b74fe8
FB
1127@end table
1128
f9859310 1129@item Ctrl-Alt
a0a821a4
FB
1130Toggle mouse and keyboard grab.
1131@end table
1132
3e11db9a
FB
1133In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
1134@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
1135
a0a821a4
FB
1136During emulation, if you are using the @option{-nographic} option, use
1137@key{Ctrl-a h} to get terminal commands:
ec410fc9
FB
1138
1139@table @key
a1b74fe8 1140@item Ctrl-a h
ec410fc9 1141Print this help
3b46e624 1142@item Ctrl-a x
366dfc52 1143Exit emulator
3b46e624 1144@item Ctrl-a s
1f47a922 1145Save disk data back to file (if -snapshot)
20d8a3ed
TS
1146@item Ctrl-a t
1147toggle console timestamps
a1b74fe8 1148@item Ctrl-a b
1f673135 1149Send break (magic sysrq in Linux)
a1b74fe8 1150@item Ctrl-a c
1f673135 1151Switch between console and monitor
a1b74fe8
FB
1152@item Ctrl-a Ctrl-a
1153Send Ctrl-a
ec410fc9 1154@end table
0806e3f6
FB
1155@c man end
1156
1157@ignore
1158
1f673135
FB
1159@c man begin SEEALSO
1160The HTML documentation of QEMU for more precise information and Linux
1161user mode emulator invocation.
1162@c man end
1163
1164@c man begin AUTHOR
1165Fabrice Bellard
1166@c man end
1167
1168@end ignore
1169
debc7065 1170@node pcsys_monitor
1f673135
FB
1171@section QEMU Monitor
1172
1173The QEMU monitor is used to give complex commands to the QEMU
1174emulator. You can use it to:
1175
1176@itemize @minus
1177
1178@item
e598752a 1179Remove or insert removable media images
89dfe898 1180(such as CD-ROM or floppies).
1f673135 1181
5fafdf24 1182@item
1f673135
FB
1183Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
1184from a disk file.
1185
1186@item Inspect the VM state without an external debugger.
1187
1188@end itemize
1189
1190@subsection Commands
1191
1192The following commands are available:
1193
1194@table @option
1195
89dfe898 1196@item help or ? [@var{cmd}]
1f673135
FB
1197Show the help for all commands or just for command @var{cmd}.
1198
3b46e624 1199@item commit
89dfe898 1200Commit changes to the disk images (if -snapshot is used).
1f673135 1201
89dfe898
TS
1202@item info @var{subcommand}
1203Show various information about the system state.
1f673135
FB
1204
1205@table @option
1206@item info network
41d03949 1207show the various VLANs and the associated devices
1f673135
FB
1208@item info block
1209show the block devices
1210@item info registers
1211show the cpu registers
1212@item info history
1213show the command line history
b389dbfb
FB
1214@item info pci
1215show emulated PCI device
1216@item info usb
1217show USB devices plugged on the virtual USB hub
1218@item info usbhost
1219show all USB host devices
a3c25997
FB
1220@item info capture
1221show information about active capturing
13a2e80f
FB
1222@item info snapshots
1223show list of VM snapshots
455204eb
TS
1224@item info mice
1225show which guest mouse is receiving events
1f673135
FB
1226@end table
1227
1228@item q or quit
1229Quit the emulator.
1230
89dfe898 1231@item eject [-f] @var{device}
e598752a 1232Eject a removable medium (use -f to force it).
1f673135 1233
89dfe898 1234@item change @var{device} @var{setting}
f858dcae 1235
89dfe898 1236Change the configuration of a device.
f858dcae
TS
1237
1238@table @option
1239@item change @var{diskdevice} @var{filename}
1240Change the medium for a removable disk device to point to @var{filename}. eg
1241
1242@example
4bf27c24 1243(qemu) change ide1-cd0 /path/to/some.iso
f858dcae
TS
1244@end example
1245
89dfe898 1246@item change vnc @var{display},@var{options}
f858dcae
TS
1247Change the configuration of the VNC server. The valid syntax for @var{display}
1248and @var{options} are described at @ref{sec_invocation}. eg
1249
1250@example
1251(qemu) change vnc localhost:1
1252@end example
1253
2569da0c 1254@item change vnc password [@var{password}]
f858dcae 1255
2569da0c
AL
1256Change the password associated with the VNC server. If the new password is not
1257supplied, the monitor will prompt for it to be entered. VNC passwords are only
1258significant up to 8 letters. eg
f858dcae
TS
1259
1260@example
1261(qemu) change vnc password
1262Password: ********
1263@end example
1264
1265@end table
1f673135 1266
89dfe898 1267@item screendump @var{filename}
1f673135
FB
1268Save screen into PPM image @var{filename}.
1269
89dfe898 1270@item mouse_move @var{dx} @var{dy} [@var{dz}]
455204eb
TS
1271Move the active mouse to the specified coordinates @var{dx} @var{dy}
1272with optional scroll axis @var{dz}.
1273
89dfe898 1274@item mouse_button @var{val}
455204eb
TS
1275Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1276
89dfe898 1277@item mouse_set @var{index}
455204eb
TS
1278Set which mouse device receives events at given @var{index}, index
1279can be obtained with
1280@example
1281info mice
1282@end example
1283
89dfe898 1284@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
a3c25997
FB
1285Capture audio into @var{filename}. Using sample rate @var{frequency}
1286bits per sample @var{bits} and number of channels @var{channels}.
1287
1288Defaults:
1289@itemize @minus
1290@item Sample rate = 44100 Hz - CD quality
1291@item Bits = 16
1292@item Number of channels = 2 - Stereo
1293@end itemize
1294
89dfe898 1295@item stopcapture @var{index}
a3c25997
FB
1296Stop capture with a given @var{index}, index can be obtained with
1297@example
1298info capture
1299@end example
1300
89dfe898 1301@item log @var{item1}[,...]
1f673135
FB
1302Activate logging of the specified items to @file{/tmp/qemu.log}.
1303
89dfe898 1304@item savevm [@var{tag}|@var{id}]
13a2e80f
FB
1305Create a snapshot of the whole virtual machine. If @var{tag} is
1306provided, it is used as human readable identifier. If there is already
1307a snapshot with the same tag or ID, it is replaced. More info at
1308@ref{vm_snapshots}.
1f673135 1309
89dfe898 1310@item loadvm @var{tag}|@var{id}
13a2e80f
FB
1311Set the whole virtual machine to the snapshot identified by the tag
1312@var{tag} or the unique snapshot ID @var{id}.
1313
89dfe898 1314@item delvm @var{tag}|@var{id}
13a2e80f 1315Delete the snapshot identified by @var{tag} or @var{id}.
1f673135
FB
1316
1317@item stop
1318Stop emulation.
1319
1320@item c or cont
1321Resume emulation.
1322
89dfe898
TS
1323@item gdbserver [@var{port}]
1324Start gdbserver session (default @var{port}=1234)
1f673135 1325
89dfe898 1326@item x/fmt @var{addr}
1f673135
FB
1327Virtual memory dump starting at @var{addr}.
1328
89dfe898 1329@item xp /@var{fmt} @var{addr}
1f673135
FB
1330Physical memory dump starting at @var{addr}.
1331
1332@var{fmt} is a format which tells the command how to format the
1333data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1334
1335@table @var
5fafdf24 1336@item count
1f673135
FB
1337is the number of items to be dumped.
1338
1339@item format
4be456f1 1340can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
1f673135
FB
1341c (char) or i (asm instruction).
1342
1343@item size
52c00a5f
FB
1344can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1345@code{h} or @code{w} can be specified with the @code{i} format to
1346respectively select 16 or 32 bit code instruction size.
1f673135
FB
1347
1348@end table
1349
5fafdf24 1350Examples:
1f673135
FB
1351@itemize
1352@item
1353Dump 10 instructions at the current instruction pointer:
5fafdf24 1354@example
1f673135
FB
1355(qemu) x/10i $eip
13560x90107063: ret
13570x90107064: sti
13580x90107065: lea 0x0(%esi,1),%esi
13590x90107069: lea 0x0(%edi,1),%edi
13600x90107070: ret
13610x90107071: jmp 0x90107080
13620x90107073: nop
13630x90107074: nop
13640x90107075: nop
13650x90107076: nop
1366@end example
1367
1368@item
1369Dump 80 16 bit values at the start of the video memory.
5fafdf24 1370@smallexample
1f673135
FB
1371(qemu) xp/80hx 0xb8000
13720x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
13730x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
13740x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
13750x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
13760x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
13770x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
13780x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
13790x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
13800x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
13810x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
debc7065 1382@end smallexample
1f673135
FB
1383@end itemize
1384
89dfe898 1385@item p or print/@var{fmt} @var{expr}
1f673135
FB
1386
1387Print expression value. Only the @var{format} part of @var{fmt} is
1388used.
0806e3f6 1389
89dfe898 1390@item sendkey @var{keys}
a3a91a35 1391
54ae1fbd
AJ
1392Send @var{keys} to the emulator. @var{keys} could be the name of the
1393key or @code{#} followed by the raw value in either decimal or hexadecimal
1394format. Use @code{-} to press several keys simultaneously. Example:
a3a91a35
FB
1395@example
1396sendkey ctrl-alt-f1
1397@end example
1398
1399This command is useful to send keys that your graphical user interface
1400intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1401
15a34c63
FB
1402@item system_reset
1403
1404Reset the system.
1405
0ecdffbb
AJ
1406@item boot_set @var{bootdevicelist}
1407
1408Define new values for the boot device list. Those values will override
1409the values specified on the command line through the @code{-boot} option.
1410
1411The values that can be specified here depend on the machine type, but are
1412the same that can be specified in the @code{-boot} command line option.
1413
89dfe898 1414@item usb_add @var{devname}
b389dbfb 1415
0aff66b5
PB
1416Add the USB device @var{devname}. For details of available devices see
1417@ref{usb_devices}
b389dbfb 1418
89dfe898 1419@item usb_del @var{devname}
b389dbfb
FB
1420
1421Remove the USB device @var{devname} from the QEMU virtual USB
1422hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1423command @code{info usb} to see the devices you can remove.
1424
1f673135 1425@end table
0806e3f6 1426
1f673135
FB
1427@subsection Integer expressions
1428
1429The monitor understands integers expressions for every integer
1430argument. You can use register names to get the value of specifics
1431CPU registers by prefixing them with @emph{$}.
ec410fc9 1432
1f47a922
FB
1433@node disk_images
1434@section Disk Images
1435
acd935ef
FB
1436Since version 0.6.1, QEMU supports many disk image formats, including
1437growable disk images (their size increase as non empty sectors are
13a2e80f
FB
1438written), compressed and encrypted disk images. Version 0.8.3 added
1439the new qcow2 disk image format which is essential to support VM
1440snapshots.
1f47a922 1441
debc7065
FB
1442@menu
1443* disk_images_quickstart:: Quick start for disk image creation
1444* disk_images_snapshot_mode:: Snapshot mode
13a2e80f 1445* vm_snapshots:: VM snapshots
debc7065 1446* qemu_img_invocation:: qemu-img Invocation
975b092b 1447* qemu_nbd_invocation:: qemu-nbd Invocation
19cb3738 1448* host_drives:: Using host drives
debc7065 1449* disk_images_fat_images:: Virtual FAT disk images
75818250 1450* disk_images_nbd:: NBD access
debc7065
FB
1451@end menu
1452
1453@node disk_images_quickstart
acd935ef
FB
1454@subsection Quick start for disk image creation
1455
1456You can create a disk image with the command:
1f47a922 1457@example
acd935ef 1458qemu-img create myimage.img mysize
1f47a922 1459@end example
acd935ef
FB
1460where @var{myimage.img} is the disk image filename and @var{mysize} is its
1461size in kilobytes. You can add an @code{M} suffix to give the size in
1462megabytes and a @code{G} suffix for gigabytes.
1463
debc7065 1464See @ref{qemu_img_invocation} for more information.
1f47a922 1465
debc7065 1466@node disk_images_snapshot_mode
1f47a922
FB
1467@subsection Snapshot mode
1468
1469If you use the option @option{-snapshot}, all disk images are
1470considered as read only. When sectors in written, they are written in
1471a temporary file created in @file{/tmp}. You can however force the
acd935ef
FB
1472write back to the raw disk images by using the @code{commit} monitor
1473command (or @key{C-a s} in the serial console).
1f47a922 1474
13a2e80f
FB
1475@node vm_snapshots
1476@subsection VM snapshots
1477
1478VM snapshots are snapshots of the complete virtual machine including
1479CPU state, RAM, device state and the content of all the writable
1480disks. In order to use VM snapshots, you must have at least one non
1481removable and writable block device using the @code{qcow2} disk image
1482format. Normally this device is the first virtual hard drive.
1483
1484Use the monitor command @code{savevm} to create a new VM snapshot or
1485replace an existing one. A human readable name can be assigned to each
19d36792 1486snapshot in addition to its numerical ID.
13a2e80f
FB
1487
1488Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1489a VM snapshot. @code{info snapshots} lists the available snapshots
1490with their associated information:
1491
1492@example
1493(qemu) info snapshots
1494Snapshot devices: hda
1495Snapshot list (from hda):
1496ID TAG VM SIZE DATE VM CLOCK
14971 start 41M 2006-08-06 12:38:02 00:00:14.954
14982 40M 2006-08-06 12:43:29 00:00:18.633
14993 msys 40M 2006-08-06 12:44:04 00:00:23.514
1500@end example
1501
1502A VM snapshot is made of a VM state info (its size is shown in
1503@code{info snapshots}) and a snapshot of every writable disk image.
1504The VM state info is stored in the first @code{qcow2} non removable
1505and writable block device. The disk image snapshots are stored in
1506every disk image. The size of a snapshot in a disk image is difficult
1507to evaluate and is not shown by @code{info snapshots} because the
1508associated disk sectors are shared among all the snapshots to save
19d36792
FB
1509disk space (otherwise each snapshot would need a full copy of all the
1510disk images).
13a2e80f
FB
1511
1512When using the (unrelated) @code{-snapshot} option
1513(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1514but they are deleted as soon as you exit QEMU.
1515
1516VM snapshots currently have the following known limitations:
1517@itemize
5fafdf24 1518@item
13a2e80f
FB
1519They cannot cope with removable devices if they are removed or
1520inserted after a snapshot is done.
5fafdf24 1521@item
13a2e80f
FB
1522A few device drivers still have incomplete snapshot support so their
1523state is not saved or restored properly (in particular USB).
1524@end itemize
1525
acd935ef
FB
1526@node qemu_img_invocation
1527@subsection @code{qemu-img} Invocation
1f47a922 1528
acd935ef 1529@include qemu-img.texi
05efe46e 1530
975b092b
TS
1531@node qemu_nbd_invocation
1532@subsection @code{qemu-nbd} Invocation
1533
1534@include qemu-nbd.texi
1535
19cb3738
FB
1536@node host_drives
1537@subsection Using host drives
1538
1539In addition to disk image files, QEMU can directly access host
1540devices. We describe here the usage for QEMU version >= 0.8.3.
1541
1542@subsubsection Linux
1543
1544On Linux, you can directly use the host device filename instead of a
4be456f1 1545disk image filename provided you have enough privileges to access
19cb3738
FB
1546it. For example, use @file{/dev/cdrom} to access to the CDROM or
1547@file{/dev/fd0} for the floppy.
1548
f542086d 1549@table @code
19cb3738
FB
1550@item CD
1551You can specify a CDROM device even if no CDROM is loaded. QEMU has
1552specific code to detect CDROM insertion or removal. CDROM ejection by
1553the guest OS is supported. Currently only data CDs are supported.
1554@item Floppy
1555You can specify a floppy device even if no floppy is loaded. Floppy
1556removal is currently not detected accurately (if you change floppy
1557without doing floppy access while the floppy is not loaded, the guest
1558OS will think that the same floppy is loaded).
1559@item Hard disks
1560Hard disks can be used. Normally you must specify the whole disk
1561(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1562see it as a partitioned disk. WARNING: unless you know what you do, it
1563is better to only make READ-ONLY accesses to the hard disk otherwise
1564you may corrupt your host data (use the @option{-snapshot} command
1565line option or modify the device permissions accordingly).
1566@end table
1567
1568@subsubsection Windows
1569
01781963
FB
1570@table @code
1571@item CD
4be456f1 1572The preferred syntax is the drive letter (e.g. @file{d:}). The
01781963
FB
1573alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1574supported as an alias to the first CDROM drive.
19cb3738 1575
e598752a 1576Currently there is no specific code to handle removable media, so it
19cb3738
FB
1577is better to use the @code{change} or @code{eject} monitor commands to
1578change or eject media.
01781963 1579@item Hard disks
89dfe898 1580Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
01781963
FB
1581where @var{N} is the drive number (0 is the first hard disk).
1582
1583WARNING: unless you know what you do, it is better to only make
1584READ-ONLY accesses to the hard disk otherwise you may corrupt your
1585host data (use the @option{-snapshot} command line so that the
1586modifications are written in a temporary file).
1587@end table
1588
19cb3738
FB
1589
1590@subsubsection Mac OS X
1591
5fafdf24 1592@file{/dev/cdrom} is an alias to the first CDROM.
19cb3738 1593
e598752a 1594Currently there is no specific code to handle removable media, so it
19cb3738
FB
1595is better to use the @code{change} or @code{eject} monitor commands to
1596change or eject media.
1597
debc7065 1598@node disk_images_fat_images
2c6cadd4
FB
1599@subsection Virtual FAT disk images
1600
1601QEMU can automatically create a virtual FAT disk image from a
1602directory tree. In order to use it, just type:
1603
5fafdf24 1604@example
2c6cadd4
FB
1605qemu linux.img -hdb fat:/my_directory
1606@end example
1607
1608Then you access access to all the files in the @file{/my_directory}
1609directory without having to copy them in a disk image or to export
1610them via SAMBA or NFS. The default access is @emph{read-only}.
1611
1612Floppies can be emulated with the @code{:floppy:} option:
1613
5fafdf24 1614@example
2c6cadd4
FB
1615qemu linux.img -fda fat:floppy:/my_directory
1616@end example
1617
1618A read/write support is available for testing (beta stage) with the
1619@code{:rw:} option:
1620
5fafdf24 1621@example
2c6cadd4
FB
1622qemu linux.img -fda fat:floppy:rw:/my_directory
1623@end example
1624
1625What you should @emph{never} do:
1626@itemize
1627@item use non-ASCII filenames ;
1628@item use "-snapshot" together with ":rw:" ;
85b2c688
FB
1629@item expect it to work when loadvm'ing ;
1630@item write to the FAT directory on the host system while accessing it with the guest system.
2c6cadd4
FB
1631@end itemize
1632
75818250
TS
1633@node disk_images_nbd
1634@subsection NBD access
1635
1636QEMU can access directly to block device exported using the Network Block Device
1637protocol.
1638
1639@example
1640qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
1641@end example
1642
1643If the NBD server is located on the same host, you can use an unix socket instead
1644of an inet socket:
1645
1646@example
1647qemu linux.img -hdb nbd:unix:/tmp/my_socket
1648@end example
1649
1650In this case, the block device must be exported using qemu-nbd:
1651
1652@example
1653qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
1654@end example
1655
1656The use of qemu-nbd allows to share a disk between several guests:
1657@example
1658qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
1659@end example
1660
1661and then you can use it with two guests:
1662@example
1663qemu linux1.img -hdb nbd:unix:/tmp/my_socket
1664qemu linux2.img -hdb nbd:unix:/tmp/my_socket
1665@end example
1666
debc7065 1667@node pcsys_network
9d4fb82e
FB
1668@section Network emulation
1669
4be456f1 1670QEMU can simulate several network cards (PCI or ISA cards on the PC
41d03949
FB
1671target) and can connect them to an arbitrary number of Virtual Local
1672Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1673VLAN. VLAN can be connected between separate instances of QEMU to
4be456f1 1674simulate large networks. For simpler usage, a non privileged user mode
41d03949
FB
1675network stack can replace the TAP device to have a basic network
1676connection.
1677
1678@subsection VLANs
9d4fb82e 1679
41d03949
FB
1680QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1681connection between several network devices. These devices can be for
1682example QEMU virtual Ethernet cards or virtual Host ethernet devices
1683(TAP devices).
9d4fb82e 1684
41d03949
FB
1685@subsection Using TAP network interfaces
1686
1687This is the standard way to connect QEMU to a real network. QEMU adds
1688a virtual network device on your host (called @code{tapN}), and you
1689can then configure it as if it was a real ethernet card.
9d4fb82e 1690
8f40c388
FB
1691@subsubsection Linux host
1692
9d4fb82e
FB
1693As an example, you can download the @file{linux-test-xxx.tar.gz}
1694archive and copy the script @file{qemu-ifup} in @file{/etc} and
1695configure properly @code{sudo} so that the command @code{ifconfig}
1696contained in @file{qemu-ifup} can be executed as root. You must verify
41d03949 1697that your host kernel supports the TAP network interfaces: the
9d4fb82e
FB
1698device @file{/dev/net/tun} must be present.
1699
ee0f4751
FB
1700See @ref{sec_invocation} to have examples of command lines using the
1701TAP network interfaces.
9d4fb82e 1702
8f40c388
FB
1703@subsubsection Windows host
1704
1705There is a virtual ethernet driver for Windows 2000/XP systems, called
1706TAP-Win32. But it is not included in standard QEMU for Windows,
1707so you will need to get it separately. It is part of OpenVPN package,
1708so download OpenVPN from : @url{http://openvpn.net/}.
1709
9d4fb82e
FB
1710@subsection Using the user mode network stack
1711
41d03949
FB
1712By using the option @option{-net user} (default configuration if no
1713@option{-net} option is specified), QEMU uses a completely user mode
4be456f1 1714network stack (you don't need root privilege to use the virtual
41d03949 1715network). The virtual network configuration is the following:
9d4fb82e
FB
1716
1717@example
1718
41d03949
FB
1719 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1720 | (10.0.2.2)
9d4fb82e 1721 |
2518bd0d 1722 ----> DNS server (10.0.2.3)
3b46e624 1723 |
2518bd0d 1724 ----> SMB server (10.0.2.4)
9d4fb82e
FB
1725@end example
1726
1727The QEMU VM behaves as if it was behind a firewall which blocks all
1728incoming connections. You can use a DHCP client to automatically
41d03949
FB
1729configure the network in the QEMU VM. The DHCP server assign addresses
1730to the hosts starting from 10.0.2.15.
9d4fb82e
FB
1731
1732In order to check that the user mode network is working, you can ping
1733the address 10.0.2.2 and verify that you got an address in the range
173410.0.2.x from the QEMU virtual DHCP server.
1735
b415a407 1736Note that @code{ping} is not supported reliably to the internet as it
4be456f1 1737would require root privileges. It means you can only ping the local
b415a407
FB
1738router (10.0.2.2).
1739
9bf05444
FB
1740When using the built-in TFTP server, the router is also the TFTP
1741server.
1742
1743When using the @option{-redir} option, TCP or UDP connections can be
1744redirected from the host to the guest. It allows for example to
1745redirect X11, telnet or SSH connections.
443f1376 1746
41d03949
FB
1747@subsection Connecting VLANs between QEMU instances
1748
1749Using the @option{-net socket} option, it is possible to make VLANs
1750that span several QEMU instances. See @ref{sec_invocation} to have a
1751basic example.
1752
9d4fb82e
FB
1753@node direct_linux_boot
1754@section Direct Linux Boot
1f673135
FB
1755
1756This section explains how to launch a Linux kernel inside QEMU without
1757having to make a full bootable image. It is very useful for fast Linux
ee0f4751 1758kernel testing.
1f673135 1759
ee0f4751 1760The syntax is:
1f673135 1761@example
ee0f4751 1762qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1f673135
FB
1763@end example
1764
ee0f4751
FB
1765Use @option{-kernel} to provide the Linux kernel image and
1766@option{-append} to give the kernel command line arguments. The
1767@option{-initrd} option can be used to provide an INITRD image.
1f673135 1768
ee0f4751
FB
1769When using the direct Linux boot, a disk image for the first hard disk
1770@file{hda} is required because its boot sector is used to launch the
1771Linux kernel.
1f673135 1772
ee0f4751
FB
1773If you do not need graphical output, you can disable it and redirect
1774the virtual serial port and the QEMU monitor to the console with the
1775@option{-nographic} option. The typical command line is:
1f673135 1776@example
ee0f4751
FB
1777qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1778 -append "root=/dev/hda console=ttyS0" -nographic
1f673135
FB
1779@end example
1780
ee0f4751
FB
1781Use @key{Ctrl-a c} to switch between the serial console and the
1782monitor (@pxref{pcsys_keys}).
1f673135 1783
debc7065 1784@node pcsys_usb
b389dbfb
FB
1785@section USB emulation
1786
0aff66b5
PB
1787QEMU emulates a PCI UHCI USB controller. You can virtually plug
1788virtual USB devices or real host USB devices (experimental, works only
1789on Linux hosts). Qemu will automatically create and connect virtual USB hubs
f542086d 1790as necessary to connect multiple USB devices.
b389dbfb 1791
0aff66b5
PB
1792@menu
1793* usb_devices::
1794* host_usb_devices::
1795@end menu
1796@node usb_devices
1797@subsection Connecting USB devices
b389dbfb 1798
0aff66b5
PB
1799USB devices can be connected with the @option{-usbdevice} commandline option
1800or the @code{usb_add} monitor command. Available devices are:
b389dbfb 1801
db380c06
AZ
1802@table @code
1803@item mouse
0aff66b5 1804Virtual Mouse. This will override the PS/2 mouse emulation when activated.
db380c06 1805@item tablet
c6d46c20 1806Pointer device that uses absolute coordinates (like a touchscreen).
0aff66b5
PB
1807This means qemu is able to report the mouse position without having
1808to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
db380c06 1809@item disk:@var{file}
0aff66b5 1810Mass storage device based on @var{file} (@pxref{disk_images})
db380c06 1811@item host:@var{bus.addr}
0aff66b5
PB
1812Pass through the host device identified by @var{bus.addr}
1813(Linux only)
db380c06 1814@item host:@var{vendor_id:product_id}
0aff66b5
PB
1815Pass through the host device identified by @var{vendor_id:product_id}
1816(Linux only)
db380c06 1817@item wacom-tablet
f6d2a316
AZ
1818Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1819above but it can be used with the tslib library because in addition to touch
1820coordinates it reports touch pressure.
db380c06 1821@item keyboard
47b2d338 1822Standard USB keyboard. Will override the PS/2 keyboard (if present).
db380c06
AZ
1823@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1824Serial converter. This emulates an FTDI FT232BM chip connected to host character
1825device @var{dev}. The available character devices are the same as for the
1826@code{-serial} option. The @code{vendorid} and @code{productid} options can be
a11d070e 1827used to override the default 0403:6001. For instance,
db380c06
AZ
1828@example
1829usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1830@end example
1831will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1832serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
2e4d9fb1
AJ
1833@item braille
1834Braille device. This will use BrlAPI to display the braille output on a real
1835or fake device.
9ad97e65
AZ
1836@item net:@var{options}
1837Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1838specifies NIC options as with @code{-net nic,}@var{options} (see description).
1839For instance, user-mode networking can be used with
6c9f886c 1840@example
9ad97e65 1841qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
6c9f886c
AZ
1842@end example
1843Currently this cannot be used in machines that support PCI NICs.
2d564691
AZ
1844@item bt[:@var{hci-type}]
1845Bluetooth dongle whose type is specified in the same format as with
1846the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
1847no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1848This USB device implements the USB Transport Layer of HCI. Example
1849usage:
1850@example
1851qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
1852@end example
0aff66b5 1853@end table
b389dbfb 1854
0aff66b5 1855@node host_usb_devices
b389dbfb
FB
1856@subsection Using host USB devices on a Linux host
1857
1858WARNING: this is an experimental feature. QEMU will slow down when
1859using it. USB devices requiring real time streaming (i.e. USB Video
1860Cameras) are not supported yet.
1861
1862@enumerate
5fafdf24 1863@item If you use an early Linux 2.4 kernel, verify that no Linux driver
b389dbfb
FB
1864is actually using the USB device. A simple way to do that is simply to
1865disable the corresponding kernel module by renaming it from @file{mydriver.o}
1866to @file{mydriver.o.disabled}.
1867
1868@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1869@example
1870ls /proc/bus/usb
1871001 devices drivers
1872@end example
1873
1874@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:
1875@example
1876chown -R myuid /proc/bus/usb
1877@end example
1878
1879@item Launch QEMU and do in the monitor:
5fafdf24 1880@example
b389dbfb
FB
1881info usbhost
1882 Device 1.2, speed 480 Mb/s
1883 Class 00: USB device 1234:5678, USB DISK
1884@end example
1885You should see the list of the devices you can use (Never try to use
1886hubs, it won't work).
1887
1888@item Add the device in QEMU by using:
5fafdf24 1889@example
b389dbfb
FB
1890usb_add host:1234:5678
1891@end example
1892
1893Normally the guest OS should report that a new USB device is
1894plugged. You can use the option @option{-usbdevice} to do the same.
1895
1896@item Now you can try to use the host USB device in QEMU.
1897
1898@end enumerate
1899
1900When relaunching QEMU, you may have to unplug and plug again the USB
1901device to make it work again (this is a bug).
1902
f858dcae
TS
1903@node vnc_security
1904@section VNC security
1905
1906The VNC server capability provides access to the graphical console
1907of the guest VM across the network. This has a number of security
1908considerations depending on the deployment scenarios.
1909
1910@menu
1911* vnc_sec_none::
1912* vnc_sec_password::
1913* vnc_sec_certificate::
1914* vnc_sec_certificate_verify::
1915* vnc_sec_certificate_pw::
1916* vnc_generate_cert::
1917@end menu
1918@node vnc_sec_none
1919@subsection Without passwords
1920
1921The simplest VNC server setup does not include any form of authentication.
1922For this setup it is recommended to restrict it to listen on a UNIX domain
1923socket only. For example
1924
1925@example
1926qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1927@end example
1928
1929This ensures that only users on local box with read/write access to that
1930path can access the VNC server. To securely access the VNC server from a
1931remote machine, a combination of netcat+ssh can be used to provide a secure
1932tunnel.
1933
1934@node vnc_sec_password
1935@subsection With passwords
1936
1937The VNC protocol has limited support for password based authentication. Since
1938the protocol limits passwords to 8 characters it should not be considered
1939to provide high security. The password can be fairly easily brute-forced by
1940a client making repeat connections. For this reason, a VNC server using password
1941authentication should be restricted to only listen on the loopback interface
34a3d239 1942or UNIX domain sockets. Password authentication is requested with the @code{password}
f858dcae
TS
1943option, and then once QEMU is running the password is set with the monitor. Until
1944the monitor is used to set the password all clients will be rejected.
1945
1946@example
1947qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1948(qemu) change vnc password
1949Password: ********
1950(qemu)
1951@end example
1952
1953@node vnc_sec_certificate
1954@subsection With x509 certificates
1955
1956The QEMU VNC server also implements the VeNCrypt extension allowing use of
1957TLS for encryption of the session, and x509 certificates for authentication.
1958The use of x509 certificates is strongly recommended, because TLS on its
1959own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1960support provides a secure session, but no authentication. This allows any
1961client to connect, and provides an encrypted session.
1962
1963@example
1964qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1965@end example
1966
1967In the above example @code{/etc/pki/qemu} should contain at least three files,
1968@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1969users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1970NB the @code{server-key.pem} file should be protected with file mode 0600 to
1971only be readable by the user owning it.
1972
1973@node vnc_sec_certificate_verify
1974@subsection With x509 certificates and client verification
1975
1976Certificates can also provide a means to authenticate the client connecting.
1977The server will request that the client provide a certificate, which it will
1978then validate against the CA certificate. This is a good choice if deploying
1979in an environment with a private internal certificate authority.
1980
1981@example
1982qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1983@end example
1984
1985
1986@node vnc_sec_certificate_pw
1987@subsection With x509 certificates, client verification and passwords
1988
1989Finally, the previous method can be combined with VNC password authentication
1990to provide two layers of authentication for clients.
1991
1992@example
1993qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1994(qemu) change vnc password
1995Password: ********
1996(qemu)
1997@end example
1998
1999@node vnc_generate_cert
2000@subsection Generating certificates for VNC
2001
2002The GNU TLS packages provides a command called @code{certtool} which can
2003be used to generate certificates and keys in PEM format. At a minimum it
2004is neccessary to setup a certificate authority, and issue certificates to
2005each server. If using certificates for authentication, then each client
2006will also need to be issued a certificate. The recommendation is for the
2007server to keep its certificates in either @code{/etc/pki/qemu} or for
2008unprivileged users in @code{$HOME/.pki/qemu}.
2009
2010@menu
2011* vnc_generate_ca::
2012* vnc_generate_server::
2013* vnc_generate_client::
2014@end menu
2015@node vnc_generate_ca
2016@subsubsection Setup the Certificate Authority
2017
2018This step only needs to be performed once per organization / organizational
2019unit. First the CA needs a private key. This key must be kept VERY secret
2020and secure. If this key is compromised the entire trust chain of the certificates
2021issued with it is lost.
2022
2023@example
2024# certtool --generate-privkey > ca-key.pem
2025@end example
2026
2027A CA needs to have a public certificate. For simplicity it can be a self-signed
2028certificate, or one issue by a commercial certificate issuing authority. To
2029generate a self-signed certificate requires one core piece of information, the
2030name of the organization.
2031
2032@example
2033# cat > ca.info <<EOF
2034cn = Name of your organization
2035ca
2036cert_signing_key
2037EOF
2038# certtool --generate-self-signed \
2039 --load-privkey ca-key.pem
2040 --template ca.info \
2041 --outfile ca-cert.pem
2042@end example
2043
2044The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
2045TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
2046
2047@node vnc_generate_server
2048@subsubsection Issuing server certificates
2049
2050Each server (or host) needs to be issued with a key and certificate. When connecting
2051the certificate is sent to the client which validates it against the CA certificate.
2052The core piece of information for a server certificate is the hostname. This should
2053be the fully qualified hostname that the client will connect with, since the client
2054will typically also verify the hostname in the certificate. On the host holding the
2055secure CA private key:
2056
2057@example
2058# cat > server.info <<EOF
2059organization = Name of your organization
2060cn = server.foo.example.com
2061tls_www_server
2062encryption_key
2063signing_key
2064EOF
2065# certtool --generate-privkey > server-key.pem
2066# certtool --generate-certificate \
2067 --load-ca-certificate ca-cert.pem \
2068 --load-ca-privkey ca-key.pem \
2069 --load-privkey server server-key.pem \
2070 --template server.info \
2071 --outfile server-cert.pem
2072@end example
2073
2074The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
2075to the server for which they were generated. The @code{server-key.pem} is security
2076sensitive and should be kept protected with file mode 0600 to prevent disclosure.
2077
2078@node vnc_generate_client
2079@subsubsection Issuing client certificates
2080
2081If the QEMU VNC server is to use the @code{x509verify} option to validate client
2082certificates as its authentication mechanism, each client also needs to be issued
2083a certificate. The client certificate contains enough metadata to uniquely identify
2084the client, typically organization, state, city, building, etc. On the host holding
2085the secure CA private key:
2086
2087@example
2088# cat > client.info <<EOF
2089country = GB
2090state = London
2091locality = London
2092organiazation = Name of your organization
2093cn = client.foo.example.com
2094tls_www_client
2095encryption_key
2096signing_key
2097EOF
2098# certtool --generate-privkey > client-key.pem
2099# certtool --generate-certificate \
2100 --load-ca-certificate ca-cert.pem \
2101 --load-ca-privkey ca-key.pem \
2102 --load-privkey client-key.pem \
2103 --template client.info \
2104 --outfile client-cert.pem
2105@end example
2106
2107The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
2108copied to the client for which they were generated.
2109
0806e3f6 2110@node gdb_usage
da415d54
FB
2111@section GDB usage
2112
2113QEMU has a primitive support to work with gdb, so that you can do
0806e3f6 2114'Ctrl-C' while the virtual machine is running and inspect its state.
da415d54 2115
9d4520d0 2116In order to use gdb, launch qemu with the '-s' option. It will wait for a
da415d54
FB
2117gdb connection:
2118@example
debc7065
FB
2119> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
2120 -append "root=/dev/hda"
da415d54
FB
2121Connected to host network interface: tun0
2122Waiting gdb connection on port 1234
2123@end example
2124
2125Then launch gdb on the 'vmlinux' executable:
2126@example
2127> gdb vmlinux
2128@end example
2129
2130In gdb, connect to QEMU:
2131@example
6c9bf893 2132(gdb) target remote localhost:1234
da415d54
FB
2133@end example
2134
2135Then you can use gdb normally. For example, type 'c' to launch the kernel:
2136@example
2137(gdb) c
2138@end example
2139
0806e3f6
FB
2140Here are some useful tips in order to use gdb on system code:
2141
2142@enumerate
2143@item
2144Use @code{info reg} to display all the CPU registers.
2145@item
2146Use @code{x/10i $eip} to display the code at the PC position.
2147@item
2148Use @code{set architecture i8086} to dump 16 bit code. Then use
294e8637 2149@code{x/10i $cs*16+$eip} to dump the code at the PC position.
0806e3f6
FB
2150@end enumerate
2151
60897d36
EI
2152Advanced debugging options:
2153
2154The 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:
94d45e44 2155@table @code
60897d36
EI
2156@item maintenance packet qqemu.sstepbits
2157
2158This will display the MASK bits used to control the single stepping IE:
2159@example
2160(gdb) maintenance packet qqemu.sstepbits
2161sending: "qqemu.sstepbits"
2162received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
2163@end example
2164@item maintenance packet qqemu.sstep
2165
2166This will display the current value of the mask used when single stepping IE:
2167@example
2168(gdb) maintenance packet qqemu.sstep
2169sending: "qqemu.sstep"
2170received: "0x7"
2171@end example
2172@item maintenance packet Qqemu.sstep=HEX_VALUE
2173
2174This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
2175@example
2176(gdb) maintenance packet Qqemu.sstep=0x5
2177sending: "qemu.sstep=0x5"
2178received: "OK"
2179@end example
94d45e44 2180@end table
60897d36 2181
debc7065 2182@node pcsys_os_specific
1a084f3d
FB
2183@section Target OS specific information
2184
2185@subsection Linux
2186
15a34c63
FB
2187To have access to SVGA graphic modes under X11, use the @code{vesa} or
2188the @code{cirrus} X11 driver. For optimal performances, use 16 bit
2189color depth in the guest and the host OS.
1a084f3d 2190
e3371e62
FB
2191When using a 2.6 guest Linux kernel, you should add the option
2192@code{clock=pit} on the kernel command line because the 2.6 Linux
2193kernels make very strict real time clock checks by default that QEMU
2194cannot simulate exactly.
2195
7c3fc84d
FB
2196When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
2197not activated because QEMU is slower with this patch. The QEMU
2198Accelerator Module is also much slower in this case. Earlier Fedora
4be456f1 2199Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
7c3fc84d
FB
2200patch by default. Newer kernels don't have it.
2201
1a084f3d
FB
2202@subsection Windows
2203
2204If you have a slow host, using Windows 95 is better as it gives the
2205best speed. Windows 2000 is also a good choice.
2206
e3371e62
FB
2207@subsubsection SVGA graphic modes support
2208
2209QEMU emulates a Cirrus Logic GD5446 Video
15a34c63
FB
2210card. All Windows versions starting from Windows 95 should recognize
2211and use this graphic card. For optimal performances, use 16 bit color
2212depth in the guest and the host OS.
1a084f3d 2213
3cb0853a
FB
2214If you are using Windows XP as guest OS and if you want to use high
2215resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
22161280x1024x16), then you should use the VESA VBE virtual graphic card
2217(option @option{-std-vga}).
2218
e3371e62
FB
2219@subsubsection CPU usage reduction
2220
2221Windows 9x does not correctly use the CPU HLT
15a34c63
FB
2222instruction. The result is that it takes host CPU cycles even when
2223idle. You can install the utility from
2224@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
2225problem. Note that no such tool is needed for NT, 2000 or XP.
1a084f3d 2226
9d0a8e6f 2227@subsubsection Windows 2000 disk full problem
e3371e62 2228
9d0a8e6f
FB
2229Windows 2000 has a bug which gives a disk full problem during its
2230installation. When installing it, use the @option{-win2k-hack} QEMU
2231option to enable a specific workaround. After Windows 2000 is
2232installed, you no longer need this option (this option slows down the
2233IDE transfers).
e3371e62 2234
6cc721cf
FB
2235@subsubsection Windows 2000 shutdown
2236
2237Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2238can. It comes from the fact that Windows 2000 does not automatically
2239use the APM driver provided by the BIOS.
2240
2241In order to correct that, do the following (thanks to Struan
2242Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
2243Add/Troubleshoot a device => Add a new device & Next => No, select the
2244hardware from a list & Next => NT Apm/Legacy Support & Next => Next
2245(again) a few times. Now the driver is installed and Windows 2000 now
5fafdf24 2246correctly instructs QEMU to shutdown at the appropriate moment.
6cc721cf
FB
2247
2248@subsubsection Share a directory between Unix and Windows
2249
2250See @ref{sec_invocation} about the help of the option @option{-smb}.
2251
2192c332 2252@subsubsection Windows XP security problem
e3371e62
FB
2253
2254Some releases of Windows XP install correctly but give a security
2255error when booting:
2256@example
2257A problem is preventing Windows from accurately checking the
2258license for this computer. Error code: 0x800703e6.
2259@end example
e3371e62 2260
2192c332
FB
2261The workaround is to install a service pack for XP after a boot in safe
2262mode. Then reboot, and the problem should go away. Since there is no
2263network while in safe mode, its recommended to download the full
2264installation of SP1 or SP2 and transfer that via an ISO or using the
2265vvfat block device ("-hdb fat:directory_which_holds_the_SP").
e3371e62 2266
a0a821a4
FB
2267@subsection MS-DOS and FreeDOS
2268
2269@subsubsection CPU usage reduction
2270
2271DOS does not correctly use the CPU HLT instruction. The result is that
2272it takes host CPU cycles even when idle. You can install the utility
2273from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
2274problem.
2275
debc7065 2276@node QEMU System emulator for non PC targets
3f9f3aa1
FB
2277@chapter QEMU System emulator for non PC targets
2278
2279QEMU is a generic emulator and it emulates many non PC
2280machines. Most of the options are similar to the PC emulator. The
4be456f1 2281differences are mentioned in the following sections.
3f9f3aa1 2282
debc7065
FB
2283@menu
2284* QEMU PowerPC System emulator::
24d4de45
TS
2285* Sparc32 System emulator::
2286* Sparc64 System emulator::
2287* MIPS System emulator::
2288* ARM System emulator::
2289* ColdFire System emulator::
debc7065
FB
2290@end menu
2291
2292@node QEMU PowerPC System emulator
3f9f3aa1 2293@section QEMU PowerPC System emulator
1a084f3d 2294
15a34c63
FB
2295Use the executable @file{qemu-system-ppc} to simulate a complete PREP
2296or PowerMac PowerPC system.
1a084f3d 2297
b671f9ed 2298QEMU emulates the following PowerMac peripherals:
1a084f3d 2299
15a34c63 2300@itemize @minus
5fafdf24
TS
2301@item
2302UniNorth PCI Bridge
15a34c63
FB
2303@item
2304PCI VGA compatible card with VESA Bochs Extensions
5fafdf24 2305@item
15a34c63 23062 PMAC IDE interfaces with hard disk and CD-ROM support
5fafdf24 2307@item
15a34c63
FB
2308NE2000 PCI adapters
2309@item
2310Non Volatile RAM
2311@item
2312VIA-CUDA with ADB keyboard and mouse.
1a084f3d
FB
2313@end itemize
2314
b671f9ed 2315QEMU emulates the following PREP peripherals:
52c00a5f
FB
2316
2317@itemize @minus
5fafdf24 2318@item
15a34c63
FB
2319PCI Bridge
2320@item
2321PCI VGA compatible card with VESA Bochs Extensions
5fafdf24 2322@item
52c00a5f
FB
23232 IDE interfaces with hard disk and CD-ROM support
2324@item
2325Floppy disk
5fafdf24 2326@item
15a34c63 2327NE2000 network adapters
52c00a5f
FB
2328@item
2329Serial port
2330@item
2331PREP Non Volatile RAM
15a34c63
FB
2332@item
2333PC compatible keyboard and mouse.
52c00a5f
FB
2334@end itemize
2335
15a34c63 2336QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
3f9f3aa1 2337@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
52c00a5f 2338
992e5acd 2339Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
13e4e059 2340for the g3beige PowerMac machine. OpenBIOS is a free (GPL v2) portable
992e5acd
BS
2341firmware implementation. The goal is to implement a 100% IEEE
23421275-1994 (referred to as Open Firmware) compliant firmware.
2343
15a34c63
FB
2344@c man begin OPTIONS
2345
2346The following options are specific to the PowerPC emulation:
2347
2348@table @option
2349
3b46e624 2350@item -g WxH[xDEPTH]
15a34c63
FB
2351
2352Set the initial VGA graphic mode. The default is 800x600x15.
2353
95efd11c
BS
2354@item -prom-env string
2355
2356Set OpenBIOS variables in NVRAM, for example:
2357
2358@example
2359qemu-system-ppc -prom-env 'auto-boot?=false' \
2360 -prom-env 'boot-device=hd:2,\yaboot' \
2361 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
2362@end example
2363
2364These variables are not used by Open Hack'Ware.
2365
15a34c63
FB
2366@end table
2367
5fafdf24 2368@c man end
15a34c63
FB
2369
2370
52c00a5f 2371More information is available at
3f9f3aa1 2372@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
52c00a5f 2373
24d4de45
TS
2374@node Sparc32 System emulator
2375@section Sparc32 System emulator
e80cfcfc 2376
34a3d239
BS
2377Use the executable @file{qemu-system-sparc} to simulate the following
2378Sun4m architecture machines:
2379@itemize @minus
2380@item
2381SPARCstation 4
2382@item
2383SPARCstation 5
2384@item
2385SPARCstation 10
2386@item
2387SPARCstation 20
2388@item
2389SPARCserver 600MP
2390@item
2391SPARCstation LX
2392@item
2393SPARCstation Voyager
2394@item
2395SPARCclassic
2396@item
2397SPARCbook
2398@end itemize
2399
2400The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2401but Linux limits the number of usable CPUs to 4.
e80cfcfc 2402
34a3d239
BS
2403It's also possible to simulate a SPARCstation 2 (sun4c architecture),
2404SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
2405emulators are not usable yet.
2406
2407QEMU emulates the following sun4m/sun4c/sun4d peripherals:
e80cfcfc
FB
2408
2409@itemize @minus
3475187d 2410@item
7d85892b 2411IOMMU or IO-UNITs
e80cfcfc
FB
2412@item
2413TCX Frame buffer
5fafdf24 2414@item
e80cfcfc
FB
2415Lance (Am7990) Ethernet
2416@item
34a3d239 2417Non Volatile RAM M48T02/M48T08
e80cfcfc 2418@item
3475187d
FB
2419Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2420and power/reset logic
2421@item
2422ESP SCSI controller with hard disk and CD-ROM support
2423@item
6a3b9cc9 2424Floppy drive (not on SS-600MP)
a2502b58
BS
2425@item
2426CS4231 sound device (only on SS-5, not working yet)
e80cfcfc
FB
2427@end itemize
2428
6a3b9cc9
BS
2429The number of peripherals is fixed in the architecture. Maximum
2430memory size depends on the machine type, for SS-5 it is 256MB and for
7d85892b 2431others 2047MB.
3475187d 2432
30a604f3 2433Since version 0.8.2, QEMU uses OpenBIOS
0986ac3b
FB
2434@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2435firmware implementation. The goal is to implement a 100% IEEE
24361275-1994 (referred to as Open Firmware) compliant firmware.
3475187d
FB
2437
2438A sample Linux 2.6 series kernel and ram disk image are available on
34a3d239
BS
2439the QEMU web site. There are still issues with NetBSD and OpenBSD, but
2440some kernel versions work. Please note that currently Solaris kernels
2441don't work probably due to interface issues between OpenBIOS and
2442Solaris.
3475187d
FB
2443
2444@c man begin OPTIONS
2445
a2502b58 2446The following options are specific to the Sparc32 emulation:
3475187d
FB
2447
2448@table @option
2449
a2502b58 2450@item -g WxHx[xDEPTH]
3475187d 2451
a2502b58
BS
2452Set the initial TCX graphic mode. The default is 1024x768x8, currently
2453the only other possible mode is 1024x768x24.
3475187d 2454
66508601
BS
2455@item -prom-env string
2456
2457Set OpenBIOS variables in NVRAM, for example:
2458
2459@example
2460qemu-system-sparc -prom-env 'auto-boot?=false' \
2461 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2462@end example
2463
34a3d239 2464@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
a2502b58
BS
2465
2466Set the emulated machine type. Default is SS-5.
2467
3475187d
FB
2468@end table
2469
5fafdf24 2470@c man end
3475187d 2471
24d4de45
TS
2472@node Sparc64 System emulator
2473@section Sparc64 System emulator
e80cfcfc 2474
34a3d239
BS
2475Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2476(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2477Niagara (T1) machine. The emulator is not usable for anything yet, but
2478it can launch some kernels.
b756921a 2479
c7ba218d 2480QEMU emulates the following peripherals:
83469015
FB
2481
2482@itemize @minus
2483@item
5fafdf24 2484UltraSparc IIi APB PCI Bridge
83469015
FB
2485@item
2486PCI VGA compatible card with VESA Bochs Extensions
2487@item
34a3d239
BS
2488PS/2 mouse and keyboard
2489@item
83469015
FB
2490Non Volatile RAM M48T59
2491@item
2492PC-compatible serial ports
c7ba218d
BS
2493@item
24942 PCI IDE interfaces with hard disk and CD-ROM support
34a3d239
BS
2495@item
2496Floppy disk
83469015
FB
2497@end itemize
2498
c7ba218d
BS
2499@c man begin OPTIONS
2500
2501The following options are specific to the Sparc64 emulation:
2502
2503@table @option
2504
34a3d239
BS
2505@item -prom-env string
2506
2507Set OpenBIOS variables in NVRAM, for example:
2508
2509@example
2510qemu-system-sparc64 -prom-env 'auto-boot?=false'
2511@end example
2512
2513@item -M [sun4u|sun4v|Niagara]
c7ba218d
BS
2514
2515Set the emulated machine type. The default is sun4u.
2516
2517@end table
2518
2519@c man end
2520
24d4de45
TS
2521@node MIPS System emulator
2522@section MIPS System emulator
9d0a8e6f 2523
d9aedc32
TS
2524Four executables cover simulation of 32 and 64-bit MIPS systems in
2525both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2526@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
88cb0a02 2527Five different machine types are emulated:
24d4de45
TS
2528
2529@itemize @minus
2530@item
2531A generic ISA PC-like machine "mips"
2532@item
2533The MIPS Malta prototype board "malta"
2534@item
d9aedc32 2535An ACER Pica "pica61". This machine needs the 64-bit emulator.
6bf5b4e8 2536@item
f0fc6f8f 2537MIPS emulator pseudo board "mipssim"
88cb0a02
AJ
2538@item
2539A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
24d4de45
TS
2540@end itemize
2541
2542The generic emulation is supported by Debian 'Etch' and is able to
2543install Debian into a virtual disk image. The following devices are
2544emulated:
3f9f3aa1
FB
2545
2546@itemize @minus
5fafdf24 2547@item
6bf5b4e8 2548A range of MIPS CPUs, default is the 24Kf
3f9f3aa1
FB
2549@item
2550PC style serial port
2551@item
24d4de45
TS
2552PC style IDE disk
2553@item
3f9f3aa1
FB
2554NE2000 network card
2555@end itemize
2556
24d4de45
TS
2557The Malta emulation supports the following devices:
2558
2559@itemize @minus
2560@item
0b64d008 2561Core board with MIPS 24Kf CPU and Galileo system controller
24d4de45
TS
2562@item
2563PIIX4 PCI/USB/SMbus controller
2564@item
2565The Multi-I/O chip's serial device
2566@item
2567PCnet32 PCI network card
2568@item
2569Malta FPGA serial device
2570@item
2571Cirrus VGA graphics card
2572@end itemize
2573
2574The ACER Pica emulation supports:
2575
2576@itemize @minus
2577@item
2578MIPS R4000 CPU
2579@item
2580PC-style IRQ and DMA controllers
2581@item
2582PC Keyboard
2583@item
2584IDE controller
2585@end itemize
3f9f3aa1 2586
f0fc6f8f
TS
2587The mipssim pseudo board emulation provides an environment similiar
2588to what the proprietary MIPS emulator uses for running Linux.
2589It supports:
6bf5b4e8
TS
2590
2591@itemize @minus
2592@item
2593A range of MIPS CPUs, default is the 24Kf
2594@item
2595PC style serial port
2596@item
2597MIPSnet network emulation
2598@end itemize
2599
88cb0a02
AJ
2600The MIPS Magnum R4000 emulation supports:
2601
2602@itemize @minus
2603@item
2604MIPS R4000 CPU
2605@item
2606PC-style IRQ controller
2607@item
2608PC Keyboard
2609@item
2610SCSI controller
2611@item
2612G364 framebuffer
2613@end itemize
2614
2615
24d4de45
TS
2616@node ARM System emulator
2617@section ARM System emulator
3f9f3aa1
FB
2618
2619Use the executable @file{qemu-system-arm} to simulate a ARM
2620machine. The ARM Integrator/CP board is emulated with the following
2621devices:
2622
2623@itemize @minus
2624@item
9ee6e8bb 2625ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
3f9f3aa1
FB
2626@item
2627Two PL011 UARTs
5fafdf24 2628@item
3f9f3aa1 2629SMC 91c111 Ethernet adapter
00a9bf19
PB
2630@item
2631PL110 LCD controller
2632@item
2633PL050 KMI with PS/2 keyboard and mouse.
a1bb27b1
PB
2634@item
2635PL181 MultiMedia Card Interface with SD card.
00a9bf19
PB
2636@end itemize
2637
2638The ARM Versatile baseboard is emulated with the following devices:
2639
2640@itemize @minus
2641@item
9ee6e8bb 2642ARM926E, ARM1136 or Cortex-A8 CPU
00a9bf19
PB
2643@item
2644PL190 Vectored Interrupt Controller
2645@item
2646Four PL011 UARTs
5fafdf24 2647@item
00a9bf19
PB
2648SMC 91c111 Ethernet adapter
2649@item
2650PL110 LCD controller
2651@item
2652PL050 KMI with PS/2 keyboard and mouse.
2653@item
2654PCI host bridge. Note the emulated PCI bridge only provides access to
2655PCI memory space. It does not provide access to PCI IO space.
4be456f1
TS
2656This means some devices (eg. ne2k_pci NIC) are not usable, and others
2657(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
00a9bf19 2658mapped control registers.
e6de1bad
PB
2659@item
2660PCI OHCI USB controller.
2661@item
2662LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
a1bb27b1
PB
2663@item
2664PL181 MultiMedia Card Interface with SD card.
3f9f3aa1
FB
2665@end itemize
2666
d7739d75
PB
2667The ARM RealView Emulation baseboard is emulated with the following devices:
2668
2669@itemize @minus
2670@item
9ee6e8bb 2671ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
d7739d75
PB
2672@item
2673ARM AMBA Generic/Distributed Interrupt Controller
2674@item
2675Four PL011 UARTs
5fafdf24 2676@item
d7739d75
PB
2677SMC 91c111 Ethernet adapter
2678@item
2679PL110 LCD controller
2680@item
2681PL050 KMI with PS/2 keyboard and mouse
2682@item
2683PCI host bridge
2684@item
2685PCI OHCI USB controller
2686@item
2687LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
a1bb27b1
PB
2688@item
2689PL181 MultiMedia Card Interface with SD card.
d7739d75
PB
2690@end itemize
2691
b00052e4
AZ
2692The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2693and "Terrier") emulation includes the following peripherals:
2694
2695@itemize @minus
2696@item
2697Intel PXA270 System-on-chip (ARM V5TE core)
2698@item
2699NAND Flash memory
2700@item
2701IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2702@item
2703On-chip OHCI USB controller
2704@item
2705On-chip LCD controller
2706@item
2707On-chip Real Time Clock
2708@item
2709TI ADS7846 touchscreen controller on SSP bus
2710@item
2711Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2712@item
2713GPIO-connected keyboard controller and LEDs
2714@item
549444e1 2715Secure Digital card connected to PXA MMC/SD host
b00052e4
AZ
2716@item
2717Three on-chip UARTs
2718@item
2719WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2720@end itemize
2721
02645926
AZ
2722The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2723following elements:
2724
2725@itemize @minus
2726@item
2727Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2728@item
2729ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2730@item
2731On-chip LCD controller
2732@item
2733On-chip Real Time Clock
2734@item
2735TI TSC2102i touchscreen controller / analog-digital converter / Audio
2736CODEC, connected through MicroWire and I@math{^2}S busses
2737@item
2738GPIO-connected matrix keypad
2739@item
2740Secure Digital card connected to OMAP MMC/SD host
2741@item
2742Three on-chip UARTs
2743@end itemize
2744
c30bb264
AZ
2745Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2746emulation supports the following elements:
2747
2748@itemize @minus
2749@item
2750Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2751@item
2752RAM and non-volatile OneNAND Flash memories
2753@item
2754Display connected to EPSON remote framebuffer chip and OMAP on-chip
2755display controller and a LS041y3 MIPI DBI-C controller
2756@item
2757TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2758driven through SPI bus
2759@item
2760National Semiconductor LM8323-controlled qwerty keyboard driven
2761through I@math{^2}C bus
2762@item
2763Secure Digital card connected to OMAP MMC/SD host
2764@item
2765Three OMAP on-chip UARTs and on-chip STI debugging console
2766@item
2d564691
AZ
2767A Bluetooth(R) transciever and HCI connected to an UART
2768@item
c30bb264
AZ
2769Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2770TUSB6010 chip - only USB host mode is supported
2771@item
2772TI TMP105 temperature sensor driven through I@math{^2}C bus
2773@item
2774TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2775@item
2776Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2777through CBUS
2778@end itemize
2779
9ee6e8bb
PB
2780The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2781devices:
2782
2783@itemize @minus
2784@item
2785Cortex-M3 CPU core.
2786@item
278764k Flash and 8k SRAM.
2788@item
2789Timers, UARTs, ADC and I@math{^2}C interface.
2790@item
2791OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2792@end itemize
2793
2794The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2795devices:
2796
2797@itemize @minus
2798@item
2799Cortex-M3 CPU core.
2800@item
2801256k Flash and 64k SRAM.
2802@item
2803Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2804@item
2805OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2806@end itemize
2807
57cd6e97
AZ
2808The Freecom MusicPal internet radio emulation includes the following
2809elements:
2810
2811@itemize @minus
2812@item
2813Marvell MV88W8618 ARM core.
2814@item
281532 MB RAM, 256 KB SRAM, 8 MB flash.
2816@item
2817Up to 2 16550 UARTs
2818@item
2819MV88W8xx8 Ethernet controller
2820@item
2821MV88W8618 audio controller, WM8750 CODEC and mixer
2822@item
2823