view docs/src/user/build.tex @ 7176:0e1838de9db8

Move XendDomainInfo.{create,recreate,parseConfig} to the top level of the
domain. This allows us to refer to them using an import statement, rather than
a from .. import. This is a step towards getting rid of the xroot hack. All
other references to XendDomainInfo methods need to be doubly qualified (once
for the module, once for the class).

Remove XendDomainDict, replacing it with a simple dictionary, folding the
get_by_name method into XendDomain.

Replace XendDomain.refresh_lock with a domains_lock which goes around any
reference to XendDomain.domains or anything that will create or destroy a
domain. This serialises most accesses through XendDomain, ensuring that we will
not return stale state when racing against the watches fired in separate
threads. This should have fixed bugs #270 and #234.

Added a number of domain_get_xyz methods. Those named xyz_nr are to allow
components internal to XendDomain (XendDomainInfo, XendCheckpoint) to call back
into XendDomain without triggering further calls to XendDomain.refresh. The
other methods simply make it clear which fallback behaviour is expected.

Replace XendDomainInfo.domain_exists with XendDomainInfo.domain_by_name; the
internals of this method needed to change to match those changes above, and it
has been a misnomer for some time.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author emellor@ewan
date Tue Oct 04 02:21:28 2005 +0100 (2005-10-04)
parents 06d84bf87159
line source
1 \chapter{Build, Boot and Debug Options}
3 This chapter describes the build- and boot-time options which may be
4 used to tailor your Xen system.
7 \section{Xen Build Options}
9 Xen provides a number of build-time options which should be set as
10 environment variables or passed on make's command-line.
12 \begin{description}
13 \item[verbose=y] Enable debugging messages when Xen detects an
14 unexpected condition. Also enables console output from all domains.
15 \item[debug=y] Enable debug assertions. Implies {\bf verbose=y}.
16 (Primarily useful for tracing bugs in Xen).
17 \item[debugger=y] Enable the in-Xen debugger. This can be used to
18 debug Xen, guest OSes, and applications.
19 \item[perfc=y] Enable performance counters for significant events
20 within Xen. The counts can be reset or displayed on Xen's console
21 via console control keys.
22 \item[trace=y] Enable per-cpu trace buffers which log a range of
23 events within Xen for collection by control software.
24 \end{description}
27 \section{Xen Boot Options}
28 \label{s:xboot}
30 These options are used to configure Xen's behaviour at runtime. They
31 should be appended to Xen's command line, either manually or by
32 editing \path{grub.conf}.
34 \begin{description}
35 \item [ noreboot ] Don't reboot the machine automatically on errors.
36 This is useful to catch debug output if you aren't catching console
37 messages via the serial line.
38 \item [ nosmp ] Disable SMP support. This option is implied by
39 `ignorebiostables'.
40 \item [ watchdog ] Enable NMI watchdog which can report certain
41 failures.
42 \item [ noirqbalance ] Disable software IRQ balancing and affinity.
43 This can be used on systems such as Dell 1850/2850 that have
44 workarounds in hardware for IRQ-routing issues.
45 \item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify
46 a list of pages not to be allocated for use because they contain bad
47 bytes. For example, if your memory tester says that byte 0x12345678
48 is bad, you would place `badpage=0x12345' on Xen's command line.
49 \item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
50 com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\
51 Xen supports up to two 16550-compatible serial ports. For example:
52 `com1=9600, 8n1, 0x408, 5' maps COM1 to a 9600-baud port, 8 data
53 bits, no parity, 1 stop bit, I/O port base 0x408, IRQ 5. If some
54 configuration options are standard (e.g., I/O base and IRQ), then
55 only a prefix of the full configuration string need be specified. If
56 the baud rate is pre-configured (e.g., by the bootloader) then you
57 can specify `auto' in place of a numeric baud rate.
58 \item [ console=$<$specifier list$>$ ] Specify the destination for Xen
59 console I/O. This is a comma-separated list of, for example:
60 \begin{description}
61 \item[ vga ] Use VGA console and allow keyboard input.
62 \item[ com1 ] Use serial port com1.
63 \item[ com2H ] Use serial port com2. Transmitted chars will have the
64 MSB set. Received chars must have MSB set.
65 \item[ com2L] Use serial port com2. Transmitted chars will have the
66 MSB cleared. Received chars must have MSB cleared.
67 \end{description}
68 The latter two examples allow a single port to be shared by two
69 subsystems (e.g.\ console and debugger). Sharing is controlled by
70 MSB of each transmitted/received character. [NB. Default for this
71 option is `com1,vga']
72 \item [ sync\_console ] Force synchronous console output. This is
73 useful if you system fails unexpectedly before it has sent all
74 available output to the console. In most cases Xen will
75 automatically enter synchronous mode when an exceptional event
76 occurs, but this option provides a manual fallback.
77 \item [ conswitch=$<$switch-char$><$auto-switch-char$>$ ] Specify how
78 to switch serial-console input between Xen and DOM0. The required
79 sequence is CTRL-$<$switch-char$>$ pressed three times. Specifying
80 the backtick character disables switching. The
81 $<$auto-switch-char$>$ specifies whether Xen should auto-switch
82 input to DOM0 when it boots --- if it is `x' then auto-switching is
83 disabled. Any other value, or omitting the character, enables
84 auto-switching. [NB. Default switch-char is `a'.]
85 \item [ nmi=xxx ]
86 Specify what to do with an NMI parity or I/O error. \\
87 `nmi=fatal': Xen prints a diagnostic and then hangs. \\
88 `nmi=dom0': Inform DOM0 of the NMI. \\
89 `nmi=ignore': Ignore the NMI.
90 \item [ mem=xxx ] Set the physical RAM address limit. Any RAM
91 appearing beyond this physical address in the memory map will be
92 ignored. This parameter may be specified with a B, K, M or G suffix,
93 representing bytes, kilobytes, megabytes and gigabytes respectively.
94 The default unit, if no suffix is specified, is kilobytes.
95 \item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to
96 domain0. In Xen 3.x the parameter may be specified with a B, K, M or
97 G suffix, representing bytes, kilobytes, megabytes and gigabytes
98 respectively; if no suffix is specified, the parameter defaults to
99 kilobytes. In previous versions of Xen, suffixes were not supported
100 and the value is always interpreted as kilobytes.
101 \item [ tbuf\_size=xxx ] Set the size of the per-cpu trace buffers, in
102 pages (default 1). Note that the trace buffers are only enabled in
103 debug builds. Most users can ignore this feature completely.
104 \item [ sched=xxx ] Select the CPU scheduler Xen should use. The
105 current possibilities are `bvt' (default), `atropos' and `rrobin'.
106 For more information see Section~\ref{s:sched}.
107 \item [ apic\_verbosity=debug,verbose ] Print more detailed
108 information about local APIC and IOAPIC configuration.
109 \item [ lapic ] Force use of local APIC even when left disabled by
110 uniprocessor BIOS.
111 \item [ nolapic ] Ignore local APIC in a uniprocessor system, even if
112 enabled by the BIOS.
113 \item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform.
114 This can usually be probed automatically.
115 \end{description}
117 In addition, the following options may be specified on the Xen command
118 line. Since domain 0 shares responsibility for booting the platform,
119 Xen will automatically propagate these options to its command line.
120 These options are taken from Linux's command-line syntax with
121 unchanged semantics.
123 \begin{description}
124 \item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and
125 domain 0) parses the BIOS ACPI tables.
126 \item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to
127 ignore timer-interrupt override instructions specified by the BIOS
128 ACPI tables.
129 \item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs
130 that are present in the system, and instead continue to use the
131 legacy PIC.
132 \end{description}
135 \section{XenLinux Boot Options}
137 In addition to the standard Linux kernel boot options, we support:
138 \begin{description}
139 \item[ xencons=xxx ] Specify the device node to which the Xen virtual
140 console driver is attached. The following options are supported:
141 \begin{center}
142 \begin{tabular}{l}
143 `xencons=off': disable virtual console \\
144 `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
145 `xencons=ttyS': attach console to /dev/ttyS0
146 \end{tabular}
147 \end{center}
148 The default is ttyS for dom0 and tty for all other domains.
149 \end{description}
152 \section{Debugging}
153 \label{s:keys}
155 Xen has a set of debugging features that can be useful to try and
156 figure out what's going on. Hit `h' on the serial line (if you
157 specified a baud rate on the Xen command line) or ScrollLock-h on the
158 keyboard to get a list of supported commands.
160 If you have a crash you'll likely get a crash dump containing an EIP
161 (PC) which, along with an \path{objdump -d image}, can be useful in
162 figuring out what's happened. Debug a Xenlinux image just as you
163 would any other Linux kernel.
165 %% We supply a handy debug terminal program which you can find in
166 %% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should
167 %% be built and executed on another machine that is connected via a
168 %% null modem cable. Documentation is included. Alternatively, if the
169 %% Xen machine is connected to a serial-port server then we supply a
170 %% dumb TCP terminal client, {\tt xencons}.