From nobody Mon Mar 20 20:13:25 2023 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4PgQsf0PBNz40Bf4; Mon, 20 Mar 2023 20:13:26 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4PgQsd5HXWz3J2j; Mon, 20 Mar 2023 20:13:25 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343205; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=MaEePwkcXh0iJhivJgNkzeidBYkMOf6rXQbSZNVOn6c=; b=a5ppWxJZUlBa/ZYtWUY0zCIRnfrdZbqWfUB/4qLRo1jYobI6ufeIIg3Y2WKE9DsvDI/Utm jGupLGYubYr+2CYXEK5/Gb0mAMv48qzGE/qB9CPvVu6ENSO6XTKvs4Jl/mmSRm4gqeyb0V pLJENBhzfWkm4uxCaz+H5nET6cUw7IcY/dObt4I9doLKfREgB4ZN2/9XWvf79DbYx8RDC7 ZY3ZSxlScWbzWphAEaggSoeiD/1i3EpbpdFHAq92/LIgj6Klqt/9M40b4zDNUldM5gdI9W h4jxWeyGxLdIK2QC/oEP2pzML5AsbHcVAvOoakjeefZ2UWxsXTEHPGg9uuuW0g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343205; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=MaEePwkcXh0iJhivJgNkzeidBYkMOf6rXQbSZNVOn6c=; b=DTPj757lsvyCQ5+s2vQpTmK/wHj3m/Gx6YzyNvmOAH44wvU2FyxbP1cAWQMYiu3SXZjWvz khu8rkBhkngnYBTVdp8+o4WRbbBm9oi/lhl6PPsERFc+GAgN3LqpLzybJ5DduXRJnuVGCz e4S64snu9a3VIV/EkDHWIW9vl1/DwKGnVHliXHZ+7L9W0zexZ3oUnMvgee/u8RNXi5Xcgz 2uq5lfJQMle/6a3mzDLAYVt6Nl00wiyRGzGcLjD/u+OIZM5hwrAT+3aZ/dZD67mpZJPB9V 27mblwaq95aamPl/PX7Mjg967Zy1Ub1A4U3sBp+JKsf/Rtr6Gvaha8Jr8ezdWA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679343205; a=rsa-sha256; cv=none; b=WgUIKUal5QrW3mwXmaDV3rs0QJvD2V+ZxawoPGVIOHOl3piEgWs2UDjOlXjs3UkSJ2V5if ljW4tfsfUW8yeIkZX578ejHq6tKyxXJ2c4UsGN18AirdNC47VV1FhB+K/NdegcXik68OJ0 jmYvYEzXxa7vgIQH+4M5iUOKfuLolE7y/Qn8m0XXdvKGoqwH595LvTe8P/QzvX9HG6OC5D 2FjszLUYbdhr6bYixc1bfjUe32pu6/dD8hK1m3+LHCrjOx62ebkBcZ9xe22v5BrI2dVh7c rL7h8VxuvMuZcXfYc9cL+93RwRM4VXX1K0eX1GV7uQ9MNO2/Qqcossd4f+kLgw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4PgQsd4Ks5zjyT; Mon, 20 Mar 2023 20:13:25 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 32KKDPvr033089; Mon, 20 Mar 2023 20:13:25 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32KKDPLD033088; Mon, 20 Mar 2023 20:13:25 GMT (envelope-from git) Date: Mon, 20 Mar 2023 20:13:25 GMT Message-Id: <202303202013.32KKDPLD033088@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: 87132d1dce4b - main - KASSERT(9): some updates List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 87132d1dce4b61c782871f450c17b818bf991ff6 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=87132d1dce4b61c782871f450c17b818bf991ff6 commit 87132d1dce4b61c782871f450c17b818bf991ff6 Author: Mitchell Horne AuthorDate: 2023-03-20 19:54:11 +0000 Commit: Mitchell Horne 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 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