Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit af9379c7 authored by David Brownell's avatar David Brownell Committed by Linus Torvalds
Browse files

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: default avatarDavid 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: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 5f820f64

include/asm-generic/bug.h

+17 −0
Original line number Diff line number Diff line
@@ -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,