X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/294e863721c6bf0930585982363c92cbdea64e64..945446c653dba61ba0bd304d14e5d4f9938e2647:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index 01f33f7e78..b5c913197c 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -1,7 +1,7 @@ \input texinfo @c -*- texinfo -*- @c %**start of header @setfilename qemu-doc.info -@settitle QEMU CPU Emulator User Documentation +@settitle QEMU Emulator User Documentation @exampleindent 0 @paragraphindent 0 @c %**end of header @@ -9,7 +9,7 @@ @iftex @titlepage @sp 7 -@center @titlefont{QEMU CPU Emulator} +@center @titlefont{QEMU Emulator} @sp 1 @center @titlefont{User Documentation} @sp 3 @@ -25,7 +25,7 @@ * Installation:: * QEMU PC System emulator:: * QEMU System emulator for non PC targets:: -* QEMU Linux User space emulator:: +* QEMU User space emulator:: * compilation:: Compilation from the sources * Index:: @end menu @@ -57,8 +57,8 @@ peripherals. It can be used to launch different Operating Systems without rebooting the PC or to debug system code. @item -User mode emulation (Linux host only). In this mode, QEMU can launch -Linux processes compiled for one CPU on another CPU. It can be used to +User mode emulation. In this mode, QEMU can launch +processes compiled for one CPU on another CPU. It can be used to launch the Wine Windows API emulator (@url{http://www.winehq.org}) or to ease cross-compilation and cross-debugging. @@ -78,9 +78,11 @@ For system emulation, the following hardware targets are supported: @item Sun4u (64-bit Sparc processor, in progress) @item Malta board (32-bit MIPS processor) @item ARM Integrator/CP (ARM926E or 1026E processor) +@item ARM Versatile baseboard (ARM926E) +@item ARM RealView Emulation baseboard (ARM926EJ-S) @end itemize -For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported. +For user emulation, x86, PowerPC, ARM, MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported. @node Installation @chapter Installation @@ -205,7 +207,7 @@ Select the emulated machine (@code{-M ?} for list) @item -fda file @item -fdb file Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can -use the host floppy by using @file{/dev/fd0} as filename. +use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}). @item -hda file @item -hdb file @@ -216,16 +218,20 @@ Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). @item -cdrom file Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and @option{-cdrom} at the same time). You can use the host CD-ROM by -using @file{/dev/cdrom} as filename. +using @file{/dev/cdrom} as filename (@pxref{host_drives}). -@item -boot [a|c|d] -Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is -the default. +@item -boot [a|c|d|n] +Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot +is the default. @item -snapshot Write to temporary files instead of disk image files. In this case, the raw disk image you use is not written back. You can however force -the write back by pressing @key{C-a s} (@pxref{disk_images}). +the write back by pressing @key{C-a s} (@pxref{disk_images}). + +@item -no-fd-bootchk +Disable boot signature checking for floppy disks in Bochs BIOS. It may +be needed to boot from old floppy disks. @item -m megs Set virtual RAM size to @var{megs} megabytes. Default is 128 MB. @@ -242,19 +248,35 @@ command line application. The emulated serial port is redirected on the console. Therefore, you can still use QEMU to debug a Linux kernel with a serial console. -@item -vnc d +@item -no-frame + +Do not use decorations for SDL windows and start them using the whole +available screen space. This makes the using QEMU in a dedicated desktop +workspace more convenient. + +@item -vnc display Normally, QEMU uses SDL to display the VGA output. With this option, -you can have QEMU listen on VNC display d and redirect the VGA display -over the VNC session. It is very useful to enable the usb tablet device -when using this option (option @option{-usbdevice tablet}). +you can have QEMU listen on VNC display @var{display} and redirect the VGA +display over the VNC session. It is very useful to enable the usb +tablet device when using this option (option @option{-usbdevice +tablet}). When using the VNC display, you must use the @option{-k} +option to set the keyboard layout if you are not using en-us. + +@var{display} may be in the form @var{interface:d}, in which case connections +will only be allowed from @var{interface} on display @var{d}. Optionally, +@var{interface} can be omitted. @var{display} can also be in the form +@var{unix:path} where @var{path} is the location of a unix socket to listen for +connections on. + @item -k language Use keyboard layout @var{language} (for example @code{fr} for French). This option is only needed where it is not easy to get raw PC -keycodes (e.g. on Macs or with some X11 servers). You don't need to -use it on PC/Linux or PC/Windows hosts. +keycodes (e.g. on Macs, with some X11 servers or with a VNC +display). You don't normally need to use it on PC/Linux or PC/Windows +hosts. The available layouts are: @example @@ -294,11 +316,25 @@ Start in full screen. Store the QEMU process PID in @var{file}. It is useful if you launch QEMU from a script. +@item -daemonize +Daemonize the QEMU process after initialization. QEMU will not detach from +standard IO until it is ready to receive connections on any of its devices. +This option is a useful way for external programs to launch QEMU without having +to cope with initialization race conditions. + @item -win2k-hack Use it when installing Windows 2000 to avoid a disk full bug. After Windows 2000 is installed, you no longer need this option (this option slows down the IDE transfers). +@item -option-rom file +Load the contents of file as an option ROM. This option is useful to load +things like EtherBoot. + +@item -name string +Sets the name of the guest. This name will be display in the SDL window +caption. The name will also be used for the VNC server. + @end table USB options: @@ -308,8 +344,7 @@ USB options: Enable the USB driver (will be the default soon) @item -usbdevice devname -Add the USB device @var{devname}. See the monitor command -@code{usb_add} to have more information. +Add the USB device @var{devname}. @xref{usb_devices}. @end table Network options: @@ -334,7 +369,8 @@ hostname reported by the builtin DHCP server. @item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file] Connect the host TAP network interface @var{name} to VLAN @var{n} and use the network script @var{file} to configure it. The default -network script is @file{/etc/qemu-ifup}. If @var{name} is not +network script is @file{/etc/qemu-ifup}. Use @option{script=no} to +disable script execution. If @var{name} is not provided, the OS automatically provides one. @option{fd=h} can be used to specify the handle of an already opened host TAP interface. Example: @@ -413,13 +449,22 @@ Indicate that no network devices should be configured. It is used to override the default configuration (@option{-net nic -net user}) which is activated if no @option{-net} options are provided. -@item -tftp prefix +@item -tftp dir When using the user mode network stack, activate a built-in TFTP -server. All filenames beginning with @var{prefix} can be downloaded -from the host to the guest using a TFTP client. The TFTP client on the -guest must be configured in binary mode (use the command @code{bin} of -the Unix TFTP client). The host IP address on the guest is as usual -10.0.2.2. +server. The files in @var{dir} will be exposed as the root of a TFTP server. +The TFTP client on the guest must be configured in binary mode (use the command +@code{bin} of the Unix TFTP client). The host IP address on the guest is as +usual 10.0.2.2. + +@item -bootp file +When using the user mode network stack, broadcast @var{file} as the BOOTP +filename. In conjunction with @option{-tftp}, this can be used to network boot +a guest from a local directory. + +Example (using pxelinux): +@example +qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0 +@end example @item -smb dir When using the user mode network stack, activate a built-in SMB @@ -436,7 +481,7 @@ or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). Then @file{dir} can be accessed in @file{\\smbserver\qemu}. Note that a SAMBA server must be installed on the host OS in -@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version +@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3. @item -redir [tcp|udp]:host-port:[guest-host]:guest-port @@ -492,13 +537,23 @@ Debug/Expert options: @table @option @item -serial dev -Redirect the virtual serial port to host device @var{dev}. Available -devices are: +Redirect the virtual serial port to host character device +@var{dev}. The default device is @code{vc} in graphical mode and +@code{stdio} in non graphical mode. + +This option can be used several times to simulate up to 4 serials +ports. + +Use @code{-serial none} to disable all serial ports. + +Available character devices are: @table @code @item vc Virtual console @item pty [Linux only] Pseudo TTY (a new PTY is automatically allocated) +@item none +No device is allocated. @item null void device @item /dev/XXX @@ -506,19 +561,88 @@ void device parameters are set according to the emulated ones. @item /dev/parportN [Linux only, parallel port only] Use host parallel port -@var{N}. Currently only SPP parallel port features can be used. +@var{N}. Currently SPP and EPP parallel port features can be used. @item file:filename Write output to filename. No character can be read. @item stdio [Unix only] standard input/output @item pipe:filename -[Unix only] name pipe @var{filename} +name pipe @var{filename} +@item COMn +[Windows only] Use host serial port @var{n} +@item udp:[remote_host]:remote_port[@@[src_ip]:src_port] +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 specifed @var{src_port} a random port is automatically chosen. + +If you just want a simple readonly console you can use @code{netcat} or +@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as: +@code{nc -u -l -p 4555}. Any time qemu writes something to that port it +will appear in the netconsole session. + +If you plan to send characters back via netconsole or you want to stop +and start qemu a lot of times, you should have qemu use the same +source port each time by using something like @code{-serial +udp::4555@@:4556} to qemu. Another approach is to use a patched +version of netcat which can listen to a TCP port and send and receive +characters via udp. If you have a patched version of netcat which +activates telnet remote echo and single char transfer, then you can +use the following options to step up a netcat redirector to allow +telnet on port 5555 to access the qemu port. +@table @code +@item Qemu Options: +-serial udp::4555@@:4556 +@item netcat options: +-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T +@item telnet options: +localhost 5555 @end table -The default device is @code{vc} in graphical mode and @code{stdio} in -non graphical mode. -This option can be used several times to simulate up to 4 serials -ports. + +@item tcp:[host]:port[,server][,nowait][,nodelay] +The TCP Net Console has two modes of operation. It can send the serial +I/O to a location or wait for a connection from a location. By default +the TCP Net Console is sent to @var{host} at the @var{port}. If you use +the @var{server} option QEMU will wait for a client socket application +to connect to the port before continuing, unless the @code{nowait} +option was specified. The @code{nodelay} option disables the Nagle buffering +algoritm. If @var{host} is omitted, 0.0.0.0 is assumed. Only +one TCP connection at a time is accepted. You can use @code{telnet} to +connect to the corresponding character device. +@table @code +@item Example to send tcp console to 192.168.0.2 port 4444 +-serial tcp:192.168.0.2:4444 +@item Example to listen and wait on port 4444 for connection +-serial tcp::4444,server +@item Example to not wait and listen on ip 192.168.0.100 port 4444 +-serial tcp:192.168.0.100:4444,server,nowait +@end table + +@item telnet:host:port[,server][,nowait][,nodelay] +The telnet protocol is used instead of raw tcp sockets. The options +work the same as if you had specified @code{-serial tcp}. The +difference is that the port acts like a telnet server or client using +telnet option negotiation. This will also allow you to send the +MAGIC_SYSRQ sequence if you use a telnet that supports sending the break +sequence. Typically in unix telnet you do it with Control-] and then +type "send break" followed by pressing the enter key. + +@item unix:path[,server][,nowait] +A unix domain socket is used instead of a tcp socket. The option works the +same as if you had specified @code{-serial tcp} except the unix domain socket +@var{path} is used for connections. + +@item mon:dev_string +This is a special option to allow the monitor to be multiplexed onto +another serial port. The monitor is accessed with key sequence of +@key{Control-a} and then pressing @key{c}. See monitor access +@ref{pcsys_keys} in the -nographic section for more keys. +@var{dev_string} should be any one of the serial devices specified +above. An example to multiplex the monitor onto a telnet server +listening on port 4444 would be: +@table @code +@item -serial mon:telnet::4444,server,nowait +@end table + +@end table @item -parallel dev Redirect the virtual parallel port to host device @var{dev} (same @@ -529,16 +653,32 @@ parallel port. This option can be used several times to simulate up to 3 parallel ports. +Use @code{-parallel none} to disable all parallel ports. + @item -monitor dev Redirect the monitor to host device @var{dev} (same devices as the serial port). The default device is @code{vc} in graphical mode and @code{stdio} in non graphical mode. +@item -echr numeric_ascii_value +Change the escape character used for switching to the monitor when using +monitor and serial sharing. The default is @code{0x01} when using the +@code{-nographic} option. @code{0x01} is equal to pressing +@code{Control-a}. You can select a different character from the ascii +control keys where 1 through 26 map to Control-a through Control-z. For +instance you could use the either of the following to change the escape +character to Control-t. +@table @code +@item -echr 0x14 +@item -echr 20 +@end table + @item -s Wait gdb connection to port 1234 (@pxref{gdb_usage}). @item -p port -Change gdb connection port. +Change gdb connection port. @var{port} can be either a decimal number +to specify a TCP port, or a host device (same devices as the serial port). @item -S Do not start CPU at startup (you must type 'c' in the monitor). @item -d @@ -550,11 +690,30 @@ translation mode (@var{t}=none, lba or auto). Usually QEMU can guess all thoses parameters. This option is useful for old MS-DOS disk images. +@item -L path +Set the directory for the BIOS, VGA BIOS and keymaps. + @item -std-vga Simulate a standard VGA card with Bochs VBE extensions (default is -Cirrus Logic GD5446 PCI VGA) +Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0 +VBE extensions (e.g. Windows XP) and if you want to use high +resolution modes (>= 1280x1024x16) then you should use this option. + +@item -no-acpi +Disable ACPI (Advanced Configuration and Power Interface) support. Use +it if your guest OS complains about ACPI problems (PC target machine +only). + +@item -no-reboot +Exit instead of rebooting. + @item -loadvm file Start right away with a saved state (@code{loadvm} in monitor) + +@item -semihosting +Enable "Angel" semihosting interface (ARM target machines only). +Note that this allows guest direct access to the host filesystem, +so should only be used with trusted guest OS. @end table @c man end @@ -594,9 +753,11 @@ During emulation, if you are using the @option{-nographic} option, use @item Ctrl-a h Print this help @item Ctrl-a x -Exit emulatior +Exit emulator @item Ctrl-a s Save disk data back to file (if -snapshot) +@item Ctrl-a t +toggle console timestamps @item Ctrl-a b Send break (magic sysrq in Linux) @item Ctrl-a c @@ -628,7 +789,7 @@ emulator. You can use it to: @itemize @minus @item -Remove or insert removable medias images +Remove or insert removable media images (such as CD-ROM or floppies) @item @@ -669,28 +830,72 @@ show emulated PCI device show USB devices plugged on the virtual USB hub @item info usbhost show all USB host devices +@item info capture +show information about active capturing +@item info snapshots +show list of VM snapshots +@item info mice +show which guest mouse is receiving events @end table @item q or quit Quit the emulator. @item eject [-f] device -Eject a removable media (use -f to force it). +Eject a removable medium (use -f to force it). @item change device filename -Change a removable media. +Change a removable medium. @item screendump filename Save screen into PPM image @var{filename}. +@item mouse_move dx dy [dz] +Move the active mouse to the specified coordinates @var{dx} @var{dy} +with optional scroll axis @var{dz}. + +@item mouse_button val +Change the active mouse button state @var{val} (1=L, 2=M, 4=R). + +@item mouse_set index +Set which mouse device receives events at given @var{index}, index +can be obtained with +@example +info mice +@end example + +@item wavcapture filename [frequency [bits [channels]]] +Capture audio into @var{filename}. Using sample rate @var{frequency} +bits per sample @var{bits} and number of channels @var{channels}. + +Defaults: +@itemize @minus +@item Sample rate = 44100 Hz - CD quality +@item Bits = 16 +@item Number of channels = 2 - Stereo +@end itemize + +@item stopcapture index +Stop capture with a given @var{index}, index can be obtained with +@example +info capture +@end example + @item log item1[,...] Activate logging of the specified items to @file{/tmp/qemu.log}. -@item savevm filename -Save the whole virtual machine state to @var{filename}. +@item savevm [tag|id] +Create a snapshot of the whole virtual machine. If @var{tag} is +provided, it is used as human readable identifier. If there is already +a snapshot with the same tag or ID, it is replaced. More info at +@ref{vm_snapshots}. -@item loadvm filename -Restore the whole virtual machine state from @var{filename}. +@item loadvm tag|id +Set the whole virtual machine to the snapshot identified by the tag +@var{tag} or the unique snapshot ID @var{id}. + +@item delvm tag|id +Delete the snapshot identified by @var{tag} or @var{id}. @item stop Stop emulation. @@ -782,10 +987,8 @@ Reset the system. @item usb_add devname -Plug the USB device devname to the QEMU virtual USB hub. @var{devname} -is either a virtual device name (for example @code{mouse}) or a host -USB device identifier. Host USB device identifiers have the following -syntax: @code{host:bus.addr} or @code{host:vendor_id:product_id}. +Add the USB device @var{devname}. For details of available devices see +@ref{usb_devices} @item usb_del devname @@ -806,12 +1009,16 @@ CPU registers by prefixing them with @emph{$}. Since version 0.6.1, QEMU supports many disk image formats, including growable disk images (their size increase as non empty sectors are -written), compressed and encrypted disk images. +written), compressed and encrypted disk images. Version 0.8.3 added +the new qcow2 disk image format which is essential to support VM +snapshots. @menu * disk_images_quickstart:: Quick start for disk image creation * disk_images_snapshot_mode:: Snapshot mode +* vm_snapshots:: VM snapshots * qemu_img_invocation:: qemu-img Invocation +* host_drives:: Using host drives * disk_images_fat_images:: Virtual FAT disk images @end menu @@ -837,11 +1044,124 @@ a temporary file created in @file{/tmp}. You can however force the write back to the raw disk images by using the @code{commit} monitor command (or @key{C-a s} in the serial console). +@node vm_snapshots +@subsection VM snapshots + +VM snapshots are snapshots of the complete virtual machine including +CPU state, RAM, device state and the content of all the writable +disks. In order to use VM snapshots, you must have at least one non +removable and writable block device using the @code{qcow2} disk image +format. Normally this device is the first virtual hard drive. + +Use the monitor command @code{savevm} to create a new VM snapshot or +replace an existing one. A human readable name can be assigned to each +snapshot in addition to its numerical ID. + +Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove +a VM snapshot. @code{info snapshots} lists the available snapshots +with their associated information: + +@example +(qemu) info snapshots +Snapshot devices: hda +Snapshot list (from hda): +ID TAG VM SIZE DATE VM CLOCK +1 start 41M 2006-08-06 12:38:02 00:00:14.954 +2 40M 2006-08-06 12:43:29 00:00:18.633 +3 msys 40M 2006-08-06 12:44:04 00:00:23.514 +@end example + +A VM snapshot is made of a VM state info (its size is shown in +@code{info snapshots}) and a snapshot of every writable disk image. +The VM state info is stored in the first @code{qcow2} non removable +and writable block device. The disk image snapshots are stored in +every disk image. The size of a snapshot in a disk image is difficult +to evaluate and is not shown by @code{info snapshots} because the +associated disk sectors are shared among all the snapshots to save +disk space (otherwise each snapshot would need a full copy of all the +disk images). + +When using the (unrelated) @code{-snapshot} option +(@ref{disk_images_snapshot_mode}), you can always make VM snapshots, +but they are deleted as soon as you exit QEMU. + +VM snapshots currently have the following known limitations: +@itemize +@item +They cannot cope with removable devices if they are removed or +inserted after a snapshot is done. +@item +A few device drivers still have incomplete snapshot support so their +state is not saved or restored properly (in particular USB). +@end itemize + @node qemu_img_invocation @subsection @code{qemu-img} Invocation @include qemu-img.texi +@node host_drives +@subsection Using host drives + +In addition to disk image files, QEMU can directly access host +devices. We describe here the usage for QEMU version >= 0.8.3. + +@subsubsection Linux + +On Linux, you can directly use the host device filename instead of a +disk image filename provided you have enough proviledge to access +it. For example, use @file{/dev/cdrom} to access to the CDROM or +@file{/dev/fd0} for the floppy. + +@table @code +@item CD +You can specify a CDROM device even if no CDROM is loaded. QEMU has +specific code to detect CDROM insertion or removal. CDROM ejection by +the guest OS is supported. Currently only data CDs are supported. +@item Floppy +You can specify a floppy device even if no floppy is loaded. Floppy +removal is currently not detected accurately (if you change floppy +without doing floppy access while the floppy is not loaded, the guest +OS will think that the same floppy is loaded). +@item Hard disks +Hard disks can be used. Normally you must specify the whole disk +(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can +see it as a partitioned disk. WARNING: unless you know what you do, it +is better to only make READ-ONLY accesses to the hard disk otherwise +you may corrupt your host data (use the @option{-snapshot} command +line option or modify the device permissions accordingly). +@end table + +@subsubsection Windows + +@table @code +@item CD +The prefered syntax is the drive letter (e.g. @file{d:}). The +alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is +supported as an alias to the first CDROM drive. + +Currently there is no specific code to handle removable media, so it +is better to use the @code{change} or @code{eject} monitor commands to +change or eject media. +@item Hard disks +Hard disks can be used with the syntax: @file{\\.\PhysicalDriveN} +where @var{N} is the drive number (0 is the first hard disk). + +WARNING: unless you know what you do, it is better to only make +READ-ONLY accesses to the hard disk otherwise you may corrupt your +host data (use the @option{-snapshot} command line so that the +modifications are written in a temporary file). +@end table + + +@subsubsection Mac OS X + +@file{/dev/cdrom} is an alias to the first CDROM. + +Currently there is no specific code to handle removable media, so it +is better to use the @code{change} or @code{eject} monitor commands to +change or eject media. + @node disk_images_fat_images @subsection Virtual FAT disk images @@ -901,6 +1221,8 @@ This is the standard way to connect QEMU to a real network. QEMU adds a virtual network device on your host (called @code{tapN}), and you can then configure it as if it was a real ethernet card. +@subsubsection Linux host + As an example, you can download the @file{linux-test-xxx.tar.gz} archive and copy the script @file{qemu-ifup} in @file{/etc} and configure properly @code{sudo} so that the command @code{ifconfig} @@ -908,9 +1230,15 @@ contained in @file{qemu-ifup} can be executed as root. You must verify that your host kernel supports the TAP network interfaces: the device @file{/dev/net/tun} must be present. -See @ref{direct_linux_boot} to have an example of network use with a -Linux distribution and @ref{sec_invocation} to have examples of -command lines using the TAP network interfaces. +See @ref{sec_invocation} to have examples of command lines using the +TAP network interfaces. + +@subsubsection Windows host + +There is a virtual ethernet driver for Windows 2000/XP systems, called +TAP-Win32. But it is not included in standard QEMU for Windows, +so you will need to get it separately. It is part of OpenVPN package, +so download OpenVPN from : @url{http://openvpn.net/}. @subsection Using the user mode network stack @@ -960,175 +1288,68 @@ basic example. This section explains how to launch a Linux kernel inside QEMU without having to make a full bootable image. It is very useful for fast Linux -kernel testing. The QEMU network configuration is also explained. +kernel testing. -@enumerate -@item -Download the archive @file{linux-test-xxx.tar.gz} containing a Linux -kernel and a disk image. - -@item Optional: If you want network support (for example to launch X11 examples), you -must copy the script @file{qemu-ifup} in @file{/etc} and configure -properly @code{sudo} so that the command @code{ifconfig} contained in -@file{qemu-ifup} can be executed as root. You must verify that your host -kernel supports the TUN/TAP network interfaces: the device -@file{/dev/net/tun} must be present. - -When network is enabled, there is a virtual network connection between -the host kernel and the emulated kernel. The emulated kernel is seen -from the host kernel at IP address 172.20.0.2 and the host kernel is -seen from the emulated kernel at IP address 172.20.0.1. - -@item Launch @code{qemu.sh}. You should have the following output: - -@smallexample -> ./qemu.sh -Connected to host network interface: tun0 -Linux version 2.4.21 (bellard@@voyager.localdomain) (gcc version 3.2.2 20030222 @/(Red Hat @/Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003 -BIOS-provided physical RAM map: - BIOS-e801: 0000000000000000 - 000000000009f000 (usable) - BIOS-e801: 0000000000100000 - 0000000002000000 (usable) -32MB LOWMEM available. -On node 0 totalpages: 8192 -zone(0): 4096 pages. -zone(1): 4096 pages. -zone(2): 0 pages. -Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe @/ide5=noprobe console=ttyS0 -ide_setup: ide2=noprobe -ide_setup: ide3=noprobe -ide_setup: ide4=noprobe -ide_setup: ide5=noprobe -Initializing CPU#0 -Detected 2399.621 MHz processor. -Console: colour EGA 80x25 -Calibrating delay loop... 4744.80 BogoMIPS -Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, @/0k highmem) -Dentry cache hash table entries: 4096 (order: 3, 32768 bytes) -Inode cache hash table entries: 2048 (order: 2, 16384 bytes) -Mount cache hash table entries: 512 (order: 0, 4096 bytes) -Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) -Page-cache hash table entries: 8192 (order: 3, 32768 bytes) -CPU: Intel Pentium Pro stepping 03 -Checking 'hlt' instruction... OK. -POSIX conformance testing by UNIFIX -Linux NET4.0 for Linux 2.4 -Based upon Swansea University Computer Society NET3.039 -Initializing RT netlink socket -apm: BIOS not found. -Starting kswapd -Journalled Block Device driver loaded -Detected PS/2 Mouse Port. -pty: 256 Unix98 ptys configured -Serial driver version 5.05c (2001-07-08) with no serial options enabled -ttyS00 at 0x03f8 (irq = 4) is a 16450 -ne.c:v1.10 9/23/94 Donald Becker (becker@@scyld.com) -Last modified Nov 1, 2000 by Paul Gortmaker -NE*000 ethercard probe at 0x300: 52 54 00 12 34 56 -eth0: NE2000 found at 0x300, using IRQ 9. -RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize -Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4 -ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx -hda: QEMU HARDDISK, ATA DISK drive -ide0 at 0x1f0-0x1f7,0x3f6 on irq 14 -hda: attached ide-disk driver. -hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63 -Partition check: - hda: -Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996 -NET4: Linux TCP/IP 1.0 for NET4.0 -IP Protocols: ICMP, UDP, TCP, IGMP -IP: routing cache hash table of 512 buckets, 4Kbytes -TCP: Hash tables configured (established 2048 bind 4096) -NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. -EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended -VFS: Mounted root (ext2 filesystem). -Freeing unused kernel memory: 64k freed - -Linux version 2.4.21 (bellard@@voyager.localdomain) (gcc version 3.2.2 20030222 @/(Red Hat @/Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003 - -QEMU Linux test distribution (based on Redhat 9) - -Type 'exit' to halt the system - -sh-2.05b# -@end smallexample - -@item -Then you can play with the kernel inside the virtual serial console. You -can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help -about the keys you can type inside the virtual serial console. In -particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as -the Magic SysRq key. - -@item -If the network is enabled, launch the script @file{/etc/linuxrc} in the -emulator (don't forget the leading dot): +The syntax is: @example -. /etc/linuxrc +qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" @end example -Then enable X11 connections on your PC from the emulated Linux: -@example -xhost +172.20.0.2 -@end example +Use @option{-kernel} to provide the Linux kernel image and +@option{-append} to give the kernel command line arguments. The +@option{-initrd} option can be used to provide an INITRD image. -You can now launch @file{xterm} or @file{xlogo} and verify that you have -a real Virtual Linux system ! - -@end enumerate - -NOTES: -@enumerate -@item -A 2.5.74 kernel is also included in the archive. Just -replace the bzImage in qemu.sh to try it. - -@item -In order to exit cleanly from qemu, you can do a @emph{shutdown} inside -qemu. qemu will automatically exit when the Linux shutdown is done. +When using the direct Linux boot, a disk image for the first hard disk +@file{hda} is required because its boot sector is used to launch the +Linux kernel. -@item -You can boot slightly faster by disabling the probe of non present IDE -interfaces. To do so, add the following options on the kernel command -line: +If you do not need graphical output, you can disable it and redirect +the virtual serial port and the QEMU monitor to the console with the +@option{-nographic} option. The typical command line is: @example -ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe +qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ + -append "root=/dev/hda console=ttyS0" -nographic @end example -@item -The example disk image is a modified version of the one made by Kevin -Lawton for the plex86 Project (@url{www.plex86.org}). - -@end enumerate +Use @key{Ctrl-a c} to switch between the serial console and the +monitor (@pxref{pcsys_keys}). @node pcsys_usb @section USB emulation -QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected -to it. You can virtually plug to the hub virtual USB devices or real -host USB devices (experimental, works only on Linux hosts). - -@subsection Using virtual USB devices - -A virtual USB mouse device is available for testing in QEMU. - -You can try it with the following monitor commands: +QEMU emulates a PCI UHCI USB controller. You can virtually plug +virtual USB devices or real host USB devices (experimental, works only +on Linux hosts). Qemu will automatically create and connect virtual USB hubs +as necessary to connect multiple USB devices. -@example -# add the mouse device -(qemu) usb_add mouse - -# show the virtual USB devices plugged on the QEMU Virtual USB hub -(qemu) info usb - Device 0.3, speed 12 Mb/s +@menu +* usb_devices:: +* host_usb_devices:: +@end menu +@node usb_devices +@subsection Connecting USB devices -# after some time you can try to remove the mouse -(qemu) usb_del 0.3 -@end example +USB devices can be connected with the @option{-usbdevice} commandline option +or the @code{usb_add} monitor command. Available devices are: -The option @option{-usbdevice} is similar to the monitor command -@code{usb_add}. +@table @var +@item @code{mouse} +Virtual Mouse. This will override the PS/2 mouse emulation when activated. +@item @code{tablet} +Pointer device that uses absolute coordinates (like a touchscreen). +This means qemu is able to report the mouse position without having +to grab the mouse. Also overrides the PS/2 mouse emulation when activated. +@item @code{disk:file} +Mass storage device based on @var{file} (@pxref{disk_images}) +@item @code{host:bus.addr} +Pass through the host device identified by @var{bus.addr} +(Linux only) +@item @code{host:vendor_id:product_id} +Pass through the host device identified by @var{vendor_id:product_id} +(Linux only) +@end table +@node host_usb_devices @subsection Using host USB devices on a Linux host WARNING: this is an experimental feature. QEMU will slow down when @@ -1250,6 +1471,11 @@ card. All Windows versions starting from Windows 95 should recognize and use this graphic card. For optimal performances, use 16 bit color depth in the guest and the host OS. +If you are using Windows XP as guest OS and if you want to use high +resolution modes which the Cirrus Logic BIOS does not support (i.e. >= +1280x1024x16), then you should use the VESA VBE virtual graphic card +(option @option{-std-vga}). + @subsubsection CPU usage reduction Windows 9x does not correctly use the CPU HLT @@ -1283,7 +1509,7 @@ correctly instructs QEMU to shutdown at the appropriate moment. See @ref{sec_invocation} about the help of the option @option{-smb}. -@subsubsection Windows XP security problems +@subsubsection Windows XP security problem Some releases of Windows XP install correctly but give a security error when booting: @@ -1291,10 +1517,12 @@ error when booting: A problem is preventing Windows from accurately checking the license for this computer. Error code: 0x800703e6. @end example -The only known workaround is to boot in Safe mode -without networking support. -Future QEMU releases are likely to correct this bug. +The workaround is to install a service pack for XP after a boot in safe +mode. Then reboot, and the problem should go away. Since there is no +network while in safe mode, its recommended to download the full +installation of SP1 or SP2 and transfer that via an ISO or using the +vvfat block device ("-hdb fat:directory_which_holds_the_SP"). @subsection MS-DOS and FreeDOS @@ -1388,7 +1616,7 @@ More information is available at @node Sparc32 System emulator invocation @section Sparc32 System emulator invocation -Use the executable @file{qemu-system-sparc} to simulate a JavaStation +Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5 (sun4m architecture). The emulation is somewhat complete. QEMU emulates the following sun4m peripherals: @@ -1413,13 +1641,14 @@ Floppy drive The number of peripherals is fixed in the architecture. -QEMU uses the Proll, a PROM replacement available at -@url{http://people.redhat.com/@/zaitcev/linux/}. The required -QEMU-specific patches are included with the sources. +Since version 0.8.2, QEMU uses OpenBIOS +@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable +firmware implementation. The goal is to implement a 100% IEEE +1275-1994 (referred to as Open Firmware) compliant firmware. A sample Linux 2.6 series kernel and ram disk image are available on -the QEMU web site. Please note that currently neither Linux 2.4 -series, NetBSD, nor OpenBSD kernels work. +the QEMU web site. Please note that currently NetBSD, OpenBSD or +Solaris kernels don't work. @c man begin OPTIONS @@ -1486,22 +1715,104 @@ ARM926E or ARM1026E CPU Two PL011 UARTs @item SMC 91c111 Ethernet adapter +@item +PL110 LCD controller +@item +PL050 KMI with PS/2 keyboard and mouse. +@item +PL181 MultiMedia Card Interface with SD card. +@end itemize + +The ARM Versatile baseboard is emulated with the following devices: + +@itemize @minus +@item +ARM926E CPU +@item +PL190 Vectored Interrupt Controller +@item +Four PL011 UARTs +@item +SMC 91c111 Ethernet adapter +@item +PL110 LCD controller +@item +PL050 KMI with PS/2 keyboard and mouse. +@item +PCI host bridge. Note the emulated PCI bridge only provides access to +PCI memory space. It does not provide access to PCI IO space. +This means some devices (eg. ne2k_pci NIC) are not useable, and others +(eg. rtl8139 NIC) are only useable when the guest drivers use the memory +mapped control registers. +@item +PCI OHCI USB controller. +@item +LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices. +@item +PL181 MultiMedia Card Interface with SD card. +@end itemize + +The ARM RealView Emulation baseboard is emulated with the following devices: + +@itemize @minus +@item +ARM926E CPU +@item +ARM AMBA Generic/Distributed Interrupt Controller +@item +Four PL011 UARTs +@item +SMC 91c111 Ethernet adapter +@item +PL110 LCD controller +@item +PL050 KMI with PS/2 keyboard and mouse +@item +PCI host bridge +@item +PCI OHCI USB controller +@item +LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices +@item +PL181 MultiMedia Card Interface with SD card. @end itemize A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive. -@node QEMU Linux User space emulator -@chapter QEMU Linux User space emulator +@node QEMU User space emulator +@chapter QEMU User space emulator + +@menu +* Supported Operating Systems :: +* Linux User space emulator:: +* Mac OS X/Darwin User space emulator :: +@end menu + +@node Supported Operating Systems +@section Supported Operating Systems + +The following OS are supported in user space emulation: + +@itemize @minus +@item +Linux (refered as qemu-linux-user) +@item +Mac OS X/Darwin (refered as qemu-darwin-user) +@end itemize + +@node Linux User space emulator +@section Linux User space emulator @menu * Quick Start:: * Wine launch:: * Command line options:: +* Other binaries:: @end menu @node Quick Start -@section Quick Start +@subsection Quick Start In order to launch a Linux process, QEMU needs the process executable itself and all the target (x86) dynamic libraries used by it. @@ -1518,7 +1829,8 @@ qemu-i386 -L / /bin/ls @code{-L /} tells that the x86 dynamic linker must be searched with a @file{/} prefix. -@item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources): +@item Since QEMU is also a linux process, you can launch qemu with +qemu (NOTE: you can only do that if you compiled QEMU from the sources): @example qemu-i386 -L / qemu-i386 -L / /bin/ls @@ -1551,7 +1863,7 @@ qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \ @end itemize @node Wine launch -@section Wine launch +@subsection Wine launch @itemize @@ -1580,7 +1892,7 @@ qemu-i386 /usr/local/qemu-i386/wine/bin/wine \ @end itemize @node Command line options -@section Command line options +@subsection Command line options @example usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] @@ -1604,6 +1916,104 @@ Activate log (logfile=/tmp/qemu.log) Act as if the host page size was 'pagesize' bytes @end table +@node Other binaries +@subsection Other binaries + +@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF +binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB +configurations), and arm-uclinux bFLT format binaries. + +@command{qemu-m68k} is capable of running semihosted binaries using the BDM +(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and +coldfire uClinux bFLT format binaries. + +The binary format is detected automatically. + +@node Mac OS X/Darwin User space emulator +@section Mac OS X/Darwin User space emulator + +@menu +* Mac OS X/Darwin Status:: +* Mac OS X/Darwin Quick Start:: +* Mac OS X/Darwin Command line options:: +@end menu + +@node Mac OS X/Darwin Status +@subsection Mac OS X/Darwin Status + +@itemize @minus +@item +target x86 on x86: Most apps (Cocoa and Carbon too) works. [1] +@item +target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!) +@item +target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1] +@item +target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported. +@end itemize + +[1] If you're host commpage can be executed by qemu. + +@node Mac OS X/Darwin Quick Start +@subsection Quick Start + +In order to launch a Mac OS X/Darwin process, QEMU needs the process executable +itself and all the target dynamic libraries used by it. If you don't have the FAT +libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X +CD or compile them by hand. + +@itemize + +@item On x86, you can just try to launch any process by using the native +libraries: + +@example +qemu-i386 /bin/ls +@end example + +or to run the ppc version of the executable: + +@example +qemu-ppc /bin/ls +@end example + +@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker) +are installed: + +@example +qemu-i386 -L /opt/x86_root/ /bin/ls +@end example + +@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in +@file{/opt/x86_root/usr/bin/dyld}. + +@end itemize + +@node Mac OS X/Darwin Command line options +@subsection Command line options + +@example +usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] +@end example + +@table @option +@item -h +Print the help +@item -L path +Set the library root path (default=/) +@item -s size +Set the stack size in bytes (default=524288) +@end table + +Debug options: + +@table @option +@item -d +Activate log (logfile=/tmp/qemu.log) +@item -p pagesize +Act as if the host page size was 'pagesize' bytes +@end table + @node compilation @chapter Compilation from the sources @@ -1638,39 +2048,15 @@ make install @end example to install QEMU in @file{/usr/local}. -@subsection Tested tool versions - -In order to compile QEMU succesfully, it is very important that you -have the right tools. The most important one is gcc. I cannot guaranty -that QEMU works if you do not use a tested gcc version. Look at -'configure' and 'Makefile' if you want to make a different gcc -version work. - -@example -host gcc binutils glibc linux distribution ----------------------------------------------------------------------- -x86 3.2 2.13.2 2.1.3 2.4.18 - 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3 - 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9 - -PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq - 3.2 - -Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0 - -Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0 +@subsection GCC version -ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0 - -[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available - for gcc version >= 3.3. -[2] Linux >= 2.4.20 is necessary for precise exception support - (untested). -[3] 2.4.9-ac10-rmk2-np1-cerf2 - -[4] gcc 2.95.x generates invalid code when using too many register -variables. You must use gcc 3.x on PowerPC. -@end example +In order to compile QEMU successfully, it is very important that you +have the right tools. The most important one is gcc. On most hosts and +in particular on x86 ones, @emph{gcc 4.x is not supported}. If your +Linux distribution includes a gcc 4.x compiler, you can usually +install an older version (it is invoked by @code{gcc32} or +@code{gcc34}). The QEMU configure script automatically probes for +these older versions so that usally you don't have to do anything. @node Windows @section Windows