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,95 @@ .\" .\" $FreeBSD$ .\" -.Dd January 14, 2000 +.Dd February 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 +.In sys/kassert.h .Fn KASSERT expression msg +.Fn MPASS expression .Sh DESCRIPTION -In a kernel compiled with -.Cd "options INVARIANTS" , -the +Assertions are widely used within the +.Fx +kernel to verify programmatic assumptions. +For run-time assumptions, invariants, and other non-recoverable errors, it is +desirable to fail as soon and as loudly as possible. +.Pp +The .Fn KASSERT -macro tests the given +macro tests the given boolean +.Fa expression . +If .Fa expression -and if it is false, -calls the -.Xr panic 9 -function, terminating the running system. -.Pp -In a kernel that does not have +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. +The second argument, +.Fa msg , +is a .Xr printf 9 format string and its arguments, enclosed in parentheses. +.Fa msg +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, programmers should not avoid the use of assertions for performance +concerns, except in extreme cases. +.Pp +The +.Fn MPASS +macro (read as: "must-pass") +is a convenience wrapper around +.Fn KASSERT +that generates a sensible assertion message including file and line +information. .Sh EXAMPLES -The kernel function -.Fn vput +The function +.Fn foo must not be called with a .Dv NULL pointer. .Bd -literal -offset indent void -vput(vp) - struct vnode *vp; +foo(struct bar *bp) { - struct proc *p = curproc; - KASSERT(vp != NULL, ("vput: null vp")); + + KASSERT(bp != NULL, ("foo: null bp")); ... } .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 == cuthread 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