ia64/xen-unstable

changeset 2855:0d263b6cd810

bitkeeper revision 1.1159.155.1 (41891476g41RZ5y7G4uFAPTllxT_MQ)

tidying up latter half - first half still needs lotsa work
author smh22@tempest.cl.cam.ac.uk
date Wed Nov 03 17:25:10 2004 +0000 (2004-11-03)
parents 123bec0b692a
children 82a6612c741f
files docs/src/user.tex
line diff
     1.1 --- a/docs/src/user.tex	Wed Nov 03 16:13:25 2004 +0000
     1.2 +++ b/docs/src/user.tex	Wed Nov 03 17:25:10 2004 +0000
     1.3 @@ -888,6 +888,10 @@ docs to do advanced stuff.
     1.4  
     1.5  \chapter{Control Software} 
     1.6  
     1.7 +The Xen control software includes the \xend node control daemon (which 
     1.8 +must be running), the xm command line tools, and the prototype 
     1.9 +xensv web interface. 
    1.10 +
    1.11  \section{\Xend (Node control daemon)}
    1.12  \label{s:xend}
    1.13  
    1.14 @@ -904,7 +908,7 @@ management functions.  A small set of co
    1.15  \verb!# xend start! & start \xend, if not already running \\
    1.16  \verb!# xend stop!  & stop \xend if already running       \\
    1.17  \verb!# xend restart! & restart \xend if running, otherwise start it \\
    1.18 -\verb!# xend trace_start! & start \xend, with very detailed debug logging \\
    1.19 +% \verb!# xend trace_start! & start \xend, with very detailed debug logging \\
    1.20  \verb!# xend status! & indicates \xend status by its return code
    1.21  \end{tabular}
    1.22  
    1.23 @@ -991,24 +995,27 @@ manage running domains.
    1.24  \chapter{Domain Configuration}
    1.25  \label{cha:config}
    1.26  
    1.27 +The following contains the syntax of the domain configuration 
    1.28 +files and description of how to further specify networking, 
    1.29 +driver domain and general scheduling behaviour. 
    1.30  
    1.31  \section{Configuration Files}
    1.32  \label{s:cfiles}
    1.33  
    1.34  Xen configuration files contain the following standard variables.
    1.35  Unless otherwise stated, configuration items should be enclosed in
    1.36 -quotes (i.e. {\tt '...'} or {\tt ``....''})):
    1.37 +quotes: see \path{/etc/xen/xmexample1} for an example. 
    1.38  
    1.39  \begin{description}
    1.40 -\item[kernel] Path to the kernel image (on the server).
    1.41 +\item[kernel] Path to the kernel image 
    1.42  \item[ramdisk] Path to a ramdisk image (optional).
    1.43  % \item[builder] The name of the domain build function (e.g. {\tt'linux'} or {\tt'netbsd'}.
    1.44  \item[memory] Memory size in megabytes.
    1.45 -\item[cpu] CPU to assign this domain to.
    1.46 +\item[cpu] CPU to run this domain on, or {\tt -1} for
    1.47 +  auto-allocation. 
    1.48  \item[nics] Number of virtual network interfaces.
    1.49  \item[vif] List of MAC addresses (random addresses are assigned if not
    1.50 -  given) and / or bridges to use for the domains network
    1.51 -  interfaces. e.g.
    1.52 +  given) and bridges to use for the domain's network interfaces, e.g.
    1.53  \begin{verbatim}
    1.54  vif = [ 'mac=aa:00:00:00:00:11, bridge=xen-br0',
    1.55          'bridge=xen-br1' ]
    1.56 @@ -1016,23 +1023,21 @@ vif = [ 'mac=aa:00:00:00:00:11, bridge=x
    1.57    to assign a MAC address and bridge to the first interface and assign
    1.58    a different bridge to the second interface, leaving \xend to choose
    1.59    the MAC address.
    1.60 -\item[disk] List of block devices to export to the domain.  e.g. \\
    1.61 +\item[disk] List of block devices to export to the domain,  e.g. \\
    1.62    \verb_disk = [ 'phy:hda1,sda1,r' ]_ \\
    1.63 -  exports device \path{/dev/hda1} to the domain, as \path{/dev/sda1} with
    1.64 -  readonly access being allowed. \\
    1.65 -  \verb_disk = [ 'phy:hda7,sda2,w', 'phy:hdb2,sda,w!' ]_ \\
    1.66 -  exports device \path{/dev/hda7} to the domain as \path{/dev/sda2} with
    1.67 -  write access enabled and \path{/dev/hdb2} as \path{/dev/sda} with write access
    1.68 -  force enabled (bypassing safety checks, as indicated by the {\tt !}).
    1.69 -\item[dhcp] Set to {\tt 'dhcp'} if you want to DHCP allocate the IP
    1.70 -address.
    1.71 -\item[netmask] IP netmask.
    1.72 -\item[gateway] IP address for the gateway (if any).
    1.73 +  exports physical device \path{/dev/hda1} to the domain 
    1.74 +  as \path{/dev/sda1} with read-only access. 
    1.75 +\item[dhcp] Set to {\tt 'dhcp'} if you want to use DHCP to configure
    1.76 +  networking. 
    1.77 +\item[netmask] Manually configured IP netmask.
    1.78 +\item[gateway] Manually configured IP gateway. 
    1.79  \item[hostname] Set the hostname for the virtual machine.
    1.80 -\item[root] Set the root device.
    1.81 -\item[nfs\_server] IP address for the NFS server.
    1.82 -\item[nfs\_root] Path of the root filesystem on the NFS server.
    1.83 -\item[extra] Extra string to append to the kernel command line.
    1.84 +\item[root] Specify the root device parameter on the kernel command
    1.85 +  line. 
    1.86 +\item[nfs\_server] IP address for the NFS server (if any). 
    1.87 +\item[nfs\_root] Path of the root filesystem on the NFS server (if any).
    1.88 +\item[extra] Extra string to append to the kernel command line (if
    1.89 +  any) 
    1.90  \item[restart] Three possible options:
    1.91    \begin{description}
    1.92    \item[always] Always restart the domain, no matter what
    1.93 @@ -1051,162 +1056,48 @@ scripting commands in configuration file
    1.94  
    1.95  \section{Network Configuration}
    1.96  
    1.97 -For simple systems with a single ethernet interface with a simple
    1.98 -configuration, the default installation should work `out of the
    1.99 -box'.  More complicated network setups, for instance with multiple
   1.100 -ethernet interfaces and / or existing bridging setups will require
   1.101 -some special configuration.
   1.102 +For many users, the default installation should work `out of the box'.
   1.103 +More complicated network setups, for instance with multiple ethernet
   1.104 +interfaces and/or existing bridging setups will require some
   1.105 +special configuration.
   1.106  
   1.107 -The purpose of this chapter is to describe the mechanisms provided by
   1.108 +The purpose of this section is to describe the mechanisms provided by
   1.109  \xend to allow a flexible configuration for Xen's virtual networking.
   1.110  
   1.111  \subsection{Xen networking scripts}
   1.112  
   1.113 -Xen's virtual networking is configured by 3 shell scripts.  These are
   1.114 -called automatically by \xend when certain events occur, with arguments
   1.115 -to the scripts providing further contextual information.  These
   1.116 -scripts are found by default in \path{/etc/xen}.  The names and
   1.117 -locations of the scripts can be configured in \path{xend-config.sxp}.
   1.118 -
   1.119 -\subsubsection{\path{network}}
   1.120 -
   1.121 -This script is called once when \xend is started and once when \xend is
   1.122 -stopped.  Its job is to do any advance preparation required for the
   1.123 -Xen virtual network when \xend starts and to do any corresponding
   1.124 -cleanup when \xend exits.
   1.125 -
   1.126 -In the default configuration, this script creates the bridge
   1.127 -`xen-br0' and moves eth0 onto that bridge, modifying the routing
   1.128 -accordingly.
   1.129 -
   1.130 -In configurations where the bridge already exists, this script could
   1.131 -be replaced with a link to \path{/bin/true} (for instance).
   1.132 -
   1.133 -When \xend exits, this script is called with the {\tt stop} argument,
   1.134 -which causes it to delete the Xen bridge and remove {\tt eth0} from
   1.135 -it, restoring the normal IP and routing configuration.
   1.136 -
   1.137 -\subsubsection{\path{vif-bridge}}
   1.138 -
   1.139 -This script is called for every domain virtual interface.  This should
   1.140 -do things like configuring firewalling rules for that interface and
   1.141 -adding it to the appropriate bridge.
   1.142 -
   1.143 -By default, this adds and removes VIFs on the default Xen bridge.
   1.144 -This script can be customized to properly deal with more complicated
   1.145 -bridging setups.
   1.146 +Xen's virtual networking is configured by two shell scripts (by
   1.147 +default \path{network} and \path{vif-bridge}).  These are
   1.148 +called automatically by \xend when certain events occur, with
   1.149 +arguments to the scripts providing further contextual information.
   1.150 +These scripts are found by default in \path{/etc/xen/scripts}.  The
   1.151 +names and locations of the scripts can be configured in
   1.152 +\path{/etc/xen/xend-config.sxp}.
   1.153  
   1.154 -\section{Scheduler Configuration}
   1.155 -
   1.156 -\subsection{Scheduler selection}
   1.157 -
   1.158 -Xen offers a boot time choice between multiple schedulers.  To select
   1.159 -a scheduler, pass the boot parameter { \tt sched=sched\_name } to Xen,
   1.160 -substituting the appropriate scheduler name.  Details of the schedulers
   1.161 -and their parameters are included below; future versions of the tools
   1.162 -will provide a higher-level interface to these tools.
   1.163 -
   1.164 -It is expected that system administrators configure their system to
   1.165 -use the scheduler most appropriate to their needs.  Currently, the BVT
   1.166 -scheduler is the recommended choice, since the Atropos scheduler is
   1.167 -not finished.
   1.168 -
   1.169 -\subsection{Borrowed Virtual Time}
   1.170 -
   1.171 -{\tt sched=bvt } (the default) \\ 
   1.172 -
   1.173 -BVT provides proportional fair shares of the CPU time.  It has been
   1.174 -observed to penalise domains that block frequently (e.g. IO intensive
   1.175 -domains), but this can be compensated by using warping. 
   1.176 -
   1.177 -\subsubsection{Global Parameters}
   1.178 -
   1.179 -\begin{description}
   1.180 -\item[ctx\_allow]
   1.181 -  the context switch allowance is similar to the "quantum"
   1.182 -  in traditional schedulers.  It is the minimum time that
   1.183 -  a scheduled domain will be allowed to run before being
   1.184 -  pre-empted.  This prevents thrashing of the CPU.
   1.185 -\end{description}
   1.186 -
   1.187 -\subsubsection{Per-domain parameters}
   1.188 +\begin{description} 
   1.189  
   1.190 -\begin{description}
   1.191 -\item[mcuadv]
   1.192 -  the MCU (Minimum Charging Unit) advance determines the
   1.193 -  proportional share of the CPU that a domain receives.  It
   1.194 -  is set inversely proportionally to a domain's sharing weight.
   1.195 -\item[warp]
   1.196 -  the amount of "virtual time" the domain is allowed to warp
   1.197 -  backwards
   1.198 -\item[warpl]
   1.199 -  the warp limit is the maximum time a domain can run warped for
   1.200 -\item[warpu]
   1.201 -  the unwarp requirement is the minimum time a domain must
   1.202 -  run unwarped for before it can warp again
   1.203 -\end{description}
   1.204 -
   1.205 -\subsection{Atropos}
   1.206 -
   1.207 -{\tt sched=atropos } \\
   1.208 -
   1.209 -Atropos is a Soft Real Time scheduler.  It provides guarantees about
   1.210 -absolute shares of the CPU (with a method for optionally sharing out
   1.211 -slack CPU time on a best-effort basis) and can provide timeliness
   1.212 -guarantees for latency-sensitive domains.
   1.213 -
   1.214 -Every domain has an associated period and slice.  The domain should
   1.215 -receive 'slice' nanoseconds every 'period' nanoseconds.  This allows
   1.216 -the administrator to configure both the absolute share of the CPU a
   1.217 -domain receives and the frequency with which it is scheduled.  When
   1.218 -domains unblock, their period is reduced to the value of the latency
   1.219 -hint (the slice is scaled accordingly so that they still get the same
   1.220 -proportion of the CPU).  For each subsequent period, the slice and
   1.221 -period times are doubled until they reach their original values.
   1.222 +\item[network:] This script is called whenever \xend is started or
   1.223 +stopped to respectively initialize or tear down the Xen virtual
   1.224 +network. In the default configuration initialization creates the
   1.225 +bridge `xen-br0' and moves eth0 onto that bridge, modifying the
   1.226 +routing accordingly. When \xend exits, it deletes the Xen bridge and
   1.227 +removes eth0, restoring the normal IP and routing configuration.
   1.228  
   1.229 -Note: don't overcommit the CPU when using Atropos (i.e. don't reserve
   1.230 -more CPU than is available - the utilisation should be kept to
   1.231 -slightly less than 100% in order to ensure predictable behaviour).
   1.232 -
   1.233 -\subsubsection{Per-domain parameters}
   1.234 +%% In configurations where the bridge already exists, this script could
   1.235 +%% be replaced with a link to \path{/bin/true} (for instance).
   1.236  
   1.237 -\begin{description}
   1.238 -\item[slice]
   1.239 -  The length of time per period that a domain is guaranteed.
   1.240 -\item[period]
   1.241 -  The period over which a domain is guaranteed to receive
   1.242 -  its slice of CPU time.
   1.243 -\item[latency]
   1.244 -  The latency hint is used to control how soon after
   1.245 -  waking up a domain should be scheduled.
   1.246 -\item[xtratime]
   1.247 -  This is a true (1) / false (0) flag that specifies whether
   1.248 -  a domain should be allowed a share of the system slack time.
   1.249 -\end{description}
   1.250 -
   1.251 -\section{Round Robin}
   1.252 +\item[vif-bridge:] This script is called for every domain virtual
   1.253 +interface and can configure firewalling rules and add the vif 
   1.254 +to the appropriate bridge. By default, this adds and removes 
   1.255 +VIFs on the default Xen bridge.
   1.256  
   1.257 -{\tt sched=rrobin } \\
   1.258 -
   1.259 -The Round Robin scheduler is included as a simple demonstration of
   1.260 -Xen's internal scheduler API.  It is not intended for production use
   1.261 ---- the other schedulers included are all more general and should give
   1.262 -higher throughput.
   1.263 +\end{description} 
   1.264  
   1.265 -\subsection{Global parameters}
   1.266 -
   1.267 -\begin{description}
   1.268 -\item[rr\_slice]
   1.269 -  The maximum time each domain runs before the next
   1.270 -  scheduling decision is made.
   1.271 -\end{description}
   1.272 -
   1.273 -\chapter{Privileged domains}
   1.274  
   1.275  %% There are two possible types of privileges:  IO privileges and
   1.276  %% administration privileges.
   1.277  
   1.278 -\section{Driver domains (I/O Privileges)}
   1.279 +\section{Driver Domain Configuration} 
   1.280  
   1.281  I/O privileges can be assigned to allow a domain to directly access
   1.282  PCI devices itself.  This is used to support driver domains.
   1.283 @@ -1217,37 +1108,33 @@ somewhere within the {\tt vm} element of
   1.284  be a {\tt backend} element of the form {\tt (backend ({\em type}))}
   1.285  where {\tt \em type} may be either {\tt netif} or {\tt blkif},
   1.286  according to the type of virtual device this domain will service.
   1.287 -After this domain has been built, \xend will connect all new and
   1.288 -existing {\em virtual} devices (of the appropriate type) to that
   1.289 -backend.
   1.290 +%% After this domain has been built, \xend will connect all new and
   1.291 +%% existing {\em virtual} devices (of the appropriate type) to that
   1.292 +%% backend.
   1.293  
   1.294 -Note that:
   1.295 -\begin{itemize}
   1.296 -\item a block backend cannot import virtual block devices from other
   1.297 -domains
   1.298 -\item a network backend cannot import virtual network devices from
   1.299 -other domains
   1.300 -\end{itemize}
   1.301 +Note that a block backend cannot import virtual block devices from
   1.302 +other domains, and a network backend cannot import virtual network
   1.303 +devices from other domains.  Thus (particularly in the case of block
   1.304 +backends, which cannot import a virtual block device as their root
   1.305 +filesystem), you may need to boot a backend domain from a ramdisk or a
   1.306 +network device.
   1.307  
   1.308 -Thus (particularly in the case of block backends, which cannot import
   1.309 -a virtual block device as their root filesystem), you may need to boot
   1.310 -a backend domain from a ramdisk or a network device.
   1.311 -
   1.312 -The privilege to drive PCI devices may also be specified on a
   1.313 -per-device basis.  Xen will assign the minimal set of hardware
   1.314 -privileges to a domain that are required to control its devices.  This
   1.315 -can be configured in either format of configuration file:
   1.316 +Access to PCI devices may be configured on a per-device basis.  Xen
   1.317 +will assign the minimal set of hardware privileges to a domain that
   1.318 +are required to control its devices.  This can be configured in either
   1.319 +format of configuration file:
   1.320  
   1.321  \begin{itemize}
   1.322 -\item SXP Format:
   1.323 -  Include {\tt device} elements
   1.324 -  {\tt (device (pci (bus {\em x}) (dev {\em y}) (func {\em z}))) } \\
   1.325 +\item SXP Format: Include device elements of the form: \\
   1.326 +\centerline{  {\tt (device (pci (bus {\em x}) (dev {\em y}) (func {\em z}))) }} \\
   1.327    inside the top-level {\tt vm} element.  Each one specifies the address
   1.328 -  of a device this domain is allowed to drive ---
   1.329 +  of a device this domain is allowed to access ---
   1.330    the numbers {\em x},{\em y} and {\em z} may be in either decimal or
   1.331    hexadecimal format.
   1.332  \item Flat Format: Include a list of PCI device addresses of the
   1.333 -  format: \\ {\tt pci = ['x,y,z', ...] } \\ where each element in the
   1.334 +  format: \\ 
   1.335 +\centerline{{\tt pci = ['x,y,z', ...] }} \\ 
   1.336 +where each element in the
   1.337    list is a string specifying the components of the PCI device
   1.338    address, separated by commas.  The components ({\tt \em x}, {\tt \em
   1.339    y} and {\tt \em z}) of the list may be formatted as either decimal
   1.340 @@ -1264,63 +1151,152 @@ can be configured in either format of co
   1.341  % Support for other administrative domains is not yet available...  perhaps
   1.342  % we should plumb it in some time
   1.343  
   1.344 -\chapter{Debugging}
   1.345 +
   1.346 +
   1.347 +
   1.348 +
   1.349 +\section{Scheduler Configuration}
   1.350 +\label{s:sched} 
   1.351 +
   1.352 +
   1.353 +Xen offers a boot time choice between multiple schedulers.  To select
   1.354 +a scheduler, pass the boot parameter {\em sched=sched\_name} to Xen,
   1.355 +substituting the appropriate scheduler name.  Details of the schedulers
   1.356 +and their parameters are included below; future versions of the tools
   1.357 +will provide a higher-level interface to these tools.
   1.358  
   1.359 -Xen has a set of debugging features that can be useful to try and
   1.360 -figure out what's going on. Hit 'h' on the serial line (if you
   1.361 -specified a baud rate on the Xen command line) or ScrollLock-h on the
   1.362 -keyboard to get a list of supported commands.
   1.363 +It is expected that system administrators configure their system to
   1.364 +use the scheduler most appropriate to their needs.  Currently, the BVT
   1.365 +scheduler is the recommended choice. 
   1.366 +
   1.367 +\subsection{Borrowed Virtual Time}
   1.368  
   1.369 -If you have a crash you'll likely get a crash dump containing an EIP
   1.370 -(PC) which, along with an 'objdump -d image', can be useful in
   1.371 -figuring out what's happened.  Debug a Xenlinux image just as you
   1.372 -would any other Linux kernel.
   1.373 +{\tt sched=bvt } (the default) \\ 
   1.374 +
   1.375 +BVT provides proportional fair shares of the CPU time.  It has been
   1.376 +observed to penalise domains that block frequently (e.g. I/O intensive
   1.377 +domains), but this can be compensated for by using warping. 
   1.378 +
   1.379 +\subsubsection{Global Parameters}
   1.380  
   1.381 -We supply a handy debug terminal program which you can find in
   1.382 -\path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/}
   1.383 -This should be built and executed on another machine that is connected
   1.384 -via a null modem cable. Documentation is included.
   1.385 -Alternatively, if the Xen machine is connected to a serial-port server
   1.386 -then we supply a dumb TCP terminal client, {\tt xencons}.
   1.387 +\begin{description}
   1.388 +\item[ctx\_allow]
   1.389 +  the context switch allowance is similar to the "quantum"
   1.390 +  in traditional schedulers.  It is the minimum time that
   1.391 +  a scheduled domain will be allowed to run before being
   1.392 +  pre-empted. 
   1.393 +\end{description}
   1.394 +
   1.395 +\subsubsection{Per-domain parameters}
   1.396  
   1.397 -\chapter{Xen build options}
   1.398 +\begin{description}
   1.399 +\item[mcuadv]
   1.400 +  the MCU (Minimum Charging Unit) advance determines the
   1.401 +  proportional share of the CPU that a domain receives.  It
   1.402 +  is set inversely proportionally to a domain's sharing weight.
   1.403 +\item[warp]
   1.404 +  the amount of ``virtual time'' the domain is allowed to warp
   1.405 +  backwards
   1.406 +\item[warpl]
   1.407 +  the warp limit is the maximum time a domain can run warped for
   1.408 +\item[warpu]
   1.409 +  the unwarp requirement is the minimum time a domain must
   1.410 +  run unwarped for before it can warp again
   1.411 +\end{description}
   1.412  
   1.413 -For most users, the default build of Xen will be adequate.  For some
   1.414 -advanced uses, Xen provides a number of build-time options:
   1.415 +\subsection{Atropos}
   1.416 +
   1.417 +{\tt sched=atropos } \\
   1.418 +
   1.419 +Atropos is a soft real time scheduler.  It provides guarantees about
   1.420 +absolute shares of the CPU, with a facility for sharing
   1.421 +slack CPU time on a best-effort basis. It can provide timeliness
   1.422 +guarantees for latency-sensitive domains.
   1.423 +
   1.424 +Every domain has an associated period and slice.  The domain should
   1.425 +receive `slice' nanoseconds every `period' nanoseconds.  This allows
   1.426 +the administrator to configure both the absolute share of the CPU a
   1.427 +domain receives and the frequency with which it is scheduled. 
   1.428  
   1.429 -At build time, these options should be set as environment variables or
   1.430 -passed on make's command-line.  For example:
   1.431 +%%  When
   1.432 +%% domains unblock, their period is reduced to the value of the latency
   1.433 +%% hint (the slice is scaled accordingly so that they still get the same
   1.434 +%% proportion of the CPU).  For each subsequent period, the slice and
   1.435 +%% period times are doubled until they reach their original values.
   1.436 +
   1.437 +Note: don't overcommit the CPU when using Atropos (i.e. don't reserve
   1.438 +more CPU than is available --- the utilisation should be kept to
   1.439 +slightly less than 100\% in order to ensure predictable behaviour).
   1.440 +
   1.441 +\subsubsection{Per-domain parameters}
   1.442  
   1.443 -\begin{verbatim}
   1.444 -export option=y; make
   1.445 -option=y make
   1.446 -make option1=y option2=y
   1.447 -\end{verbatim}
   1.448 +\begin{description}
   1.449 +\item[period] The regular time interval during which a domain is
   1.450 +  guaranteed to receive its allocation of CPU time.
   1.451 +\item[slice]
   1.452 +  The length of time per period that a domain is guaranteed to run
   1.453 +  for (in the absence of voluntary yielding of the CPU). 
   1.454 +\item[latency]
   1.455 +  The latency hint is used to control how soon after
   1.456 +  waking up a domain it should be scheduled.
   1.457 +\item[xtratime] This is a boolean flag that specifies whether a domain
   1.458 +  should be allowed a share of the system slack time.
   1.459 +\end{description}
   1.460  
   1.461 -\section{List of options}
   1.462 +\section{Round Robin}
   1.463 +
   1.464 +{\tt sched=rrobin } \\
   1.465 +
   1.466 +The round robin scheduler is included as a simple demonstration of
   1.467 +Xen's internal scheduler API.  It is not intended for production use. 
   1.468 +
   1.469 +\subsection{Global parameters}
   1.470  
   1.471 -{\bf verbose=y }\\
   1.472 -Enable debugging messages when Xen detects an unexpected condition.
   1.473 -Also enables console output from all domains. \\
   1.474 -{\bf debug=y }\\
   1.475 -Enable debug assertions.  Implies {\bf verbose=y }.
   1.476 -(Primarily useful for tracing bugs in Xen).        \\
   1.477 -{\bf debugger=y }\\
   1.478 -Enable the in-Xen pervasive debugger (PDB).
   1.479 -This can be used to debug Xen, guest OSes, and
   1.480 -applications. For more information see the 
   1.481 -XenDebugger-HOWTO.                                 \\
   1.482 -{\bf perfc=y }\\
   1.483 -Enable performance-counters for significant events
   1.484 +\begin{description}
   1.485 +\item[rr\_slice]
   1.486 +  The maximum time each domain runs before the next
   1.487 +  scheduling decision is made.
   1.488 +\end{description}
   1.489 +
   1.490 +
   1.491 +
   1.492 +
   1.493 +
   1.494 +
   1.495 +
   1.496 +
   1.497 +
   1.498 +
   1.499 +
   1.500 +
   1.501 +\chapter{Build, Boot and Debug options} 
   1.502 +
   1.503 +This chapter describes the build- and boot-time options 
   1.504 +which may be used to tailor your Xen system. 
   1.505 +
   1.506 +\section{Xen build options}
   1.507 +
   1.508 +Xen provides a number of build-time options which should be 
   1.509 +set as environment variables or passed on make's command-line.  
   1.510 +
   1.511 +\begin{description} 
   1.512 +\item[verbose=y] Enable debugging messages when Xen detects an unexpected condition.
   1.513 +Also enables console output from all domains.
   1.514 +\item[debug=y] 
   1.515 +Enable debug assertions.  Implies {\bf verbose=y}.
   1.516 +(Primarily useful for tracing bugs in Xen).       
   1.517 +\item[debugger=y] 
   1.518 +Enable the in-Xen debugger. This can be used to debug 
   1.519 +Xen, guest OSes, and applications.
   1.520 +\item[perfc=y] 
   1.521 +Enable performance counters for significant events
   1.522  within Xen. The counts can be reset or displayed
   1.523 -on Xen's console via console control keys.          \\
   1.524 -{\bf trace=y }\\
   1.525 +on Xen's console via console control keys.
   1.526 +\item[trace=y] 
   1.527  Enable per-cpu trace buffers which log a range of
   1.528  events within Xen for collection by control
   1.529 -software.  For more information see the chapter on debugging,
   1.530 -in the Xen Interface Manual.
   1.531 -
   1.532 -\chapter{Boot options}
   1.533 +software. 
   1.534 +\end{description} 
   1.535  
   1.536  \section{Xen boot options}
   1.537  
   1.538 @@ -1328,49 +1304,48 @@ These options are used to configure Xen'
   1.539  should be appended to Xen's command line, either manually or by
   1.540  editing \path{grub.conf}.
   1.541  
   1.542 -{\bf ignorebiostables }\\
   1.543 +\begin{description}
   1.544 +\item [ignorebiostables ] 
   1.545   Disable parsing of BIOS-supplied tables. This may help with some
   1.546   chipsets that aren't fully supported by Xen. If you specify this
   1.547   option then ACPI tables are also ignored, and SMP support is
   1.548 - disabled. \\
   1.549 + disabled. 
   1.550  
   1.551 -{\bf noreboot } \\
   1.552 +\item [noreboot ] 
   1.553   Don't reboot the machine automatically on errors.  This is
   1.554   useful to catch debug output if you aren't catching console messages
   1.555 - via the serial line. \\
   1.556 + via the serial line. 
   1.557  
   1.558 -{\bf nosmp } \\
   1.559 +\item [nosmp ] 
   1.560   Disable SMP support.
   1.561 - This option is implied by 'ignorebiostables'. \\
   1.562 + This option is implied by `ignorebiostables'. 
   1.563  
   1.564 -{\bf noacpi } \\
   1.565 +\item [noacpi ] 
   1.566   Disable ACPI tables, which confuse Xen on some chipsets.
   1.567 - This option is implied by 'ignorebiostables'. \\
   1.568 + This option is implied by `ignorebiostables'. 
   1.569  
   1.570 -{\bf watchdog } \\
   1.571 - Enable NMI watchdog which can report certain failures. \\
   1.572 +\item [watchdog ] 
   1.573 + Enable NMI watchdog which can report certain failures. 
   1.574  
   1.575 -{\bf noht } \\
   1.576 - Disable Hyperthreading. \\
   1.577 +\item [noht ] 
   1.578 + Disable Hyperthreading. 
   1.579  
   1.580 -{\bf badpage=$<$page number$>$[,$<$page number$>$] } \\
   1.581 +\item [badpage=$<$page number$>$,$<$page number$>$, \ldots ] 
   1.582   Specify a list of pages not to be allocated for use 
   1.583   because they contain bad bytes. For example, if your
   1.584   memory tester says that byte 0x12345678 is bad, you would
   1.585 - place 'badpage=0x12345' on Xen's command line (i.e., the
   1.586 - last three digits of the byte address are not
   1.587 - included!). \\
   1.588 + place `badpage=0x12345' on Xen's command line. 
   1.589  
   1.590 -{\bf com1=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] \\
   1.591 - com2=$<$baud$>$,DPS[,$<$io\_base$>$,$<$irq$>$] } \\
   1.592 +\item [com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
   1.593 + com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\ 
   1.594   Xen supports up to two 16550-compatible serial ports.
   1.595   For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
   1.596   9600-baud port, 8 data bits, no parity, 1 stop bit,
   1.597   I/O port base 0x408, IRQ 5.
   1.598   If the I/O base and IRQ are standard (com1:0x3f8,4;
   1.599 - com2:0x2f8,3) then they need not be specified. \\
   1.600 + com2:0x2f8,3) then they need not be specified. 
   1.601  
   1.602 -{\bf console=$<$specifier list$>$ } \\
   1.603 +\item [console=$<$specifier list$>$ ] 
   1.604   Specify the destination for Xen console I/O.
   1.605   This is a comma-separated list of, for example:
   1.606  \begin{description}
   1.607 @@ -1387,55 +1362,89 @@ editing \path{grub.conf}.
   1.608   shared by two subsystems (e.g. console and
   1.609   debugger). Sharing is controlled by MSB of each
   1.610   transmitted/received character.
   1.611 - [NB. Default for this option is 'com1,tty'] \\
   1.612 + [NB. Default for this option is `com1,vga'] 
   1.613  
   1.614 -{\bf conswitch=$<$switch-char$><$auto-switch-char$>$ } \\
   1.615 +\item [conswitch=$<$switch-char$><$auto-switch-char$>$ ] 
   1.616   Specify how to switch serial-console input between
   1.617 - Xen and DOM0. The required sequence is CTRL-<switch-char>
   1.618 - pressed three times. Specifying '`' disables switching.
   1.619 - The <auto-switch-char> specifies whether Xen should
   1.620 - auto-switch input to DOM0 when it boots -- if it is 'x'
   1.621 + Xen and DOM0. The required sequence is CTRL-$<$switch-char$>$
   1.622 + pressed three times. Specifying the backtick character 
   1.623 + disables switching.
   1.624 + The $<$auto-switch-char$>$ specifies whether Xen should
   1.625 + auto-switch input to DOM0 when it boots --- if it is `x'
   1.626   then auto-switching is disabled.  Any other value, or
   1.627   omitting the character, enables auto-switching.
   1.628 - [NB. Default for this option is 'a'] \\
   1.629 + [NB. default switch-char is `a'] 
   1.630  
   1.631 -{\bf nmi=xxx } \\
   1.632 +\item [nmi=xxx ] 
   1.633   Specify what to do with an NMI parity or I/O error. \\
   1.634 - 'nmi=fatal':  Xen prints a diagnostic and then hangs. \\
   1.635 - 'nmi=dom0':   Inform DOM0 of the NMI. \\
   1.636 - 'nmi=ignore': Ignore the NMI. \\
   1.637 + `nmi=fatal':  Xen prints a diagnostic and then hangs. \\
   1.638 + `nmi=dom0':   Inform DOM0 of the NMI. \\
   1.639 + `nmi=ignore': Ignore the NMI. 
   1.640  
   1.641 -{\bf dom0\_mem=xxx } \\
   1.642 - Set the maximum amount of memory for domain0. \\
   1.643 +\item [dom0\_mem=xxx ] 
   1.644 + Set the amount of memory (in kB) to be allocated to domain0.  
   1.645  
   1.646 -{\bf tbuf\_size=xxx } \\
   1.647 +\item [tbuf\_size=xxx ] 
   1.648   Set the size of the per-cpu trace buffers, in pages
   1.649   (default 1).  Note that the trace buffers are only
   1.650   enabled in debug builds.  Most users can ignore
   1.651 - this feature completely. \\
   1.652 + this feature completely. 
   1.653  
   1.654 -{\bf sched=xxx } \\
   1.655 +\item [sched=xxx ] 
   1.656   Select the CPU scheduler Xen should use.  The current
   1.657 - possibilities are 'bvt', 'atropos' and 'rrobin'.  The
   1.658 - default is 'bvt'.  For more information see
   1.659 - Sched-HOWTO.txt. \\
   1.660 + possibilities are `bvt' (default), `atropos' and `rrobin'. 
   1.661 + For more information see Section~\ref{s:sched}. 
   1.662  
   1.663 -{\bf pci\_dom0\_hide=(xx.xx.x)(yy.yy.y)... } \\
   1.664 +\item [pci\_dom0\_hide=(xx.xx.x)(yy.yy.y)\ldots ] 
   1.665  Hide selected PCI devices from domain 0 (for instance, to stop it
   1.666  taking ownership of them so that they can be driven by another
   1.667  domain).  Device IDs should be given in hex format.  Bridge devices do
   1.668  not need to be hidden --- they are hidden implicitly, since guest OSes
   1.669  do not need to configure them.
   1.670 +\end{description} 
   1.671 +
   1.672 +
   1.673  
   1.674  \section{XenLinux Boot Options}
   1.675  
   1.676 -{\bf xencons=xxx}
   1.677 -Specify the device node to
   1.678 -which the Xen virtual console driver is attached: \\
   1.679 - 'xencons=off': disable virtual console \\
   1.680 - 'xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
   1.681 - 'xencons=ttyS': attach console to /dev/ttyS0\\
   1.682 +In addition to the standard linux kernel boot options, we support: 
   1.683 +\begin{description} 
   1.684 +\item[xencons=xxx ] Specify the device node to which the Xen virtual
   1.685 +console driver is attached. The following options are supported:
   1.686 +\begin{center}
   1.687 +\begin{tabular}{l}
   1.688 +`xencons=off': disable virtual console \\ 
   1.689 +`xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
   1.690 +`xencons=ttyS': attach console to /dev/ttyS0
   1.691 +\end{tabular}
   1.692 +\end{center}
   1.693  The default is ttyS for dom0 and tty for all other domains.
   1.694 +\end{description} 
   1.695 +
   1.696 +
   1.697 +
   1.698 +\section{Debugging}
   1.699 +\label{s:keys} 
   1.700 +
   1.701 +Xen has a set of debugging features that can be useful to try and
   1.702 +figure out what's going on. Hit 'h' on the serial line (if you
   1.703 +specified a baud rate on the Xen command line) or ScrollLock-h on the
   1.704 +keyboard to get a list of supported commands.
   1.705 +
   1.706 +If you have a crash you'll likely get a crash dump containing an EIP
   1.707 +(PC) which, along with an 'objdump -d image', can be useful in
   1.708 +figuring out what's happened.  Debug a Xenlinux image just as you
   1.709 +would any other Linux kernel.
   1.710 +
   1.711 +%% We supply a handy debug terminal program which you can find in
   1.712 +%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/}
   1.713 +%% This should be built and executed on another machine that is connected
   1.714 +%% via a null modem cable. Documentation is included.
   1.715 +%% Alternatively, if the Xen machine is connected to a serial-port server
   1.716 +%% then we supply a dumb TCP terminal client, {\tt xencons}.
   1.717 +
   1.718 +
   1.719 +
   1.720  
   1.721  \chapter{Further Support}
   1.722  
   1.723 @@ -1455,13 +1464,13 @@ into this manual.
   1.724  
   1.725  \section{Online references}
   1.726  
   1.727 -The official Xen web site is found at: \\
   1.728 -{\tt
   1.729 -http://www.cl.cam.ac.uk/Research/SRG/netos/xen/] }.
   1.730 +The official Xen web site is found at:
   1.731 +\begin{quote}
   1.732 +{\tt http://www.cl.cam.ac.uk/Research/SRG/netos/xen/}
   1.733 +\end{quote}
   1.734  
   1.735 -Links to other
   1.736 -documentation sources are listed at: \\ {\tt
   1.737 -http://www.cl.cam.ac.uk/Research/SRG/netos/xen/documentation.html}.
   1.738 +This contains links to the latest versions of all on-line 
   1.739 +documentation. 
   1.740  
   1.741  \section{Mailing lists}
   1.742  
   1.743 @@ -1470,13 +1479,13 @@ There are currently three official Xen m
   1.744  \begin{description}
   1.745  \item[xen-devel@lists.sourceforge.net] Used for development
   1.746  discussions and requests for help.  Subscribe at: \\
   1.747 -{\tt http://lists.sourceforge.net/mailman/listinfo/xen-devel}
   1.748 +{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-devel}}
   1.749  \item[xen-announce@lists.sourceforge.net] Used for announcements only.
   1.750  Subscribe at: \\
   1.751 -{\tt http://lists.sourceforge.net/mailman/listinfo/xen-announce}
   1.752 +{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-announce}}
   1.753  \item[xen-changelog@lists.sourceforge.net]  Changelog feed
   1.754  from the unstable and 2.0 trees - developer oriented.  Subscribe at: \\
   1.755 -{\tt http://lists.sourceforge.net/mailman/listinfo/xen-changelog}
   1.756 +{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-changelog}}
   1.757  \end{description}
   1.758  
   1.759  Although there is no specific user support list, the developers try to
   1.760 @@ -1485,12 +1494,13 @@ list increases, a dedicated user support
   1.761  
   1.762  \appendix
   1.763  
   1.764 +
   1.765  \chapter{Installing Debian}
   1.766  
   1.767 -The Debian project provides a tool called {\tt debootstrap} which
   1.768 +The Debian project provides a tool called {\small {\tt debootstrap}} which
   1.769  allows a base Debian system to be installed into a filesystem without
   1.770  requiring the host system to have any Debian-specific software (such
   1.771 -as {\tt apt}).
   1.772 +as {\small {\tt apt}}).
   1.773  
   1.774  Here's some info how to install Debian 3.1 (Sarge) for an unprivileged
   1.775  Xen domain:
   1.776 @@ -1502,116 +1512,116 @@ Xen domain:
   1.777  \item Create disk images for root-fs and swap (alternatively, you
   1.778        might create dedicated partitions, LVM logical volumes, etc. if
   1.779        that suits your setup).
   1.780 -\begin{verbatim}  
   1.781 +\begin{small}\begin{verbatim}  
   1.782  dd if=/dev/zero of=/path/diskimage bs=1024k count=size_in_mbytes
   1.783  dd if=/dev/zero of=/path/swapimage bs=1024k count=size_in_mbytes
   1.784 -\end{verbatim}
   1.785 +\end{verbatim}\end{small}
   1.786        If you're going to use this filesystem / diskimage only as a
   1.787        `template' for other vm diskimages, something like 300 MB should
   1.788        be enough.. (of course it depends what kind of packages you are
   1.789        planning to install to the template)
   1.790  
   1.791  \item Create the filesystem and initialise the swap image
   1.792 -\begin{verbatim}
   1.793 +\begin{small}\begin{verbatim}
   1.794  mkfs.ext3 /path/diskimage
   1.795  mkswap /path/swapimage
   1.796 -\end{verbatim}
   1.797 +\end{verbatim}\end{small}
   1.798  
   1.799  \item Mount the diskimage for installation
   1.800 -\begin{verbatim}
   1.801 +\begin{small}\begin{verbatim}
   1.802  mount -o loop /path/diskimage /mnt/disk
   1.803 -\end{verbatim}
   1.804 +\end{verbatim}\end{small}
   1.805  
   1.806 -\item Install {\tt debootstrap}
   1.807 +\item Install {\small {\tt debootstrap}}
   1.808  
   1.809  Make sure you have debootstrap installed on the host.  If you are
   1.810  running Debian sarge (3.1 / testing) or unstable you can install it by
   1.811 -running {\tt apt-get install debootstrap}.  Otherwise, it can be
   1.812 +running {\small {\tt apt-get install debootstrap}}.  Otherwise, it can be
   1.813  downloaded from the Debian project website.
   1.814  
   1.815  \item Install debian base to the diskimage:
   1.816 -\begin{verbatim}
   1.817 +\begin{small}\begin{verbatim}
   1.818  debootstrap --arch i386 sarge /mnt/disk  \
   1.819              http://ftp.<countrycode>.debian.org/debian
   1.820 -\end{verbatim}
   1.821 +\end{verbatim}\end{small}
   1.822  
   1.823  You can use any other Debian http/ftp mirror you want.
   1.824  
   1.825  \item When debootstrap completes successfully, modify settings:
   1.826 -\begin{verbatim}
   1.827 +\begin{small}\begin{verbatim}
   1.828  chroot /mnt/disk /bin/bash
   1.829 -\end{verbatim}
   1.830 +\end{verbatim}\end{small}
   1.831  
   1.832  Edit the following files using vi or nano and make needed changes:
   1.833 -\begin{verbatim}
   1.834 +\begin{small}\begin{verbatim}
   1.835  /etc/hostname
   1.836  /etc/hosts
   1.837  /etc/resolv.conf
   1.838  /etc/network/interfaces
   1.839  /etc/networks
   1.840 -\end{verbatim}
   1.841 +\end{verbatim}\end{small}
   1.842  
   1.843  Set up access to the services, edit:
   1.844 -\begin{verbatim}
   1.845 +\begin{small}\begin{verbatim}
   1.846  /etc/hosts.deny
   1.847  /etc/hosts.allow
   1.848  /etc/inetd.conf
   1.849 -\end{verbatim}
   1.850 +\end{verbatim}\end{small}
   1.851  
   1.852  Add Debian mirror to:   
   1.853 -\begin{verbatim}
   1.854 +\begin{small}\begin{verbatim}
   1.855  /etc/apt/sources.list
   1.856 -\end{verbatim}
   1.857 +\end{verbatim}\end{small}
   1.858  
   1.859  Create fstab like this:
   1.860 -\begin{verbatim}
   1.861 +\begin{small}\begin{verbatim}
   1.862  /dev/sda1       /       ext3    errors=remount-ro       0       1
   1.863  /dev/sda2       none    swap    sw                      0       0
   1.864  proc            /proc   proc    defaults                0       0
   1.865 -\end{verbatim}
   1.866 +\end{verbatim}\end{small}
   1.867  
   1.868  Logout
   1.869  
   1.870  \item      Umount the diskimage
   1.871 -\begin{verbatim}
   1.872 +\begin{small}\begin{verbatim}
   1.873  umount /mnt/disk
   1.874 -\end{verbatim}
   1.875 +\end{verbatim}\end{small}
   1.876  
   1.877  \item Create Xen 2.0 configuration file for the new domain. You can
   1.878          use the example-configurations coming with xen as a template.
   1.879  
   1.880          Make sure you have the following set up:
   1.881 -\begin{verbatim}
   1.882 +\begin{small}\begin{verbatim}
   1.883  disk = [ 'file:/path/diskimage,sda1,w', 'file:/path/swapimage,sda2,w' ]
   1.884  root = "/dev/sda1 ro"
   1.885 -\end{verbatim}
   1.886 +\end{verbatim}\end{small}
   1.887  
   1.888  \item Start the new domain
   1.889 -\begin{verbatim}
   1.890 +\begin{small}\begin{verbatim}
   1.891  xm create -f domain_config_file
   1.892 -\end{verbatim}
   1.893 +\end{verbatim}\end{small}
   1.894  
   1.895  Check that the new domain is running:
   1.896 -\begin{verbatim}
   1.897 +\begin{small}\begin{verbatim}
   1.898  xm list
   1.899 -\end{verbatim}
   1.900 +\end{verbatim}\end{small}
   1.901  
   1.902  \item   Attach to the console of the new domain.
   1.903          You should see something like this when starting the new domain:
   1.904  
   1.905 -\begin{verbatim}
   1.906 +\begin{small}\begin{verbatim}
   1.907  Started domain testdomain2, console on port 9626
   1.908 -\end{verbatim}
   1.909 +\end{verbatim}\end{small}
   1.910          
   1.911          There you can see the ID of the console: 26. You can also list
   1.912 -        the consoles with {\tt xm consoles"}. (ID is the last two
   1.913 +        the consoles with {\small {\tt xm consoles}} (ID is the last two
   1.914          digits of the portnumber.)
   1.915  
   1.916          Attach to the console:
   1.917  
   1.918 -\begin{verbatim}
   1.919 +\begin{small}\begin{verbatim}
   1.920  xm console 26
   1.921 -\end{verbatim}
   1.922 +\end{verbatim}\end{small}
   1.923  
   1.924          or by telnetting to the port 9626 of localhost (the xm console
   1.925          progam works better).
   1.926 @@ -1624,21 +1634,22 @@ xm console 26
   1.927          errors.  Check that the swap is active, and the network settings are
   1.928          correct.
   1.929  
   1.930 -        Run {\tt /usr/sbin/base-config} to set up the Debian settings.
   1.931 +        Run {\small {\tt/usr/sbin/base-config}} to set up the Debian settings.
   1.932  
   1.933          Set up the password for root using passwd.
   1.934  
   1.935 -\item     Done. You can exit the console by pressing {\tt Ctrl + ]}
   1.936 +\item     Done. You can exit the console by pressing {\small {\tt Ctrl + ]}}
   1.937  
   1.938  \end{enumerate}
   1.939  
   1.940  If you need to create new domains, you can just copy the contents of
   1.941  the `template'-image to the new disk images, either by mounting the
   1.942 -template and the new image, and using {\tt cp -a} or {\tt tar} or by
   1.943 +template and the new image, and using {\small {\tt cp -a}} or {\small
   1.944 +    {\tt tar}} or by
   1.945  simply copying the image file.  Once this is done, modify the
   1.946  image-specific settings (hostname, network settings, etc).
   1.947  
   1.948 -\chapter{Installing Xen / XenLinux on Redhat / Fedora}
   1.949 +\chapter{Installing Xen / XenLinux on Redhat or Fedora Core}
   1.950  
   1.951  When using Xen / Xenlinux on a standard Linux distribution there are
   1.952  a couple of things to watch out for:
   1.953 @@ -1670,13 +1681,13 @@ systems way to late in the boot process.
   1.954  this was to have a \path{/linuxrc} script run ahead of
   1.955  \path{/sbin/init} that mounts \path{/usr}:
   1.956  
   1.957 -\begin{verbatim}
   1.958 +\begin{small}\begin{verbatim}
   1.959   #!/bin/bash
   1.960   /sbin/ipconfig lo 127.0.0.1
   1.961   /sbin/portmap
   1.962   /bin/mount /usr
   1.963   exec /sbin/init "$@" <>/dev/console 2>&1
   1.964 -\end{verbatim}
   1.965 +\end{verbatim}\end{small}
   1.966  
   1.967  %$ XXX SMH: font lock fix :-)  
   1.968