# HG changeset patch
# User Robb Romans <FMJ@xxxxxxxxxx>
# Node ID 63f9c8dd13d4282543b9ccf37211c78dc354da6b
# Parent e13c994bdccbfea46fd702fac8ce844c6fc8496c
Reorg patch 1 to match http://wiki.xensource.com/xenwiki/Xen3DocsToDo
First patch to reorganize the manual to match the structure in the
Xen3DocsToDo Wiki entry.
Incorporates a patch from Nivedita Singhvi to clean up the Further
Support Chapter.
Signed-off-by: Robb Romans <FMJ@xxxxxxxxxx>
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user.tex
--- a/docs/src/user.tex Fri Dec 2 15:26:57 2005
+++ b/docs/src/user.tex Fri Dec 2 21:29:25 2005
@@ -29,10 +29,10 @@
\end{center}
{\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
- developers' mailing list. Contributions of material, suggestions
- and corrections are welcome.}
+ development and as such there may be mistakes and omissions --- watch
+ out for these and please report any you find to the developers'
+ mailing list. Contributions of material, suggestions and corrections
+ are welcome.}
\vfill
\cleardoublepage
@@ -60,102 +60,84 @@
\setstretch{1.1}
-\part{Introduction and Tutorial}
+\part{Introduction}
%% Chapter Introduction moved to introduction.tex
\include{src/user/introduction}
-%% Chapter Installation moved to installation.tex
+
+\part{Installation}
+
+%% Chapter Basic Installation
\include{src/user/installation}
-%% Chapter Starting Additional Domains moved to start_addl_dom.tex
+%% Chapter Installing Xen on Debian
+\include{src/user/debian}
+
+%% Chapter Installing Xen on Fedora Core
+\include{src/user/fedora}
+
+%% Chapter Installing Xen on Gentoo Linux
+\include{src/user/gentoo}
+
+%% Chapter Installing Xen on Red Hat Enterprise Linux (RHEL)
+\include{src/user/rhel}
+
+%% Chapter Installing Xen on SuSE or SuSE SLES
+\include{src/user/suse}
+
+
+\part{Configuration and Management}
+
+%% Chapter Starting Additional Domains
\include{src/user/start_addl_dom}
-%% Chapter Domain Management Tools moved to domain_mgmt.tex
+%% Chapter Domain Management Tools
\include{src/user/domain_mgmt}
-%% Chapter Domain Filesystem Storage moved to domain_filesystem.tex
+%% Chapter Domain Filesystem Storage
\include{src/user/domain_filesystem}
-
-
-\part{User Reference Documentation}
-
-%% Chapter Control Software moved to control_software.tex
-\include{src/user/control_software}
-
-%% Chapter Domain Configuration moved to domain_configuration.tex
+%% Chapter Domain Configuration
\include{src/user/domain_configuration}
%% Chapter Securing Xen
\include{src/user/securing_xen}
-%% Chapter Build, Boot and Debug Options moved to build.tex
-\include{src/user/build}
-
-
-\chapter{Further Support}
-
-If you have questions that are not answered by this manual, the
-sources of information listed below may be of interest to you. Note
-that bug reports, suggestions and contributions related to the
-software (or the documentation) should be sent to the Xen developers'
-mailing list (address below).
-
-
-\section{Other Documentation}
-
-For developers interested in porting operating systems to Xen, the
-\emph{Xen Interface Manual} is distributed in the \path{docs/}
-directory of the Xen source distribution.
-
-% Various HOWTOs are available in \path{docs/HOWTOS} but this content
-% is being integrated into this manual.
-
-
-\section{Online References}
-
-The official Xen web site is found at:
-\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/}
-\end{quote}
-
-This contains links to the latest versions of all online
-documentation, including the latest version of the FAQ.
-
-
-\section{Mailing Lists}
-
-There are currently four official Xen mailing lists:
-
-\begin{description}
-\item[xen-devel@xxxxxxxxxxxxxxxxxxx] Used for development
- discussions and bug reports. Subscribe at: \\
- {\small {\tt http://lists.xensource.com/xen-devel}}
-\item[xen-users@xxxxxxxxxxxxxxxxxxx] Used for installation and usage
- discussions and requests for help. Subscribe at: \\
- {\small {\tt http://lists.xensource.com/xen-users}}
-\item[xen-announce@xxxxxxxxxxxxxxxxxxx] Used for announcements only.
- Subscribe at: \\
- {\small {\tt http://lists.xensource.com/xen-announce}}
-\item[xen-changelog@xxxxxxxxxxxxxxxxxxx] Changelog feed
- from the unstable and 2.0 trees - developer oriented. Subscribe at: \\
- {\small {\tt http://lists.xensource.com/xen-changelog}}
-\end{description}
-
-
+
+\part{Troubleshooting}
+
+%% Chapter Monitoring Xen
+\include{src/user/monitoring_xen}
+
+%% Chapter Debugging and Tracing
+\include{src/user/debugging}
+
+%% Chapter Known Problems
+\include{src/user/known_problems}
+
+%% Chapter Testing Xen
+\include{src/user/testing}
+
+
+\part{Reference Documentation}
+
+%% Chapter Control Software
+\include{src/user/control_software}
+
+%% Chapter Build and Boot Options
+\include{src/user/options}
+
+%% Chapter Further Support
+\include{src/user/further_support}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
-
-%% Chapter Installing Xen / XenLinux on Debian moved to debian.tex
-\include{src/user/debian}
-
-%% Chapter Installing Xen on Red Hat moved to redhat.tex
-\include{src/user/redhat}
%% Chapter Glossary of Terms moved to glossary.tex
\include{src/user/glossary}
-
-
\end{document}
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/debian.tex
--- a/docs/src/user/debian.tex Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/debian.tex Fri Dec 2 21:29:25 2005
@@ -1,4 +1,4 @@
-\chapter{Installing Xen / XenLinux on Debian}
+\chapter{Installing Xen on Debian}
The Debian project provides a tool called \path{debootstrap} which
allows a base Debian system to be installed into a filesystem without
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/installation.tex
--- a/docs/src/user/installation.tex Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/installation.tex Fri Dec 2 21:29:25 2005
@@ -1,9 +1,9 @@
-\chapter{Installation}
+\chapter{Basic Installation}
The Xen distribution includes three main components: Xen itself, ports
of Linux and NetBSD to run on Xen, and the userspace
tools required to manage a Xen-based system. This chapter describes
-how to install the Xen~2.0 distribution from source. Alternatively,
+how to install the Xen~3.0 distribution from source. Alternatively,
there may be pre-built packages available as part of your operating
system distribution.
@@ -122,16 +122,16 @@
\path{dist/install/boot/} along with the image for Xen itself and the
configuration files used during the build.
-The NetBSD port can be built using:
-\begin{quote}
-\begin{verbatim}
-# make netbsd20
-\end{verbatim}\end{quote}
-NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
-The snapshot is downloaded as part of the build process if it is not
-yet present in the \path{NETBSD\_SRC\_PATH} search path. The build
-process also downloads a toolchain which includes all of the tools
-necessary to build the NetBSD kernel under Linux.
+%The NetBSD port can be built using:
+%\begin{quote}
+%\begin{verbatim}
+%# make netbsd20
+%\end{verbatim}\end{quote}
+%NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
+%The snapshot is downloaded as part of the build process if it is not
+%yet present in the \path{NETBSD\_SRC\_PATH} search path. The build
+%process also downloads a toolchain which includes all of the tools
+%necessary to build the NetBSD kernel under Linux.
To customize the set of kernels built you need to edit the top-level
Makefile. Look for the line:
@@ -169,7 +169,7 @@
%% currently), you'll need to enable devfs and devfs mount at boot
%% time in the xen0 config. }}
-\subsection{Custom XenLinux Builds}
+\subsection{Custom Kernels}
% If you have an SMP machine you may wish to give the {\tt '-j4'}
% argument to make to get a parallel build.
@@ -206,7 +206,7 @@
suffixed privileged versions can be used to boot the system, as well
as in driver domains and unprivileged domains.
-\subsection{Installing the Binaries}
+\subsection{Installing Generated Binaries}
The files produced by the build process are stored under the
\path{dist/install/} directory. To install them in their default
@@ -307,7 +307,7 @@
\end{quote}
This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1
-stop bit and no parity. Modify these parameters for your set up.
+stop bit and no parity. Modify these parameters for your environment.
One can also configure XenLinux to share the serial console; to
achieve this append ``\path{console=ttyS0}'' to your module line.
@@ -325,38 +325,38 @@
Users of the XenLinux 2.6 kernel should disable Thread Local Storage
(TLS) (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before
-attempting to boot a XenLinux kernel\footnote{If you boot without
- first disabling TLS, you will get a warning message during the boot
- process. In this case, simply perform the rename after the machine
- is up and then run \texttt{/sbin/ldconfig} to make it take effect.}.
-You can always reenable TLS by restoring the directory to its original
-location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
+attempting to boot a XenLinux kernel\footnote{If you boot without first
+ disabling TLS, you will get a warning message during the boot process.
+ In this case, simply perform the rename after the machine is up and
+ then run \path{/sbin/ldconfig} to make it take effect.}. You can
+always reenable TLS by restoring the directory to its original location
+(i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
The reason for this is that the current TLS implementation uses
-segmentation in a way that is not permissible under Xen. If TLS is
-not disabled, an emulation mode is used within Xen which reduces
-performance substantially.
+segmentation in a way that is not permissible under Xen. If TLS is not
+disabled, an emulation mode is used within Xen which reduces performance
+substantially.
We hope that this issue can be resolved by working with Linux
-distributions to implement a minor backward-compatible change
-to the TLS library.
+distributions to implement a minor backward-compatible change to the TLS
+library.
\section{Booting Xen}
-It should now be possible to restart the system and use Xen. Reboot
-and choose the new Xen option when the Grub screen appears.
-
-What follows should look much like a conventional Linux boot. The
-first portion of the output comes from Xen itself, supplying low level
-information about itself and the underlying hardware. The last
-portion of the output comes from XenLinux.
-
-You may see some errors during the XenLinux boot. These are not
+It should now be possible to restart the system and use Xen. Reboot and
+choose the new Xen option when the Grub screen appears.
+
+What follows should look much like a conventional Linux boot. The first
+portion of the output comes from Xen itself, supplying low level
+information about itself and the underlying hardware. The last portion
+of the output comes from XenLinux.
+
+You may see some errors during the XenLinux boot. These are not
necessarily anything to worry about --- they may result from kernel
configuration differences between your XenLinux kernel and the one you
usually use.
When the boot completes, you should be able to log into your system as
-usual. If you are unable to log in, you should still be able to
-reboot with your normal Linux kernel.
+usual. If you are unable to log in, you should still be able to reboot
+with your normal Linux kernel.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/introduction.tex
--- a/docs/src/user/introduction.tex Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/introduction.tex Fri Dec 2 21:29:25 2005
@@ -1,7 +1,7 @@
\chapter{Introduction}
-Xen is a \emph{paravirtualising} virtual machine monitor (VMM), or
+Xen is a \emph{paravirtualizing} virtual machine monitor (VMM), or
``hypervisor'', for the x86 processor architecture. Xen can securely
execute multiple virtual machines on a single physical system with
close-to-native performance. The virtual machine technology
@@ -139,4 +139,4 @@
Xen 3.0 features greatly enhanced hardware support, configuration
flexibility, usability and a larger complement of supported operating
systems. This latest release takes Xen a step closer to becoming the
-definitive open source solution for virtualisation.
+definitive open source solution for virtualization.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/debugging.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/debugging.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,25 @@
+\chapter{Debugging and Tracing}
+
+\section{Debugging}
+\label{s:keys}
+
+Xen has a set of debugging features that can be useful to try and figure
+out what's going on. Hit ``h'' on the serial line (if you specified a baud
+rate on the Xen command line) or ScrollLock-h on the keyboard to get a
+list of supported commands.
+
+If you have a crash you'll likely get a crash dump containing an EIP
+(PC) which, along with an \path{objdump -d image}, can be useful in
+figuring out what's happened. Debug a Xenlinux image just as you would
+any other Linux kernel.
+
+%% We supply a handy debug terminal program which you can find in
+%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should
+%% be built and executed on another machine that is connected via a
+%% null modem cable. Documentation is included. Alternatively, if the
+%% Xen machine is connected to a serial-port server then we supply a
+%% dumb TCP terminal client, {\tt xencons}.
+
+\section{Tracing}
+
+Placeholder.
\ No newline at end of file
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/fedora.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/fedora.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,61 @@
+\chapter{Installing Xen on Red~Hat or Fedora Core}
+
+When using Xen / XenLinux on a standard Linux distribution there are a
+couple of things to watch out for:
+
+Note that, because domains greater than 0 don't have any privileged
+access at all, certain commands in the default boot sequence will fail
+e.g.\ attempts to update the hwclock, change the console font, update
+the keytable map, start apmd (power management), or gpm (mouse
+cursor). Either ignore the errors (they should be harmless), or
+remove them from the startup scripts. Deleting the following links
+are a good start: {\path{S24pcmcia}}, {\path{S09isdn}},
+{\path{S17keytable}}, {\path{S26apmd}}, {\path{S85gpm}}.
+
+If you want to use a single root file system that works cleanly for
+both domain~0 and unprivileged domains, a useful trick is to use
+different `init' run levels. For example, use run level 3 for
+domain~0, and run level 4 for other domains. This enables different
+startup scripts to be run in depending on the run level number passed
+on the kernel command line.
+
+If using NFS root files systems mounted either from an external server
+or from domain0 there are a couple of other gotchas. The default
+{\path{/etc/sysconfig/iptables}} rules block NFS, so part way through
+the boot sequence things will suddenly go dead.
+
+If you're planning on having a separate NFS {\path{/usr}} partition,
+the RH9 boot scripts don't make life easy - they attempt to mount NFS
+file systems way to late in the boot process. The easiest way I found
+to do this was to have a {\path{/linuxrc}} script run ahead of
+{\path{/sbin/init}} that mounts {\path{/usr}}:
+
+\begin{quote}
+ \begin{small}\begin{verbatim}
+ #!/bin/bash
+ /sbin/ipconfig lo 127.0.0.1
+ /sbin/portmap
+ /bin/mount /usr
+ exec /sbin/init "$@" <>/dev/console 2>&1
+\end{verbatim}\end{small}
+\end{quote}
+
+%% $ XXX SMH: font lock fix :-)
+
+The one slight complication with the above is that
+{\path{/sbin/portmap}} is dynamically linked against
+{\path{/usr/lib/libwrap.so.0}} Since this is in {\path{/usr}}, it
+won't work. This can be solved by copying the file (and link) below
+the {\path{/usr}} mount point, and just let the file be `covered' when
+the mount happens.
+
+In some installations, where a shared read-only {\path{/usr}} is being
+used, it may be desirable to move other large directories over into
+the read-only {\path{/usr}}. For example, you might replace
+{\path{/bin}}, {\path{/lib}} and {\path{/sbin}} with links into
+{\path{/usr/root/bin}}, {\path{/usr/root/lib}} and
+{\path{/usr/root/sbin}} respectively. This creates other problems for
+running the {\path{/linuxrc}} script, requiring bash, portmap, mount,
+ifconfig, and a handful of other shared libraries to be copied below
+the mount point --- a simple statically-linked C program would solve
+this problem.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/further_support.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/further_support.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,52 @@
+\chapter{Further Support}
+
+If you have questions that are not answered by this manual, the
+sources of information listed below may be of interest to you. Note
+that bug reports, suggestions and contributions related to the
+software (or the documentation) should be sent to the Xen developers'
+mailing list (address below).
+
+
+\section{Other Documentation}
+
+For developers interested in porting operating systems to Xen, the
+\emph{Xen Interface Manual} is distributed in the \path{docs/}
+directory of the Xen source distribution.
+
+
+\section{Online References}
+
+The official Xen web site is found at:
+\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/}
+\end{quote}
+
+This contains links to the latest versions of all online
+documentation, including the latest version of the FAQ.
+
+Information regarding Xen is also available at the Xen Wiki at
+\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote}
+The Xen project uses Bugzilla as its bug tracking system. You'll find
+the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/.
+
+
+\section{Mailing Lists}
+
+There are several mailing lists that are used to discuss Xen related
+topics. The most widely relevant are listed below. An official page of
+mailing lists and subscription information can be found at \begin{quote}
+ {\tt http://lists.xensource.com/} \end{quote}
+
+\begin{description}
+\item[xen-devel@xxxxxxxxxxxxxxxxxxx] Used for development
+ discussions and bug reports. Subscribe at: \\
+ {\small {\tt http://lists.xensource.com/xen-devel}}
+\item[xen-users@xxxxxxxxxxxxxxxxxxx] Used for installation and usage
+ discussions and requests for help. Subscribe at: \\
+ {\small {\tt http://lists.xensource.com/xen-users}}
+\item[xen-announce@xxxxxxxxxxxxxxxxxxx] Used for announcements only.
+ Subscribe at: \\
+ {\small {\tt http://lists.xensource.com/xen-announce}}
+\item[xen-changelog@xxxxxxxxxxxxxxxxxxx] Changelog feed
+ from the unstable and 2.0 trees - developer oriented. Subscribe at: \\
+ {\small {\tt http://lists.xensource.com/xen-changelog}}
+\end{description}
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/gentoo.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/gentoo.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Installing Xen on Gentoo Linux}
+
+Placeholder.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/known_problems.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/known_problems.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Known Problems}
+
+Problem One: No Known Problems Chapter.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/monitoring_xen.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/monitoring_xen.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Monitoring Xen}
+
+Placeholder.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/options.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/options.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,149 @@
+\chapter{Build and Boot Options}
+
+This chapter describes the build- and boot-time options which may be
+used to tailor your Xen system.
+
+
+\section{Xen Build Options}
+
+Xen provides a number of build-time options which should be set as
+environment variables or passed on make's command-line.
+
+\begin{description}
+\item[verbose=y] Enable debugging messages when Xen detects an
+ unexpected condition. Also enables console output from all domains.
+\item[debug=y] Enable debug assertions. Implies {\bf verbose=y}.
+ (Primarily useful for tracing bugs in Xen).
+\item[debugger=y] Enable the in-Xen debugger. This can be used to
+ debug Xen, guest OSes, and applications.
+\item[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.
+\item[trace=y] Enable per-cpu trace buffers which log a range of
+ events within Xen for collection by control software.
+\end{description}
+
+
+\section{Xen Boot Options}
+\label{s:xboot}
+
+These options are used to configure Xen's behaviour at runtime. They
+should be appended to Xen's command line, either manually or by
+editing \path{grub.conf}.
+
+\begin{description}
+\item [ 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.
+\item [ nosmp ] Disable SMP support. This option is implied by
+ `ignorebiostables'.
+\item [ watchdog ] Enable NMI watchdog which can report certain
+ failures.
+\item [ noirqbalance ] Disable software IRQ balancing and affinity.
+ This can be used on systems such as Dell 1850/2850 that have
+ workarounds in hardware for IRQ-routing issues.
+\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify
+ a list of pages not to be allocated for use because they contain bad
+ bytes. For example, if your memory tester says that byte 0x12345678
+ is bad, you would place `badpage=0x12345' on Xen's command line.
+\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
+ com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\
+ 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 some
+ configuration options are standard (e.g., I/O base and IRQ), then
+ only a prefix of the full configuration string need be specified. If
+ the baud rate is pre-configured (e.g., by the bootloader) then you
+ can specify `auto' in place of a numeric baud rate.
+\item [ 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 (e.g.\ console and debugger). Sharing is controlled by
+ MSB of each transmitted/received character. [NB. Default for this
+ option is `com1,vga']
+\item [ sync\_console ] Force synchronous console output. This is
+ useful if you system fails unexpectedly before it has sent all
+ available output to the console. In most cases Xen will
+ automatically enter synchronous mode when an exceptional event
+ occurs, but this option provides a manual fallback.
+\item [ 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
+ the backtick character 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 switch-char is `a'.]
+\item [ nmi=xxx ]
+ Specify what to do with an NMI parity or I/O error. \\
+ `nmi=fatal': Xen prints a diagnostic and then hangs. \\
+ `nmi=dom0': Inform DOM0 of the NMI. \\
+ `nmi=ignore': Ignore the NMI.
+\item [ mem=xxx ] Set the physical RAM address limit. Any RAM
+ appearing beyond this physical address in the memory map will be
+ ignored. This parameter may be specified with a B, K, M or G suffix,
+ representing bytes, kilobytes, megabytes and gigabytes respectively.
+ The default unit, if no suffix is specified, is kilobytes.
+\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to
+ domain0. In Xen 3.x the parameter may be specified with a B, K, M or
+ G suffix, representing bytes, kilobytes, megabytes and gigabytes
+ respectively; if no suffix is specified, the parameter defaults to
+ kilobytes. In previous versions of Xen, suffixes were not supported
+ and the value is always interpreted as kilobytes.
+\item [ 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.
+\item [ sched=xxx ] Select the CPU scheduler Xen should use. The
+ current possibilities are `bvt' (default), `atropos' and `rrobin'.
+ For more information see Section~\ref{s:sched}.
+\item [ apic\_verbosity=debug,verbose ] Print more detailed
+ information about local APIC and IOAPIC configuration.
+\item [ lapic ] Force use of local APIC even when left disabled by
+ uniprocessor BIOS.
+\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if
+ enabled by the BIOS.
+\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform.
+ This can usually be probed automatically.
+\end{description}
+
+In addition, the following options may be specified on the Xen command
+line. Since domain 0 shares responsibility for booting the platform,
+Xen will automatically propagate these options to its command line.
+These options are taken from Linux's command-line syntax with
+unchanged semantics.
+
+\begin{description}
+\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and
+ domain 0) parses the BIOS ACPI tables.
+\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to
+ ignore timer-interrupt override instructions specified by the BIOS
+ ACPI tables.
+\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs
+ that are present in the system, and instead continue to use the
+ legacy PIC.
+\end{description}
+
+
+\section{XenLinux Boot Options}
+
+In addition to the standard Linux kernel boot options, we support:
+\begin{description}
+\item[ xencons=xxx ] Specify the device node to which the Xen virtual
+ console driver is attached. The following options are supported:
+ \begin{center}
+ \begin{tabular}{l}
+ `xencons=off': disable virtual console \\
+ `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
+ `xencons=ttyS': attach console to /dev/ttyS0
+ \end{tabular}
+\end{center}
+The default is ttyS for dom0 and tty for all other domains.
+\end{description}
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/rhel.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/rhel.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Installing Xen on Red Hat Enterprise Linux (RHEL)}
+
+Placeholder.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/suse.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/suse.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Installing Xen on SuSE or SuSE Linux Enterprise Server (SLES)}
+
+Placeholder.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/testing.tex
--- /dev/null Fri Dec 2 15:26:57 2005
+++ b/docs/src/user/testing.tex Fri Dec 2 21:29:25 2005
@@ -0,0 +1,3 @@
+\chapter{Testing Xen}
+
+Placeholder.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/build.tex
--- a/docs/src/user/build.tex Fri Dec 2 15:26:57 2005
+++ /dev/null Fri Dec 2 21:29:25 2005
@@ -1,170 +0,0 @@
-\chapter{Build, Boot and Debug Options}
-
-This chapter describes the build- and boot-time options which may be
-used to tailor your Xen system.
-
-
-\section{Xen Build Options}
-
-Xen provides a number of build-time options which should be set as
-environment variables or passed on make's command-line.
-
-\begin{description}
-\item[verbose=y] Enable debugging messages when Xen detects an
- unexpected condition. Also enables console output from all domains.
-\item[debug=y] Enable debug assertions. Implies {\bf verbose=y}.
- (Primarily useful for tracing bugs in Xen).
-\item[debugger=y] Enable the in-Xen debugger. This can be used to
- debug Xen, guest OSes, and applications.
-\item[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.
-\item[trace=y] Enable per-cpu trace buffers which log a range of
- events within Xen for collection by control software.
-\end{description}
-
-
-\section{Xen Boot Options}
-\label{s:xboot}
-
-These options are used to configure Xen's behaviour at runtime. They
-should be appended to Xen's command line, either manually or by
-editing \path{grub.conf}.
-
-\begin{description}
-\item [ 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.
-\item [ nosmp ] Disable SMP support. This option is implied by
- `ignorebiostables'.
-\item [ watchdog ] Enable NMI watchdog which can report certain
- failures.
-\item [ noirqbalance ] Disable software IRQ balancing and affinity.
- This can be used on systems such as Dell 1850/2850 that have
- workarounds in hardware for IRQ-routing issues.
-\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify
- a list of pages not to be allocated for use because they contain bad
- bytes. For example, if your memory tester says that byte 0x12345678
- is bad, you would place `badpage=0x12345' on Xen's command line.
-\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
- com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\
- 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 some
- configuration options are standard (e.g., I/O base and IRQ), then
- only a prefix of the full configuration string need be specified. If
- the baud rate is pre-configured (e.g., by the bootloader) then you
- can specify `auto' in place of a numeric baud rate.
-\item [ 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 (e.g.\ console and debugger). Sharing is controlled by
- MSB of each transmitted/received character. [NB. Default for this
- option is `com1,vga']
-\item [ sync\_console ] Force synchronous console output. This is
- useful if you system fails unexpectedly before it has sent all
- available output to the console. In most cases Xen will
- automatically enter synchronous mode when an exceptional event
- occurs, but this option provides a manual fallback.
-\item [ 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
- the backtick character 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 switch-char is `a'.]
-\item [ nmi=xxx ]
- Specify what to do with an NMI parity or I/O error. \\
- `nmi=fatal': Xen prints a diagnostic and then hangs. \\
- `nmi=dom0': Inform DOM0 of the NMI. \\
- `nmi=ignore': Ignore the NMI.
-\item [ mem=xxx ] Set the physical RAM address limit. Any RAM
- appearing beyond this physical address in the memory map will be
- ignored. This parameter may be specified with a B, K, M or G suffix,
- representing bytes, kilobytes, megabytes and gigabytes respectively.
- The default unit, if no suffix is specified, is kilobytes.
-\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to
- domain0. In Xen 3.x the parameter may be specified with a B, K, M or
- G suffix, representing bytes, kilobytes, megabytes and gigabytes
- respectively; if no suffix is specified, the parameter defaults to
- kilobytes. In previous versions of Xen, suffixes were not supported
- and the value is always interpreted as kilobytes.
-\item [ 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.
-\item [ sched=xxx ] Select the CPU scheduler Xen should use. The
- current possibilities are `bvt' (default), `atropos' and `rrobin'.
- For more information see Section~\ref{s:sched}.
-\item [ apic\_verbosity=debug,verbose ] Print more detailed
- information about local APIC and IOAPIC configuration.
-\item [ lapic ] Force use of local APIC even when left disabled by
- uniprocessor BIOS.
-\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if
- enabled by the BIOS.
-\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform.
- This can usually be probed automatically.
-\end{description}
-
-In addition, the following options may be specified on the Xen command
-line. Since domain 0 shares responsibility for booting the platform,
-Xen will automatically propagate these options to its command line.
-These options are taken from Linux's command-line syntax with
-unchanged semantics.
-
-\begin{description}
-\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and
- domain 0) parses the BIOS ACPI tables.
-\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to
- ignore timer-interrupt override instructions specified by the BIOS
- ACPI tables.
-\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs
- that are present in the system, and instead continue to use the
- legacy PIC.
-\end{description}
-
-
-\section{XenLinux Boot Options}
-
-In addition to the standard Linux kernel boot options, we support:
-\begin{description}
-\item[ xencons=xxx ] Specify the device node to which the Xen virtual
- console driver is attached. The following options are supported:
- \begin{center}
- \begin{tabular}{l}
- `xencons=off': disable virtual console \\
- `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
- `xencons=ttyS': attach console to /dev/ttyS0
- \end{tabular}
-\end{center}
-The default is ttyS for dom0 and tty for all other domains.
-\end{description}
-
-
-\section{Debugging}
-\label{s:keys}
-
-Xen has a set of debugging features that can be useful to try and
-figure out what's going on. Hit `h' on the serial line (if you
-specified a baud rate on the Xen command line) or ScrollLock-h on the
-keyboard to get a list of supported commands.
-
-If you have a crash you'll likely get a crash dump containing an EIP
-(PC) which, along with an \path{objdump -d image}, can be useful in
-figuring out what's happened. Debug a Xenlinux image just as you
-would any other Linux kernel.
-
-%% We supply a handy debug terminal program which you can find in
-%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should
-%% be built and executed on another machine that is connected via a
-%% null modem cable. Documentation is included. Alternatively, if the
-%% Xen machine is connected to a serial-port server then we supply a
-%% dumb TCP terminal client, {\tt xencons}.
diff -r e13c994bdccb -r 63f9c8dd13d4 docs/src/user/redhat.tex
--- a/docs/src/user/redhat.tex Fri Dec 2 15:26:57 2005
+++ /dev/null Fri Dec 2 21:29:25 2005
@@ -1,61 +0,0 @@
-\chapter{Installing Xen / XenLinux on Red~Hat or Fedora Core}
-
-When using Xen / XenLinux on a standard Linux distribution there are a
-couple of things to watch out for:
-
-Note that, because domains greater than 0 don't have any privileged
-access at all, certain commands in the default boot sequence will fail
-e.g.\ attempts to update the hwclock, change the console font, update
-the keytable map, start apmd (power management), or gpm (mouse
-cursor). Either ignore the errors (they should be harmless), or
-remove them from the startup scripts. Deleting the following links
-are a good start: {\path{S24pcmcia}}, {\path{S09isdn}},
-{\path{S17keytable}}, {\path{S26apmd}}, {\path{S85gpm}}.
-
-If you want to use a single root file system that works cleanly for
-both domain~0 and unprivileged domains, a useful trick is to use
-different `init' run levels. For example, use run level 3 for
-domain~0, and run level 4 for other domains. This enables different
-startup scripts to be run in depending on the run level number passed
-on the kernel command line.
-
-If using NFS root files systems mounted either from an external server
-or from domain0 there are a couple of other gotchas. The default
-{\path{/etc/sysconfig/iptables}} rules block NFS, so part way through
-the boot sequence things will suddenly go dead.
-
-If you're planning on having a separate NFS {\path{/usr}} partition,
-the RH9 boot scripts don't make life easy - they attempt to mount NFS
-file systems way to late in the boot process. The easiest way I found
-to do this was to have a {\path{/linuxrc}} script run ahead of
-{\path{/sbin/init}} that mounts {\path{/usr}}:
-
-\begin{quote}
- \begin{small}\begin{verbatim}
- #!/bin/bash
- /sbin/ipconfig lo 127.0.0.1
- /sbin/portmap
- /bin/mount /usr
- exec /sbin/init "$@" <>/dev/console 2>&1
-\end{verbatim}\end{small}
-\end{quote}
-
-%% $ XXX SMH: font lock fix :-)
-
-The one slight complication with the above is that
-{\path{/sbin/portmap}} is dynamically linked against
-{\path{/usr/lib/libwrap.so.0}} Since this is in {\path{/usr}}, it
-won't work. This can be solved by copying the file (and link) below
-the {\path{/usr}} mount point, and just let the file be `covered' when
-the mount happens.
-
-In some installations, where a shared read-only {\path{/usr}} is being
-used, it may be desirable to move other large directories over into
-the read-only {\path{/usr}}. For example, you might replace
-{\path{/bin}}, {\path{/lib}} and {\path{/sbin}} with links into
-{\path{/usr/root/bin}}, {\path{/usr/root/lib}} and
-{\path{/usr/root/sbin}} respectively. This creates other problems for
-running the {\path{/linuxrc}} script, requiring bash, portmap, mount,
-ifconfig, and a handful of other shared libraries to be copied below
-the mount point --- a simple statically-linked C program would solve
-this problem.
_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog
|
Home