ia64/xen-unstable

changeset 1909:af423aeca402

bitkeeper revision 1.1108.1.23 (41051bc8Pfe6s4D_U9HcNPC_bL3t_g)

Merge ssh://srg//auto/groups/xeno/BK/xeno.bk
into equilibrium.research.intel-research.net:/export/scratch/mwilli2/temp/xeno.bk
author mwilli2@equilibrium.research.intel-research.net
date Mon Jul 26 14:57:12 2004 +0000 (2004-07-26)
parents 997d615bd58b edc7bf00ee37
children 408ce4535108 3ca25713a583
files .rootkeys docs/user.tex
line diff
     1.1 --- a/.rootkeys	Mon Jul 26 14:43:34 2004 +0000
     1.2 +++ b/.rootkeys	Mon Jul 26 14:57:12 2004 +0000
     1.3 @@ -16,6 +16,7 @@ 3f9e7d60PWZJeVh5xdnk0nLUdxlqEA docs/eps/
     1.4  3f9e7d63lTwQbp2fnx7yY93epWS-eQ docs/figs/dummy
     1.5  3f9e7d564bWFB-Czjv1qdmE6o0GqNg docs/interface.tex
     1.6  3f9e7d58t7N6hjjBMxSn-NMxBphchA docs/style.tex
     1.7 +410144afnSd2Yw68AHGO5gXu2m3y6A docs/user.tex
     1.8  40d6ccbfKKBq8jE0ula4eHEzBiQuDA docs/xen_config.html
     1.9  3f9e7d5bz8BwYkNuwyiPVu7JJG441A docs/xenstyle.cls
    1.10  3f815144d1vI2777JI-dO4wk49Iw7g extras/mini-os/Makefile
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/docs/user.tex	Mon Jul 26 14:57:12 2004 +0000
     2.3 @@ -0,0 +1,752 @@
     2.4 +\documentclass[11pt,twoside,final,openright]{xenstyle}
     2.5 +\usepackage{a4,graphicx,setspace}
     2.6 +\setstretch{1.15}
     2.7 +\input{style.tex}
     2.8 +
     2.9 +\begin{document}
    2.10 +
    2.11 +% TITLE PAGE
    2.12 +\pagestyle{empty}
    2.13 +\begin{center}
    2.14 +\vspace*{\fill}
    2.15 +\includegraphics{eps/xenlogo.eps}
    2.16 +\vfill
    2.17 +\vfill
    2.18 +\vfill
    2.19 +\begin{tabular}{l}
    2.20 +{\Huge \bf Users' manual} \\[4mm]
    2.21 +{\huge Xen v2.0 for x86} \\[80mm]
    2.22 +
    2.23 +{\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm]
    2.24 +{\Large University of Cambridge, UK} \\[20mm]
    2.25 +{\large Last updated on 11th March, 2004}
    2.26 +\end{tabular}
    2.27 +\vfill
    2.28 +\end{center}
    2.29 +\cleardoublepage
    2.30 +
    2.31 +% TABLE OF CONTENTS
    2.32 +\pagestyle{plain}
    2.33 +\pagenumbering{roman}
    2.34 +{ \parskip 0pt plus 1pt
    2.35 +  \tableofcontents }
    2.36 +\cleardoublepage
    2.37 +
    2.38 +% PREPARE FOR MAIN TEXT
    2.39 +\pagenumbering{arabic}
    2.40 +\raggedbottom
    2.41 +\widowpenalty=10000
    2.42 +\clubpenalty=10000
    2.43 +\parindent=0pt
    2.44 +\renewcommand{\topfraction}{.8}
    2.45 +\renewcommand{\bottomfraction}{.8}
    2.46 +\renewcommand{\textfraction}{.2}
    2.47 +\renewcommand{\floatpagefraction}{.8}
    2.48 +\setstretch{1.15}
    2.49 +
    2.50 +\newcommand{\path}[1]{{\tt #1}}
    2.51 +
    2.52 +\part{Introduction and Tutorial}
    2.53 +\chapter{Introduction}
    2.54 +
    2.55 +Xen is a { \em paravirtualising } virtual machine monitor (VMM) or
    2.56 +``Hypervisor'' for the x86 processor architecture.  Xen can securely
    2.57 +multiplex heterogeneous virtual machines on a single physical with
    2.58 +near-native performance.  The virtual machine technology facilitates
    2.59 +enterprise-grade functionality, including:
    2.60 +
    2.61 +\begin{itemize}
    2.62 +\item Virtual machines with close to native performance.
    2.63 +\item Live migration of running virtual machines.
    2.64 +\item Excellent hardware support (use unmodified Linux device drivers).
    2.65 +\item Suspend to disk / resume from disk of running virtual machines.
    2.66 +\item Transparent copy on write disks.
    2.67 +\item Sandboxed, restartable device drivers.
    2.68 +\item Pervasive debugging - debug whole OSes, from kernel to applications.
    2.69 +\end{itemize}
    2.70 +
    2.71 +Xen support is available for increasingly many operating systems.  The
    2.72 +following OSs have either been ported already or a port is in
    2.73 +progress:
    2.74 +\begin{itemize}
    2.75 +\item Linux 2.4
    2.76 +\item Linux 2.6
    2.77 +\item FreeBSD 4.8
    2.78 +\item NetBSD 2.0
    2.79 +\item Plan 9
    2.80 +\end{itemize}
    2.81 +
    2.82 +Possible usage scenarios for Xen include:
    2.83 +\begin{description}
    2.84 +\item [Kernel development] test and debug kernel modifications in a
    2.85 +      sandboxed virtual machine --- no need for a separate test
    2.86 +      machine
    2.87 +\item [Multiple OS Configurations] run multiple operating systems
    2.88 +      simultaneously, for instance for compatibility or QA purposes
    2.89 +\item [Server consolidation] move multiple servers onto one box,
    2.90 +      provided performance and fault isolation at virtual machine
    2.91 +      boundaries
    2.92 +\item [Cluster computing] improve manageability and efficiency by
    2.93 +      running services in virtual machines, isolated from
    2.94 +      machine-specifics and load balance using live migration
    2.95 +\item [High availability computing] run device drivers in sandboxed
    2.96 +      domains for increased robustness
    2.97 +\end{description}
    2.98 +
    2.99 +\section{Structure}
   2.100 +
   2.101 +\subsection{High level}
   2.102 +
   2.103 +A Xen system has multiple layers.  The lowest layer is Xen itself ---
   2.104 +the most privileged piece of code in the system.  On top of Xen run
   2.105 +guest operating system kernels.  These are scheduled pre-emptively by
   2.106 +Xen.  On top of these run the applications of the guest OSs.  Guest
   2.107 +OSs are responsible for scheduling their own applications within the
   2.108 +time allotted to them by Xen.
   2.109 +
   2.110 +One of the domains --- { \em Domain 0 } --- is privileged.  It is
   2.111 +started by Xen at system boot and is responsible for initialising and
   2.112 +managing the whole machine.  Domain 0 builds other domains and manages
   2.113 +their virtual devices.  It also performs suspend, resume and
   2.114 +migration of other virtual machines.  Where it is used, the X server
   2.115 +is also run in domain 0.
   2.116 +
   2.117 +Within Domain 0, a process called ``Xend'' runs to manage the system.
   2.118 +Xend is responsible for managing virtual machines and providing access
   2.119 +to their consoles.  Commands are issued to Xend over an HTTP
   2.120 +interface, either from a command-line tool or from a web browser.
   2.121 +
   2.122 +XXX need diagram(s) here to make this make sense
   2.123 +
   2.124 +\subsection{Paravirtualisation}
   2.125 +
   2.126 +Paravirtualisation allows very high performance virtual machine
   2.127 +technology, even on architectures (like x86) which are traditionally
   2.128 +hard to virtualise.
   2.129 +
   2.130 +Paravirtualisation requires guest operating systems to be { \em ported
   2.131 +} to run on the VMM.  This process is similar to a port of an
   2.132 +operating system to a new hardware platform.  Although operating
   2.133 +system kernels must explicitly support Xen in order to run in a
   2.134 +virtual machine, { \em user space applications and libraries
   2.135 +do not require modification }.
   2.136 +
   2.137 +\subsection{History}
   2.138 +
   2.139 +The first public release of Xen (1.0) was made in October 2003.  Xen
   2.140 +was developed as a research project by the University of Cambridge
   2.141 +Computer Laboratory (UK).  Xen was the first Virtual Machine Monitor
   2.142 +to make use of {\em paravirtualisation} to achieve near-native
   2.143 +performance virtualisation of commodity operating systems.  Since
   2.144 +then, Xen has been extensively developed and is now used in production
   2.145 +scenarios on multiple sites.
   2.146 +
   2.147 +Xen 2.0 is the latest release, featuring greatly enhanced hardware
   2.148 +support, configuration flexibility, useability and a larger complement
   2.149 +of supported operating systems.
   2.150 +
   2.151 +\chapter{Installation}
   2.152 +
   2.153 +The Xen distribution includes three main components: Xen itself,
   2.154 +utilities to convert a standard Linux tree to run on Xen and the
   2.155 +userspace tools required to operate a Xen-based system.
   2.156 +
   2.157 +This manual describes how to install the Xen 2.0 distribution from
   2.158 +source.  Alternatively, there may be packages available for your
   2.159 +operating system distribution.
   2.160 +
   2.161 +Prerequisites:
   2.162 +\begin{itemize}
   2.163 +\item A working installation of your favourite Linux distribution.
   2.164 +\item A working installation of the GRUB bootloader.
   2.165 +\item An installation of Twisted v1.3 or above (see {\tt
   2.166 +http://www.twistedmatrix.com}.
   2.167 +\end{itemize}
   2.168 +
   2.169 +\section{Download the Xen source code}
   2.170 +
   2.171 +The public master BK repository for the 2.0 release lives at:
   2.172 +{\tt bk://xen.bkbits.net/xeno-unstable.bk}.
   2.173 +
   2.174 +To fetch a local copy, first download the BitKeeper tools at: {\tt
   2.175 +http://www.bitmover.com/download } with username 'bitkeeper' and
   2.176 +password 'get bitkeeper'.
   2.177 +
   2.178 +Then install the tools and then run:
   2.179 +\begin{verbatim}
   2.180 +# bk clone bk://xen.bkbits.net/xeno-unstable.bk
   2.181 +\end{verbatim}
   2.182 +
   2.183 +Under your current directory, a new directory named 'xeno-unstable.bk'
   2.184 +has been created, which contains all the necessary source code for the
   2.185 +Xen hypervisor and Linux guest OSes.
   2.186 +
   2.187 +To update to the newest changes to the repository, run
   2.188 +\begin{verbatim}
   2.189 +# cd xeno-unstable.bk # to change into the local repository
   2.190 +# bk pull             # to update the repository
   2.191 +\end{verbatim}
   2.192 +
   2.193 +\section{The distribution}
   2.194 +
   2.195 +The Xen source code repository is structured as follows:
   2.196 +
   2.197 +\begin{description}
   2.198 +\item[tools] Xen node controller daemon (Xend), command line tools, 
   2.199 +  control libraries
   2.200 +\item[xen] The Xen hypervisor itself.
   2.201 +\item[linux-2.4.26-xen] Linux 2.4 support for Xen
   2.202 +\item[linux-2.6.7-xen] Linux 2.6 support for Xen
   2.203 +\item[doc] various documentation files for users and developers
   2.204 +\item[extras] currently this contains the Mini OS, aimed at developers
   2.205 +\end{description}
   2.206 +
   2.207 +\section{Build and install}
   2.208 +
   2.209 +\begin{verbatim}
   2.210 +# make world
   2.211 +\end{verbatim}
   2.212 +
   2.213 +The Xen makefile includes a target ``world'' that will do the
   2.214 +following:
   2.215 +
   2.216 +\begin{itemize}
   2.217 +\item Build Xen
   2.218 +\item Build the control tools, including Xend
   2.219 +\item Download the ebtables patch
   2.220 +\item Download (if necessary) and unpack the Linux 2.4 source code,
   2.221 +      and patch it for use with Xen
   2.222 +\item Build a Linux kernel to use in domain 0 and a smaller
   2.223 +      unprivileged kernel, which can optionally be used for
   2.224 +      unprivileged virtual machines.
   2.225 +\end{itemize}
   2.226 +
   2.227 +The files produced are stored under the \path{install/} directory.  To
   2.228 +install them in their default locations, do:
   2.229 +
   2.230 +\begin{verbatim}
   2.231 +# make install
   2.232 +\end{verbatim}
   2.233 +
   2.234 +Alternatively, users with special installation requirements may wish
   2.235 +to install them manually by copying file to their appropriate
   2.236 +destinations.
   2.237 +
   2.238 +\section{Configuration}
   2.239 +
   2.240 +\subsection{\path{grub.conf}}
   2.241 +
   2.242 +An entry should be added to \path{grub.conf} (often found under
   2.243 +\path{/boot/grub.conf} or \path{/boot/grub/grub.conf}) to allow Xen /
   2.244 +XenLinux to boot.  The entry should look something like the following:
   2.245 +
   2.246 +\begin{verbatim}
   2.247 +title Xen 2.0 / XenoLinux 2.4.26
   2.248 +        kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
   2.249 +        module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
   2.250 +\end{verbatim}
   2.251 +
   2.252 +The first line of the configuration (kernel...) tells GRUB where to
   2.253 +find Xen itself and what boot parameters should be passed to it.  The
   2.254 +second line of the configuration describes the location of the
   2.255 +XenoLinux kernel that Xen should start and the parameters that should
   2.256 +be passed to it.
   2.257 +
   2.258 +\subsection{Serial Console}
   2.259 +
   2.260 +In order to configure serial console output, it is necessary to add a
   2.261 +line into \path{/etc/inittab}.  The XenLinux console driver is
   2.262 +designed to make this procedure the same as configuring a normal
   2.263 +serial console.  Add the line:
   2.264 +
   2.265 +{\tt c:2345:respawn:/sbin/mingetty ttyS0}
   2.266 +
   2.267 +\chapter{Starting a domain}
   2.268 +
   2.269 +The first step in creating a new domain is to prepare a root
   2.270 +filesystem for it to boot off.  Typically, this might be stored in a
   2.271 +normal partition, a disk file and LVM volume, or on an NFS server.
   2.272 +
   2.273 +A simple way to do this is simply to boot from your standard OS
   2.274 +install CD and install the distribution into another partition on your
   2.275 +hard drive.
   2.276 +
   2.277 +\section{From the web interface}
   2.278 +
   2.279 +\begin{itemize}
   2.280 +\item Boot the Xen machine and start Xend
   2.281 +\item Point your web browser at {\tt http://your\_machine:8080/}
   2.282 +\item XXX More explanation needed here...
   2.283 +\end{itemize}
   2.284 +
   2.285 +\section{From the command line}
   2.286 +
   2.287 +Full details of the {\tt xm} tool are found in Chapter~\ref{cha:xm}.
   2.288 +
   2.289 +This example explains how to use the \path{xmdefaults} file.  If you
   2.290 +require a more complex setup, you will want to write a custom
   2.291 +configuration file --- details of the configuration file formats are
   2.292 +included in Chapter~\ref{cha:config}.
   2.293 +
   2.294 +XXX More explanation needed here...
   2.295 +
   2.296 +\part{Quick Reference}
   2.297 +
   2.298 +\chapter{Domain Configuration Files}
   2.299 +\label{cha:config}
   2.300 +
   2.301 +XXX Could use a little explanation about possible values
   2.302 +
   2.303 +Xen configuration files contain the following standard variables:
   2.304 +
   2.305 +\begin{description}
   2.306 +\item[kernel] Path to the kernel image (on the server).
   2.307 +\item[ramdisk] Path to a ramdisk image (optional).
   2.308 +\item[builder] The name of the domain build function (e.g. {\tt'linux'} or {\tt'netbsd'}.
   2.309 +\item[memory] Memory size in megabytes.
   2.310 +\item[cpu] CPU to assign this domain to.
   2.311 +\item[nics] Number of virtual network interfaces.
   2.312 +\item[vif] List of MAC addresses (random addresses are assigned if not given).
   2.313 +\item[disk] Regions of disk to export to the domain.
   2.314 +\item[dhcp] Set to {\tt 'dhcp'} if you want to DHCP allocate the IP addres.
   2.315 +\item[netmask] IP netmask.
   2.316 +\item[gateway] IP address for the gateway (if any).
   2.317 +\item[hostname] Set the hostname for the virtual machine.
   2.318 +\item[root] Set the root device.
   2.319 +\item[nfs\_server] IP address for the NFS server.
   2.320 +\item[nfs\_root] Path of the root filesystem on the NFS server.
   2.321 +\item[extra] Extra string to append to the kernel command line.
   2.322 +\item[restart] Three possible options:
   2.323 +  \begin{description}
   2.324 +  \item[always] Always restart the domain, no matter what
   2.325 +                its exit code is.
   2.326 +  \item[never]  Never restart the domain.
   2.327 +  \item[onreboot] (restart the domain if it requests reboot).
   2.328 +  \end{description}
   2.329 +\end{description}
   2.330 +
   2.331 +It is also possible to include Python scripting commands in
   2.332 +configuration files.  This is done in the \path{xmdefaults} file in
   2.333 +order to handle the {\tt vmid} variable.
   2.334 +
   2.335 +\chapter{The xm tool}
   2.336 +\label{cha:xm}
   2.337 +
   2.338 +XXX Add description of arguments and switches for all the options
   2.339 +
   2.340 +The xm tool is the primary tool for managing Xen from the console.
   2.341 +The general format of an xm command line is:
   2.342 +
   2.343 +\begin{verbatim}
   2.344 +# xm command [switches] [arguments] [variables]
   2.345 +\end{verbatim}
   2.346 +
   2.347 +The available {\em switches } and {\em arguments}are dependent on the
   2.348 +{\em command} chosen.  The {\em variables} may be set using
   2.349 +declarations of the form {\tt variable=value} and may be used to set /
   2.350 +override any of the values in the configuration file being used,
   2.351 +including the standard variables described above and any custom
   2.352 +variables (for instance, the \path{xmdefaults} file uses a {\tt vmid}
   2.353 +variable).
   2.354 +
   2.355 +The available commands are as follows:
   2.356 +
   2.357 +\begin{description}
   2.358 +\item[create] Create a new domain.
   2.359 +\item[destroy] Kill a domain immediately.
   2.360 +\item[list] List running domains.
   2.361 +\item[shutdown] Ask a domain to shutdown.
   2.362 +\item[dmesg] Fetch the Xen (not Linux!) boot output.
   2.363 +\item[consoles] Lists the available consoles.
   2.364 +\item[console] Connect to the console for a domain.
   2.365 +\item[help] Get help on xm commands.
   2.366 +\item[save] Suspend a domain to disk.
   2.367 +\item[restore] Restore a domain from disk.
   2.368 +\item[pause] Pause a domain's execution.
   2.369 +\item[unpause] Unpause a domain.
   2.370 +\item[pincpu] Pin a domain to a CPU.
   2.371 +\item[bvt] Set BVT scheduler parameters for a domain.
   2.372 +\item[bvt\_ctxallow] Set the BVT context switching allowance for the system.
   2.373 +\item[fbvt] Set the FBVT scheduler parameters for a domain.
   2.374 +\item[fbvt\_ctxallow] Set the FBVT context switching allowance for the system.
   2.375 +\item[atropos] Set the atropos parameters for a domain.
   2.376 +\item[rrobin] Set the round robin time slice for the system.
   2.377 +\item[info] Get information about the Xen host.
   2.378 +\item[call] Call a Xend HTTP API function directly.
   2.379 +\end{description}
   2.380 +
   2.381 +\chapter{Glossary}
   2.382 +
   2.383 +XXX More to add here
   2.384 +
   2.385 +\begin{description}
   2.386 +\item[Atropos]             One of the CPU schedulers provided by Xen.
   2.387 +                           Atropos provides domains with absolute shares
   2.388 +			   of the CPU, with timeliness guarantees and a
   2.389 +			   mechanism for sharing out ``slack time''.
   2.390 +
   2.391 +\item[BVT]                 The BVT scheduler is used to give propotional
   2.392 +                           fair shares of the CPU to domains.
   2.393 +
   2.394 +\item[FBVT]                A derivative of the { \bf BVT } scheduler that
   2.395 +                           aims to give better fairness performance to IO
   2.396 +			   intensive domains in competition with CPU
   2.397 +			   intensive domains.
   2.398 +
   2.399 +\item[Domain]              A domain is the execution context that
   2.400 +                           contains a running { \bf virtual machine }.
   2.401 +			   The relationship between virtual machines
   2.402 +			   and domains on Xen is similar to that between
   2.403 +			   programs and processes in an operating
   2.404 +			   system: a virtual machine is a persistent
   2.405 +			   entity that resides on disk (somewhat like
   2.406 +			   a program).  When it is loaded for execution,
   2.407 +			   it runs in a domain.  Each domain has a
   2.408 +			   { \bf domain ID }.
   2.409 +
   2.410 +\item[Domain 0]            The first domain to be started on a Xen
   2.411 +                           machine.  Domain 0 is responsible for managing
   2.412 +			   the system.
   2.413 +
   2.414 +\item[Domain ID]           A unique identifier for a { \bf domain },
   2.415 +                           analagous to a process ID in an operating
   2.416 +			   system.  Apart from domain
   2.417 +
   2.418 +\item[Full virtualisation] An approach to virtualisation which
   2.419 +                           requires no modifications to the hosted
   2.420 +                           operating system, providing the illusion of
   2.421 +                           a complete system of real hardware devices.
   2.422 +
   2.423 +\item[Hypervisor]          An alternative term for { \bf VMM }, used
   2.424 +                           because it means ``beyond supervisor'',
   2.425 +			   since it is responsible for managing multiple
   2.426 +			   ``supervisor'' kernels.
   2.427 +
   2.428 +\item[NetBSD/Xen]          A port of NetBSD to the Xen architecture.
   2.429 +
   2.430 +\item[Paravirtualisation]  An approach to virtualisation which requires
   2.431 +                           modifications to the operating system in
   2.432 +                           order to run in a virtual machine.  Xen
   2.433 +                           uses paravirtualisation but preserves
   2.434 +                           binary compatibility for user space
   2.435 +                           applications.
   2.436 +
   2.437 +\item[Virtual Machine]     The environment in which a hosted operating
   2.438 +                           system runs, providing the abstraction of a
   2.439 +                           dedicated machine.  A virtual machine may
   2.440 +                           be identical to the underlying hardware (as
   2.441 +                           in { \bf full virtualisation }, or it may
   2.442 +                           differ, as in { \bf paravirtualisation }.
   2.443 +
   2.444 +\item[VMM]                 Virtual Machine Monitor - the software that
   2.445 +                           allows multiple virtual machines to be
   2.446 +			   multiplexed on a single physical machine.
   2.447 +
   2.448 +\item[Xen]                 Xen is a paravirtualising virtual machine
   2.449 +                           monitor, developed primarily by the
   2.450 +			   Systems Research Group at the University
   2.451 +			   of Cambridge Computer Laboratory.
   2.452 +
   2.453 +\item[XenLinux]            Official name for the port of the Linux kernel
   2.454 +                           that runs on Xen.
   2.455 +
   2.456 +\end{description}
   2.457 +
   2.458 +\part{Advanced Topics}
   2.459 +
   2.460 +XXX More to add here, including config file format
   2.461 +
   2.462 +\chapter{Advanced Network Configuration}
   2.463 +
   2.464 +For simple systems with a single ethernet interface with a simple
   2.465 +configuration, the default installation should work ``out of the
   2.466 +box''.  More complicated network setups, for instance with multiple
   2.467 +ethernet interfaces and / or existing bridging setups will require
   2.468 +some special configuration.
   2.469 +
   2.470 +The purpose of this chapter is to describe the mechanisms provided by
   2.471 +xend to allow a flexible configuration for Xen's virtual networking.
   2.472 +
   2.473 +\section{Xen networking scripts}
   2.474 +
   2.475 +Xen's virtual networking is configured by 3 shell scripts.  These are
   2.476 +called automatically by Xend when certain events occur, with arguments
   2.477 +to the scripts providing further contextual information.  These
   2.478 +scripts are found by default in \path{/etc/xen}.  The names and
   2.479 +locations of the scripts can be configured in \path{xend-config.sxp}.
   2.480 +
   2.481 +\subsection{\path{network}}
   2.482 +
   2.483 +This script is called once when Xend is started and once when Xend is
   2.484 +stopped.  Its job is to do any advance preparation required for the
   2.485 +Xen virtual network when Xend starts and to do any corresponding
   2.486 +cleanup when Xend exits.
   2.487 +
   2.488 +In the default configuration, this script creates the bridge
   2.489 +``xen-br0'' and moves eth0 onto that bridge, modifying the routing
   2.490 +accordingly.
   2.491 +
   2.492 +In configurations where the bridge already exists, this script could
   2.493 +be replaced with a link to \path{/bin/true} (for instance).
   2.494 +
   2.495 +When Xend exits, this script is called with the {\tt stop} argument,
   2.496 +which causes it to delete the Xen bridge and remove {\tt eth0} from
   2.497 +it, restoring the normal IP and routing configuration.
   2.498 +
   2.499 +\subsection{\path{vif-bridge}}
   2.500 +
   2.501 +This script is called for every domain virtual interface.  This should
   2.502 +do things like configuring firewalling rules for that interface and
   2.503 +adding it to the appropriate bridge.
   2.504 +
   2.505 +By default, this adds and removes VIFs on the default Xen bridge.
   2.506 +This script can be customized to properly deal with more complicated
   2.507 +bridging setups.
   2.508 +
   2.509 +\chapter{Advanced Scheduling Configuration}
   2.510 +
   2.511 +\section{Scheduler selection}
   2.512 +
   2.513 +Xen offers a boot time choice between multiple schedulers.  To select
   2.514 +a scheduler, pass the boot parameter { \tt sched=sched\_name } to Xen,
   2.515 +substituting the apropriate scheduler name.  Details of the schedulers
   2.516 +and their parameters are included below; future verions of the tools
   2.517 +will provide a higher-level interface to these tools.
   2.518 +
   2.519 +\section{Borrowed Virtual Time}
   2.520 +
   2.521 +BVT provides proportional fair shares of the CPU time.  It has been
   2.522 +observed to penalise domains that block frequently (e.g. IO intensive
   2.523 +domains), so the FBVT derivative has been included as an alternative.
   2.524 +
   2.525 +\subsection{Global Parameters}
   2.526 +
   2.527 +\begin{description}
   2.528 +\item[ctx\_allow]
   2.529 +  the context switch allowance is similar to the "quantum"
   2.530 +  in traditional schedulers.  It is the minimum time that
   2.531 +  a scheduled domain will be allowed to run before be
   2.532 +  pre-empted.  This prevents thrashing of the CPU.
   2.533 +\end{description}
   2.534 +
   2.535 +\subsection{Per-domain parameters}
   2.536 +
   2.537 +\begin{description}
   2.538 +\item[mcuadv]
   2.539 +  the MCU (Minimum Charging Unit) advance determines the
   2.540 +  proportional share of the CPU that a domain receives.  It
   2.541 +  is set inversely proportionally to a domain's sharing weight.
   2.542 +\item[warp]
   2.543 +  the amount of "virtual time" the domain is allowed to warp
   2.544 +  backwards
   2.545 +\item[warpl]
   2.546 +  the warp limit is the maximum time a domain can run warped for
   2.547 +\item[warpu]
   2.548 +  the unwarp requirement is the minimum time a domain must
   2.549 +  run unwarped for before it can warp again
   2.550 +\end{description}
   2.551 +
   2.552 +\section{Fair Borrowed Virtual Time}
   2.553 +
   2.554 +This is a derivative for BVT that aims to provide better fairness for
   2.555 +IO intensive domains as well as for CPU intensive domains.
   2.556 +
   2.557 +\subsection{Global Parameters}
   2.558 +
   2.559 +Same as for BVT.
   2.560 +
   2.561 +\subsection{Per-domain parameters}
   2.562 +
   2.563 +Same as for BVT.
   2.564 +
   2.565 +\section{Atropos}
   2.566 +
   2.567 +Atropos is a Soft Real Time scheduler.  It provides guarantees about
   2.568 +absolute shares of the CPU (with a method for optionally sharing out
   2.569 +slack CPU time on a best-effort basis) and can provide timeliness
   2.570 +guarantees for latency-sensitive domains.
   2.571 +
   2.572 +\subsection{Per-domain parameters}
   2.573 +
   2.574 +\begin{description}
   2.575 +\item[slice]
   2.576 +  The length of time per period that a domain is guaranteed.
   2.577 +\item[period]
   2.578 +  The period over which a domain is guaranteed to receive
   2.579 +  its slice of CPU time.
   2.580 +\item[latency]
   2.581 +  The latency hint is used to control how soon after
   2.582 +  waking up a domain should be scheduled.
   2.583 +\item[xtratime]
   2.584 +  This is a true (1) / false (0) flag that specifies whether
   2.585 +  a domain should be allowed a share of the system slack time.
   2.586 +\end{description}
   2.587 +
   2.588 +\section{Round Robin}
   2.589 +
   2.590 +The Round Robin scheduler is included as a simple demonstration of
   2.591 +Xen's internal scheduler API.  It is not intended for production use
   2.592 +--- the other schedulers included are all more general and should give
   2.593 +higher throughput.
   2.594 +
   2.595 +\subsection{Global parameters}
   2.596 +
   2.597 +\begin{description}
   2.598 +\item[rr\_slice]
   2.599 +  The maximum time each domain runs before the next
   2.600 +  scheduling decision is made.
   2.601 +\end{description}
   2.602 +
   2.603 +\chapter{Privileged domains}
   2.604 +
   2.605 +There are two possible types of privileges: IO privileges and
   2.606 +administration privileges.
   2.607 +
   2.608 +\section{Driver domains (IO Privileges)}
   2.609 +
   2.610 +IO privileges can be assigned to allow a domain to drive PCI devices
   2.611 +itself.  This is used for to support driver domains.
   2.612 +
   2.613 +\section{Administration Domains}
   2.614 +
   2.615 +Administration privileges allow a domain to use the ``dom0
   2.616 +operations'' (so called because they are usually available only to
   2.617 +domain 0).  A privileged domain can build other domains, set scheduling
   2.618 +parameters, etc.
   2.619 +
   2.620 +% Support for other administrative domains is not yet available...
   2.621 +
   2.622 +\chapter{Xen build options}
   2.623 +
   2.624 +For most users, the default build of Xen will be adequate.  For some
   2.625 +advanced uses, Xen provides a number of build-time options:
   2.626 +
   2.627 +At build time, these options should be set as environment variables or
   2.628 +passed on make's command-line.  For example:
   2.629 +
   2.630 +\begin{verbatim}
   2.631 +export option=y; make
   2.632 +option=y make
   2.633 +make option1=y option2=y
   2.634 +\end{verbatim}
   2.635 +
   2.636 +\section{List of options}
   2.637 +
   2.638 +{\bf debug=y }\\
   2.639 +Enable debug assertions and console output.
   2.640 +(Primarily useful for tracing bugs in Xen).        \\
   2.641 +{\bf debugger=y }\\
   2.642 +Enable the in-Xen pervasive debugger (PDB).
   2.643 +This can be used to debug Xen, guest OSes, and
   2.644 +applications. For more information see the 
   2.645 +XenDebugger-HOWTO.                                 \\
   2.646 +{\bf perfc=y }\\
   2.647 +Enable performance-counters for significant events
   2.648 +within Xen. The counts can be reset or displayed
   2.649 +on Xen's console via console control keys.          \\
   2.650 +{\bf trace=y }\\
   2.651 +Enable per-cpu trace buffers which log a range of
   2.652 +events within Xen for collection by control
   2.653 +software.  For more information see the chapter on debugging,
   2.654 +in the Xen Interface Manual.
   2.655 +
   2.656 +\chapter{Xen boot options}
   2.657 +
   2.658 +These options are used to configure Xen's behaviour at runtime.  They
   2.659 +should be appended to Xen's command line, either manually or by
   2.660 +editting \path{grub.conf}.
   2.661 +
   2.662 +\section{List of options}
   2.663 +
   2.664 +{\bf ignorebiostables }\\
   2.665 + Disable parsing of BIOS-supplied tables. This may help with some
   2.666 + chipsets that aren't fully supported by Xen. If you specify this
   2.667 + option then ACPI tables are also ignored, and SMP support is
   2.668 + disabled. \\
   2.669 +
   2.670 +{\bf noreboot } \\
   2.671 + Don't reboot the machine automatically on errors.  This is
   2.672 + useful to catch debug output if you aren't catching console messages
   2.673 + via the serial line. \\
   2.674 +
   2.675 +{\bf nosmp } \\
   2.676 + Disable SMP support.
   2.677 + This option is implied by 'ignorebiostables'. \\
   2.678 +
   2.679 +{\bf noacpi } \\
   2.680 + Disable ACPI tables, which confuse Xen on some chipsets.
   2.681 + This option is implied by 'ignorebiostables'. \\
   2.682 +
   2.683 +{\bf watchdog } \\
   2.684 + Enable NMI watchdog which can report certain failures. \\
   2.685 +
   2.686 +{\bf noht } \\
   2.687 + Disable Hyperthreading. \\
   2.688 +
   2.689 +{\bf ifname=ethXX }\\ 
   2.690 + Select which Ethernet interface to use. \\
   2.691 +
   2.692 +{\bf ifname=dummy } \\
   2.693 + Don't use any network interface. \\
   2.694 +
   2.695 +{\bf com1=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] \\
   2.696 + com2=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] } \\
   2.697 + Xen supports up to two 16550-compatible serial ports.
   2.698 + For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
   2.699 + 9600-baud port, 8 data bits, no parity, 1 stop bit,
   2.700 + I/O port base 0x408, IRQ 5.
   2.701 + If the I/O base and IRQ are standard (com1:0x3f8,4;
   2.702 + com2:0x2f8,3) then they need not be specified. \\
   2.703 +
   2.704 +{\bf console=$<$specifier list$>$ } \\
   2.705 + Specify the destination for Xen console I/O.
   2.706 + This is a comma-separated list of, for example:
   2.707 +\begin{description}
   2.708 + \item[vga]  use VGA console and allow keyboard input
   2.709 + \item[com1] use serial port com1
   2.710 + \item[com2H] use serial port com2. Transmitted chars will
   2.711 +   have the MSB set. Received chars must have
   2.712 +   MSB set.
   2.713 + \item[com2L] use serial port com2. Transmitted chars will
   2.714 +   have the MSB cleared. Received chars must
   2.715 +   have MSB cleared.
   2.716 +\end{description}
   2.717 + The latter two examples allow a single port to be
   2.718 + shared by two subsystems (eg. console and
   2.719 + debugger). Sharing is controlled by MSB of each
   2.720 + transmitted/received character.
   2.721 + [NB. Default for this option is 'com1,tty'] \\
   2.722 +
   2.723 +{\bf conswitch=$<$switch-char$><$auto-switch-char$>$ } \\
   2.724 + Specify how to switch serial-console input between
   2.725 + Xen and DOM0. The required sequence is CTRL-<switch-char>
   2.726 + pressed three times. Specifying '`' disables switching.
   2.727 + The <auto-switch-char> specifies whether Xen should
   2.728 + auto-switch input to DOM0 when it boots -- if it is 'x'
   2.729 + then auto-switching is disabled. Any other value, or
   2.730 + omitting the character, enables auto-switching.
   2.731 + [NB. Default for this option is 'a'] \\
   2.732 +
   2.733 +{\bf dom0\_mem=xxx } \\
   2.734 + Set the maximum amount of memory for domain0. \\
   2.735 +
   2.736 +{\bf tbuf\_size=xxx } \\
   2.737 + Set the size of the per-cpu trace buffers, in pages
   2.738 + (default 1).  Note that the trace buffers are only
   2.739 + enabled in debug builds.  Most users can ignore
   2.740 + this feature completely. \\
   2.741 +
   2.742 +{\bf sched=xxx } \\
   2.743 + Select the CPU scheduler Xen should use.  The current
   2.744 + possibilities are 'bvt', 'atropos' and 'rrobin'.  The
   2.745 + default is 'bvt'.  For more information see
   2.746 + Sched-HOWTO.txt. \\
   2.747 +
   2.748 +{\bf pci\_dom0\_hide=(xx.xx.x)(yy.yy.y)... } \\
   2.749 +Hide selected PCI devices from domain 0 (for instance, to stop it
   2.750 +taking ownership of them so that they can be driven by another
   2.751 +domain).  Device IDs should be given in hex format.  Bridge devices do
   2.752 +not need to be hidden --- they are hidden implicitly, since guest OSes
   2.753 +do not need to configure them.
   2.754 +
   2.755 +\end{document}