Error handling in Xen --------------------- 1. domain_crash() ----------------- Crash the specified domain due to buggy or unsupported behaviour of the guest. This should not be used where the hypervisor itself is in error, even if the scope of that error affects only a single domain. BUG() is a more appropriate failure method for hypervisor bugs. To repeat: domain_crash() is the correct response for erroneous or unsupported *guest* behaviour! Note that this should be used in most cases in preference to domain_crash_synchronous(): domain_crash() returns to the caller, allowing the crash to be deferred for the currently executing VCPU until certain resources (notably, spinlocks) have been released. Example usages: * Unrecoverable guest kernel stack overflows * Unsupported corners of HVM device models 2. BUG() -------- Crashes the host system with an informative file/line error message and a backtrace. Use this to check consistency assumptions within the hypervisor. Be careful not to use BUG() (or BUG_ON(), or ASSERT()) for failures *outside* the hypervisor software -- in particular, guest bugs (where domain_crash() is more appropriate) or non-critical BIOS or hardware errors (where retry or feature disable are more appropriate). Example usage: In arch/x86/hvm/i8254.c an I/O port handler includes the check BUG_ON(bytes != 1). We choose this extreme reaction to the unexpected error case because, although it could be handled by failing the I/O access or crashing the domain, it is indicative of an unexpected inconsistency in the hypervisor itself (since the I/O handler was only registered for single-byte accesses). 3. BUG_ON() ----------- BUG_ON(...) is merely a convenient short form for "if (...) BUG()". It is most commonly used as an 'always on' alternative to ASSERT(). 4. ASSERT() ----------- Similar to BUG_ON(), except that it is only enabled for debug builds of the hypervisor. Typically ASSERT() is used only where the (usually small) overheads of an always-on debug check might be considered excessive. A good example might be within inner loops of time-critical functions, or where an assertion is extreme paranoia (considered *particularly* unlikely ever to fail). In general, if in doubt, use BUG_ON() in preference to ASSERT(). 5. panic() ---------- Like BUG() and ASSERT() this will crash and reboot the host system. However it does this after printing only an error message with no extra diagnostic information such as a backtrace. panic() is generally used where an unsupported system configuration is detected, particularly during boot, and where extra diagnostic information about CPU context would not be useful. It may also be used before exception handling is enabled during Xen bootstrap (on x86, BUG() and ASSERT() depend on Xen's exception-handling capabilities). Example usage: Most commonly for out-of-memory errors during bootstrap. The failure is unexpected since a host should always have enough memory to boot Xen, but if the failure does occur then the context of the failed memory allocation itself is not very interesting. 6. Feature disable ------------------ A possible approach to dealing with boot-time errors, rather than crashing the hypervisor. It's particularly appropriate when parsing non-critical BIOS tables and detecting extended hardware features. 7. BUILD_BUG_ON() ----------------- Useful for assertions which can be evaluated at compile time. For example, making explicit assumptions about size and alignment of C structures.