summaryrefslogtreecommitdiff
path: root/Documentation/process
diff options
context:
space:
mode:
authorKees Cook <keescook@chromium.org>2020-03-14 15:29:50 -0700
committerJonathan Corbet <corbet@lwn.net>2020-03-20 17:24:49 -0600
commit7af51678b6d367ee93dc3d21e72ecf15be50fcb1 (patch)
tree2135504e098dcb80bc953c62692baffe551b9e14 /Documentation/process
parent6735c208c1326f2d56bdcd1f41f6062baef73bec (diff)
downloadlwn-7af51678b6d367ee93dc3d21e72ecf15be50fcb1.tar.gz
lwn-7af51678b6d367ee93dc3d21e72ecf15be50fcb1.zip
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/9d3e3c705eb395528fd8f17208c87581b134da48 Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/202003141524.59C619B51A@keescook Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/process')
-rw-r--r--Documentation/process/deprecated.rst22
1 files changed, 22 insertions, 0 deletions
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index e924d3197761..652e2aa02a66 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
+<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_
+feelings `about this
+<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_.
+
+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
+<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
+
open-coded arithmetic in allocator arguments
--------------------------------------------
Dynamic size calculations (especially multiplication) should not be