diff options
| author | David Brownell <dbrownell@users.sourceforge.net> | 2009-01-06 14:41:01 -0800 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2009-01-06 15:59:13 -0800 |
| commit | af9379c7121d5543722c00bbd1adf7dcaa0b6448 (patch) | |
| tree | 798ddf46cd7b3edbec70d8b1af5f064d1db83532 /include/asm-generic/bug.h | |
| parent | 5f820f648c92a5ecc771a96b3c29aa6e90013bba (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>
Diffstat (limited to 'include/asm-generic/bug.h')
| -rw-r--r-- | include/asm-generic/bug.h | 17 |
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, |