From: John Hubbard <jhubbard@nvidia.com>
To: David Hildenbrand <david@redhat.com>, linux-kernel@vger.kernel.org
Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com>,
Baoquan He <bhe@redhat.com>,
linux-doc@vger.kernel.org, linuxppc-dev@lists.ozlabs.org,
Dave Young <dyoung@redhat.com>, Jonathan Corbet <corbet@lwn.net>,
Nicholas Piggin <npiggin@gmail.com>,
Jani Nikula <jani.nikula@linux.intel.com>,
linux-mm@kvack.org, David Laight <David.Laight@ACULAB.COM>,
Dwaipayan Ray <dwaipayanray1@gmail.com>,
Andy Whitcroft <apw@canonical.com>, Joe Perches <joe@perches.com>,
Andrew Morton <akpm@linux-foundation.org>,
Linus Torvalds <torvalds@linux-foundation.org>,
Ingo Molnar <mingo@kernel.org>, Vivek Goyal <vgoyal@redhat.com>
Subject: Re: [PATCH v1 1/3] coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel")
Date: Thu, 22 Sep 2022 19:26:35 -0700 [thread overview]
Message-ID: <3dcbcc7b-9ca0-1465-5a73-075a1c151331@nvidia.com> (raw)
In-Reply-To: <20220920122302.99195-2-david@redhat.com>
On 9/20/22 05:23, David Hildenbrand wrote:
> [1] https://lkml.kernel.org/r/CAHk-=wiEAH+ojSpAgx_Ep=NKPWHU8AdO3V56BXcCsU97oYJ1EA@mail.gmail.com
> [2] https://lore.kernel.org/r/CAHk-=wg40EAZofO16Eviaj7mfqDhZ2gVEbvfsMf6gYzspRjYvw@mail.gmail.com
> [2] https://lkml.kernel.org/r/CAHk-=wit-DmhMfQErY29JSPjFgebx_Ld+pnerc4J2Ag990WwAA@mail.gmail.com
s/2/3/
...
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 03eb53fd029a..e05899cbfd49 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1186,6 +1186,67 @@ expression used. For instance:
> #endif /* CONFIG_SOMETHING */
>
>
> +22) Do not crash the kernel
> +---------------------------
> +
> +In general, it is not the kernel developer's decision to crash the kernel.
What do you think of this alternate wording:
In general, the decision to crash the kernel belongs to the user, rather
than to the kernel developer.
> +
> +Avoid panic()
> +=============
> +
> +panic() should be used with care and primarily only during system boot.
> +panic() is, for example, acceptable when running out of memory during boot and
> +not being able to continue.
> +
> +Use WARN() rather than BUG()
> +============================
> +
> +Do not add new code that uses any of the BUG() variants, such as BUG(),
> +BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably
> +WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not
> +required if there is no reasonable way to at least partially recover.
> +
> +"I'm too lazy to do error handling" is not an excuse for using BUG(). Major
> +internal corruptions with no way of continuing may still use BUG(), but need
> +good justification.
> +
> +Use WARN_ON_ONCE() rather than WARN() or WARN_ON()
> +**************************************************
> +
> +WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it
> +is common for a given warning condition, if it occurs at all, to occur
> +multiple times. This can fill up and wrap the kernel log, and can even slow
> +the system enough that the excessive logging turns into its own, additional
> +problem.
> +
> +Do not WARN lightly
> +*******************
> +
> +WARN*() is intended for unexpected, this-should-never-happen situations.
> +WARN*() macros are not to be used for anything that is expected to happen
> +during normal operation. These are not pre- or post-condition asserts, for
> +example. Again: WARN*() must not be used for a condition that is expected
> +to trigger easily, for example, by user space actions. pr_warn_once() is a
> +possible alternative, if you need to notify the user of a problem.
> +
> +Do not worry about panic_on_warn users
> +**************************************
> +
> +A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an
> +available kernel option, and that many users set this option. This is why
> +there is a "Do not WARN lightly" writeup, above. However, the existence of
> +panic_on_warn users is not a valid reason to avoid the judicious use
> +WARN*(). That is because, whoever enables panic_on_warn has explicitly
> +asked the kernel to crash if a WARN*() fires, and such users must be
> +prepared to deal with the consequences of a system that is somewhat more
> +likely to crash.
> +
> +Use BUILD_BUG_ON() for compile-time assertions
> +**********************************************
> +
> +The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
> +compile-time assertion that has no effect at runtime.
> +
> Appendix I) References
> ----------------------
>
I like the wording, it feels familiar somehow! :)
Reviewed-by: John Hubbard <jhubbard@nvidia.com>
thanks,
--
John Hubbard
NVIDIA
next prev parent reply other threads:[~2022-09-23 2:27 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-09-20 12:22 [PATCH v1 0/3] coding-style.rst: document BUG() and WARN() rules David Hildenbrand
2022-09-20 12:23 ` [PATCH v1 1/3] coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") David Hildenbrand
2022-09-21 4:40 ` Kalle Valo
2022-09-22 14:12 ` David Hildenbrand
2022-09-26 7:44 ` Kalle Valo
2022-10-04 12:32 ` David Hildenbrand
2022-09-22 13:43 ` Akira Yokosawa
2022-09-22 14:41 ` David Hildenbrand
2022-09-23 2:26 ` John Hubbard [this message]
2022-09-23 2:37 ` John Hubbard
2022-09-23 10:55 ` David Hildenbrand
2022-09-20 12:23 ` [PATCH v1 2/3] powerpc/prom_init: drop PROM_BUG() David Hildenbrand
2022-09-21 13:02 ` Michael Ellerman
2022-09-21 13:03 ` David Hildenbrand
2022-09-20 12:23 ` [PATCH v1 3/3] checkpatch: warn on usage of VM_BUG_ON() and other BUG variants David Hildenbrand
2022-09-23 2:05 ` John Hubbard
2022-09-23 2:11 ` Joe Perches
2022-09-23 2:20 ` John Hubbard
2022-09-23 10:58 ` David Hildenbrand
2022-10-04 13:24 ` (subset) [PATCH v1 0/3] coding-style.rst: document BUG() and WARN() rules Michael Ellerman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3dcbcc7b-9ca0-1465-5a73-075a1c151331@nvidia.com \
--to=jhubbard@nvidia.com \
--cc=David.Laight@ACULAB.COM \
--cc=akpm@linux-foundation.org \
--cc=apw@canonical.com \
--cc=bhe@redhat.com \
--cc=corbet@lwn.net \
--cc=david@redhat.com \
--cc=dwaipayanray1@gmail.com \
--cc=dyoung@redhat.com \
--cc=jani.nikula@linux.intel.com \
--cc=joe@perches.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=lukas.bulwahn@gmail.com \
--cc=mingo@kernel.org \
--cc=npiggin@gmail.com \
--cc=torvalds@linux-foundation.org \
--cc=vgoyal@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).