aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Brownell <dbrownell@users.sourceforge.net>2009-01-06 14:41:01 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2009-01-06 15:59:13 -0800
commitaf9379c7121d5543722c00bbd1adf7dcaa0b6448 (patch)
tree798ddf46cd7b3edbec70d8b1af5f064d1db83532
parent5f820f648c92a5ecc771a96b3c29aa6e90013bba (diff)
documentation: when to BUG(), and when to not BUG()
Provide some basic advice about when to use BUG()/BUG_ON(): never, unless there's really no better option. This matches my understanding of the standard policy ... which seems not to be written down so far, outside of LKML messages that I haven't bookmarked. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Cc: Hans Verkuil <hverkuil@xs4all.nl> Cc: Ingo Molnar <mingo@elte.hu> Cc: Arjan van de Ven <arjan@infradead.org> Cc: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r--include/asm-generic/bug.h17
1 files changed, 17 insertions, 0 deletions
diff --git a/include/asm-generic/bug.h b/include/asm-generic/bug.h
index 8af276361bf..37b82cb96c8 100644
--- a/include/asm-generic/bug.h
+++ b/include/asm-generic/bug.h
@@ -28,6 +28,17 @@ struct bug_entry {
#define BUGFLAG_WARNING (1<<0)
#endif /* CONFIG_GENERIC_BUG */
+/*
+ * Don't use BUG() or BUG_ON() unless there's really no way out; one
+ * example might be detecting data structure corruption in the middle
+ * of an operation that can't be backed out of. If the (sub)system
+ * can somehow continue operating, perhaps with reduced functionality,
+ * it's probably not BUG-worthy.
+ *
+ * If you're tempted to BUG(), think again: is completely giving up
+ * really the *only* solution? There are usually better options, where
+ * users don't need to reboot ASAP and can mostly shut down cleanly.
+ */
#ifndef HAVE_ARCH_BUG
#define BUG() do { \
printk("BUG: failure at %s:%d/%s()!\n", __FILE__, __LINE__, __func__); \
@@ -39,6 +50,12 @@ struct bug_entry {
#define BUG_ON(condition) do { if (unlikely(condition)) BUG(); } while(0)
#endif
+/*
+ * WARN(), WARN_ON(), WARN_ON_ONCE, and so on can be used to report
+ * significant issues that need prompt attention if they should ever
+ * appear at runtime. Use the versions with printk format strings
+ * to provide better diagnostics.
+ */
#ifndef __WARN
#ifndef __ASSEMBLY__
extern void warn_slowpath(const char *file, const int line,