xen/docs/user.tex

\documentclass[11pt,twoside,final,openright]{xenstyle}
\usepackage{a4,graphicx,setspace}
\setstretch{1.15}
\input{style.tex}

\begin{document}

% TITLE PAGE
\pagestyle{empty}
\begin{center}
\vspace*{\fill}
\includegraphics{eps/xenlogo.eps}
\vfill
\vfill
\vfill
\begin{tabular}{l}
{\Huge \bf Users' manual} \\[4mm]
{\huge Xen v2.0 for x86} \\[80mm]

{\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm]
{\Large University of Cambridge, UK} \\[20mm]
{\large Last updated on 11th March, 2004}
\end{tabular}
\vfill
\end{center}
\cleardoublepage

% TABLE OF CONTENTS
\pagestyle{plain}
\pagenumbering{roman}
{ \parskip 0pt plus 1pt
  \tableofcontents }
\cleardoublepage

% PREPARE FOR MAIN TEXT
\pagenumbering{arabic}
\raggedbottom
\widowpenalty=10000
\clubpenalty=10000
\parindent=0pt
\renewcommand{\topfraction}{.8}
\renewcommand{\bottomfraction}{.8}
\renewcommand{\textfraction}{.2}
\renewcommand{\floatpagefraction}{.8}
\setstretch{1.15}

\newcommand{\path}[1]{{\tt #1}}

\part{Introduction and Tutorial}
\chapter{Introduction}

{\bf
DISCLAIMER: This documentation is currently under active development
and as such there may be mistakes and omissions --- watch out for
these and please report any you find to the developer's mailing list.
Contributions of material, suggestions and corrections are welcome.
}

Xen is a { \em paravirtualising } virtual machine monitor (VMM) or
``Hypervisor'' for the x86 processor architecture.  Xen can securely
multiplex heterogeneous virtual machines on a single physical with
near-native performance.  The virtual machine technology facilitates
enterprise-grade functionality, including:

\begin{itemize}
\item Virtual machines with close to native performance.
\item Live migration of running virtual machines.
\item Excellent hardware support (use unmodified Linux device drivers).
\item Suspend to disk / resume from disk of running virtual machines.
\item Transparent copy on write disks.
\item Sandboxed, restartable device drivers.
\item Pervasive debugging - debug whole OSes, from kernel to applications.
\end{itemize}

Xen support is available for increasingly many operating systems.  The
following OSs have either been ported already or a port is in
progress:
\begin{itemize}
\item Linux 2.4
\item Linux 2.6
\item FreeBSD 4.8
\item NetBSD 2.0
\item Plan 9
\end{itemize}

Possible usage scenarios for Xen include:
\begin{description}
\item [Kernel development] test and debug kernel modifications in a
      sandboxed virtual machine --- no need for a separate test
      machine
\item [Multiple OS Configurations] run multiple operating systems
      simultaneously, for instance for compatibility or QA purposes
\item [Server consolidation] move multiple servers onto one box,
      provided performance and fault isolation at virtual machine
      boundaries
\item [Cluster computing] improve manageability and efficiency by
      running services in virtual machines, isolated from
      machine-specifics and load balance using live migration
\item [High availability computing] run device drivers in sandboxed
      domains for increased robustness
\end{description}

\section{Structure}

\subsection{High level}

A Xen system has multiple layers.  The lowest layer is Xen itself ---
the most privileged piece of code in the system.  On top of Xen run
guest operating system kernels.  These are scheduled pre-emptively by
Xen.  On top of these run the applications of the guest OSs.  Guest
OSs are responsible for scheduling their own applications within the
time allotted to them by Xen.

One of the domains --- { \em Domain 0 } --- is privileged.  It is
started by Xen at system boot and is responsible for initialising and
managing the whole machine.  Domain 0 builds other domains and manages
their virtual devices.  It also performs suspend, resume and
migration of other virtual machines.  Where it is used, the X server
is also run in domain 0.

Within Domain 0, a process called ``Xend'' runs to manage the system.
Xend is responsible for managing virtual machines and providing access
to their consoles.  Commands are issued to Xend over an HTTP
interface, either from a command-line tool or from a web browser.

XXX need diagram(s) here to make this make sense

\subsection{Paravirtualisation}

Paravirtualisation allows very high performance virtual machine
technology, even on architectures (like x86) which are traditionally
hard to virtualise.

Paravirtualisation requires guest operating systems to be { \em ported
} to run on the VMM.  This process is similar to a port of an
operating system to a new hardware platform.  Although operating
system kernels must explicitly support Xen in order to run in a
virtual machine, { \em user space applications and libraries
do not require modification }.

\subsection{History}

The first public release of Xen (1.0) was made in October 2003.  Xen
was developed as a research project by the University of Cambridge
Computer Laboratory (UK).  Xen was the first Virtual Machine Monitor
to make use of {\em paravirtualisation} to achieve near-native
performance virtualisation of commodity operating systems.  Since
then, Xen has been extensively developed and is now used in production
scenarios on multiple sites.

Xen 2.0 is the latest release, featuring greatly enhanced hardware
support, configuration flexibility, useability and a larger complement
of supported operating systems.

\chapter{Installation}

The Xen distribution includes three main components: Xen itself,
utilities to convert a standard Linux tree to run on Xen and the
userspace tools required to operate a Xen-based system.

This manual describes how to install the Xen 2.0 distribution from
source.  Alternatively, there may be packages available for your
operating system distribution.

Prerequisites:
\begin{itemize}
\item A working installation of your favourite Linux distribution.
\item A working installation of the GRUB bootloader.
\item An installation of Twisted v1.3 or above (see {\tt
http://www.twistedmatrix.com}.  There may be a package available for
your distribution; alternatively it can be installed by running {\tt \#
make install-twisted} in the root of the Xen source tree.
\item The Linux bridge control tools (see {\tt
http://bridge.sourceforge.net }).  There may be a packages of these
tools available for your distribution.
\end{itemize}

Optional:
\begin{itemize}
\item The Python logging package (see {\tt http://www.red-dove.com/})
for additional Xend logging functionality.
\end{itemize}

\section{Download the Xen source code}

The public master BK repository for the 2.0 release lives at:
{\tt bk://xen.bkbits.net/xeno-unstable.bk}.

To fetch a local copy, first download the BitKeeper tools at: {\tt
http://www.bitmover.com/download } with username 'bitkeeper' and
password 'get bitkeeper'.

Then install the tools and then run:
\begin{verbatim}
# bk clone bk://xen.bkbits.net/xeno-unstable.bk
\end{verbatim}

Under your current directory, a new directory named 'xeno-unstable.bk'
has been created, which contains all the necessary source code for the
Xen hypervisor and Linux guest OSes.

To update to the newest changes to the repository, run
\begin{verbatim}
# cd xeno-unstable.bk # to change into the local repository
# bk pull             # to update the repository
\end{verbatim}

\section{The distribution}

The Xen source code repository is structured as follows:

\begin{description}
\item[\path{tools/}] Xen node controller daemon (Xend), command line tools, 
  control libraries
\item[\path{xen/}] The Xen hypervisor itself.
\item[\path{linux-2.4.26-xen}] Linux 2.4 support for Xen
\item[\path{linux-2.6.7-xen}] Linux 2.6 support for Xen
\item[\path{doc}] various documentation files for users and developers
\item[\path{extras}] currently this contains the Mini OS, aimed at developers
\end{description}

\section{Build and install}

The Xen makefile includes a target ``world'' that will do the
following:

\begin{itemize}
\item Build Xen
\item Build the control tools, including Xend
\item Download the ebtables patch
\item Download (if necessary) and unpack the Linux 2.4 source code,
      and patch it for use with Xen
\item Build a Linux kernel to use in domain 0 and a smaller
      unprivileged kernel, which can optionally be used for
      unprivileged virtual machines.
\end{itemize}

\begin{verbatim}
# make world
\end{verbatim}

To build the unprivileged port of Linux 2.6, do:
\begin{verbatim}
# make linux26
\end{verbatim}

The files produced by the build process are stored under the
\path{install/} directory.  To install them in their default
locations, do:

\begin{verbatim}
# make install
\end{verbatim}

Alternatively, users with special installation requirements may wish
to install them manually by copying file to their appropriate
destinations.

\section{Configuration}

\subsection{\path{grub.conf}}

An entry should be added to \path{grub.conf} (often found under
\path{/boot/grub.conf} or \path{/boot/grub/grub.conf}) to allow Xen /
XenLinux to boot.  The entry should look something like the following:

\begin{verbatim}
title Xen 2.0 / XenoLinux 2.4.26
        kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
        module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
\end{verbatim}

The first line of the configuration (kernel...) tells GRUB where to
find Xen itself and what boot parameters should be passed to it.  The
second line of the configuration describes the location of the
XenoLinux kernel that Xen should start and the parameters that should
be passed to it.

\subsection{Serial Console}

In order to configure serial console output, it is necessary to add a
line into \path{/etc/inittab}.  The XenLinux console driver is
designed to make this procedure the same as configuring a normal
serial console.  Add the line:

{\tt c:2345:respawn:/sbin/mingetty ttyS0}

\chapter{Starting a domain}

The first step in creating a new domain is to prepare a root
filesystem for it to boot off.  Typically, this might be stored in a
normal partition, a disk file and LVM volume, or on an NFS server.

A simple way to do this is simply to boot from your standard OS
install CD and install the distribution into another partition on your
hard drive.

\section{From the web interface}

\begin{itemize}
\item Boot the Xen machine and start Xend
\item Point your web browser at {\tt http://your\_machine:8080/}
\item XXX More explanation needed here...
\end{itemize}

\section{From the command line}

Full details of the {\tt xm} tool are found in Chapter~\ref{cha:xm}.

This example explains how to use the \path{xmdefaults} file.  If you
require a more complex setup, you will want to write a custom
configuration file --- details of the configuration file formats are
included in Chapter~\ref{cha:config}.

The \path{xmdefaults} file is a template description that is intended
to be reused for multiple virtual machines.  Setting the value of the
{\tt vmid} variable fills in parts of this template.

\subsection{Editing \path{xmdefaults}}

At minimum, you should edit the following variables in \path{xmdefaults}:

\begin{description}
\item[kernel] Set this to the path of the kernel you compiled for use
              with Xen. [e.g. {\tt kernel =
              '/root/xeno-unstable.bk/install/boot/vmlinuz-2.4.26-xenU'}]
\item[memory] Set this to the size of the domain's memory in
megabytes. [e.g. {\tt memory = 64 } ]
\item[disk] Set the first entry in this list to calculate the offset
of the domain's root partition, based on the domain ID.  Set the
second to the location of \path{/usr} (if you are sharing it between
domains). [i.e. {\tt disk = ['phy:your\_hard\_drive\%d,sda1,w' \%
(base\_partition\_number + vmid), 'phy:your\_usr\_partition,sda6,r' ]}
\item[dhcp] Uncomment the dhcp variable, so that the domain will
receive its IP address from a DHCP server. [i.e. {\tt dhcp=''dhcp''}]
\end{description}

\subsection{Starting the domain}

The {\tt xm} tool provides a variety of commands for managing domains.
Use the {\tt create} command to start new domains.  To start the
virtual machine with virtual machine ID 1.

\begin{verbatim}
# xm create -c vmid=1
\end{verbatim}

The {\tt -c} switch causes {\tt xm} to turn into the domain's console
after creation.  The {\tt vmid=1} sets the {\tt vmid} variable used in
the {\tt xmdefaults} file.  The tool uses the
\path{/etc/xen/xmdefaults} file, since no custom configuration file
was specified on the command line.

 XXX More explanation needed here...

\part{Quick Reference}

\chapter{Domain Configuration Files}
\label{cha:config}

XXX Could use a little explanation about possible values

Xen configuration files contain the following standard variables:

\begin{description}
\item[kernel] Path to the kernel image (on the server).
\item[ramdisk] Path to a ramdisk image (optional).
\item[builder] The name of the domain build function (e.g. {\tt'linux'} or {\tt'netbsd'}.
\item[memory] Memory size in megabytes.
\item[cpu] CPU to assign this domain to.
\item[nics] Number of virtual network interfaces.
\item[vif] List of MAC addresses (random addresses are assigned if not given).
\item[disk] Regions of disk to export to the domain.
\item[dhcp] Set to {\tt 'dhcp'} if you want to DHCP allocate the IP addres.
\item[netmask] IP netmask.
\item[gateway] IP address for the gateway (if any).
\item[hostname] Set the hostname for the virtual machine.
\item[root] Set the root device.
\item[nfs\_server] IP address for the NFS server.
\item[nfs\_root] Path of the root filesystem on the NFS server.
\item[extra] Extra string to append to the kernel command line.
\item[restart] Three possible options:
  \begin{description}
  \item[always] Always restart the domain, no matter what
                its exit code is.
  \item[never]  Never restart the domain.
  \item[onreboot] (restart the domain if it requests reboot).
  \end{description}
\end{description}

It is also possible to include Python scripting commands in
configuration files.  This is done in the \path{xmdefaults} file in
order to handle the {\tt vmid} variable.

\chapter{The xm tool}
\label{cha:xm}

XXX Add description of arguments and switches for all the options

The xm tool is the primary tool for managing Xen from the console.
The general format of an xm command line is:

\begin{verbatim}
# xm command [switches] [arguments] [variables]
\end{verbatim}

The available {\em switches } and {\em arguments}are dependent on the
{\em command} chosen.  The {\em variables} may be set using
declarations of the form {\tt variable=value} and may be used to set /
override any of the values in the configuration file being used,
including the standard variables described above and any custom
variables (for instance, the \path{xmdefaults} file uses a {\tt vmid}
variable).

The available commands are as follows:

\begin{description}
\item[create] Create a new domain.
\item[destroy] Kill a domain immediately.
\item[list] List running domains.
\item[shutdown] Ask a domain to shutdown.
\item[dmesg] Fetch the Xen (not Linux!) boot output.
\item[consoles] Lists the available consoles.
\item[console] Connect to the console for a domain.
\item[help] Get help on xm commands.
\item[save] Suspend a domain to disk.
\item[restore] Restore a domain from disk.
\item[pause] Pause a domain's execution.
\item[unpause] Unpause a domain.
\item[pincpu] Pin a domain to a CPU.
\item[bvt] Set BVT scheduler parameters for a domain.
\item[bvt\_ctxallow] Set the BVT context switching allowance for the system.
\item[fbvt] Set the FBVT scheduler parameters for a domain.
\item[fbvt\_ctxallow] Set the FBVT context switching allowance for the system.
\item[atropos] Set the atropos parameters for a domain.
\item[rrobin] Set the round robin time slice for the system.
\item[info] Get information about the Xen host.
\item[call] Call a Xend HTTP API function directly.
\end{description}

\chapter{Glossary}

XXX More to add here

\begin{description}
\item[Atropos]             One of the CPU schedulers provided by Xen.
                           Atropos provides domains with absolute shares
			   of the CPU, with timeliness guarantees and a
			   mechanism for sharing out ``slack time''.

\item[BVT]                 The BVT scheduler is used to give propotional
                           fair shares of the CPU to domains.

\item[FBVT]                A derivative of the { \bf BVT } scheduler that
                           aims to give better fairness performance to IO
			   intensive domains in competition with CPU
			   intensive domains.

\item[Domain]              A domain is the execution context that
                           contains a running { \bf virtual machine }.
			   The relationship between virtual machines
			   and domains on Xen is similar to that between
			   programs and processes in an operating
			   system: a virtual machine is a persistent
			   entity that resides on disk (somewhat like
			   a program).  When it is loaded for execution,
			   it runs in a domain.  Each domain has a
			   { \bf domain ID }.

\item[Domain 0]            The first domain to be started on a Xen
                           machine.  Domain 0 is responsible for managing
			   the system.

\item[Domain ID]           A unique identifier for a { \bf domain },
                           analagous to a process ID in an operating
			   system.  Apart from domain

\item[Full virtualisation] An approach to virtualisation which
                           requires no modifications to the hosted
                           operating system, providing the illusion of
                           a complete system of real hardware devices.

\item[Hypervisor]          An alternative term for { \bf VMM }, used
                           because it means ``beyond supervisor'',
			   since it is responsible for managing multiple
			   ``supervisor'' kernels.

\item[NetBSD/Xen]          A port of NetBSD to the Xen architecture.

\item[Paravirtualisation]  An approach to virtualisation which requires
                           modifications to the operating system in
                           order to run in a virtual machine.  Xen
                           uses paravirtualisation but preserves
                           binary compatibility for user space
                           applications.

\item[Virtual Machine]     The environment in which a hosted operating
                           system runs, providing the abstraction of a
                           dedicated machine.  A virtual machine may
                           be identical to the underlying hardware (as
                           in { \bf full virtualisation }, or it may
                           differ, as in { \bf paravirtualisation }.

\item[VMM]                 Virtual Machine Monitor - the software that
                           allows multiple virtual machines to be
			   multiplexed on a single physical machine.

\item[Xen]                 Xen is a paravirtualising virtual machine
                           monitor, developed primarily by the
			   Systems Research Group at the University
			   of Cambridge Computer Laboratory.

\item[XenLinux]            Official name for the port of the Linux kernel
                           that runs on Xen.

\end{description}

\part{Advanced Topics}

XXX More to add here, including config file format

\chapter{Advanced Network Configuration}

For simple systems with a single ethernet interface with a simple
configuration, the default installation should work ``out of the
box''.  More complicated network setups, for instance with multiple
ethernet interfaces and / or existing bridging setups will require
some special configuration.

The purpose of this chapter is to describe the mechanisms provided by
xend to allow a flexible configuration for Xen's virtual networking.

\section{Xen networking scripts}

Xen's virtual networking is configured by 3 shell scripts.  These are
called automatically by Xend when certain events occur, with arguments
to the scripts providing further contextual information.  These
scripts are found by default in \path{/etc/xen}.  The names and
locations of the scripts can be configured in \path{xend-config.sxp}.

\subsection{\path{network}}

This script is called once when Xend is started and once when Xend is
stopped.  Its job is to do any advance preparation required for the
Xen virtual network when Xend starts and to do any corresponding
cleanup when Xend exits.

In the default configuration, this script creates the bridge
``xen-br0'' and moves eth0 onto that bridge, modifying the routing
accordingly.

In configurations where the bridge already exists, this script could
be replaced with a link to \path{/bin/true} (for instance).

When Xend exits, this script is called with the {\tt stop} argument,
which causes it to delete the Xen bridge and remove {\tt eth0} from
it, restoring the normal IP and routing configuration.

\subsection{\path{vif-bridge}}

This script is called for every domain virtual interface.  This should
do things like configuring firewalling rules for that interface and
adding it to the appropriate bridge.

By default, this adds and removes VIFs on the default Xen bridge.
This script can be customized to properly deal with more complicated
bridging setups.

\chapter{Advanced Scheduling Configuration}

\section{Scheduler selection}

Xen offers a boot time choice between multiple schedulers.  To select
a scheduler, pass the boot parameter { \tt sched=sched\_name } to Xen,
substituting the apropriate scheduler name.  Details of the schedulers
and their parameters are included below; future verions of the tools
will provide a higher-level interface to these tools.

\section{Borrowed Virtual Time}

BVT provides proportional fair shares of the CPU time.  It has been
observed to penalise domains that block frequently (e.g. IO intensive
domains), so the FBVT derivative has been included as an alternative.

\subsection{Global Parameters}

\begin{description}
\item[ctx\_allow]
  the context switch allowance is similar to the "quantum"
  in traditional schedulers.  It is the minimum time that
  a scheduled domain will be allowed to run before be
  pre-empted.  This prevents thrashing of the CPU.
\end{description}

\subsection{Per-domain parameters}

\begin{description}
\item[mcuadv]
  the MCU (Minimum Charging Unit) advance determines the
  proportional share of the CPU that a domain receives.  It
  is set inversely proportionally to a domain's sharing weight.
\item[warp]
  the amount of "virtual time" the domain is allowed to warp
  backwards
\item[warpl]
  the warp limit is the maximum time a domain can run warped for
\item[warpu]
  the unwarp requirement is the minimum time a domain must
  run unwarped for before it can warp again
\end{description}

\section{Fair Borrowed Virtual Time}

This is a derivative for BVT that aims to provide better fairness for
IO intensive domains as well as for CPU intensive domains.

\subsection{Global Parameters}

Same as for BVT.

\subsection{Per-domain parameters}

Same as for BVT.

\section{Atropos}

Atropos is a Soft Real Time scheduler.  It provides guarantees about
absolute shares of the CPU (with a method for optionally sharing out
slack CPU time on a best-effort basis) and can provide timeliness
guarantees for latency-sensitive domains.

\subsection{Per-domain parameters}

\begin{description}
\item[slice]
  The length of time per period that a domain is guaranteed.
\item[period]
  The period over which a domain is guaranteed to receive
  its slice of CPU time.
\item[latency]
  The latency hint is used to control how soon after
  waking up a domain should be scheduled.
\item[xtratime]
  This is a true (1) / false (0) flag that specifies whether
  a domain should be allowed a share of the system slack time.
\end{description}

\section{Round Robin}

The Round Robin scheduler is included as a simple demonstration of
Xen's internal scheduler API.  It is not intended for production use
--- the other schedulers included are all more general and should give
higher throughput.

\subsection{Global parameters}

\begin{description}
\item[rr\_slice]
  The maximum time each domain runs before the next
  scheduling decision is made.
\end{description}

\chapter{Privileged domains}

There are two possible types of privileges: IO privileges and
administration privileges.

\section{Driver domains (IO Privileges)}

IO privileges can be assigned to allow a domain to drive PCI devices
itself.  This is used for to support driver domains.

\section{Administration Domains}

Administration privileges allow a domain to use the ``dom0
operations'' (so called because they are usually available only to
domain 0).  A privileged domain can build other domains, set scheduling
parameters, etc.

% Support for other administrative domains is not yet available...

\chapter{Xen build options}

For most users, the default build of Xen will be adequate.  For some
advanced uses, Xen provides a number of build-time options:

At build time, these options should be set as environment variables or
passed on make's command-line.  For example:

\begin{verbatim}
export option=y; make
option=y make
make option1=y option2=y
\end{verbatim}

\section{List of options}

{\bf debug=y }\\
Enable debug assertions and console output.
(Primarily useful for tracing bugs in Xen).        \\
{\bf debugger=y }\\
Enable the in-Xen pervasive debugger (PDB).
This can be used to debug Xen, guest OSes, and
applications. For more information see the 
XenDebugger-HOWTO.                                 \\
{\bf perfc=y }\\
Enable performance-counters for significant events
within Xen. The counts can be reset or displayed
on Xen's console via console control keys.          \\
{\bf trace=y }\\
Enable per-cpu trace buffers which log a range of
events within Xen for collection by control
software.  For more information see the chapter on debugging,
in the Xen Interface Manual.

\chapter{Xen boot options}

These options are used to configure Xen's behaviour at runtime.  They
should be appended to Xen's command line, either manually or by
editting \path{grub.conf}.

\section{List of options}

{\bf ignorebiostables }\\
 Disable parsing of BIOS-supplied tables. This may help with some
 chipsets that aren't fully supported by Xen. If you specify this
 option then ACPI tables are also ignored, and SMP support is
 disabled. \\

{\bf noreboot } \\
 Don't reboot the machine automatically on errors.  This is
 useful to catch debug output if you aren't catching console messages
 via the serial line. \\

{\bf nosmp } \\
 Disable SMP support.
 This option is implied by 'ignorebiostables'. \\

{\bf noacpi } \\
 Disable ACPI tables, which confuse Xen on some chipsets.
 This option is implied by 'ignorebiostables'. \\

{\bf watchdog } \\
 Enable NMI watchdog which can report certain failures. \\

{\bf noht } \\
 Disable Hyperthreading. \\

{\bf ifname=ethXX }\\ 
 Select which Ethernet interface to use. \\

{\bf ifname=dummy } \\
 Don't use any network interface. \\

{\bf com1=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] \\
 com2=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] } \\
 Xen supports up to two 16550-compatible serial ports.
 For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
 9600-baud port, 8 data bits, no parity, 1 stop bit,
 I/O port base 0x408, IRQ 5.
 If the I/O base and IRQ are standard (com1:0x3f8,4;
 com2:0x2f8,3) then they need not be specified. \\

{\bf console=$<$specifier list$>$ } \\
 Specify the destination for Xen console I/O.
 This is a comma-separated list of, for example:
\begin{description}
 \item[vga]  use VGA console and allow keyboard input
 \item[com1] use serial port com1
 \item[com2H] use serial port com2. Transmitted chars will
   have the MSB set. Received chars must have
   MSB set.
 \item[com2L] use serial port com2. Transmitted chars will
   have the MSB cleared. Received chars must
   have MSB cleared.
\end{description}
 The latter two examples allow a single port to be
 shared by two subsystems (eg. console and
 debugger). Sharing is controlled by MSB of each
 transmitted/received character.
 [NB. Default for this option is 'com1,tty'] \\

{\bf conswitch=$<$switch-char$><$auto-switch-char$>$ } \\
 Specify how to switch serial-console input between
 Xen and DOM0. The required sequence is CTRL-<switch-char>
 pressed three times. Specifying '`' disables switching.
 The <auto-switch-char> specifies whether Xen should
 auto-switch input to DOM0 when it boots -- if it is 'x'
 then auto-switching is disabled. Any other value, or
 omitting the character, enables auto-switching.
 [NB. Default for this option is 'a'] \\

{\bf dom0\_mem=xxx } \\
 Set the maximum amount of memory for domain0. \\

{\bf tbuf\_size=xxx } \\
 Set the size of the per-cpu trace buffers, in pages
 (default 1).  Note that the trace buffers are only
 enabled in debug builds.  Most users can ignore
 this feature completely. \\

{\bf sched=xxx } \\
 Select the CPU scheduler Xen should use.  The current
 possibilities are 'bvt', 'atropos' and 'rrobin'.  The
 default is 'bvt'.  For more information see
 Sched-HOWTO.txt. \\

{\bf pci\_dom0\_hide=(xx.xx.x)(yy.yy.y)... } \\
Hide selected PCI devices from domain 0 (for instance, to stop it
taking ownership of them so that they can be driven by another
domain).  Device IDs should be given in hex format.  Bridge devices do
not need to be hidden --- they are hidden implicitly, since guest OSes
do not need to configure them.

\end{document}