Make qemu_ram_alloc() be able to allocate more than 4GB of memory
[qemu-kvm/fedora.git] / qemu-doc.texi
blobc3a529ba9c6874aa3b9d14f83c5df73cd66decbc
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-doc.info
4 @settitle QEMU Emulator User Documentation
5 @exampleindent 0
6 @paragraphindent 0
7 @c %**end of header
9 @iftex
10 @titlepage
11 @sp 7
12 @center @titlefont{QEMU Emulator}
13 @sp 1
14 @center @titlefont{User Documentation}
15 @sp 3
16 @end titlepage
17 @end iftex
19 @ifnottex
20 @node Top
21 @top
23 @menu
24 * Introduction::
25 * Installation::
26 * QEMU PC System emulator::
27 * QEMU System emulator for non PC targets::
28 * QEMU User space emulator::
29 * compilation:: Compilation from the sources
30 * Index::
31 @end menu
32 @end ifnottex
34 @contents
36 @node Introduction
37 @chapter Introduction
39 @menu
40 * intro_features:: Features
41 @end menu
43 @node intro_features
44 @section Features
46 QEMU is a FAST! processor emulator using dynamic translation to
47 achieve good emulation speed.
49 QEMU has two operating modes:
51 @itemize @minus
53 @item
54 Full system emulation. In this mode, QEMU emulates a full system (for
55 example a PC), including one or several processors and various
56 peripherals. It can be used to launch different Operating Systems
57 without rebooting the PC or to debug system code.
59 @item
60 User mode emulation. In this mode, QEMU can launch
61 processes compiled for one CPU on another CPU. It can be used to
62 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63 to ease cross-compilation and cross-debugging.
65 @end itemize
67 QEMU can run without an host kernel driver and yet gives acceptable
68 performance.
70 For system emulation, the following hardware targets are supported:
71 @itemize
72 @item PC (x86 or x86_64 processor)
73 @item ISA PC (old style PC without PCI bus)
74 @item PREP (PowerPC processor)
75 @item G3 BW PowerMac (PowerPC processor)
76 @item Mac99 PowerMac (PowerPC processor, in progress)
77 @item Sun4m (32-bit Sparc processor)
78 @item Sun4u (64-bit Sparc processor, in progress)
79 @item Malta board (32-bit MIPS processor)
80 @item ARM Integrator/CP (ARM926E, 1026E or 946E processor)
81 @item ARM Versatile baseboard (ARM926E)
82 @item ARM RealView Emulation baseboard (ARM926EJ-S)
83 @item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
84 @item Freescale MCF5208EVB (ColdFire V2).
85 @item Arnewsh MCF5206 evaluation board (ColdFire V2).
86 @end itemize
88 For user emulation, x86, PowerPC, ARM, MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
90 @node Installation
91 @chapter Installation
93 If you want to compile QEMU yourself, see @ref{compilation}.
95 @menu
96 * install_linux::   Linux
97 * install_windows:: Windows
98 * install_mac::     Macintosh
99 @end menu
101 @node install_linux
102 @section Linux
104 If a precompiled package is available for your distribution - you just
105 have to install it. Otherwise, see @ref{compilation}.
107 @node install_windows
108 @section Windows
110 Download the experimental binary installer at
111 @url{http://www.free.oszoo.org/@/download.html}.
113 @node install_mac
114 @section Mac OS X
116 Download the experimental binary installer at
117 @url{http://www.free.oszoo.org/@/download.html}.
119 @node QEMU PC System emulator
120 @chapter QEMU PC System emulator
122 @menu
123 * pcsys_introduction:: Introduction
124 * pcsys_quickstart::   Quick Start
125 * sec_invocation::     Invocation
126 * pcsys_keys::         Keys
127 * pcsys_monitor::      QEMU Monitor
128 * disk_images::        Disk Images
129 * pcsys_network::      Network emulation
130 * direct_linux_boot::  Direct Linux Boot
131 * pcsys_usb::          USB emulation
132 * vnc_security::       VNC security
133 * gdb_usage::          GDB usage
134 * pcsys_os_specific::  Target OS specific information
135 @end menu
137 @node pcsys_introduction
138 @section Introduction
140 @c man begin DESCRIPTION
142 The QEMU PC System emulator simulates the
143 following peripherals:
145 @itemize @minus
146 @item
147 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
148 @item
149 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
150 extensions (hardware level, including all non standard modes).
151 @item
152 PS/2 mouse and keyboard
153 @item
154 2 PCI IDE interfaces with hard disk and CD-ROM support
155 @item
156 Floppy disk
157 @item
158 PCI/ISA PCI network adapters
159 @item
160 Serial ports
161 @item
162 Creative SoundBlaster 16 sound card
163 @item
164 ENSONIQ AudioPCI ES1370 sound card
165 @item
166 Adlib(OPL2) - Yamaha YM3812 compatible chip
167 @item
168 PCI UHCI USB controller and a virtual USB hub.
169 @end itemize
171 SMP is supported with up to 255 CPUs.
173 Note that adlib is only available when QEMU was configured with
174 -enable-adlib
176 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
177 VGA BIOS.
179 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
181 @c man end
183 @node pcsys_quickstart
184 @section Quick Start
186 Download and uncompress the linux image (@file{linux.img}) and type:
188 @example
189 qemu linux.img
190 @end example
192 Linux should boot and give you a prompt.
194 @node sec_invocation
195 @section Invocation
197 @example
198 @c man begin SYNOPSIS
199 usage: qemu [options] [disk_image]
200 @c man end
201 @end example
203 @c man begin OPTIONS
204 @var{disk_image} is a raw hard disk image for IDE hard disk 0.
206 General options:
207 @table @option
208 @item -M machine
209 Select the emulated machine (@code{-M ?} for list)
211 @item -fda file
212 @item -fdb file
213 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
214 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
216 @item -hda file
217 @item -hdb file
218 @item -hdc file
219 @item -hdd file
220 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
222 @item -cdrom file
223 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
224 @option{-cdrom} at the same time). You can use the host CD-ROM by
225 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
227 @item -boot [a|c|d|n]
228 Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
229 is the default.
231 @item -snapshot
232 Write to temporary files instead of disk image files. In this case,
233 the raw disk image you use is not written back. You can however force
234 the write back by pressing @key{C-a s} (@pxref{disk_images}).
236 @item -no-fd-bootchk
237 Disable boot signature checking for floppy disks in Bochs BIOS. It may
238 be needed to boot from old floppy disks.
240 @item -m megs
241 Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
243 @item -smp n
244 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
245 CPUs are supported.
247 @item -audio-help
249 Will show the audio subsystem help: list of drivers, tunable
250 parameters.
252 @item -soundhw card1,card2,... or -soundhw all
254 Enable audio and selected sound hardware. Use ? to print all
255 available sound hardware.
257 @example
258 qemu -soundhw sb16,adlib hda
259 qemu -soundhw es1370 hda
260 qemu -soundhw all hda
261 qemu -soundhw ?
262 @end example
264 @item -localtime
265 Set the real time clock to local time (the default is to UTC
266 time). This option is needed to have correct date in MS-DOS or
267 Windows.
269 @item -pidfile file
270 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
271 from a script.
273 @item -daemonize
274 Daemonize the QEMU process after initialization.  QEMU will not detach from
275 standard IO until it is ready to receive connections on any of its devices.
276 This option is a useful way for external programs to launch QEMU without having
277 to cope with initialization race conditions.
279 @item -win2k-hack
280 Use it when installing Windows 2000 to avoid a disk full bug. After
281 Windows 2000 is installed, you no longer need this option (this option
282 slows down the IDE transfers).
284 @item -option-rom file
285 Load the contents of file as an option ROM.  This option is useful to load
286 things like EtherBoot.
288 @item -name string
289 Sets the name of the guest.  This name will be display in the SDL window
290 caption.  The name will also be used for the VNC server.
292 @end table
294 Display options:
295 @table @option
297 @item -nographic
299 Normally, QEMU uses SDL to display the VGA output. With this option,
300 you can totally disable graphical output so that QEMU is a simple
301 command line application. The emulated serial port is redirected on
302 the console. Therefore, you can still use QEMU to debug a Linux kernel
303 with a serial console.
305 @item -no-frame
307 Do not use decorations for SDL windows and start them using the whole
308 available screen space. This makes the using QEMU in a dedicated desktop
309 workspace more convenient.
311 @item -full-screen
312 Start in full screen.
314 @item -vnc display[,option[,option[,...]]]
316 Normally, QEMU uses SDL to display the VGA output.  With this option,
317 you can have QEMU listen on VNC display @var{display} and redirect the VGA
318 display over the VNC session.  It is very useful to enable the usb
319 tablet device when using this option (option @option{-usbdevice
320 tablet}). When using the VNC display, you must use the @option{-k}
321 parameter to set the keyboard layout if you are not using en-us. Valid
322 syntax for the @var{display} is
324 @table @code
326 @item @var{interface:d}
328 TCP connections will only be allowed from @var{interface} on display @var{d}.
329 By convention the TCP port is 5900+@var{d}. Optionally, @var{interface} can
330 be omitted in which case the server will bind to all interfaces.
332 @item @var{unix:path}
334 Connections will be allowed over UNIX domain sockets where @var{path} is the
335 location of a unix socket to listen for connections on.
337 @item @var{none}
339 VNC is initialized by not started. The monitor @code{change} command can be used
340 to later start the VNC server.
342 @end table
344 Following the @var{display} value there may be one or more @var{option} flags
345 separated by commas. Valid options are
347 @table @code
349 @item @var{password}
351 Require that password based authentication is used for client connections.
352 The password must be set separately using the @code{change} command in the
353 @ref{pcsys_monitor}
355 @item @var{tls}
357 Require that client use TLS when communicating with the VNC server. This
358 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
359 attack. It is recommended that this option be combined with either the
360 @var{x509} or @var{x509verify} options.
362 @item @var{x509=/path/to/certificate/dir}
364 Valid if @var{tls} is specified. Require that x509 credentials are used
365 for negotiating the TLS session. The server will send its x509 certificate
366 to the client. It is recommended that a password be set on the VNC server
367 to provide authentication of the client when this is used. The path following
368 this option specifies where the x509 certificates are to be loaded from.
369 See the @ref{vnc_security} section for details on generating certificates.
371 @item @var{x509verify=/path/to/certificate/dir}
373 Valid if @var{tls} is specified. Require that x509 credentials are used
374 for negotiating the TLS session. The server will send its x509 certificate
375 to the client, and request that the client send its own x509 certificate.
376 The server will validate the client's certificate against the CA certificate,
377 and reject clients when validation fails. If the certificate authority is
378 trusted, this is a sufficient authentication mechanism. You may still wish
379 to set a password on the VNC server as a second authentication layer. The
380 path following this option specifies where the x509 certificates are to
381 be loaded from. See the @ref{vnc_security} section for details on generating
382 certificates.
384 @end table
386 @item -k language
388 Use keyboard layout @var{language} (for example @code{fr} for
389 French). This option is only needed where it is not easy to get raw PC
390 keycodes (e.g. on Macs, with some X11 servers or with a VNC
391 display). You don't normally need to use it on PC/Linux or PC/Windows
392 hosts.
394 The available layouts are:
395 @example
396 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
397 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
398 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
399 @end example
401 The default is @code{en-us}.
403 @end table
405 USB options:
406 @table @option
408 @item -usb
409 Enable the USB driver (will be the default soon)
411 @item -usbdevice devname
412 Add the USB device @var{devname}. @xref{usb_devices}.
413 @end table
415 Network options:
417 @table @option
419 @item -net nic[,vlan=n][,macaddr=addr][,model=type]
420 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
421 = 0 is the default). The NIC is an ne2k_pci by default on the PC
422 target. Optionally, the MAC address can be changed. If no
423 @option{-net} option is specified, a single NIC is created.
424 Qemu can emulate several different models of network card.
425 Valid values for @var{type} are
426 @code{i82551}, @code{i82557b}, @code{i82559er},
427 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
428 @code{smc91c111}, @code{lance} and @code{mcf_fec}.
429 Not all devices are supported on all targets.  Use -net nic,model=?
430 for a list of available devices for your target.
432 @item -net user[,vlan=n][,hostname=name]
433 Use the user mode network stack which requires no administrator
434 privilege to run.  @option{hostname=name} can be used to specify the client
435 hostname reported by the builtin DHCP server.
437 @item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
438 Connect the host TAP network interface @var{name} to VLAN @var{n} and
439 use the network script @var{file} to configure it. The default
440 network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
441 disable script execution. If @var{name} is not
442 provided, the OS automatically provides one.  @option{fd=h} can be
443 used to specify the handle of an already opened host TAP interface. Example:
445 @example
446 qemu linux.img -net nic -net tap
447 @end example
449 More complicated example (two NICs, each one connected to a TAP device)
450 @example
451 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
452                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
453 @end example
456 @item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
458 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
459 machine using a TCP socket connection. If @option{listen} is
460 specified, QEMU waits for incoming connections on @var{port}
461 (@var{host} is optional). @option{connect} is used to connect to
462 another QEMU instance using the @option{listen} option. @option{fd=h}
463 specifies an already opened TCP socket.
465 Example:
466 @example
467 # launch a first QEMU instance
468 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
469                -net socket,listen=:1234
470 # connect the VLAN 0 of this instance to the VLAN 0
471 # of the first instance
472 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
473                -net socket,connect=127.0.0.1:1234
474 @end example
476 @item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]
478 Create a VLAN @var{n} shared with another QEMU virtual
479 machines using a UDP multicast socket, effectively making a bus for
480 every QEMU with same multicast address @var{maddr} and @var{port}.
481 NOTES:
482 @enumerate
483 @item
484 Several QEMU can be running on different hosts and share same bus (assuming
485 correct multicast setup for these hosts).
486 @item
487 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
488 @url{http://user-mode-linux.sf.net}.
489 @item
490 Use @option{fd=h} to specify an already opened UDP multicast socket.
491 @end enumerate
493 Example:
494 @example
495 # launch one QEMU instance
496 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
497                -net socket,mcast=230.0.0.1:1234
498 # launch another QEMU instance on same "bus"
499 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
500                -net socket,mcast=230.0.0.1:1234
501 # launch yet another QEMU instance on same "bus"
502 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
503                -net socket,mcast=230.0.0.1:1234
504 @end example
506 Example (User Mode Linux compat.):
507 @example
508 # launch QEMU instance (note mcast address selected
509 # is UML's default)
510 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
511                -net socket,mcast=239.192.168.1:1102
512 # launch UML
513 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
514 @end example
516 @item -net none
517 Indicate that no network devices should be configured. It is used to
518 override the default configuration (@option{-net nic -net user}) which
519 is activated if no @option{-net} options are provided.
521 @item -tftp dir
522 When using the user mode network stack, activate a built-in TFTP
523 server. The files in @var{dir} will be exposed as the root of a TFTP server.
524 The TFTP client on the guest must be configured in binary mode (use the command
525 @code{bin} of the Unix TFTP client). The host IP address on the guest is as
526 usual 10.0.2.2.
528 @item -bootp file
529 When using the user mode network stack, broadcast @var{file} as the BOOTP
530 filename.  In conjunction with @option{-tftp}, this can be used to network boot
531 a guest from a local directory.
533 Example (using pxelinux):
534 @example
535 qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
536 @end example
538 @item -smb dir
539 When using the user mode network stack, activate a built-in SMB
540 server so that Windows OSes can access to the host files in @file{dir}
541 transparently.
543 In the guest Windows OS, the line:
544 @example
545 10.0.2.4 smbserver
546 @end example
547 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
548 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
550 Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
552 Note that a SAMBA server must be installed on the host OS in
553 @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
554 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
556 @item -redir [tcp|udp]:host-port:[guest-host]:guest-port
558 When using the user mode network stack, redirect incoming TCP or UDP
559 connections to the host port @var{host-port} to the guest
560 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
561 is not specified, its value is 10.0.2.15 (default address given by the
562 built-in DHCP server).
564 For example, to redirect host X11 connection from screen 1 to guest
565 screen 0, use the following:
567 @example
568 # on the host
569 qemu -redir tcp:6001::6000 [...]
570 # this host xterm should open in the guest X11 server
571 xterm -display :1
572 @end example
574 To redirect telnet connections from host port 5555 to telnet port on
575 the guest, use the following:
577 @example
578 # on the host
579 qemu -redir tcp:5555::23 [...]
580 telnet localhost 5555
581 @end example
583 Then when you use on the host @code{telnet localhost 5555}, you
584 connect to the guest telnet server.
586 @end table
588 Linux boot specific: When using these options, you can use a given
589 Linux kernel without installing it in the disk image. It can be useful
590 for easier testing of various kernels.
592 @table @option
594 @item -kernel bzImage
595 Use @var{bzImage} as kernel image.
597 @item -append cmdline
598 Use @var{cmdline} as kernel command line
600 @item -initrd file
601 Use @var{file} as initial ram disk.
603 @end table
605 Debug/Expert options:
606 @table @option
608 @item -serial dev
609 Redirect the virtual serial port to host character device
610 @var{dev}. The default device is @code{vc} in graphical mode and
611 @code{stdio} in non graphical mode.
613 This option can be used several times to simulate up to 4 serials
614 ports.
616 Use @code{-serial none} to disable all serial ports.
618 Available character devices are:
619 @table @code
620 @item vc[:WxH]
621 Virtual console. Optionally, a width and height can be given in pixel with
622 @example
623 vc:800x600
624 @end example
625 It is also possible to specify width or height in characters:
626 @example
627 vc:80Cx24C
628 @end example
629 @item pty
630 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
631 @item none
632 No device is allocated.
633 @item null
634 void device
635 @item /dev/XXX
636 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
637 parameters are set according to the emulated ones.
638 @item /dev/parportN
639 [Linux only, parallel port only] Use host parallel port
640 @var{N}. Currently SPP and EPP parallel port features can be used.
641 @item file:filename
642 Write output to filename. No character can be read.
643 @item stdio
644 [Unix only] standard input/output
645 @item pipe:filename
646 name pipe @var{filename}
647 @item COMn
648 [Windows only] Use host serial port @var{n}
649 @item udp:[remote_host]:remote_port[@@[src_ip]:src_port]
650 This implements UDP Net Console.  When @var{remote_host} or @var{src_ip} are not specified they default to @code{0.0.0.0}.  When not using a specified @var{src_port} a random port is automatically chosen.
652 If you just want a simple readonly console you can use @code{netcat} or
653 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
654 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
655 will appear in the netconsole session.
657 If you plan to send characters back via netconsole or you want to stop
658 and start qemu a lot of times, you should have qemu use the same
659 source port each time by using something like @code{-serial
660 udp::4555@@:4556} to qemu. Another approach is to use a patched
661 version of netcat which can listen to a TCP port and send and receive
662 characters via udp.  If you have a patched version of netcat which
663 activates telnet remote echo and single char transfer, then you can
664 use the following options to step up a netcat redirector to allow
665 telnet on port 5555 to access the qemu port.
666 @table @code
667 @item Qemu Options:
668 -serial udp::4555@@:4556
669 @item netcat options:
670 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
671 @item telnet options:
672 localhost 5555
673 @end table
676 @item tcp:[host]:port[,server][,nowait][,nodelay]
677 The TCP Net Console has two modes of operation.  It can send the serial
678 I/O to a location or wait for a connection from a location.  By default
679 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
680 the @var{server} option QEMU will wait for a client socket application
681 to connect to the port before continuing, unless the @code{nowait}
682 option was specified.  The @code{nodelay} option disables the Nagle buffering
683 algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
684 one TCP connection at a time is accepted. You can use @code{telnet} to
685 connect to the corresponding character device.
686 @table @code
687 @item Example to send tcp console to 192.168.0.2 port 4444
688 -serial tcp:192.168.0.2:4444
689 @item Example to listen and wait on port 4444 for connection
690 -serial tcp::4444,server
691 @item Example to not wait and listen on ip 192.168.0.100 port 4444
692 -serial tcp:192.168.0.100:4444,server,nowait
693 @end table
695 @item telnet:host:port[,server][,nowait][,nodelay]
696 The telnet protocol is used instead of raw tcp sockets.  The options
697 work the same as if you had specified @code{-serial tcp}.  The
698 difference is that the port acts like a telnet server or client using
699 telnet option negotiation.  This will also allow you to send the
700 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
701 sequence.  Typically in unix telnet you do it with Control-] and then
702 type "send break" followed by pressing the enter key.
704 @item unix:path[,server][,nowait]
705 A unix domain socket is used instead of a tcp socket.  The option works the
706 same as if you had specified @code{-serial tcp} except the unix domain socket
707 @var{path} is used for connections.
709 @item mon:dev_string
710 This is a special option to allow the monitor to be multiplexed onto
711 another serial port.  The monitor is accessed with key sequence of
712 @key{Control-a} and then pressing @key{c}. See monitor access
713 @ref{pcsys_keys} in the -nographic section for more keys.
714 @var{dev_string} should be any one of the serial devices specified
715 above.  An example to multiplex the monitor onto a telnet server
716 listening on port 4444 would be:
717 @table @code
718 @item -serial mon:telnet::4444,server,nowait
719 @end table
721 @end table
723 @item -parallel dev
724 Redirect the virtual parallel port to host device @var{dev} (same
725 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
726 be used to use hardware devices connected on the corresponding host
727 parallel port.
729 This option can be used several times to simulate up to 3 parallel
730 ports.
732 Use @code{-parallel none} to disable all parallel ports.
734 @item -monitor dev
735 Redirect the monitor to host device @var{dev} (same devices as the
736 serial port).
737 The default device is @code{vc} in graphical mode and @code{stdio} in
738 non graphical mode.
740 @item -echr numeric_ascii_value
741 Change the escape character used for switching to the monitor when using
742 monitor and serial sharing.  The default is @code{0x01} when using the
743 @code{-nographic} option.  @code{0x01} is equal to pressing
744 @code{Control-a}.  You can select a different character from the ascii
745 control keys where 1 through 26 map to Control-a through Control-z.  For
746 instance you could use the either of the following to change the escape
747 character to Control-t.
748 @table @code
749 @item -echr 0x14
750 @item -echr 20
751 @end table
753 @item -s
754 Wait gdb connection to port 1234 (@pxref{gdb_usage}).
755 @item -p port
756 Change gdb connection port.  @var{port} can be either a decimal number
757 to specify a TCP port, or a host device (same devices as the serial port).
758 @item -S
759 Do not start CPU at startup (you must type 'c' in the monitor).
760 @item -d
761 Output log in /tmp/qemu.log
762 @item -hdachs c,h,s,[,t]
763 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
764 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
765 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
766 all those parameters. This option is useful for old MS-DOS disk
767 images.
769 @item -L path
770 Set the directory for the BIOS, VGA BIOS and keymaps.
772 @item -std-vga
773 Simulate a standard VGA card with Bochs VBE extensions (default is
774 Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
775 VBE extensions (e.g. Windows XP) and if you want to use high
776 resolution modes (>= 1280x1024x16) then you should use this option.
778 @item -no-acpi
779 Disable ACPI (Advanced Configuration and Power Interface) support. Use
780 it if your guest OS complains about ACPI problems (PC target machine
781 only).
783 @item -no-reboot
784 Exit instead of rebooting.
786 @item -loadvm file
787 Start right away with a saved state (@code{loadvm} in monitor)
789 @item -semihosting
790 Enable semihosting syscall emulation (ARM and M68K target machines only).
792 On ARM this implements the "Angel" interface.
793 On M68K this implements the "ColdFire GDB" interface used by libgloss.
795 Note that this allows guest direct access to the host filesystem,
796 so should only be used with trusted guest OS.
797 @end table
799 @c man end
801 @node pcsys_keys
802 @section Keys
804 @c man begin OPTIONS
806 During the graphical emulation, you can use the following keys:
807 @table @key
808 @item Ctrl-Alt-f
809 Toggle full screen
811 @item Ctrl-Alt-n
812 Switch to virtual console 'n'. Standard console mappings are:
813 @table @emph
814 @item 1
815 Target system display
816 @item 2
817 Monitor
818 @item 3
819 Serial port
820 @end table
822 @item Ctrl-Alt
823 Toggle mouse and keyboard grab.
824 @end table
826 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
827 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
829 During emulation, if you are using the @option{-nographic} option, use
830 @key{Ctrl-a h} to get terminal commands:
832 @table @key
833 @item Ctrl-a h
834 Print this help
835 @item Ctrl-a x
836 Exit emulator
837 @item Ctrl-a s
838 Save disk data back to file (if -snapshot)
839 @item Ctrl-a t
840 toggle console timestamps
841 @item Ctrl-a b
842 Send break (magic sysrq in Linux)
843 @item Ctrl-a c
844 Switch between console and monitor
845 @item Ctrl-a Ctrl-a
846 Send Ctrl-a
847 @end table
848 @c man end
850 @ignore
852 @c man begin SEEALSO
853 The HTML documentation of QEMU for more precise information and Linux
854 user mode emulator invocation.
855 @c man end
857 @c man begin AUTHOR
858 Fabrice Bellard
859 @c man end
861 @end ignore
863 @node pcsys_monitor
864 @section QEMU Monitor
866 The QEMU monitor is used to give complex commands to the QEMU
867 emulator. You can use it to:
869 @itemize @minus
871 @item
872 Remove or insert removable media images
873 (such as CD-ROM or floppies)
875 @item
876 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
877 from a disk file.
879 @item Inspect the VM state without an external debugger.
881 @end itemize
883 @subsection Commands
885 The following commands are available:
887 @table @option
889 @item help or ? [cmd]
890 Show the help for all commands or just for command @var{cmd}.
892 @item commit
893 Commit changes to the disk images (if -snapshot is used)
895 @item info subcommand
896 show various information about the system state
898 @table @option
899 @item info network
900 show the various VLANs and the associated devices
901 @item info block
902 show the block devices
903 @item info registers
904 show the cpu registers
905 @item info history
906 show the command line history
907 @item info pci
908 show emulated PCI device
909 @item info usb
910 show USB devices plugged on the virtual USB hub
911 @item info usbhost
912 show all USB host devices
913 @item info capture
914 show information about active capturing
915 @item info snapshots
916 show list of VM snapshots
917 @item info mice
918 show which guest mouse is receiving events
919 @end table
921 @item q or quit
922 Quit the emulator.
924 @item eject [-f] device
925 Eject a removable medium (use -f to force it).
927 @item change device setting
929 Change the configuration of a device
931 @table @option
932 @item change @var{diskdevice} @var{filename}
933 Change the medium for a removable disk device to point to @var{filename}. eg
935 @example
936 (qemu) change cdrom /path/to/some.iso
937 @end example
939 @item change vnc @var{display,options}
940 Change the configuration of the VNC server. The valid syntax for @var{display}
941 and @var{options} are described at @ref{sec_invocation}. eg
943 @example
944 (qemu) change vnc localhost:1
945 @end example
947 @item change vnc password
949 Change the password associated with the VNC server. The monitor will prompt for
950 the new password to be entered. VNC passwords are only significant upto 8 letters.
953 @example
954 (qemu) change vnc password
955 Password: ********
956 @end example
958 @end table
960 @item screendump filename
961 Save screen into PPM image @var{filename}.
963 @item mouse_move dx dy [dz]
964 Move the active mouse to the specified coordinates @var{dx} @var{dy}
965 with optional scroll axis @var{dz}.
967 @item mouse_button val
968 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
970 @item mouse_set index
971 Set which mouse device receives events at given @var{index}, index
972 can be obtained with
973 @example
974 info mice
975 @end example
977 @item wavcapture filename [frequency [bits [channels]]]
978 Capture audio into @var{filename}. Using sample rate @var{frequency}
979 bits per sample @var{bits} and number of channels @var{channels}.
981 Defaults:
982 @itemize @minus
983 @item Sample rate = 44100 Hz - CD quality
984 @item Bits = 16
985 @item Number of channels = 2 - Stereo
986 @end itemize
988 @item stopcapture index
989 Stop capture with a given @var{index}, index can be obtained with
990 @example
991 info capture
992 @end example
994 @item log item1[,...]
995 Activate logging of the specified items to @file{/tmp/qemu.log}.
997 @item savevm [tag|id]
998 Create a snapshot of the whole virtual machine. If @var{tag} is
999 provided, it is used as human readable identifier. If there is already
1000 a snapshot with the same tag or ID, it is replaced. More info at
1001 @ref{vm_snapshots}.
1003 @item loadvm tag|id
1004 Set the whole virtual machine to the snapshot identified by the tag
1005 @var{tag} or the unique snapshot ID @var{id}.
1007 @item delvm tag|id
1008 Delete the snapshot identified by @var{tag} or @var{id}.
1010 @item stop
1011 Stop emulation.
1013 @item c or cont
1014 Resume emulation.
1016 @item gdbserver [port]
1017 Start gdbserver session (default port=1234)
1019 @item x/fmt addr
1020 Virtual memory dump starting at @var{addr}.
1022 @item xp /fmt addr
1023 Physical memory dump starting at @var{addr}.
1025 @var{fmt} is a format which tells the command how to format the
1026 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1028 @table @var
1029 @item count
1030 is the number of items to be dumped.
1032 @item format
1033 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
1034 c (char) or i (asm instruction).
1036 @item size
1037 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1038 @code{h} or @code{w} can be specified with the @code{i} format to
1039 respectively select 16 or 32 bit code instruction size.
1041 @end table
1043 Examples:
1044 @itemize
1045 @item
1046 Dump 10 instructions at the current instruction pointer:
1047 @example
1048 (qemu) x/10i $eip
1049 0x90107063:  ret
1050 0x90107064:  sti
1051 0x90107065:  lea    0x0(%esi,1),%esi
1052 0x90107069:  lea    0x0(%edi,1),%edi
1053 0x90107070:  ret
1054 0x90107071:  jmp    0x90107080
1055 0x90107073:  nop
1056 0x90107074:  nop
1057 0x90107075:  nop
1058 0x90107076:  nop
1059 @end example
1061 @item
1062 Dump 80 16 bit values at the start of the video memory.
1063 @smallexample
1064 (qemu) xp/80hx 0xb8000
1065 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
1066 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
1067 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
1068 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
1069 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
1070 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
1071 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1072 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1073 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1074 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1075 @end smallexample
1076 @end itemize
1078 @item p or print/fmt expr
1080 Print expression value. Only the @var{format} part of @var{fmt} is
1081 used.
1083 @item sendkey keys
1085 Send @var{keys} to the emulator. Use @code{-} to press several keys
1086 simultaneously. Example:
1087 @example
1088 sendkey ctrl-alt-f1
1089 @end example
1091 This command is useful to send keys that your graphical user interface
1092 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1094 @item system_reset
1096 Reset the system.
1098 @item usb_add devname
1100 Add the USB device @var{devname}.  For details of available devices see
1101 @ref{usb_devices}
1103 @item usb_del devname
1105 Remove the USB device @var{devname} from the QEMU virtual USB
1106 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1107 command @code{info usb} to see the devices you can remove.
1109 @end table
1111 @subsection Integer expressions
1113 The monitor understands integers expressions for every integer
1114 argument. You can use register names to get the value of specifics
1115 CPU registers by prefixing them with @emph{$}.
1117 @node disk_images
1118 @section Disk Images
1120 Since version 0.6.1, QEMU supports many disk image formats, including
1121 growable disk images (their size increase as non empty sectors are
1122 written), compressed and encrypted disk images. Version 0.8.3 added
1123 the new qcow2 disk image format which is essential to support VM
1124 snapshots.
1126 @menu
1127 * disk_images_quickstart::    Quick start for disk image creation
1128 * disk_images_snapshot_mode:: Snapshot mode
1129 * vm_snapshots::              VM snapshots
1130 * qemu_img_invocation::       qemu-img Invocation
1131 * host_drives::               Using host drives
1132 * disk_images_fat_images::    Virtual FAT disk images
1133 @end menu
1135 @node disk_images_quickstart
1136 @subsection Quick start for disk image creation
1138 You can create a disk image with the command:
1139 @example
1140 qemu-img create myimage.img mysize
1141 @end example
1142 where @var{myimage.img} is the disk image filename and @var{mysize} is its
1143 size in kilobytes. You can add an @code{M} suffix to give the size in
1144 megabytes and a @code{G} suffix for gigabytes.
1146 See @ref{qemu_img_invocation} for more information.
1148 @node disk_images_snapshot_mode
1149 @subsection Snapshot mode
1151 If you use the option @option{-snapshot}, all disk images are
1152 considered as read only. When sectors in written, they are written in
1153 a temporary file created in @file{/tmp}. You can however force the
1154 write back to the raw disk images by using the @code{commit} monitor
1155 command (or @key{C-a s} in the serial console).
1157 @node vm_snapshots
1158 @subsection VM snapshots
1160 VM snapshots are snapshots of the complete virtual machine including
1161 CPU state, RAM, device state and the content of all the writable
1162 disks. In order to use VM snapshots, you must have at least one non
1163 removable and writable block device using the @code{qcow2} disk image
1164 format. Normally this device is the first virtual hard drive.
1166 Use the monitor command @code{savevm} to create a new VM snapshot or
1167 replace an existing one. A human readable name can be assigned to each
1168 snapshot in addition to its numerical ID.
1170 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1171 a VM snapshot. @code{info snapshots} lists the available snapshots
1172 with their associated information:
1174 @example
1175 (qemu) info snapshots
1176 Snapshot devices: hda
1177 Snapshot list (from hda):
1178 ID        TAG                 VM SIZE                DATE       VM CLOCK
1179 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
1180 2                                 40M 2006-08-06 12:43:29   00:00:18.633
1181 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
1182 @end example
1184 A VM snapshot is made of a VM state info (its size is shown in
1185 @code{info snapshots}) and a snapshot of every writable disk image.
1186 The VM state info is stored in the first @code{qcow2} non removable
1187 and writable block device. The disk image snapshots are stored in
1188 every disk image. The size of a snapshot in a disk image is difficult
1189 to evaluate and is not shown by @code{info snapshots} because the
1190 associated disk sectors are shared among all the snapshots to save
1191 disk space (otherwise each snapshot would need a full copy of all the
1192 disk images).
1194 When using the (unrelated) @code{-snapshot} option
1195 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1196 but they are deleted as soon as you exit QEMU.
1198 VM snapshots currently have the following known limitations:
1199 @itemize
1200 @item
1201 They cannot cope with removable devices if they are removed or
1202 inserted after a snapshot is done.
1203 @item
1204 A few device drivers still have incomplete snapshot support so their
1205 state is not saved or restored properly (in particular USB).
1206 @end itemize
1208 @node qemu_img_invocation
1209 @subsection @code{qemu-img} Invocation
1211 @include qemu-img.texi
1213 @node host_drives
1214 @subsection Using host drives
1216 In addition to disk image files, QEMU can directly access host
1217 devices. We describe here the usage for QEMU version >= 0.8.3.
1219 @subsubsection Linux
1221 On Linux, you can directly use the host device filename instead of a
1222 disk image filename provided you have enough privileges to access
1223 it. For example, use @file{/dev/cdrom} to access to the CDROM or
1224 @file{/dev/fd0} for the floppy.
1226 @table @code
1227 @item CD
1228 You can specify a CDROM device even if no CDROM is loaded. QEMU has
1229 specific code to detect CDROM insertion or removal. CDROM ejection by
1230 the guest OS is supported. Currently only data CDs are supported.
1231 @item Floppy
1232 You can specify a floppy device even if no floppy is loaded. Floppy
1233 removal is currently not detected accurately (if you change floppy
1234 without doing floppy access while the floppy is not loaded, the guest
1235 OS will think that the same floppy is loaded).
1236 @item Hard disks
1237 Hard disks can be used. Normally you must specify the whole disk
1238 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1239 see it as a partitioned disk. WARNING: unless you know what you do, it
1240 is better to only make READ-ONLY accesses to the hard disk otherwise
1241 you may corrupt your host data (use the @option{-snapshot} command
1242 line option or modify the device permissions accordingly).
1243 @end table
1245 @subsubsection Windows
1247 @table @code
1248 @item CD
1249 The preferred syntax is the drive letter (e.g. @file{d:}). The
1250 alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1251 supported as an alias to the first CDROM drive.
1253 Currently there is no specific code to handle removable media, so it
1254 is better to use the @code{change} or @code{eject} monitor commands to
1255 change or eject media.
1256 @item Hard disks
1257 Hard disks can be used with the syntax: @file{\\.\PhysicalDriveN}
1258 where @var{N} is the drive number (0 is the first hard disk).
1260 WARNING: unless you know what you do, it is better to only make
1261 READ-ONLY accesses to the hard disk otherwise you may corrupt your
1262 host data (use the @option{-snapshot} command line so that the
1263 modifications are written in a temporary file).
1264 @end table
1267 @subsubsection Mac OS X
1269 @file{/dev/cdrom} is an alias to the first CDROM.
1271 Currently there is no specific code to handle removable media, so it
1272 is better to use the @code{change} or @code{eject} monitor commands to
1273 change or eject media.
1275 @node disk_images_fat_images
1276 @subsection Virtual FAT disk images
1278 QEMU can automatically create a virtual FAT disk image from a
1279 directory tree. In order to use it, just type:
1281 @example
1282 qemu linux.img -hdb fat:/my_directory
1283 @end example
1285 Then you access access to all the files in the @file{/my_directory}
1286 directory without having to copy them in a disk image or to export
1287 them via SAMBA or NFS. The default access is @emph{read-only}.
1289 Floppies can be emulated with the @code{:floppy:} option:
1291 @example
1292 qemu linux.img -fda fat:floppy:/my_directory
1293 @end example
1295 A read/write support is available for testing (beta stage) with the
1296 @code{:rw:} option:
1298 @example
1299 qemu linux.img -fda fat:floppy:rw:/my_directory
1300 @end example
1302 What you should @emph{never} do:
1303 @itemize
1304 @item use non-ASCII filenames ;
1305 @item use "-snapshot" together with ":rw:" ;
1306 @item expect it to work when loadvm'ing ;
1307 @item write to the FAT directory on the host system while accessing it with the guest system.
1308 @end itemize
1310 @node pcsys_network
1311 @section Network emulation
1313 QEMU can simulate several network cards (PCI or ISA cards on the PC
1314 target) and can connect them to an arbitrary number of Virtual Local
1315 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1316 VLAN. VLAN can be connected between separate instances of QEMU to
1317 simulate large networks. For simpler usage, a non privileged user mode
1318 network stack can replace the TAP device to have a basic network
1319 connection.
1321 @subsection VLANs
1323 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1324 connection between several network devices. These devices can be for
1325 example QEMU virtual Ethernet cards or virtual Host ethernet devices
1326 (TAP devices).
1328 @subsection Using TAP network interfaces
1330 This is the standard way to connect QEMU to a real network. QEMU adds
1331 a virtual network device on your host (called @code{tapN}), and you
1332 can then configure it as if it was a real ethernet card.
1334 @subsubsection Linux host
1336 As an example, you can download the @file{linux-test-xxx.tar.gz}
1337 archive and copy the script @file{qemu-ifup} in @file{/etc} and
1338 configure properly @code{sudo} so that the command @code{ifconfig}
1339 contained in @file{qemu-ifup} can be executed as root. You must verify
1340 that your host kernel supports the TAP network interfaces: the
1341 device @file{/dev/net/tun} must be present.
1343 See @ref{sec_invocation} to have examples of command lines using the
1344 TAP network interfaces.
1346 @subsubsection Windows host
1348 There is a virtual ethernet driver for Windows 2000/XP systems, called
1349 TAP-Win32. But it is not included in standard QEMU for Windows,
1350 so you will need to get it separately. It is part of OpenVPN package,
1351 so download OpenVPN from : @url{http://openvpn.net/}.
1353 @subsection Using the user mode network stack
1355 By using the option @option{-net user} (default configuration if no
1356 @option{-net} option is specified), QEMU uses a completely user mode
1357 network stack (you don't need root privilege to use the virtual
1358 network). The virtual network configuration is the following:
1360 @example
1362          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
1363                            |          (10.0.2.2)
1364                            |
1365                            ---->  DNS server (10.0.2.3)
1366                            |
1367                            ---->  SMB server (10.0.2.4)
1368 @end example
1370 The QEMU VM behaves as if it was behind a firewall which blocks all
1371 incoming connections. You can use a DHCP client to automatically
1372 configure the network in the QEMU VM. The DHCP server assign addresses
1373 to the hosts starting from 10.0.2.15.
1375 In order to check that the user mode network is working, you can ping
1376 the address 10.0.2.2 and verify that you got an address in the range
1377 10.0.2.x from the QEMU virtual DHCP server.
1379 Note that @code{ping} is not supported reliably to the internet as it
1380 would require root privileges. It means you can only ping the local
1381 router (10.0.2.2).
1383 When using the built-in TFTP server, the router is also the TFTP
1384 server.
1386 When using the @option{-redir} option, TCP or UDP connections can be
1387 redirected from the host to the guest. It allows for example to
1388 redirect X11, telnet or SSH connections.
1390 @subsection Connecting VLANs between QEMU instances
1392 Using the @option{-net socket} option, it is possible to make VLANs
1393 that span several QEMU instances. See @ref{sec_invocation} to have a
1394 basic example.
1396 @node direct_linux_boot
1397 @section Direct Linux Boot
1399 This section explains how to launch a Linux kernel inside QEMU without
1400 having to make a full bootable image. It is very useful for fast Linux
1401 kernel testing.
1403 The syntax is:
1404 @example
1405 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1406 @end example
1408 Use @option{-kernel} to provide the Linux kernel image and
1409 @option{-append} to give the kernel command line arguments. The
1410 @option{-initrd} option can be used to provide an INITRD image.
1412 When using the direct Linux boot, a disk image for the first hard disk
1413 @file{hda} is required because its boot sector is used to launch the
1414 Linux kernel.
1416 If you do not need graphical output, you can disable it and redirect
1417 the virtual serial port and the QEMU monitor to the console with the
1418 @option{-nographic} option. The typical command line is:
1419 @example
1420 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1421      -append "root=/dev/hda console=ttyS0" -nographic
1422 @end example
1424 Use @key{Ctrl-a c} to switch between the serial console and the
1425 monitor (@pxref{pcsys_keys}).
1427 @node pcsys_usb
1428 @section USB emulation
1430 QEMU emulates a PCI UHCI USB controller. You can virtually plug
1431 virtual USB devices or real host USB devices (experimental, works only
1432 on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1433 as necessary to connect multiple USB devices.
1435 @menu
1436 * usb_devices::
1437 * host_usb_devices::
1438 @end menu
1439 @node usb_devices
1440 @subsection Connecting USB devices
1442 USB devices can be connected with the @option{-usbdevice} commandline option
1443 or the @code{usb_add} monitor command.  Available devices are:
1445 @table @var
1446 @item @code{mouse}
1447 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1448 @item @code{tablet}
1449 Pointer device that uses absolute coordinates (like a touchscreen).
1450 This means qemu is able to report the mouse position without having
1451 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1452 @item @code{disk:file}
1453 Mass storage device based on @var{file} (@pxref{disk_images})
1454 @item @code{host:bus.addr}
1455 Pass through the host device identified by @var{bus.addr}
1456 (Linux only)
1457 @item @code{host:vendor_id:product_id}
1458 Pass through the host device identified by @var{vendor_id:product_id}
1459 (Linux only)
1460 @item @code{wacom-tablet}
1461 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1462 above but it can be used with the tslib library because in addition to touch
1463 coordinates it reports touch pressure.
1464 @item @code{keyboard}
1465 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1466 @end table
1468 @node host_usb_devices
1469 @subsection Using host USB devices on a Linux host
1471 WARNING: this is an experimental feature. QEMU will slow down when
1472 using it. USB devices requiring real time streaming (i.e. USB Video
1473 Cameras) are not supported yet.
1475 @enumerate
1476 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1477 is actually using the USB device. A simple way to do that is simply to
1478 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1479 to @file{mydriver.o.disabled}.
1481 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1482 @example
1483 ls /proc/bus/usb
1484 001  devices  drivers
1485 @end example
1487 @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:
1488 @example
1489 chown -R myuid /proc/bus/usb
1490 @end example
1492 @item Launch QEMU and do in the monitor:
1493 @example
1494 info usbhost
1495   Device 1.2, speed 480 Mb/s
1496     Class 00: USB device 1234:5678, USB DISK
1497 @end example
1498 You should see the list of the devices you can use (Never try to use
1499 hubs, it won't work).
1501 @item Add the device in QEMU by using:
1502 @example
1503 usb_add host:1234:5678
1504 @end example
1506 Normally the guest OS should report that a new USB device is
1507 plugged. You can use the option @option{-usbdevice} to do the same.
1509 @item Now you can try to use the host USB device in QEMU.
1511 @end enumerate
1513 When relaunching QEMU, you may have to unplug and plug again the USB
1514 device to make it work again (this is a bug).
1516 @node vnc_security
1517 @section VNC security
1519 The VNC server capability provides access to the graphical console
1520 of the guest VM across the network. This has a number of security
1521 considerations depending on the deployment scenarios.
1523 @menu
1524 * vnc_sec_none::
1525 * vnc_sec_password::
1526 * vnc_sec_certificate::
1527 * vnc_sec_certificate_verify::
1528 * vnc_sec_certificate_pw::
1529 * vnc_generate_cert::
1530 @end menu
1531 @node vnc_sec_none
1532 @subsection Without passwords
1534 The simplest VNC server setup does not include any form of authentication.
1535 For this setup it is recommended to restrict it to listen on a UNIX domain
1536 socket only. For example
1538 @example
1539 qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1540 @end example
1542 This ensures that only users on local box with read/write access to that
1543 path can access the VNC server. To securely access the VNC server from a
1544 remote machine, a combination of netcat+ssh can be used to provide a secure
1545 tunnel.
1547 @node vnc_sec_password
1548 @subsection With passwords
1550 The VNC protocol has limited support for password based authentication. Since
1551 the protocol limits passwords to 8 characters it should not be considered
1552 to provide high security. The password can be fairly easily brute-forced by
1553 a client making repeat connections. For this reason, a VNC server using password
1554 authentication should be restricted to only listen on the loopback interface
1555 or UNIX domain sockets. Password ayuthentication is requested with the @code{password}
1556 option, and then once QEMU is running the password is set with the monitor. Until
1557 the monitor is used to set the password all clients will be rejected.
1559 @example
1560 qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1561 (qemu) change vnc password
1562 Password: ********
1563 (qemu)
1564 @end example
1566 @node vnc_sec_certificate
1567 @subsection With x509 certificates
1569 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1570 TLS for encryption of the session, and x509 certificates for authentication.
1571 The use of x509 certificates is strongly recommended, because TLS on its
1572 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1573 support provides a secure session, but no authentication. This allows any
1574 client to connect, and provides an encrypted session.
1576 @example
1577 qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1578 @end example
1580 In the above example @code{/etc/pki/qemu} should contain at least three files,
1581 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1582 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1583 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1584 only be readable by the user owning it.
1586 @node vnc_sec_certificate_verify
1587 @subsection With x509 certificates and client verification
1589 Certificates can also provide a means to authenticate the client connecting.
1590 The server will request that the client provide a certificate, which it will
1591 then validate against the CA certificate. This is a good choice if deploying
1592 in an environment with a private internal certificate authority.
1594 @example
1595 qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1596 @end example
1599 @node vnc_sec_certificate_pw
1600 @subsection With x509 certificates, client verification and passwords
1602 Finally, the previous method can be combined with VNC password authentication
1603 to provide two layers of authentication for clients.
1605 @example
1606 qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1607 (qemu) change vnc password
1608 Password: ********
1609 (qemu)
1610 @end example
1612 @node vnc_generate_cert
1613 @subsection Generating certificates for VNC
1615 The GNU TLS packages provides a command called @code{certtool} which can
1616 be used to generate certificates and keys in PEM format. At a minimum it
1617 is neccessary to setup a certificate authority, and issue certificates to
1618 each server. If using certificates for authentication, then each client
1619 will also need to be issued a certificate. The recommendation is for the
1620 server to keep its certificates in either @code{/etc/pki/qemu} or for
1621 unprivileged users in @code{$HOME/.pki/qemu}.
1623 @menu
1624 * vnc_generate_ca::
1625 * vnc_generate_server::
1626 * vnc_generate_client::
1627 @end menu
1628 @node vnc_generate_ca
1629 @subsubsection Setup the Certificate Authority
1631 This step only needs to be performed once per organization / organizational
1632 unit. First the CA needs a private key. This key must be kept VERY secret
1633 and secure. If this key is compromised the entire trust chain of the certificates
1634 issued with it is lost.
1636 @example
1637 # certtool --generate-privkey > ca-key.pem
1638 @end example
1640 A CA needs to have a public certificate. For simplicity it can be a self-signed
1641 certificate, or one issue by a commercial certificate issuing authority. To
1642 generate a self-signed certificate requires one core piece of information, the
1643 name of the organization.
1645 @example
1646 # cat > ca.info <<EOF
1647 cn = Name of your organization
1649 cert_signing_key
1651 # certtool --generate-self-signed \
1652            --load-privkey ca-key.pem
1653            --template ca.info \
1654            --outfile ca-cert.pem
1655 @end example
1657 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1658 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1660 @node vnc_generate_server
1661 @subsubsection Issuing server certificates
1663 Each server (or host) needs to be issued with a key and certificate. When connecting
1664 the certificate is sent to the client which validates it against the CA certificate.
1665 The core piece of information for a server certificate is the hostname. This should
1666 be the fully qualified hostname that the client will connect with, since the client
1667 will typically also verify the hostname in the certificate. On the host holding the
1668 secure CA private key:
1670 @example
1671 # cat > server.info <<EOF
1672 organization = Name  of your organization
1673 cn = server.foo.example.com
1674 tls_www_server
1675 encryption_key
1676 signing_key
1678 # certtool --generate-privkey > server-key.pem
1679 # certtool --generate-certificate \
1680            --load-ca-certificate ca-cert.pem \
1681            --load-ca-privkey ca-key.pem \
1682            --load-privkey server server-key.pem \
1683            --template server.info \
1684            --outfile server-cert.pem
1685 @end example
1687 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1688 to the server for which they were generated. The @code{server-key.pem} is security
1689 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1691 @node vnc_generate_client
1692 @subsubsection Issuing client certificates
1694 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1695 certificates as its authentication mechanism, each client also needs to be issued
1696 a certificate. The client certificate contains enough metadata to uniquely identify
1697 the client, typically organization, state, city, building, etc. On the host holding
1698 the secure CA private key:
1700 @example
1701 # cat > client.info <<EOF
1702 country = GB
1703 state = London
1704 locality = London
1705 organiazation = Name of your organization
1706 cn = client.foo.example.com
1707 tls_www_client
1708 encryption_key
1709 signing_key
1711 # certtool --generate-privkey > client-key.pem
1712 # certtool --generate-certificate \
1713            --load-ca-certificate ca-cert.pem \
1714            --load-ca-privkey ca-key.pem \
1715            --load-privkey client-key.pem \
1716            --template client.info \
1717            --outfile client-cert.pem
1718 @end example
1720 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1721 copied to the client for which they were generated.
1723 @node gdb_usage
1724 @section GDB usage
1726 QEMU has a primitive support to work with gdb, so that you can do
1727 'Ctrl-C' while the virtual machine is running and inspect its state.
1729 In order to use gdb, launch qemu with the '-s' option. It will wait for a
1730 gdb connection:
1731 @example
1732 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1733        -append "root=/dev/hda"
1734 Connected to host network interface: tun0
1735 Waiting gdb connection on port 1234
1736 @end example
1738 Then launch gdb on the 'vmlinux' executable:
1739 @example
1740 > gdb vmlinux
1741 @end example
1743 In gdb, connect to QEMU:
1744 @example
1745 (gdb) target remote localhost:1234
1746 @end example
1748 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1749 @example
1750 (gdb) c
1751 @end example
1753 Here are some useful tips in order to use gdb on system code:
1755 @enumerate
1756 @item
1757 Use @code{info reg} to display all the CPU registers.
1758 @item
1759 Use @code{x/10i $eip} to display the code at the PC position.
1760 @item
1761 Use @code{set architecture i8086} to dump 16 bit code. Then use
1762 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1763 @end enumerate
1765 @node pcsys_os_specific
1766 @section Target OS specific information
1768 @subsection Linux
1770 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1771 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1772 color depth in the guest and the host OS.
1774 When using a 2.6 guest Linux kernel, you should add the option
1775 @code{clock=pit} on the kernel command line because the 2.6 Linux
1776 kernels make very strict real time clock checks by default that QEMU
1777 cannot simulate exactly.
1779 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1780 not activated because QEMU is slower with this patch. The QEMU
1781 Accelerator Module is also much slower in this case. Earlier Fedora
1782 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1783 patch by default. Newer kernels don't have it.
1785 @subsection Windows
1787 If you have a slow host, using Windows 95 is better as it gives the
1788 best speed. Windows 2000 is also a good choice.
1790 @subsubsection SVGA graphic modes support
1792 QEMU emulates a Cirrus Logic GD5446 Video
1793 card. All Windows versions starting from Windows 95 should recognize
1794 and use this graphic card. For optimal performances, use 16 bit color
1795 depth in the guest and the host OS.
1797 If you are using Windows XP as guest OS and if you want to use high
1798 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1799 1280x1024x16), then you should use the VESA VBE virtual graphic card
1800 (option @option{-std-vga}).
1802 @subsubsection CPU usage reduction
1804 Windows 9x does not correctly use the CPU HLT
1805 instruction. The result is that it takes host CPU cycles even when
1806 idle. You can install the utility from
1807 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1808 problem. Note that no such tool is needed for NT, 2000 or XP.
1810 @subsubsection Windows 2000 disk full problem
1812 Windows 2000 has a bug which gives a disk full problem during its
1813 installation. When installing it, use the @option{-win2k-hack} QEMU
1814 option to enable a specific workaround. After Windows 2000 is
1815 installed, you no longer need this option (this option slows down the
1816 IDE transfers).
1818 @subsubsection Windows 2000 shutdown
1820 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1821 can. It comes from the fact that Windows 2000 does not automatically
1822 use the APM driver provided by the BIOS.
1824 In order to correct that, do the following (thanks to Struan
1825 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1826 Add/Troubleshoot a device => Add a new device & Next => No, select the
1827 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1828 (again) a few times. Now the driver is installed and Windows 2000 now
1829 correctly instructs QEMU to shutdown at the appropriate moment.
1831 @subsubsection Share a directory between Unix and Windows
1833 See @ref{sec_invocation} about the help of the option @option{-smb}.
1835 @subsubsection Windows XP security problem
1837 Some releases of Windows XP install correctly but give a security
1838 error when booting:
1839 @example
1840 A problem is preventing Windows from accurately checking the
1841 license for this computer. Error code: 0x800703e6.
1842 @end example
1844 The workaround is to install a service pack for XP after a boot in safe
1845 mode. Then reboot, and the problem should go away. Since there is no
1846 network while in safe mode, its recommended to download the full
1847 installation of SP1 or SP2 and transfer that via an ISO or using the
1848 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1850 @subsection MS-DOS and FreeDOS
1852 @subsubsection CPU usage reduction
1854 DOS does not correctly use the CPU HLT instruction. The result is that
1855 it takes host CPU cycles even when idle. You can install the utility
1856 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1857 problem.
1859 @node QEMU System emulator for non PC targets
1860 @chapter QEMU System emulator for non PC targets
1862 QEMU is a generic emulator and it emulates many non PC
1863 machines. Most of the options are similar to the PC emulator. The
1864 differences are mentioned in the following sections.
1866 @menu
1867 * QEMU PowerPC System emulator::
1868 * Sparc32 System emulator::
1869 * Sparc64 System emulator::
1870 * MIPS System emulator::
1871 * ARM System emulator::
1872 * ColdFire System emulator::
1873 @end menu
1875 @node QEMU PowerPC System emulator
1876 @section QEMU PowerPC System emulator
1878 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1879 or PowerMac PowerPC system.
1881 QEMU emulates the following PowerMac peripherals:
1883 @itemize @minus
1884 @item
1885 UniNorth PCI Bridge
1886 @item
1887 PCI VGA compatible card with VESA Bochs Extensions
1888 @item
1889 2 PMAC IDE interfaces with hard disk and CD-ROM support
1890 @item
1891 NE2000 PCI adapters
1892 @item
1893 Non Volatile RAM
1894 @item
1895 VIA-CUDA with ADB keyboard and mouse.
1896 @end itemize
1898 QEMU emulates the following PREP peripherals:
1900 @itemize @minus
1901 @item
1902 PCI Bridge
1903 @item
1904 PCI VGA compatible card with VESA Bochs Extensions
1905 @item
1906 2 IDE interfaces with hard disk and CD-ROM support
1907 @item
1908 Floppy disk
1909 @item
1910 NE2000 network adapters
1911 @item
1912 Serial port
1913 @item
1914 PREP Non Volatile RAM
1915 @item
1916 PC compatible keyboard and mouse.
1917 @end itemize
1919 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1920 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1922 @c man begin OPTIONS
1924 The following options are specific to the PowerPC emulation:
1926 @table @option
1928 @item -g WxH[xDEPTH]
1930 Set the initial VGA graphic mode. The default is 800x600x15.
1932 @end table
1934 @c man end
1937 More information is available at
1938 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1940 @node Sparc32 System emulator
1941 @section Sparc32 System emulator
1943 Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5
1944 or SparcStation 10 (sun4m architecture). The emulation is somewhat complete.
1946 QEMU emulates the following sun4m peripherals:
1948 @itemize @minus
1949 @item
1950 IOMMU
1951 @item
1952 TCX Frame buffer
1953 @item
1954 Lance (Am7990) Ethernet
1955 @item
1956 Non Volatile RAM M48T08
1957 @item
1958 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1959 and power/reset logic
1960 @item
1961 ESP SCSI controller with hard disk and CD-ROM support
1962 @item
1963 Floppy drive
1964 @item
1965 CS4231 sound device (only on SS-5, not working yet)
1966 @end itemize
1968 The number of peripherals is fixed in the architecture.
1970 Since version 0.8.2, QEMU uses OpenBIOS
1971 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1972 firmware implementation. The goal is to implement a 100% IEEE
1973 1275-1994 (referred to as Open Firmware) compliant firmware.
1975 A sample Linux 2.6 series kernel and ram disk image are available on
1976 the QEMU web site. Please note that currently NetBSD, OpenBSD or
1977 Solaris kernels don't work.
1979 @c man begin OPTIONS
1981 The following options are specific to the Sparc32 emulation:
1983 @table @option
1985 @item -g WxHx[xDEPTH]
1987 Set the initial TCX graphic mode. The default is 1024x768x8, currently
1988 the only other possible mode is 1024x768x24.
1990 @item -prom-env string
1992 Set OpenBIOS variables in NVRAM, for example:
1994 @example
1995 qemu-system-sparc -prom-env 'auto-boot?=false' \
1996  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1997 @end example
1999 @item -M [SS-5|SS-10]
2001 Set the emulated machine type. Default is SS-5.
2003 @end table
2005 @c man end
2007 @node Sparc64 System emulator
2008 @section Sparc64 System emulator
2010 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
2011 The emulator is not usable for anything yet.
2013 QEMU emulates the following sun4u peripherals:
2015 @itemize @minus
2016 @item
2017 UltraSparc IIi APB PCI Bridge
2018 @item
2019 PCI VGA compatible card with VESA Bochs Extensions
2020 @item
2021 Non Volatile RAM M48T59
2022 @item
2023 PC-compatible serial ports
2024 @end itemize
2026 @node MIPS System emulator
2027 @section MIPS System emulator
2029 Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
2030 Three different machine types are emulated:
2032 @itemize @minus
2033 @item
2034 A generic ISA PC-like machine "mips"
2035 @item
2036 The MIPS Malta prototype board "malta"
2037 @item
2038 An ACER Pica "pica61"
2039 @end itemize
2041 The generic emulation is supported by Debian 'Etch' and is able to
2042 install Debian into a virtual disk image. The following devices are
2043 emulated:
2045 @itemize @minus
2046 @item
2047 MIPS 24Kf CPU
2048 @item
2049 PC style serial port
2050 @item
2051 PC style IDE disk
2052 @item
2053 NE2000 network card
2054 @end itemize
2056 The Malta emulation supports the following devices:
2058 @itemize @minus
2059 @item
2060 Core board with MIPS 24Kf CPU and Galileo system controller
2061 @item
2062 PIIX4 PCI/USB/SMbus controller
2063 @item
2064 The Multi-I/O chip's serial device
2065 @item
2066 PCnet32 PCI network card
2067 @item
2068 Malta FPGA serial device
2069 @item
2070 Cirrus VGA graphics card
2071 @end itemize
2073 The ACER Pica emulation supports:
2075 @itemize @minus
2076 @item
2077 MIPS R4000 CPU
2078 @item
2079 PC-style IRQ and DMA controllers
2080 @item
2081 PC Keyboard
2082 @item
2083 IDE controller
2084 @end itemize
2086 @node ARM System emulator
2087 @section ARM System emulator
2089 Use the executable @file{qemu-system-arm} to simulate a ARM
2090 machine. The ARM Integrator/CP board is emulated with the following
2091 devices:
2093 @itemize @minus
2094 @item
2095 ARM926E, ARM1026E or ARM946E CPU
2096 @item
2097 Two PL011 UARTs
2098 @item
2099 SMC 91c111 Ethernet adapter
2100 @item
2101 PL110 LCD controller
2102 @item
2103 PL050 KMI with PS/2 keyboard and mouse.
2104 @item
2105 PL181 MultiMedia Card Interface with SD card.
2106 @end itemize
2108 The ARM Versatile baseboard is emulated with the following devices:
2110 @itemize @minus
2111 @item
2112 ARM926E CPU
2113 @item
2114 PL190 Vectored Interrupt Controller
2115 @item
2116 Four PL011 UARTs
2117 @item
2118 SMC 91c111 Ethernet adapter
2119 @item
2120 PL110 LCD controller
2121 @item
2122 PL050 KMI with PS/2 keyboard and mouse.
2123 @item
2124 PCI host bridge.  Note the emulated PCI bridge only provides access to
2125 PCI memory space.  It does not provide access to PCI IO space.
2126 This means some devices (eg. ne2k_pci NIC) are not usable, and others
2127 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2128 mapped control registers.
2129 @item
2130 PCI OHCI USB controller.
2131 @item
2132 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2133 @item
2134 PL181 MultiMedia Card Interface with SD card.
2135 @end itemize
2137 The ARM RealView Emulation baseboard is emulated with the following devices:
2139 @itemize @minus
2140 @item
2141 ARM926E CPU
2142 @item
2143 ARM AMBA Generic/Distributed Interrupt Controller
2144 @item
2145 Four PL011 UARTs
2146 @item
2147 SMC 91c111 Ethernet adapter
2148 @item
2149 PL110 LCD controller
2150 @item
2151 PL050 KMI with PS/2 keyboard and mouse
2152 @item
2153 PCI host bridge
2154 @item
2155 PCI OHCI USB controller
2156 @item
2157 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2158 @item
2159 PL181 MultiMedia Card Interface with SD card.
2160 @end itemize
2162 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2163 and "Terrier") emulation includes the following peripherals:
2165 @itemize @minus
2166 @item
2167 Intel PXA270 System-on-chip (ARM V5TE core)
2168 @item
2169 NAND Flash memory
2170 @item
2171 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2172 @item
2173 On-chip OHCI USB controller
2174 @item
2175 On-chip LCD controller
2176 @item
2177 On-chip Real Time Clock
2178 @item
2179 TI ADS7846 touchscreen controller on SSP bus
2180 @item
2181 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2182 @item
2183 GPIO-connected keyboard controller and LEDs
2184 @item
2185 Secure Digital card connected to PXA MMC/SD host
2186 @item
2187 Three on-chip UARTs
2188 @item
2189 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2190 @end itemize
2192 A Linux 2.6 test image is available on the QEMU web site. More
2193 information is available in the QEMU mailing-list archive.
2195 @node ColdFire System emulator
2196 @section ColdFire System emulator
2198 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2199 The emulator is able to boot a uClinux kernel.
2201 The M5208EVB emulation includes the following devices:
2203 @itemize @minus
2204 @item
2205 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2206 @item
2207 Three Two on-chip UARTs.
2208 @item
2209 Fast Ethernet Controller (FEC)
2210 @end itemize
2212 The AN5206 emulation includes the following devices:
2214 @itemize @minus
2215 @item
2216 MCF5206 ColdFire V2 Microprocessor.
2217 @item
2218 Two on-chip UARTs.
2219 @end itemize
2221 @node QEMU User space emulator
2222 @chapter QEMU User space emulator
2224 @menu
2225 * Supported Operating Systems ::
2226 * Linux User space emulator::
2227 * Mac OS X/Darwin User space emulator ::
2228 @end menu
2230 @node Supported Operating Systems
2231 @section Supported Operating Systems
2233 The following OS are supported in user space emulation:
2235 @itemize @minus
2236 @item
2237 Linux (referred as qemu-linux-user)
2238 @item
2239 Mac OS X/Darwin (referred as qemu-darwin-user)
2240 @end itemize
2242 @node Linux User space emulator
2243 @section Linux User space emulator
2245 @menu
2246 * Quick Start::
2247 * Wine launch::
2248 * Command line options::
2249 * Other binaries::
2250 @end menu
2252 @node Quick Start
2253 @subsection Quick Start
2255 In order to launch a Linux process, QEMU needs the process executable
2256 itself and all the target (x86) dynamic libraries used by it.
2258 @itemize
2260 @item On x86, you can just try to launch any process by using the native
2261 libraries:
2263 @example
2264 qemu-i386 -L / /bin/ls
2265 @end example
2267 @code{-L /} tells that the x86 dynamic linker must be searched with a
2268 @file{/} prefix.
2270 @item Since QEMU is also a linux process, you can launch qemu with
2271 qemu (NOTE: you can only do that if you compiled QEMU from the sources):
2273 @example
2274 qemu-i386 -L / qemu-i386 -L / /bin/ls
2275 @end example
2277 @item On non x86 CPUs, you need first to download at least an x86 glibc
2278 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2279 @code{LD_LIBRARY_PATH} is not set:
2281 @example
2282 unset LD_LIBRARY_PATH
2283 @end example
2285 Then you can launch the precompiled @file{ls} x86 executable:
2287 @example
2288 qemu-i386 tests/i386/ls
2289 @end example
2290 You can look at @file{qemu-binfmt-conf.sh} so that
2291 QEMU is automatically launched by the Linux kernel when you try to
2292 launch x86 executables. It requires the @code{binfmt_misc} module in the
2293 Linux kernel.
2295 @item The x86 version of QEMU is also included. You can try weird things such as:
2296 @example
2297 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2298           /usr/local/qemu-i386/bin/ls-i386
2299 @end example
2301 @end itemize
2303 @node Wine launch
2304 @subsection Wine launch
2306 @itemize
2308 @item Ensure that you have a working QEMU with the x86 glibc
2309 distribution (see previous section). In order to verify it, you must be
2310 able to do:
2312 @example
2313 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2314 @end example
2316 @item Download the binary x86 Wine install
2317 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2319 @item Configure Wine on your account. Look at the provided script
2320 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2321 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2323 @item Then you can try the example @file{putty.exe}:
2325 @example
2326 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2327           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2328 @end example
2330 @end itemize
2332 @node Command line options
2333 @subsection Command line options
2335 @example
2336 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2337 @end example
2339 @table @option
2340 @item -h
2341 Print the help
2342 @item -L path
2343 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2344 @item -s size
2345 Set the x86 stack size in bytes (default=524288)
2346 @end table
2348 Debug options:
2350 @table @option
2351 @item -d
2352 Activate log (logfile=/tmp/qemu.log)
2353 @item -p pagesize
2354 Act as if the host page size was 'pagesize' bytes
2355 @end table
2357 @node Other binaries
2358 @subsection Other binaries
2360 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2361 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2362 configurations), and arm-uclinux bFLT format binaries.
2364 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2365 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2366 coldfire uClinux bFLT format binaries.
2368 The binary format is detected automatically.
2370 @node Mac OS X/Darwin User space emulator
2371 @section Mac OS X/Darwin User space emulator
2373 @menu
2374 * Mac OS X/Darwin Status::
2375 * Mac OS X/Darwin Quick Start::
2376 * Mac OS X/Darwin Command line options::
2377 @end menu
2379 @node Mac OS X/Darwin Status
2380 @subsection Mac OS X/Darwin Status
2382 @itemize @minus
2383 @item
2384 target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2385 @item
2386 target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2387 @item
2388 target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
2389 @item
2390 target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2391 @end itemize
2393 [1] If you're host commpage can be executed by qemu.
2395 @node Mac OS X/Darwin Quick Start
2396 @subsection Quick Start
2398 In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2399 itself and all the target dynamic libraries used by it. If you don't have the FAT
2400 libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2401 CD or compile them by hand.
2403 @itemize
2405 @item On x86, you can just try to launch any process by using the native
2406 libraries:
2408 @example
2409 qemu-i386 /bin/ls
2410 @end example
2412 or to run the ppc version of the executable:
2414 @example
2415 qemu-ppc /bin/ls
2416 @end example
2418 @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2419 are installed:
2421 @example
2422 qemu-i386 -L /opt/x86_root/ /bin/ls
2423 @end example
2425 @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2426 @file{/opt/x86_root/usr/bin/dyld}.
2428 @end itemize
2430 @node Mac OS X/Darwin Command line options
2431 @subsection Command line options
2433 @example
2434 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2435 @end example
2437 @table @option
2438 @item -h
2439 Print the help
2440 @item -L path
2441 Set the library root path (default=/)
2442 @item -s size
2443 Set the stack size in bytes (default=524288)
2444 @end table
2446 Debug options:
2448 @table @option
2449 @item -d
2450 Activate log (logfile=/tmp/qemu.log)
2451 @item -p pagesize
2452 Act as if the host page size was 'pagesize' bytes
2453 @end table
2455 @node compilation
2456 @chapter Compilation from the sources
2458 @menu
2459 * Linux/Unix::
2460 * Windows::
2461 * Cross compilation for Windows with Linux::
2462 * Mac OS X::
2463 @end menu
2465 @node Linux/Unix
2466 @section Linux/Unix
2468 @subsection Compilation
2470 First you must decompress the sources:
2471 @example
2472 cd /tmp
2473 tar zxvf qemu-x.y.z.tar.gz
2474 cd qemu-x.y.z
2475 @end example
2477 Then you configure QEMU and build it (usually no options are needed):
2478 @example
2479 ./configure
2480 make
2481 @end example
2483 Then type as root user:
2484 @example
2485 make install
2486 @end example
2487 to install QEMU in @file{/usr/local}.
2489 @subsection GCC version
2491 In order to compile QEMU successfully, it is very important that you
2492 have the right tools. The most important one is gcc. On most hosts and
2493 in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
2494 Linux distribution includes a gcc 4.x compiler, you can usually
2495 install an older version (it is invoked by @code{gcc32} or
2496 @code{gcc34}). The QEMU configure script automatically probes for
2497 these older versions so that usually you don't have to do anything.
2499 @node Windows
2500 @section Windows
2502 @itemize
2503 @item Install the current versions of MSYS and MinGW from
2504 @url{http://www.mingw.org/}. You can find detailed installation
2505 instructions in the download section and the FAQ.
2507 @item Download
2508 the MinGW development library of SDL 1.2.x
2509 (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2510 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
2511 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2512 directory. Edit the @file{sdl-config} script so that it gives the
2513 correct SDL directory when invoked.
2515 @item Extract the current version of QEMU.
2517 @item Start the MSYS shell (file @file{msys.bat}).
2519 @item Change to the QEMU directory. Launch @file{./configure} and
2520 @file{make}.  If you have problems using SDL, verify that
2521 @file{sdl-config} can be launched from the MSYS command line.
2523 @item You can install QEMU in @file{Program Files/Qemu} by typing
2524 @file{make install}. Don't forget to copy @file{SDL.dll} in
2525 @file{Program Files/Qemu}.
2527 @end itemize
2529 @node Cross compilation for Windows with Linux
2530 @section Cross compilation for Windows with Linux
2532 @itemize
2533 @item
2534 Install the MinGW cross compilation tools available at
2535 @url{http://www.mingw.org/}.
2537 @item
2538 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
2539 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
2540 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
2541 the QEMU configuration script.
2543 @item
2544 Configure QEMU for Windows cross compilation:
2545 @example
2546 ./configure --enable-mingw32
2547 @end example
2548 If necessary, you can change the cross-prefix according to the prefix
2549 chosen for the MinGW tools with --cross-prefix. You can also use
2550 --prefix to set the Win32 install path.
2552 @item You can install QEMU in the installation directory by typing
2553 @file{make install}. Don't forget to copy @file{SDL.dll} in the
2554 installation directory.
2556 @end itemize
2558 Note: Currently, Wine does not seem able to launch
2559 QEMU for Win32.
2561 @node Mac OS X
2562 @section Mac OS X
2564 The Mac OS X patches are not fully merged in QEMU, so you should look
2565 at the QEMU mailing list archive to have all the necessary
2566 information.
2568 @node Index
2569 @chapter Index
2570 @printindex cp
2572 @bye