git: 87132d1dce4b - main - KASSERT(9): some updates

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=87132d1dce4b61c782871f450c17b818bf991ff6

commit 87132d1dce4b61c782871f450c17b818bf991ff6
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-03-20 19:54:11 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-03-20 20:12:11 +0000

    KASSERT(9): some updates
    
     - Add a little bit of introductory text
     - Improve the existing example: ANSI C, use a better assertion than a
       NULL check (which is discouraged)
     - Document the widely used MPASS macro in this page
     - Drop the cross-reference to config(8)
    
    Reviewed by:    kib, markj, rpokala, Pau Amma <pauamma@gundo.com>
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D39131
---
 share/man/man9/KASSERT.9 | 104 ++++++++++++++++++++++++++++++++++-------------
 share/man/man9/Makefile  |   1 +
 2 files changed, 76 insertions(+), 29 deletions(-)

diff --git a/share/man/man9/KASSERT.9 b/share/man/man9/KASSERT.9
index 0c6898a7799b..de2b9ca8d2a8 100644
--- a/share/man/man9/KASSERT.9
+++ b/share/man/man9/KASSERT.9
@@ -1,8 +1,11 @@
-.\" -*- nroff -*-
+.\" SPDX-License-Identifier: BSD-2-Clause
 .\"
 .\" Copyright (c) 2000 Jonathan M. Bresler
-.\"
 .\" All rights reserved.
+.\" Copyright (c) 2023 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Mitchell Horne
+.\" under sponsorship from the FreeBSD Foundation.
 .\"
 .\" This program is free software.
 .\"
@@ -28,59 +31,102 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 14, 2000
+.Dd March 16, 2023
 .Dt KASSERT 9
 .Os
 .Sh NAME
 .Nm KASSERT
-.Nd kernel expression verification macro
+.Nd kernel expression verification macros
 .Sh SYNOPSIS
 .Cd "options INVARIANTS"
 .Pp
 .In sys/param.h
 .In sys/systm.h
 .Fn KASSERT expression msg
+.Fn MPASS expression
 .Sh DESCRIPTION
-In a kernel compiled with
-.Cd "options INVARIANTS" ,
-the
-.Fn KASSERT
-macro tests the given
-.Fa expression
-and if it is false,
-calls the
+Assertions are widely used within the
+.Fx
+kernel to verify programmatic assumptions.
+For violations of run-time assumptions and invariants, it is desirable to fail
+as soon and as loudly as possible.
+Assertions are optional code; for non-recoverable error conditions an explicit
+call to
 .Xr panic 9
-function, terminating the running system.
+is usually preferred.
 .Pp
-In a kernel that does not have
+The
+.Fn KASSERT
+macro tests the given boolean
+.Fa expression .
+If
+.Fa expression
+evaluates to
+.Dv false ,
+and the kernel is compiled with
 .Cd "options INVARIANTS" ,
 the
-.Fn KASSERT
-macro is defined to be a no-op.
-The
-second argument is a
+.Xr panic 9
+function is called.
+This terminates the running system at the point of the error, possibly dropping
+into the kernel debugger or initiating a kernel core dump.
+The second argument,
+.Fa msg ,
+is a
 .Xr printf 9
 format string and its arguments,
 enclosed in parentheses.
+The formatted string will become the panic string.
+.Pp
+In a kernel that is built without
+.Cd "options INVARIANTS" ,
+the assertion macros are defined to be no-ops.
+This eliminates the runtime overhead of widespread assertions from release
+builds of the kernel.
+Therefore, checks which can be performed in a constant amount of time can be
+added as assertions without concern about their performance impact.
+More expensive checks, such as those that output to console, or verify the
+integrity of a chain of objects are generally best hidden behind the
+.Cd DIAGNOSTIC
+kernel option.
+.Pp
+The
+.Fn MPASS
+macro (read as: "must-pass")
+is a convenience wrapper around
+.Fn KASSERT
+that automatically generates a sensible assertion message including file and
+line information.
 .Sh EXAMPLES
-The kernel function
-.Fn vput
-must not be called with a
-.Dv NULL
-pointer.
+A hypothetical
+.Vt struct foo
+object must not have its 'active' flag set when calling
+.Fn foo_dealloc :
 .Bd -literal -offset indent
 void
-vput(vp)
-        struct vnode *vp;
+foo_dealloc(struct foo *fp)
 {
-	struct proc *p = curproc;
-	KASSERT(vp != NULL, ("vput: null vp"));
+
+	KASSERT((fp->foo_flags & FOO_ACTIVE) == 0,
+	    ("%s: fp %p is still active", __func__, fp));
 	...
 }
 .Ed
+.Pp
+The assertion
+.Bd -literal -offset indent
+MPASS(td == curthread);
+.Ed
+.Pp
+located on line 87 of a file named foo.c would generate the following panic
+message:
+.Bd -literal -offset indent
+panic: Assertion td == curthread failed at foo.c:87
+.Ed
 .Sh SEE ALSO
-.Xr config 8 ,
 .Xr panic 9
 .Sh AUTHORS
 This manual page was written by
-.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org .
+.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org
+and
+.An Mitchell Horne Aq Mt mhorne@FreeBSD.org .
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index fdd81ba18b11..875a7f52be77 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1334,6 +1334,7 @@ MLINKS+=intr_event.9 intr_event_add_handler.9 \
 	intr_event.9 intr_event_handle.9 \
 	intr_event.9 intr_event_remove_handler.9 \
 	intr_event.9 intr_priority.9
+MLINKS+=KASSERT.9 MPASS.9
 MLINKS+=kern_yield.9 maybe_yield.9 \
 	kern_yield.9 should_yield.9
 MLINKS+=kernacc.9 useracc.9