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