X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=qemu-doc.texi;h=e5d7ac41ab55748c383dabb0ec71019967defac0;hb=115c2b5a6806615206dfa5518509911bfc7b1d07;hp=c3765293d3d84a1d2ed7b6256f3b37f544a8b2a0;hpb=48f57044e6a826329ebcac5d5a76d776a14e5d43;p=qemu.git

diff --git a/qemu-doc.texi b/qemu-doc.texi
index c3765293d..e5d7ac41a 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -107,9 +107,9 @@ 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
@@ -162,6 +162,7 @@ TODO (no longer available)
 * pcsys_monitor::      QEMU Monitor
 * disk_images::        Disk Images
 * pcsys_network::      Network emulation
+* pcsys_other_devs::   Other Devices
 * direct_linux_boot::  Direct Linux Boot
 * pcsys_usb::          USB emulation
 * vnc_security::       VNC security
@@ -200,7 +201,9 @@ ENSONIQ AudioPCI ES1370 sound card
 @item
 Intel 82801AA AC97 Audio compatible sound card
 @item
-Adlib(OPL2) - Yamaha YM3812 compatible chip
+Intel HD Audio Controller and HDA codec
+@item
+Adlib (OPL2) - Yamaha YM3812 compatible chip
 @item
 Gravis Ultrasound GF1 sound card
 @item
@@ -220,10 +223,10 @@ VGA BIOS.
 
 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
 
-QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
+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
+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
@@ -275,12 +278,24 @@ targets do not need a disk image.
 
 @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
@@ -404,6 +419,8 @@ snapshots.
 * host_drives::               Using host drives
 * 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
@@ -627,6 +644,164 @@ qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
 qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
 @end example
 
+@node disk_images_sheepdog
+@subsection Sheepdog disk images
+
+Sheepdog is a distributed storage system for QEMU.  It provides highly
+available block level storage volumes that can be attached to
+QEMU-based virtual machines.
+
+You can create a Sheepdog disk image with the command:
+@example
+qemu-img create sheepdog:@var{image} @var{size}
+@end example
+where @var{image} is the Sheepdog image name and @var{size} is its
+size.
+
+To import the existing @var{filename} to Sheepdog, you can use a
+convert command.
+@example
+qemu-img convert @var{filename} sheepdog:@var{image}
+@end example
+
+You can boot from the Sheepdog disk image with the command:
+@example
+qemu sheepdog:@var{image}
+@end example
+
+You can also create a snapshot of the Sheepdog image like qcow2.
+@example
+qemu-img snapshot -c @var{tag} sheepdog:@var{image}
+@end example
+where @var{tag} is a tag name of the newly created snapshot.
+
+To boot from the Sheepdog snapshot, specify the tag name of the
+snapshot.
+@example
+qemu sheepdog:@var{image}:@var{tag}
+@end example
+
+You can create a cloned image from the existing snapshot.
+@example
+qemu-img create -b sheepdog:@var{base}:@var{tag} sheepdog:@var{image}
+@end example
+where @var{base} is a image name of the source snapshot and @var{tag}
+is its tag name.
+
+If the Sheepdog daemon doesn't run on the local host, you need to
+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}
+@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.
+
+@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
 
@@ -713,6 +888,7 @@ Using the @option{-net socket} option, it is possible to make VLANs
 that span several QEMU instances. See @ref{sec_invocation} to have a
 basic example.
 
+@node pcsys_other_devs
 @section Other Devices
 
 @subsection Inter-VM Shared Memory device
@@ -792,7 +968,7 @@ monitor (@pxref{pcsys_keys}).
 
 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
@@ -830,7 +1006,7 @@ Standard USB keyboard.  Will override the PS/2 keyboard (if present).
 Serial converter. This emulates an FTDI FT232BM chip connected to host character
 device @var{dev}. The available character devices are the same as for the
 @code{-serial} option. The @code{vendorid} and @code{productid} options can be
-used to override the default 0403:6001. For instance, 
+used to override the default 0403:6001. For instance,
 @example
 usb_add serial:productid=FA00:tcp:192.168.0.2:4444
 @end example
@@ -1045,7 +1221,7 @@ qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
 
 The GNU TLS packages provides a command called @code{certtool} which can
 be used to generate certificates and keys in PEM format. At a minimum it
-is neccessary to setup a certificate authority, and issue certificates to
+is necessary to setup a certificate authority, and issue certificates to
 each server. If using certificates for authentication, then each client
 will also need to be issued a certificate. The recommendation is for the
 server to keep its certificates in either @code{/etc/pki/qemu} or for
@@ -1188,7 +1364,7 @@ keytab: /etc/qemu/krb5.tab
 For this to work the administrator of your KDC must generate a Kerberos
 principal for the server, with a name of  'qemu/somehost.example.com@@EXAMPLE.COM'
 replacing 'somehost.example.com' with the fully qualified host name of the
-machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
+machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
 
 Other configurations will be left as an exercise for the reader. It should
 be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
@@ -1378,6 +1554,7 @@ differences are mentioned in the following sections.
 * Cris System emulator::
 * Microblaze System emulator::
 * SH4 System emulator::
+* Xtensa System emulator::
 @end menu
 
 @node PowerPC System emulator
@@ -1679,7 +1856,7 @@ PC Keyboard
 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:
 
@@ -1770,7 +1947,7 @@ enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
 disabled and expect 1024M RAM.
 
-The following devices are emuilated:
+The following devices are emulated:
 
 @itemize @minus
 @item
@@ -1870,7 +2047,7 @@ Secure Digital card connected to OMAP MMC/SD host
 @item
 Three OMAP on-chip UARTs and on-chip STI debugging console
 @item
-A Bluetooth(R) transciever and HCI connected to an UART
+A Bluetooth(R) transceiver and HCI connected to an UART
 @item
 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
 TUSB6010 chip - only USB host mode is supported
@@ -1932,7 +2109,7 @@ MV88W8618 audio controller, WM8750 CODEC and mixer
 @end itemize
 
 The Siemens SX1 models v1 and v2 (default) basic emulation.
-The emulaton includes the following elements:
+The emulation includes the following elements:
 
 @itemize @minus
 @item
@@ -1953,28 +2130,6 @@ Secure Digital card connected to OMAP MMC/SD host
 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.
 
@@ -2056,13 +2211,65 @@ TODO
 
 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
 
@@ -2075,8 +2282,6 @@ The following OS are supported in user space emulation:
 @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
 
@@ -2128,7 +2333,7 @@ Then you can launch the precompiled @file{ls} x86 executable:
 @example
 qemu-i386 tests/i386/ls
 @end example
-You can look at @file{qemu-binfmt-conf.sh} so that
+You can look at @file{scripts/qemu-binfmt-conf.sh} so that
 QEMU is automatically launched by the Linux kernel when you try to
 launch x86 executables. It requires the @code{binfmt_misc} module in the
 Linux kernel.
@@ -2188,7 +2393,7 @@ Set the x86 stack size in bytes (default=524288)
 Select CPU model (-cpu ? for list and additional feature selection)
 @item -ignore-environment
 Start with an empty environment. Without this option,
-the inital environment is a copy of the caller's environment.
+the initial environment is a copy of the caller's environment.
 @item -E @var{var}=@var{value}
 Set environment @var{var} to @var{value}.
 @item -U @var{var}
@@ -2199,7 +2404,7 @@ the address region required by guest applications is reserved on the host.
 This option is currently only supported on some hosts.
 @item -R size
 Pre-allocate a guest virtual address space of the given size (in bytes).
-"G", "M", and "k" suffixes may be used when specifying the size.  
+"G", "M", and "k" suffixes may be used when specifying the size.
 @end table
 
 Debug options:
@@ -2281,93 +2486,6 @@ The binary format is detected automatically.
 @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
 
@@ -2418,7 +2536,7 @@ Set the library root path (default=/)
 Set the stack size in bytes (default=524288)
 @item -ignore-environment
 Start with an empty environment. Without this option,
-the inital environment is a copy of the caller's environment.
+the initial environment is a copy of the caller's environment.
 @item -E @var{var}=@var{value}
 Set environment @var{var} to @var{value}.
 @item -U @var{var}
@@ -2491,7 +2609,7 @@ correct SDL directory when invoked.
 
 @item Install the MinGW version of zlib and make sure
 @file{zlib.h} and @file{libz.dll.a} are in
-MingGW's default header and linker search paths.
+MinGW's default header and linker search paths.
 
 @item Extract the current version of QEMU.
 
@@ -2501,9 +2619,9 @@ MingGW's default header and linker search paths.
 @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
 
@@ -2526,7 +2644,7 @@ the QEMU configuration script.
 
 @item Install the MinGW version of zlib and make sure
 @file{zlib.h} and @file{libz.dll.a} are in
-MingGW's default header and linker search paths.
+MinGW's default header and linker search paths.
 
 @item
 Configure QEMU for Windows cross compilation:
@@ -2535,9 +2653,9 @@ PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i
 @end example
 The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
 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
+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