From 3dee866c9bae58d4f3be9d99a8ae65c9903846ff Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Sat, 14 Mar 2020 15:29:50 -0700 Subject: [PATCH] docs: deprecated.rst: Add BUG()-family Linus continues to remind[1] people to stop using the BUG()-family of functions. We should have this better documented (even if checkpatch.pl has been warning[2] since 2015), so add more details to deprecated.rst, as a distinct place to point people to for guidance. [1] https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/ [2] https://git.kernel.org/linus/58042742cc2a7d50ca28d3a60af223b4890091a6 Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/202003141524.59C619B51A@keescook Signed-off-by: Jonathan Corbet --- Documentation/process/deprecated.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index e924d31977619..652e2aa02a66c 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -29,6 +29,28 @@ a header file, it isn't the full solution. Such interfaces must either be fully removed from the kernel, or added to this file to discourage others from using them in the future. +BUG() and BUG_ON() +------------------ +Use WARN() and WARN_ON() instead, and handle the "impossible" +error condition as gracefully as possible. While the BUG()-family +of APIs were originally designed to act as an "impossible situation" +assert and to kill a kernel thread "safely", they turn out to just be +too risky. (e.g. "In what order do locks need to be released? Have +various states been restored?") Very commonly, using BUG() will +destabilize a system or entirely break it, which makes it impossible +to debug or even get viable crash reports. Linus has `very strong +`_ +feelings `about this +`_. + +Note that the WARN()-family should only be used for "expected to +be unreachable" situations. If you want to warn about "reachable +but undesirable" situations, please use the pr_warn()-family of +functions. System owners may have set the *panic_on_warn* sysctl, +to make sure their systems do not continue running in the face of +"unreachable" conditions. (For example, see commits like `this one +`_.) + open-coded arithmetic in allocator arguments -------------------------------------------- Dynamic size calculations (especially multiplication) should not be -- 2.39.5