@end itemize
-QEMU can run without an host kernel driver and yet gives acceptable
+QEMU can run without a host kernel driver and yet gives acceptable
performance.
For system emulation, the following hardware targets are supported:
@item MusicPal (MV88W8618 ARM processor)
@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
@item Siemens SX1 smartphone (OMAP310 processor)
-@item Syborg SVP base model (ARM Cortex-A8).
@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
+@item Avnet LX60/LX110/LX200 boards (Xtensa)
@end itemize
@cindex supported user mode targets
QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
by Tibor "TS" Schütz.
-Not that, by default, GUS shares IRQ(7) with parallel ports and so
-qemu must be told to not have parallel ports to have working GUS
+Note that, by default, GUS shares IRQ(7) with parallel ports and so
+QEMU must be told to not have parallel ports to have working GUS.
@example
-qemu dos.img -soundhw gus -parallel none
+qemu-system-i386 dos.img -soundhw gus -parallel none
@end example
Alternatively:
@example
-qemu dos.img -device gus,irq=5
+qemu-system-i386 dos.img -device gus,irq=5
@end example
Or some other unclaimed IRQ.
Download and uncompress the linux image (@file{linux.img}) and type:
@example
-qemu linux.img
+qemu-system-i386 linux.img
@end example
Linux should boot and give you a prompt.
@example
@c man begin SYNOPSIS
-usage: qemu [options] [@var{disk_image}]
+usage: qemu-system-i386 [options] [@var{disk_image}]
@c man end
@end example
@c man begin OPTIONS
-During the graphical emulation, you can use the following keys:
+During the graphical emulation, you can use special key combinations to change
+modes. The default key mappings are shown below, but if you use @code{-alt-grab}
+then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
+@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
+
@table @key
@item Ctrl-Alt-f
@kindex Ctrl-Alt-f
Toggle full screen
+@item Ctrl-Alt-+
+@kindex Ctrl-Alt-+
+Enlarge the screen
+
+@item Ctrl-Alt--
+@kindex Ctrl-Alt--
+Shrink the screen
+
@item Ctrl-Alt-u
@kindex Ctrl-Alt-u
Restore the screen's un-scaled dimensions
* disk_images_fat_images:: Virtual FAT disk images
* disk_images_nbd:: NBD access
* disk_images_sheepdog:: Sheepdog disk images
+* disk_images_iscsi:: iSCSI LUNs
@end menu
@node disk_images_quickstart
directory tree. In order to use it, just type:
@example
-qemu linux.img -hdb fat:/my_directory
+qemu-system-i386 linux.img -hdb fat:/my_directory
@end example
Then you access access to all the files in the @file{/my_directory}
Floppies can be emulated with the @code{:floppy:} option:
@example
-qemu linux.img -fda fat:floppy:/my_directory
+qemu-system-i386 linux.img -fda fat:floppy:/my_directory
@end example
A read/write support is available for testing (beta stage) with the
@code{:rw:} option:
@example
-qemu linux.img -fda fat:floppy:rw:/my_directory
+qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
@end example
What you should @emph{never} do:
protocol.
@example
-qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
+qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
@end example
If the NBD server is located on the same host, you can use an unix socket instead
of an inet socket:
@example
-qemu linux.img -hdb nbd:unix:/tmp/my_socket
+qemu-system-i386 linux.img -hdb nbd:unix:/tmp/my_socket
@end example
In this case, the block device must be exported using qemu-nbd:
and then you can use it with two guests:
@example
-qemu linux1.img -hdb nbd:unix:/tmp/my_socket
-qemu linux2.img -hdb nbd:unix:/tmp/my_socket
+qemu-system-i386 linux1.img -hdb nbd:unix:/tmp/my_socket
+qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
@end example
If the nbd-server uses named exports (since NBD 2.9.18), you must use the
"exportname" option:
@example
-qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
-qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
+qemu-system-i386 -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
+qemu-system-i386 -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
@end example
@node disk_images_sheepdog
You can boot from the Sheepdog disk image with the command:
@example
-qemu sheepdog:@var{image}
+qemu-system-i386 sheepdog:@var{image}
@end example
You can also create a snapshot of the Sheepdog image like qcow2.
To boot from the Sheepdog snapshot, specify the tag name of the
snapshot.
@example
-qemu sheepdog:@var{image}:@var{tag}
+qemu-system-i386 sheepdog:@var{image}:@var{tag}
@end example
You can create a cloned image from the existing snapshot.
specify one of the Sheepdog servers to connect to.
@example
qemu-img create sheepdog:@var{hostname}:@var{port}:@var{image} @var{size}
-qemu sheepdog:@var{hostname}:@var{port}:@var{image}
+qemu-system-i386 sheepdog:@var{hostname}:@var{port}:@var{image}
+@end example
+
+@node disk_images_iscsi
+@subsection iSCSI LUNs
+
+iSCSI is a popular protocol used to access SCSI devices across a computer
+network.
+
+There are two different ways iSCSI devices can be used by QEMU.
+
+The first method is to mount the iSCSI LUN on the host, and make it appear as
+any other ordinary SCSI device on the host and then to access this device as a
+/dev/sd device from QEMU. How to do this differs between host OSes.
+
+The second method involves using the iSCSI initiator that is built into
+QEMU. This provides a mechanism that works the same way regardless of which
+host OS you are running QEMU on. This section will describe this second method
+of using iSCSI together with QEMU.
+
+In QEMU, iSCSI devices are described using special iSCSI URLs
+
+@example
+URL syntax:
+iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
+@end example
+
+Username and password are optional and only used if your target is set up
+using CHAP authentication for access control.
+Alternatively the username and password can also be set via environment
+variables to have these not show up in the process list
+
+@example
+export LIBISCSI_CHAP_USERNAME=<username>
+export LIBISCSI_CHAP_PASSWORD=<password>
+iscsi://<host>/<target-iqn-name>/<lun>
@end example
+Various session related parameters can be set via special options, either
+in a configuration file provided via '-readconfig' or directly on the
+command line.
+
+If the initiator-name is not specified qemu will use a default name
+of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
+virtual machine.
+
+
+@example
+Setting a specific initiator name to use when logging in to the target
+-iscsi initiator-name=iqn.qemu.test:my-initiator
+@end example
+
+@example
+Controlling which type of header digest to negotiate with the target
+-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+@end example
+
+These can also be set via a configuration file
+@example
+[iscsi]
+ user = "CHAP username"
+ password = "CHAP password"
+ initiator-name = "iqn.qemu.test:my-initiator"
+ # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+ header-digest = "CRC32C"
+@end example
+
+
+Setting the target name allows different options for different targets
+@example
+[iscsi "iqn.target.name"]
+ user = "CHAP username"
+ password = "CHAP password"
+ initiator-name = "iqn.qemu.test:my-initiator"
+ # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+ header-digest = "CRC32C"
+@end example
+
+
+Howto use a configuration file to set iSCSI configuration options:
+@example
+cat >iscsi.conf <<EOF
+[iscsi]
+ user = "me"
+ password = "my password"
+ initiator-name = "iqn.qemu.test:my-initiator"
+ header-digest = "CRC32C"
+EOF
+
+qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
+ -readconfig iscsi.conf
+@end example
+
+
+Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
+@example
+This example shows how to set up an iSCSI target with one CDROM and one DISK
+using the Linux STGT software target. This target is available on Red Hat based
+systems as the package 'scsi-target-utils'.
+
+tgtd --iscsi portal=127.0.0.1:3260
+tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
+tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
+ -b /IMAGES/disk.img --device-type=disk
+tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
+ -b /IMAGES/cd.iso --device-type=cd
+tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
+
+qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
+ -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
+ -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
+@end example
+
+
+
@node pcsys_network
@section Network emulation
syntax is:
@example
-qemu -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
+qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
@end example
If desired, interrupts can be sent between guest VMs accessing the same shared
memory server is:
@example
-qemu -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
- [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
-qemu -chardev socket,path=<path>,id=<id>
+qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
+ [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
+qemu
-system-i386 -chardev socket,path=<path>,id=<id>
@end example
When using the server, the guest will be assigned a VM ID (>=0) that allows guests
The syntax is:
@example
-qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
+qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
@end example
Use @option{-kernel} to provide the Linux kernel image and
the virtual serial port and the QEMU monitor to the console with the
@option{-nographic} option. The typical command line is:
@example
-qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
- -append "root=/dev/hda console=ttyS0" -nographic
+qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
+ -append "root=/dev/hda console=ttyS0" -nographic
@end example
Use @key{Ctrl-a c} to switch between the serial console and the
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
+on Linux hosts). QEMU will automatically create and connect virtual USB hubs
as necessary to connect multiple USB devices.
@menu
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
@item tablet
Pointer device that uses absolute coordinates (like a touchscreen).
-This means qemu is able to report the mouse position without having
+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 disk:@var{file}
Mass storage device based on @var{file} (@pxref{disk_images})
specifies NIC options as with @code{-net nic,}@var{options} (see description).
For instance, user-mode networking can be used with
@example
-qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
+qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
@end example
Currently this cannot be used in machines that support PCI NICs.
@item bt[:@var{hci-type}]
This USB device implements the USB Transport Layer of HCI. Example
usage:
@example
-qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
+qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
@end example
@end table
socket only. For example
@example
-qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
+qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
@end example
This ensures that only users on local box with read/write access to that
to provide high security. The password can be fairly easily brute-forced by
a client making repeat connections. For this reason, a VNC server using password
authentication should be restricted to only listen on the loopback interface
-or UNIX domain sockets. Password authentication is requested with the @code{password}
-option, and then once QEMU is running the password is set with the monitor. Until
-the monitor is used to set the password all clients will be rejected.
+or UNIX domain sockets. Password authentication is not supported when operating
+in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
+authentication is requested with the @code{password} option, and then once QEMU
+is running the password is set with the monitor. Until the monitor is used to
+set the password all clients will be rejected.
@example
-qemu [...OPTIONS...] -vnc :1,password -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
(qemu) change vnc password
Password: ********
(qemu)
client to connect, and provides an encrypted session.
@example
-qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
@end example
In the above example @code{/etc/pki/qemu} should contain at least three files,
in an environment with a private internal certificate authority.
@example
-qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
@end example
to provide two layers of authentication for clients.
@example
-qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
(qemu) change vnc password
Password: ********
(qemu)
then QEMU can be launched with:
@example
-qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
@end example
@node vnc_sec_certificate_sasl
with the aforementioned TLS + x509 options:
@example
-qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
+qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
@end example
QEMU has a primitive support to work with gdb, so that you can do
'Ctrl-C' while the virtual machine is running and inspect its state.
-In order to use gdb, launch qemu with the '-s' option. It will wait for a
+In order to use gdb, launch QEMU with the '-s' option. It will wait for a
gdb connection:
@example
-> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
- -append "root=/dev/hda"
+qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
+ -append "root=/dev/hda"
Connected to host network interface: tun0
Waiting gdb connection on port 1234
@end example
* Cris System emulator::
* Microblaze System emulator::
* SH4 System emulator::
+* Xtensa System emulator::
@end menu
@node PowerPC System emulator
IDE controller
@end itemize
-The mipssim pseudo board emulation provides an environment similiar
+The mipssim pseudo board emulation provides an environment similar
to what the proprietary MIPS emulator uses for running Linux.
It supports:
Three on-chip UARTs
@end itemize
-The "Syborg" Symbian Virtual Platform base model includes the following
-elements:
-
-@itemize @minus
-@item
-ARM Cortex-A8 CPU
-@item
-Interrupt controller
-@item
-Timer
-@item
-Real Time Clock
-@item
-Keyboard
-@item
-Framebuffer
-@item
-Touchscreen
-@item
-UARTs
-@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.
TODO
+@node Xtensa System emulator
+@section Xtensa System emulator
+@cindex system emulation (Xtensa)
+
+Two executables cover simulation of both Xtensa endian options,
+@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
+Two different machine types are emulated:
+
+@itemize @minus
+@item
+Xtensa emulator pseudo board "sim"
+@item
+Avnet LX60/LX110/LX200 board
+@end itemize
+
+The sim pseudo board emulation provides an environment similar
+to one provided by the proprietary Tensilica ISS.
+It supports:
+
+@itemize @minus
+@item
+A range of Xtensa CPUs, default is the DC232B
+@item
+Console and filesystem access via semihosting calls
+@end itemize
+
+The Avnet LX60/LX110/LX200 emulation supports:
+
+@itemize @minus
+@item
+A range of Xtensa CPUs, default is the DC232B
+@item
+16550 UART
+@item
+OpenCores 10/100 Mbps Ethernet MAC
+@end itemize
+
+@c man begin OPTIONS
+
+The following options are specific to the Xtensa emulation:
+
+@table @option
+
+@item -semihosting
+Enable semihosting syscall emulation.
+
+Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
+Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
+
+Note that this allows guest direct access to the host filesystem,
+so should only be used with trusted guest OS.
+
+@end table
@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 ::
* BSD User space emulator ::
@end menu
@item
Linux (referred as qemu-linux-user)
@item
-Mac OS X/Darwin (referred as qemu-darwin-user)
-@item
BSD (referred as qemu-bsd-user)
@end itemize
@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
@item -s size
Set the x86 stack size in bytes (default=524288)
@item -cpu model
-Select CPU model (-cpu ? for list and additional feature selection)
+Select CPU model (-cpu help for list and additional feature selection)
@item -ignore-environment
Start with an empty environment. Without this option,
the initial environment is a copy of the caller's environment.
@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
-@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
-@item -singlestep
-Run the emulation in single step mode.
-@end table
-
@node BSD User space emulator
@section BSD User space emulator
@file{make}. If you have problems using SDL, verify that
@file{sdl-config} can be launched from the MSYS command line.
-@item You can install QEMU in @file{Program Files/Qemu} by typing
+@item You can install QEMU in @file{Program Files/QEMU} by typing
@file{make install}. Don't forget to copy @file{SDL.dll} in
-@file{Program Files/Qemu}.
+@file{Program Files/QEMU}.
@end itemize
MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
use --cross-prefix to specify the name of the cross compiler.
-You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
+You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}.
Under Fedora Linux, you can run:
@example
@end itemize
-Wine can be used to launch the resulting qemu.exe compiled for Win32.
+Wine can be used to launch the resulting qemu-system-i386.exe
+and all other qemu-system-@var{target}.exe compiled for Win32.
@node Mac OS X
@section Mac OS X
projects / sdk / emulator / qemu.git / blobdiff