Date: Mon, 27 Mar 2023 17:21:53 GMT From: Mitchell Horne <mhorne@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org Subject: git: d85a53128792 - stable/13 - KASSERT(9): some updates Message-ID: <202303271721.32RHLrit050446@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=d85a5312879247569f9ca4e3a3ebab2833e6d84a commit d85a5312879247569f9ca4e3a3ebab2833e6d84a Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-03-20 19:54:11 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-03-27 17:18:14 +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 (cherry picked from commit 87132d1dce4b61c782871f450c17b818bf991ff6) --- 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 ed6de288cfa4..bab0cfb76134 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1338,6 +1338,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+=kernacc.9 useracc.9 MLINKS+=kernel_mount.9 free_mntarg.9 \ kernel_mount.9 kernel_vmount.9 \
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202303271721.32RHLrit050446>