xen/docs/src/user/build.tex

\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}.