changeset 1972:e295e6b0e112

bitkeeper revision 1.1108.33.3 (410817b8l8iY5hb257vj-ECAksWmhA)

Tweaks + incorporate text from the existing README file.
There's quite a lot of relevant information in here now, although
there's still some way to go.
author mwilli2@equilibrium.research.intel-research.net
date Wed Jul 28 21:16:40 2004 +0000 (2004-07-28)
parents 6d2b5ebbf4b6
children e8d6db73f188
files docs/user.tex
line diff
     1.1 --- a/docs/user.tex	Wed Jul 28 18:03:08 2004 +0000
     1.2 +++ b/docs/user.tex	Wed Jul 28 21:16:40 2004 +0000
     1.3 @@ -76,13 +76,28 @@ Xen support is available for increasingl
     1.4  following OSs have either been ported already or a port is in
     1.5  progress:
     1.6  \begin{itemize}
     1.7 +\item Dragonfly BSD
     1.8 +\item FreeBSD 4.8
     1.9  \item Linux 2.4
    1.10  \item Linux 2.6
    1.11 -\item FreeBSD 4.8
    1.12  \item NetBSD 2.0
    1.13  \item Plan 9
    1.14 +\item Windows XP
    1.15  \end{itemize}
    1.17 +Right now, Linux 2.4 and 2.6 are available for on Xen 2.0 (the
    1.18 +modifications to Linux are distributed with Xen).  The NetBSD port
    1.19 +will be updated to run on Xen 2.0, hopefully in time for the Xen 2.0
    1.20 +release.  Even running multiple copies of the same OS can be very
    1.21 +useful, as it provides a means of containing faults to one OS image,
    1.22 +and also for providing performance isolation between the various OS,
    1.23 +enabling you to either restrict, or reserve resources for, particular
    1.24 +VM instances.  It is intended that Xen support be integrated into the
    1.25 +official releases of Linux 2.6, NetBSD 2.0, FreeBSD and Dragonfly.
    1.26 +
    1.27 +The Windows XP port is only available to those who have signed the
    1.28 +Microsoft Academic Source License.
    1.29 +
    1.30  Possible usage scenarios for Xen include:
    1.31  \begin{description}
    1.32  \item [Kernel development] test and debug kernel modifications in a
    1.33 @@ -98,6 +113,10 @@ Possible usage scenarios for Xen include
    1.34        machine-specifics and load balance using live migration
    1.35  \item [High availability computing] run device drivers in sandboxed
    1.36        domains for increased robustness
    1.37 +\item [Hardware support for custom OSes] export drivers from a
    1.38 +      mainstream OS (e.g. Linux) with good hardware support
    1.39 +      to your custom OS, avoiding the need for you to port existing
    1.40 +      drivers to achieve good hardware support
    1.41  \end{description}
    1.43  \section{Structure}
    1.44 @@ -138,8 +157,71 @@ system kernels must explicitly support X
    1.45  virtual machine, { \em user space applications and libraries
    1.46  do not require modification }.
    1.48 -\subsection{History}
    1.49 +\section{Hardware Support}
    1.50 +
    1.51 +Xen currently runs on the x86 architecture, but could in principle be
    1.52 +ported to others. In fact, it would have been rather easier to write
    1.53 +Xen for pretty much any other architecture as x86 is particularly
    1.54 +tricky to handle. A good description of Xen's design, implementation
    1.55 +and performance is contained in the October 2003 SOSP paper, available
    1.56 +at:
    1.57 +{\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}
    1.58 +Work to port Xen to x86\_64 and IA64 is currently underway.
    1.59 +
    1.60 +Xen is targetted at server-class machines, and the current list of
    1.61 +supported hardware very much reflects this, avoiding the need for us
    1.62 +to write drivers for "legacy" hardware. It is likely that some desktop
    1.63 +chipsets will fail to work properly with the default Xen
    1.64 +configuration: specifying {\tt noacpi} or {\tt ignorebiostables} when
    1.65 +booting Xen may help in these cases.
    1.66 +
    1.67 +Xen requires a ``P6'' or newer processor (e.g. Pentium Pro, Celeron,
    1.68 +Pentium II, Pentium III, Pentium IV, Xeon, AMD Athlon, AMD Duron).
    1.69 +Multiprocessor machines are supported, and we also have basic support
    1.70 +for HyperThreading (SMT), although this remains a topic for ongoing
    1.71 +research. We're also working on an x86_64 port (though Xen should
    1.72 +already run on these systems just fine in 32-bit mode).
    1.73 +
    1.74 +Xen can currently use up to 4GB of memory.  It is possible for x86
    1.75 +machines to address up to 64GB of physical memory but (unless an
    1.76 +external developer volunteers) there are no plans to support these
    1.77 +systems.  The x86\_64 port is the planned route to supporting more
    1.78 +than 4GB of memory.
    1.80 +In contrast to previous Xen versions, in Xen 2.0 device drivers run
    1.81 +within a privileged guest OS rather than within Xen itself. This means
    1.82 +that we should be compatible with the majority of device hardware
    1.83 +supported by Linux.  The default XenLinux build contains support for
    1.84 +relatively modern server-class network and disk hardware, but you can
    1.85 +add suppport for other hardware by configuring your XenLinux kernel in
    1.86 +the normal way (e.g. \verb_# make ARCH=xen xconfig_).
    1.87 +
    1.88 +\section{History}
    1.89 +
    1.90 +
    1.91 +``Xen'' is a Virtual Machine Monitor (VMM) originally developed by the
    1.92 +Systems Research Group of the University of Cambridge Computer
    1.93 +Laboratory, as part of the UK-EPSRC funded XenoServers project.
    1.94 +
    1.95 +The XenoServers project aims to provide a ``public infrastructure for
    1.96 +global distributed computing'', and Xen plays a key part in that,
    1.97 +allowing us to efficiently partition a single machine to enable
    1.98 +multiple independent clients to run their operating systems and
    1.99 +applications in an environment providing protection, resource
   1.100 +isolation and accounting.  The project web page contains further
   1.101 +information along with pointers to papers and technical reports:
   1.102 +{\tt http://www.cl.cam.ac.uk/xeno}
   1.103 +
   1.104 +Xen has since grown into a project in its own right, enabling us to
   1.105 +investigate interesting research issues regarding the best techniques
   1.106 +for virtualizing resources such as the CPU, memory, disk and network.
   1.107 +The project has been bolstered by support from Intel Research
   1.108 +Cambridge, and HP Labs, who are now working closely with us. We're
   1.109 +also in receipt of support from Microsoft Research Cambridge to port
   1.110 +Windows XP to run on Xen.
   1.111 +
   1.112 +Xen was first described in the 2003 paper at SOSP
   1.113 +({\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}).
   1.114  The first public release of Xen (1.0) was made in October 2003.  Xen
   1.115  was developed as a research project by the University of Cambridge
   1.116  Computer Laboratory (UK).  Xen was the first Virtual Machine Monitor
   1.117 @@ -150,7 +232,10 @@ scenarios on multiple sites.
   1.119  Xen 2.0 is the latest release, featuring greatly enhanced hardware
   1.120  support, configuration flexibility, useability and a larger complement
   1.121 -of supported operating systems.
   1.122 +of supported operating systems.  We think that Xen has the potential
   1.123 +to become {\em the} definitive open source virtualisation solution and
   1.124 +will work to conclusively achieve that position.
   1.125 +
   1.127  \chapter{Installation}
   1.129 @@ -204,8 +289,9 @@ line.
   1.131  \subsection{Using Bitkeeper}
   1.133 -The public master BK repository for the 2.0 release lives at:
   1.134 -{\tt bk://xen.bkbits.net/xeno-unstable.bk}.
   1.135 +The public master BK repository for the 2.0 release lives at: \\
   1.136 +{\tt bk://xen.bkbits.net/xeno-unstable.bk}.  You can use Bitkeeper to
   1.137 +download it and keep it updated with the latest features and fixes.
   1.139  Change to the directory in which you want to put the source code, then
   1.140  run:
   1.141 @@ -226,6 +312,13 @@ changes to the repository by running:
   1.142  # bk pull             # to update the repository
   1.143  \end{verbatim}
   1.145 +\subsection{Without Bitkeeper}
   1.146 +
   1.147 +The Xen source tree is also available in gzipped tarball form from the
   1.148 +Xen downloads page:\\
   1.149 +{\tt http://www.cl.cam.ac.uk/Research/SRG/netos/xen/downloads.html}.
   1.150 +Prebuilt tarballs are also available but are very large.
   1.151 +
   1.152  \section{The distribution}
   1.154  The Xen source code repository is structured as follows:
   1.155 @@ -256,27 +349,63 @@ following:
   1.156        unprivileged virtual machines.
   1.157  \end{itemize}
   1.159 -\begin{verbatim}
   1.160 -# make world
   1.161 -\end{verbatim}
   1.162 +Inspect the Makefile if you want to see what goes on during a
   1.163 +build. Building Xen and the tools is straightforward, but XenLinux is
   1.164 +more complicated. The makefile needs a `pristine' linux kernel tree
   1.165 +which it will then add the Xen architecture files to. You can tell the
   1.166 +makefile the location of the appropriate linux compressed tar file by
   1.167 +setting the LINUX\_SRC environment variable, e.g. \\
   1.168 +\verb!# LINUX\_SRC=/tmp/linux-2.4.26.tar.gz make world! \\
   1.169 +or by placing
   1.170 +the tar file somewhere in the search path of LINUX_SRC_PATH which
   1.171 +defaults to ".:..". If the makefile can't find a suitable kernel tar
   1.172 +file it attempts to download it from kernel.org (this won't work if
   1.173 +you're behind a firewall).
   1.175 -To build the unprivileged port of Linux 2.6, do:
   1.176 -\begin{verbatim}
   1.177 -# make linux26
   1.178 -\end{verbatim}
   1.179 +After untaring the pristine kernel tree, the makefile uses the {\tt
   1.180 +mkbuildtree} script to add the Xen patches the kernel. It then builds
   1.181 +two different XenLinux images, one with a ``-xen0'' extension which
   1.182 +contains hardware device drivers and is intended to be used in the
   1.183 +first virtual machine (``domain 0''), and one with a ``-xenU''
   1.184 +extension that just contains virtual-device drivers.
   1.185 +
   1.186 +The procedure is similar to build the Linux 2.6 port: \\
   1.187 +\verb!LINUX\_SRC=/path/to/linux2.6/source make linux26!
   1.188 +
   1.189 +In both cases, if you have an SMP machine you may wish to give the
   1.190 +{\tt '-j4'} argument to make to get a parallel build.
   1.192  The files produced by the build process are stored under the
   1.193  \path{install/} directory.  To install them in their default
   1.194 -locations, do:
   1.195 -
   1.196 -\begin{verbatim}
   1.197 -# make install
   1.198 -\end{verbatim}
   1.199 +locations, do: \\
   1.200 +\verb_# make install_\\
   1.202  Alternatively, users with special installation requirements may wish
   1.203  to install them manually by copying file to their appropriate
   1.204  destinations.
   1.206 +Take a look at the files in \path{install/boot/}:
   1.207 +\begin{itemize}
   1.208 +\item \path{install/boot/xen.gz} The Xen 'kernel'
   1.209 +\item \path{install/boot/vmlinuz-2.4.26-xen0}  Domain 0 XenLinux kernel
   1.210 +\item \path{install/boot/vmlinuz-2.4.26-xenU}  Unprivileged XenLinux kernel
   1.211 +\end{itemize}
   1.212 +
   1.213 +The difference between the two Linux kernels that are built is due to
   1.214 +the configuration file used for each. The "U" suffixed unprivileged
   1.215 +version doesn't contain any of the physical hardware device drivers
   1.216 +--- it is 30\% smaller and hence may be preferred for your
   1.217 +non-privileged domains.  The ``0'' suffixed privileged version can be
   1.218 +used to boot the system, as well as in driver domains and unprivileged
   1.219 +domains.
   1.220 +
   1.221 +The \path{install/boot} directory will also contain the config files
   1.222 +used for building the XenLinux kernels, and also versions of Xen and
   1.223 +XenLinux kernels that contain debug symbols (\path{xen-syms} and
   1.224 +\path{vmlinux-syms-2.4.26-xen0}) which are essential for interpreting crash
   1.225 +dumps.  Retain these files as the developers may wish to see them if
   1.226 +you post on the mailing list.
   1.227 +
   1.228  \section{Configuration}
   1.230  \subsection{GRUB Configuration}
   1.231 @@ -429,6 +558,30 @@ The most important {\tt xm} commands are
   1.232  \verb_# xm console_: open a console to a domain.
   1.233  e.g. \verb_# xm console 1_ (open console to domain 1)
   1.235 +\subsection{\tt xm list}
   1.236 +
   1.237 +The output of {\tt xm list} is in rows of the following format:\\
   1.238 +\verb_domid name memory cpu state cputime_
   1.239 +
   1.240 +\begin{description}
   1.241 +\item[domid] The number of the domain ID this virtual machine is running in.
   1.242 +\item[name]  The descriptive name of the virtual machine.
   1.243 +\item[memory] Memory size in megabytes.
   1.244 +\item[cpu]   The CPU this domain is running on.
   1.245 +\item[state] Domain state consists of 5 fields:
   1.246 +  \begin{description}
   1.247 +  \item[r] running
   1.248 +  \item[b] blocked
   1.249 +  \item[p] paused
   1.250 +  \item[s] shutdown
   1.251 +  \item[c] crashed
   1.252 +  \end{description}
   1.253 +\item[cputime] How much CPU time (in seconds) the domain has used so far.
   1.254 +
   1.255 +The {\tt xm list} command also supports a long output format when the
   1.256 +{\tt -l} switch is used.  This outputs the fulls details of the
   1.257 +running domains in SXP format.
   1.258 +
   1.259   XXX More explanation needed here...
   1.261  \chapter{Other kinds of storage}