From nobody Mon Mar 27 17:21:53 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 4PlfkT31VHz41pTN; Mon, 27 Mar 2023 17:21:53 +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 4PlfkT2Slvz4Qq4; Mon, 27 Mar 2023 17:21:53 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937713; 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=u7iPdQ1xc3F7elZPLaP8UisL8Cvjn2brhBqVy3f9RCA=; b=fvoi/8XhJXFESuDetcvWlkkdpI4cfqeSls1mAskRFZF5SuLJqX0sxCtEf4hmkddfSaMA5D T42AIdPQGxF7ltNPt6jukTw38WNZbNNEdegdKkCbqe1fM8SYmXtQiBU7A6ZMsOGDB91gYm lMkG2U3aj67rnDBYdtAIeBTknhe3/tCryAE8EDmQDGiZMolBkIPYHLCEa7WCDaGW57zxfa x0ywSbrj5NH2OPzAlNUDqrHAUL4NKLZV0t/n4KrSrdJvga+M95h88GVXoB8Ye/V8Y/eEjB r4iVWxwkCq0G69Y1+EeXTBLy9KZ0rTrfA7tBCQofByJ169mS1cKfYQ8F/cB+KQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937713; 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=u7iPdQ1xc3F7elZPLaP8UisL8Cvjn2brhBqVy3f9RCA=; b=dCc0yNy1kJGPq/YtYzy2rJVtWhPpugKBPhIEh+L28tGMgsuob7z5gbZkTxje0X99n5nP/j rCTtgFw8RxmCmXFRzD38Df0aWDNhggqgrmxXFFLZvuPMpLNRJCzqlUgMBr8uFXAlNrwH0A gQWewYE9+XmpH8lPLvTs1ZjuH6E00wXzC0J4U8lPFM0wfGBRFcauFJnGf2b+fe1zr68+qx 6KXHqu/qSK/kM5wx7EYbbnQak6yWQKa1BZ72O0IbmiA9hoe11thhuLddyUOaW+zlVniNQ+ 4lotY4IeARTBUAUXArXxVmUlBtYIFy6gEKKrbhKVSGnnt7JdHEVGtVA4gyiEUQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679937713; a=rsa-sha256; cv=none; b=SHbBXtcmho3ZwU2DzqHzDdnai4dwvS9MShZcEcb8/1MyFShcWESrGG1RUMylxPB4wUaDgz YUkdVqXxY52xT4ym5paD3gaDptL7L5lWp41c/T4CUMHtegkHd/m17losXeEef8tKji6o09 TRQHqR1KWd5AFZgXgjTAYvx1XFXoxkXv9/MI5amGKM9lsSRFxTch6eYC35ODPV5JZvhsad 0N1x8GKaI8K/GK1ALYqreyAF0mPqJ45cuvM/jTtIOS03oJZ+MevPwV5a+g8Pl0EGP0IAg9 pgUwqL/lnDqHfYxzp92gROKzg0QZOM9cB1NcRtQIjP7DXOlf4ac1/VavT/O2Yg== 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 4PlfkT12B6zW5Q; Mon, 27 Mar 2023 17:21:53 +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 32RHLrOt050459; Mon, 27 Mar 2023 17:21:53 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32RHLrit050446; Mon, 27 Mar 2023 17:21:53 GMT (envelope-from git) Date: Mon, 27 Mar 2023 17:21:53 GMT Message-Id: <202303271721.32RHLrit050446@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Mitchell Horne Subject: git: d85a53128792 - stable/13 - 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/stable/13 X-Git-Reftype: branch X-Git-Commit: d85a5312879247569f9ca4e3a3ebab2833e6d84a Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=d85a5312879247569f9ca4e3a3ebab2833e6d84a commit d85a5312879247569f9ca4e3a3ebab2833e6d84a Author: Mitchell Horne AuthorDate: 2023-03-20 19:54:11 +0000 Commit: Mitchell Horne 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 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 \