The branch main has been updated by mhorne:
URL:
https://cgit.FreeBSD.org/src/commit/?id=36de8bb226671ef9fe373d8d95f77cdb76157738
commit 36de8bb226671ef9fe373d8d95f77cdb76157738
Author: Mitchell Horne <mho...@freebsd.org>
AuthorDate: 2024-03-21 15:21:41 +0000
Commit: Mitchell Horne <mho...@freebsd.org>
CommitDate: 2024-03-21 15:24:47 +0000
kassert.h: update MPASS definition commentary
We now have a detailed man page describing both MPASS and KASSERT. Give
a warning that careless use of MPASS can result in inadequate assertion
messages, and point to the MPASS(9) page which describes this.
While here add a comment above the KASSERT definitions pointing to the
man page.
Suggested by: bz
Reviewed by: emaste
MFC after: 1 week
Sponsored by: The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D44438
---
sys/sys/kassert.h | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/sys/sys/kassert.h b/sys/sys/kassert.h
index 25e2b025a11a..ab2313bcbd8b 100644
--- a/sys/sys/kassert.h
+++ b/sys/sys/kassert.h
@@ -142,6 +142,9 @@ void kassert_panic(const char *fmt, ...)
__printflike(1, 2);
# endif /* defined(WITNESS) || defined(INVARIANT_SUPPORT) */
#endif /* _STANDALONE */
+/*
+ * Kernel assertion; see KASSERT(9) for details.
+ */
#if (defined(_KERNEL) && defined(INVARIANTS)) || defined(_STANDALONE)
#define KASSERT(exp,msg) do {
\
if (__predict_false(!(exp))) \
@@ -154,8 +157,11 @@ void kassert_panic(const char *fmt, ...)
__printflike(1, 2);
#ifdef _KERNEL
/*
- * Helpful macros for quickly coming up with assertions with informative
- * panic messages.
+ * Macros for generating panic messages based on the exact condition text.
+ *
+ * NOTE: Use these with care, as the resulting message might omit key
+ * information required to understand the assertion failure. Consult the
+ * MPASS(9) man page for guidance.
*/
#define MPASS(ex) MPASS4(ex, #ex, __FILE__, __LINE__)
#define MPASS2(ex, what) MPASS4(ex, what, __FILE__, __LINE__)
