ia64/xen-unstable

changeset 17365:720552439f74

docs: Fix HVM user documentation

Summary of changes:

- replaced VMX with HVM
- added AMD as a vendor of HVM capable processors
- removed LibVNCServer as a requirement for HVM builds
- fixed name of HVM example file
- changed default value of acpi, apic and pae options
- added hap option
- removed reference to cdrom option and integrated it into "disk"
- improved examples for disk option
- replaced vncviewer option with vncconsole
- removed obsolete ne2000 option
- replaced enable-audio with soundhw
- fixed dd usage for creating sparse files (count=0)
- remove acpi=0 hint for Windows guests
- removed reference to (obsolete?) -f option for xm create
- made shutdown advice less Linux centric
- removed comment about save/restore and migration not yet ready

Signed-off-by: Andre Przywara <andre.przywara@amd.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 01 17:24:22 2008 +0100 (2008-04-01)
parents baff5b3aaf13
children 250606290439
files docs/src/user.tex
line diff
     1.1 --- a/docs/src/user.tex	Tue Apr 01 17:22:52 2008 +0100
     1.2 +++ b/docs/src/user.tex	Tue Apr 01 17:24:22 2008 +0100
     1.3 @@ -1618,9 +1618,9 @@ if a virtual machine uses only half of i
     1.4  really takes up half of the size allocated.
     1.5  
     1.6  For example, to create a 2GB sparse file-backed virtual block device
     1.7 -(actually only consumes 1KB of disk):
     1.8 +(actually only consumes no disk space at all):
     1.9  \begin{quote}
    1.10 -  \verb_# dd if=/dev/zero of=vm1disk bs=1k seek=2048k count=1_
    1.11 +  \verb_# dd if=/dev/zero of=vm1disk bs=1k seek=2048k count=0_
    1.12  \end{quote}
    1.13  
    1.14  Make a file system in the disk file:
    1.15 @@ -4306,14 +4306,22 @@ mailing lists and subscription informati
    1.16  
    1.17  \appendix
    1.18  
    1.19 -\chapter{Unmodified (VMX) guest domains in Xen with Intel\textregistered Virtualization Technology (VT)}
    1.20 -
    1.21 -Xen supports guest domains running unmodified Guest operating systems using Virtualization Technology (VT) available on recent Intel Processors. More information about the Intel Virtualization Technology implementing Virtual Machine Extensions (VMX) in the processor is available on the Intel website at \\
    1.22 +\chapter{Unmodified (HVM) guest domains in Xen with Hardware support for Virtualization}
    1.23 +
    1.24 +Xen supports guest domains running unmodified guest operating systems using
    1.25 +virtualization extensions available on recent processors. Currently processors
    1.26 +featuring the Intel Virtualization Extension (Intel-VT) or the AMD extension
    1.27 +(AMD-V) are supported. The technology covering both implementations is
    1.28 +called HVM (for Hardware Virtual Machine) in Xen. More information about the
    1.29 +virtualization extensions are available on the respective websites:
    1.30   {\small {\tt http://www.intel.com/technology/computing/vptech}}
    1.31  
    1.32 -\section{Building Xen with VT support}
    1.33 -
    1.34 -The following packages need to be installed in order to build Xen with VT support. Some Linux distributions do not provide these packages by default.
    1.35 +
    1.36 + {\small {\tt http://www.amd.com/us-en/assets/content\_type/white\_papers\_and\_tech\_docs/24593.pdf}}
    1.37 +
    1.38 +\section{Building Xen with HVM support}
    1.39 +
    1.40 +The following packages need to be installed in order to build Xen with HVM support. Some Linux distributions do not provide these packages by default.
    1.41  
    1.42  \begin{tabular}{lp{11.0cm}}
    1.43  {\bfseries Package} & {\bfseries Description} \\
    1.44 @@ -4322,70 +4330,75 @@ dev86 & The dev86 package provides an as
    1.45  
    1.46  If the dev86 package is not available on the x86\_64 distribution, you can install the i386 version of it. The dev86 rpm package for various distributions can be found at {\scriptsize {\tt http://www.rpmfind.net/linux/rpm2html/search.php?query=dev86\&submit=Search}} \\
    1.47  
    1.48 -LibVNCServer & The unmodified guest's VGA display, keyboard, and mouse can be virtualized by the vncserver library. You can get the sources of libvncserver from {\small {\tt http://sourceforge.net/projects/libvncserver}}. Build and install the sources on the build system to get the libvncserver library. There is a significant performance degradation in 0.8 version. The current sources in the CVS tree have fixed this degradation. So it is highly recommended to download the latest CVS sources and install them.\\
    1.49 -
    1.50  SDL-devel, SDL & Simple DirectMedia Layer (SDL) is another way of virtualizing the unmodified guest console. It provides an X window for the guest console. 
    1.51  
    1.52  If the SDL and SDL-devel packages are not installed by default on the build system, they can be obtained from  {\scriptsize {\tt http://www.rpmfind.net/linux/rpm2html/search.php?query=SDL\&amp;submit=Search}}
    1.53 -, {\scriptsize {\tt http://www.rpmfind.net/linux/rpm2html/search.php?query=SDL-devel\&submit=Search}} \\
    1.54 +
    1.55 +
    1.56 +{\scriptsize {\tt http://www.rpmfind.net/linux/rpm2html/search.php?query=SDL-devel\&submit=Search}} \\
    1.57  
    1.58  \end{tabular}
    1.59  
    1.60 -\section{Configuration file for unmodified VMX guests}
    1.61 -
    1.62 -The Xen installation includes a sample configuration file, {\small {\tt /etc/xen/xmexample.vmx}}. There are comments describing all the options. In addition to the common options that are the same as those for paravirtualized guest configurations, VMX guest configurations have the following settings:
    1.63 +\section{Configuration file for unmodified HVM guests}
    1.64 +
    1.65 +The Xen installation includes a sample configuration file, {\small {\tt /etc/xen/xmexample.hvm}}. There are comments describing all the options. In addition to the common options that are the same as those for paravirtualized guest configurations, HVM guest configurations have the following settings:
    1.66  
    1.67  \begin{tabular}{lp{11.0cm}}
    1.68  
    1.69  {\bfseries Parameter} & {\bfseries Description} \\
    1.70  
    1.71 -kernel &        The VMX firmware loader, {\small {\tt /usr/lib/xen/boot/vmxloader}}\\
    1.72 -
    1.73 -builder &       The domain build function. The VMX domain uses the vmx builder.\\
    1.74 -
    1.75 -acpi & Enable VMX guest ACPI, default=0 (disabled)\\
    1.76 -
    1.77 -apic & Enable VMX guest APIC, default=0 (disabled)\\
    1.78 -
    1.79 -pae & Enable VMX guest PAE, default=0 (disabled)\\
    1.80 -
    1.81 -vif     & Optionally defines MAC address and/or bridge for the network interfaces. Random MACs are assigned if not given. {\small {\tt type=ioemu}} means ioemu is used to virtualize the VMX NIC. If no type is specified, vbd is used, as with paravirtualized guests.\\
    1.82 -
    1.83 -disk & Defines the disk devices you want the domain to have access to, and what you want them accessible as. If using a physical device as the VMX guest's disk, each disk entry is of the form 
    1.84 +kernel &        The HVM firmware loader, {\small {\tt /usr/lib/xen/boot/hvmloader}}\\
    1.85 +
    1.86 +builder &       The domain build function. The HVM domain uses the 'hvm' builder.\\
    1.87 +
    1.88 +acpi & Enable HVM guest ACPI, default=1 (enabled)\\
    1.89 +
    1.90 +apic & Enable HVM guest APIC, default=1 (enabled)\\
    1.91 +
    1.92 +pae & Enable HVM guest PAE, default=1 (enabled)\\
    1.93 +
    1.94 +hap & Enable hardware-assisted paging support, such as AMD-V's nested paging
    1.95 +or Intel\textregistered VT's extended paging. If available, Xen will
    1.96 +use hardware-assisted paging instead of shadow paging for this guest's memory
    1.97 +management.\\
    1.98 +
    1.99 +vif     & Optionally defines MAC address and/or bridge for the network interfaces. Random MACs are assigned if not given. {\small {\tt type=ioemu}} means ioemu is used to virtualize the HVM NIC. If no type is specified, vbd is used, as with paravirtualized guests.\\
   1.100 +
   1.101 +disk & Defines the disk devices you want the domain to have access to, and what you want them accessible as. If using a physical device as the HVM guest's disk, each disk entry is of the form 
   1.102  
   1.103  {\small {\tt phy:UNAME,ioemu:DEV,MODE,}}
   1.104  
   1.105 -where UNAME is the device, DEV is the device name the domain will see, and MODE is r for read-only, w for read-write. ioemu means the disk will use ioemu to virtualize the VMX disk. If not adding ioemu, it uses vbd like paravirtualized guests.
   1.106 +where UNAME is the host device file, DEV is the device name the domain will see, and MODE is r for read-only, w for read-write. ioemu means the disk will use ioemu to virtualize the HVM disk. If not adding ioemu, it uses vbd like paravirtualized guests.
   1.107  
   1.108  If using disk image file, its form should be like 
   1.109  
   1.110  {\small {\tt file:FILEPATH,ioemu:DEV,MODE}}
   1.111  
   1.112 +Optical devices can be emulated by appending cdrom to the device type
   1.113 +
   1.114 +{\small {\tt ',hdc:cdrom,r'}}
   1.115 +
   1.116  If using more than one disk, there should be a comma between each disk entry. For example:
   1.117  
   1.118 -{\scriptsize {\tt disk = ['file:/var/images/image1.img,ioemu:hda,w', 'file:/var/images/image2.img,ioemu:hdb,w']}}\\
   1.119 -
   1.120 -cdrom   & Disk image for CD-ROM. The default is {\small {\tt /dev/cdrom}} for Domain0. Inside the VMX domain, the CD-ROM will available as device {\small {\tt /dev/hdc}}. The entry can also point to an ISO file.\\
   1.121 -
   1.122 -boot & Boot from floppy (a), hard disk (c) or CD-ROM (d). For example, to boot from CD-ROM, the entry should be:
   1.123 -
   1.124 -boot='d'\\
   1.125 -
   1.126 -device\_model & The device emulation tool for VMX guests. This parameter should not be changed.\\
   1.127 +{\scriptsize {\tt disk = ['file:/var/images/image1.img,ioemu:hda,w', 'phy:hda1,hdb1,w', 'file:/var/images/install1.iso,hdc:cdrom,r']}}\\
   1.128 +
   1.129 +boot & Boot from floppy (a), hard disk (c) or CD-ROM (d). For example, to boot from CD-ROM and fallback to HD, the entry should be:
   1.130 +
   1.131 +boot='dc'\\
   1.132 +
   1.133 +device\_model & The device emulation tool for HVM guests. This parameter should not be changed.\\
   1.134  
   1.135  sdl &   Enable SDL library for graphics, default = 0 (disabled)\\
   1.136  
   1.137  vnc &   Enable VNC library for graphics, default = 1 (enabled)\\
   1.138  
   1.139 -vncviewer &     Enable spawning of the vncviewer (only valid when vnc=1), default = 1 (enabled)
   1.140 -
   1.141 -If vnc=1 and vncviewer=0, user can use vncviewer to manually connect VMX from remote. For example:
   1.142 -
   1.143 -{\small {\tt vncviewer domain0\_IP\_address:VMX\_domain\_id}} \\
   1.144 -
   1.145 -ne2000 &        Enable ne2000, default = 0 (disabled; use pcnet)\\
   1.146 -
   1.147 -serial &        Enable redirection of VMX serial output to pty device\\
   1.148 +vncconsole &     Enable spawning of the vncviewer (only valid when vnc=1), default = 0 (disabled)
   1.149 +
   1.150 +If vnc=1 and vncconsole=0, user can use vncviewer to manually connect HVM from remote. For example:
   1.151 +
   1.152 +{\small {\tt vncviewer domain0\_IP\_address:HVM\_domain\_id}} \\
   1.153 +
   1.154 +serial &        Enable redirection of HVM serial output to pty device\\
   1.155  
   1.156  \end{tabular}
   1.157  
   1.158 @@ -4416,9 +4429,9 @@ Details about mouse emulation are provid
   1.159  
   1.160  localtime &     Set the real time clock to local time [default=0, that is, set to UTC].\\
   1.161  
   1.162 -enable-audio &  Enable audio support. This is under development.\\
   1.163 -
   1.164 -full-screen     & Start in full screen. This is under development.\\
   1.165 +soundhw   &     Enable sound card support and specify the hardware to emulate. Values can be sb16, es1370 or all. Default is none.\\
   1.166 +
   1.167 +full-screen   & Start in full screen.\\
   1.168  
   1.169  nographic &     Another way to redirect serial output. If enabled, no 'sdl' or 'vnc' can work. Not recommended.\\
   1.170  
   1.171 @@ -4430,18 +4443,18 @@ nographic &     Another way to redirect 
   1.172  If you are using a physical disk or physical disk partition, you need to install a Linux OS on the disk first. Then the boot loader should be installed in the correct place. For example {\small {\tt dev/sda}} for booting from the whole disk, or {\small {\tt /dev/sda1}} for booting from partition 1.
   1.173  
   1.174  \subsection{Using disk image files}
   1.175 -You need to create a large empty disk image file first; then, you need to install a Linux OS onto it. There are two methods you can choose. One is directly installing it using a VMX guest while booting from the OS installation CD-ROM. The other is copying an installed OS into it. The boot loader will also need to be installed.
   1.176 +You need to create a large empty disk image file first; then, you need to install a Linux OS onto it. There are two methods you can choose. One is directly installing it using a HVM guest while booting from the OS installation CD-ROM. The other is copying an installed OS into it. The boot loader will also need to be installed.
   1.177  
   1.178  \subsubsection*{To create the image file:}
   1.179  The image size should be big enough to accommodate the entire OS. This example assumes the size is 1G (which is probably too small for most OSes).
   1.180  
   1.181 -{\small {\tt \# dd if=/dev/zero of=hd.img bs=1M count=1 seek=1023}}
   1.182 -
   1.183 -\subsubsection*{To directly install Linux OS into an image file using a VMX guest:}
   1.184 -
   1.185 -Install Xen and create VMX with the original image file with booting from CD-ROM. Then it is just like a normal Linux OS installation. The VMX configuration file should have these two entries before creating:
   1.186 -
   1.187 -{\small {\tt cdrom='/dev/cdrom'
   1.188 +{\small {\tt \# dd if=/dev/zero of=hd.img bs=1M count=0 seek=1024}}
   1.189 +
   1.190 +\subsubsection*{To directly install Linux OS into an image file using a HVM guest:}
   1.191 +
   1.192 +Install Xen and create HVM with the original image file with booting from CD-ROM. Then it is just like a normal Linux OS installation. The HVM configuration file should have a stanza for the CD-ROM as well as a boot device specification:
   1.193 +
   1.194 +{\small {\tt disk=['file:/var/images/your-hd.img,hda,w', ',hdc:cdrom,r' ]
   1.195  boot='d'}}
   1.196  
   1.197  If this method does not succeed, you can choose the following method of copying an installed Linux OS into an image file.
   1.198 @@ -4509,31 +4522,28 @@ none            /sys            sysfs   
   1.199  
   1.200  Now, the guest OS image {\small {\tt hd.img}} is ready. You can also reference {\small {\tt http://free.oszoo.org}} for quickstart images. But make sure to install the boot loader.
   1.201  
   1.202 -\subsection{Install Windows into an Image File using a VMX guest}
   1.203 -In order to install a Windows OS, you should keep {\small {\tt acpi=0}} in your VMX configuration file.
   1.204 -
   1.205 -\section{VMX Guests}
   1.206 -\subsection{Editing the Xen VMX config file}
   1.207 -Make a copy of the example VMX configuration file {\small {\tt /etc/xen/xmeaxmple.vmx}} and edit the line that reads
   1.208 -
   1.209 -{\small {\tt disk = [ 'file:/var/images/\emph{guest.img},ioemu:hda,w' ]}}
   1.210 -
   1.211 -replacing \emph{guest.img} with the name of the guest OS image file you just made.
   1.212 -
   1.213 -\subsection{Creating VMX guests}
   1.214 -Simply follow the usual method of creating the guest, using the -f parameter and providing the filename of your VMX configuration file:\\
   1.215 +\section{HVM Guests}
   1.216 +\subsection{Editing the Xen HVM config file}
   1.217 +Make a copy of the example HVM configuration file {\small {\tt /etc/xen/xmexample.hvm}} and edit the line that reads
   1.218 +
   1.219 +{\small {\tt disk = [ 'file:/var/images/\emph{min-el3-i386.img},hda,w' ]}}
   1.220 +
   1.221 +replacing \emph{min-el3-i386.img} with the name of the guest OS image file you just made.
   1.222 +
   1.223 +\subsection{Creating HVM guests}
   1.224 +Simply follow the usual method of creating the guest, providing the filename of your HVM configuration file:\\
   1.225  
   1.226  {\small {\tt \# xend start\\
   1.227 -\# xm create /etc/xen/vmxguest.vmx}}
   1.228 -
   1.229 -In the default configuration, VNC is on and SDL is off. Therefore VNC windows will open when VMX guests are created. If you want to use SDL to create VMX guests, set {\small {\tt sdl=1}} in your VMX configuration file. You can also turn off VNC by setting {\small {\tt vnc=0}}.
   1.230 +\# xm create /etc/xen/hvmguest.hvm}}
   1.231 +
   1.232 +In the default configuration, VNC is on and SDL is off. Therefore VNC windows will open when HVM guests are created. If you want to use SDL to create HVM guests, set {\small {\tt sdl=1}} in your HVM configuration file. You can also turn off VNC by setting {\small {\tt vnc=0}}.
   1.233   
   1.234  \subsection{Mouse issues, especially under VNC}
   1.235  Mouse handling when using VNC is a little problematic.
   1.236  The problem is that the VNC viewer provides a virtual pointer which is
   1.237  located at an absolute location in the VNC window and only absolute
   1.238  coordinates are provided.
   1.239 -The VMX device model converts these absolute mouse coordinates
   1.240 +The HVM device model converts these absolute mouse coordinates
   1.241  into the relative motion deltas that are expected by the PS/2
   1.242  mouse driver running in the guest.
   1.243  Unfortunately,
   1.244 @@ -4550,7 +4560,7 @@ there are no longer any left mouse delta
   1.245  can be provided by the device model emulation code.)
   1.246  
   1.247  To deal with these mouse issues there are 4 different
   1.248 -mouse emulations available from the VMX device model:
   1.249 +mouse emulations available from the HVM device model:
   1.250  
   1.251  \begin{description}
   1.252  \item[PS/2 mouse over the PS/2 port.]
   1.253 @@ -4845,7 +4855,7 @@ vendor id
   1.254  and product id
   1.255  \textbf{310b}.
   1.256  This device could be made available
   1.257 -to the VMX guest by including the
   1.258 +to the HVM guest by including the
   1.259  config file entry
   1.260  {\small
   1.261  \begin{verbatim}
   1.262 @@ -4959,7 +4969,7 @@ not the guest can see a USB mouse.}
   1.263  will remove the USB mouse
   1.264  driver from the Dom0 kernel
   1.265  and the mouse will now be
   1.266 -accessible by the VMX guest.
   1.267 +accessible by the HVM guest.
   1.268  
   1.269  Be aware the the Linux USB
   1.270  hotplug system will reload
   1.271 @@ -4981,26 +4991,25 @@ just to make sure it doesn't get
   1.272  reloaded.
   1.273  \end{description}
   1.274  
   1.275 -\subsection{Destroy VMX guests}
   1.276 -VMX guests can be destroyed in the same way as can paravirtualized guests. We recommend that you type the command 
   1.277 +\subsection{Destroy HVM guests}
   1.278 +HVM guests can be destroyed in the same way as can paravirtualized guests. We recommend that you shut-down the guest using the guest OS' provided method, for Linux, type the command
   1.279  
   1.280  {\small {\tt poweroff}} 
   1.281  
   1.282 -in the VMX guest's console first to prevent data loss. Then execute the command 
   1.283 +in the HVM guest's console, for Windows use Start -> Shutdown first to prevent
   1.284 +data loss. Depending on the configuration the guest will be automatically
   1.285 +destroyed, otherwise execute the command 
   1.286  
   1.287  {\small {\tt xm destroy \emph{vmx\_guest\_id} }} 
   1.288  
   1.289  at the Domain0 console.
   1.290  
   1.291 -\subsection{VMX window (X or VNC) Hot Key}
   1.292 -If you are running in the X environment after creating a VMX guest, an X window is created. There are several hot keys for control of the VMX guest that can be used in the window.
   1.293 +\subsection{HVM window (X or VNC) Hot Key}
   1.294 +If you are running in the X environment after creating a HVM guest, an X window is created. There are several hot keys for control of the HVM guest that can be used in the window.
   1.295   
   1.296 -{\bfseries Ctrl+Alt+2} switches from guest VGA window to the control window. Typing {\small {\tt help }} shows the control commands help. For example, 'q' is the command to destroy the VMX guest.\\
   1.297 -{\bfseries Ctrl+Alt+1} switches back to VMX guest's VGA.\\
   1.298 -{\bfseries Ctrl+Alt+3} switches to serial port output. It captures serial output from the VMX guest. It works only if the VMX guest was configured to use the serial port. \\
   1.299 -
   1.300 -\subsection{Save/Restore and Migration}
   1.301 -VMX guests currently cannot be saved and restored, nor migrated. These features are currently under active development.
   1.302 +{\bfseries Ctrl+Alt+2} switches from guest VGA window to the control window. Typing {\small {\tt help }} shows the control commands help. For example, 'q' is the command to destroy the HVM guest.\\
   1.303 +{\bfseries Ctrl+Alt+1} switches back to HVM guest's VGA.\\
   1.304 +{\bfseries Ctrl+Alt+3} switches to serial port output. It captures serial output from the HVM guest. It works only if the HVM guest was configured to use the serial port. \\
   1.305  
   1.306  \chapter{Vnets - Domain Virtual Networking}
   1.307