diff --git a/share/man/man9/KASSERT.9 b/share/man/man9/KASSERT.9 --- 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 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1333,6 +1333,7 @@ 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