view docs/misc/xen-error-handling.txt @ 18947:2dffa6ceb0af

Support S3 for MSI interrupt

From: "Jiang, Yunhong" <yunhong.jiang@intel.com>
Signed-off-by: Keir Fraser <keir.fraser@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Fri Dec 19 14:56:36 2008 +0000 (2008-12-19)
parents 1b173394f815
line source
1 Error handling in Xen
2 ---------------------
4 1. domain_crash()
5 -----------------
6 Crash the specified domain due to buggy or unsupported behaviour of the
7 guest. This should not be used where the hypervisor itself is in
8 error, even if the scope of that error affects only a single
9 domain. BUG() is a more appropriate failure method for hypervisor
10 bugs. To repeat: domain_crash() is the correct response for erroneous
11 or unsupported *guest* behaviour!
13 Note that this should be used in most cases in preference to
14 domain_crash_synchronous(): domain_crash() returns to the caller,
15 allowing the crash to be deferred for the currently executing VCPU
16 until certain resources (notably, spinlocks) have been released.
18 Example usages:
19 * Unrecoverable guest kernel stack overflows
20 * Unsupported corners of HVM device models
22 2. BUG()
23 --------
24 Crashes the host system with an informative file/line error message
25 and a backtrace. Use this to check consistency assumptions within the
26 hypervisor.
28 Be careful not to use BUG() (or BUG_ON(), or ASSERT()) for failures
29 *outside* the hypervisor software -- in particular, guest bugs (where
30 domain_crash() is more appropriate) or non-critical BIOS or hardware
31 errors (where retry or feature disable are more appropriate).
33 Example usage: In arch/x86/hvm/i8254.c an I/O port handler includes
34 the check BUG_ON(bytes != 1). We choose this extreme reaction to the
35 unexpected error case because, although it could be handled by failing
36 the I/O access or crashing the domain, it is indicative of an
37 unexpected inconsistency in the hypervisor itself (since the I/O
38 handler was only registered for single-byte accesses).
41 3. BUG_ON()
42 -----------
43 BUG_ON(...) is merely a convenient short form for "if (...) BUG()". It
44 is most commonly used as an 'always on' alternative to ASSERT().
47 4. ASSERT()
48 -----------
49 Similar to BUG_ON(), except that it is only enabled for debug builds
50 of the hypervisor. Typically ASSERT() is used only where the (usually
51 small) overheads of an always-on debug check might be considered
52 excessive. A good example might be within inner loops of time-critical
53 functions, or where an assertion is extreme paranoia (considered
54 *particularly* unlikely ever to fail).
56 In general, if in doubt, use BUG_ON() in preference to ASSERT().
59 5. panic()
60 ----------
61 Like BUG() and ASSERT() this will crash and reboot the host
62 system. However it does this after printing only an error message with
63 no extra diagnostic information such as a backtrace. panic() is
64 generally used where an unsupported system configuration is detected,
65 particularly during boot, and where extra diagnostic information about
66 CPU context would not be useful. It may also be used before exception
67 handling is enabled during Xen bootstrap (on x86, BUG() and ASSERT()
68 depend on Xen's exception-handling capabilities).
70 Example usage: Most commonly for out-of-memory errors during
71 bootstrap. The failure is unexpected since a host should always have
72 enough memory to boot Xen, but if the failure does occur then the
73 context of the failed memory allocation itself is not very
74 interesting.
77 6. Feature disable
78 ------------------
79 A possible approach to dealing with boot-time errors, rather than
80 crashing the hypervisor. It's particularly appropriate when parsing
81 non-critical BIOS tables and detecting extended hardware features.
84 7. BUILD_BUG_ON()
85 -----------------
86 Useful for assertions which can be evaluated at compile time. For
87 example, making explicit assumptions about size and alignment of C
88 structures.