From nobody Mon Mar 27 17:21:52 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 4PlfkS2C2Wz41p8c; Mon, 27 Mar 2023 17:21:52 +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 4PlfkS1mtyz4R1F; Mon, 27 Mar 2023 17:21:52 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937712; 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=0tG7j1AveKiidRx73Kwtf9T4LoVRTOjsmqfqYBAuXIs=; b=OMkuwRqyF/d9qcKdmLoRzTY52F2NAZGzdzKe5eWKxo4e6buqw2cGVYV36+uXV2rrdyISB5 Jrn/KY4T7izukN8tpdkmfe9qMoJ6edjN42GNB5S4a7igRE898SUMw0pTpJCXMSqzHcbb0P H4pWU0NwUUIHR5aMSVniTN1sX1vqy3LPwIv62jJyre3SeJEpmqXhk3CUu6/TE4CxoPRGPm pRSVb4JHcmM3ODfXyBLkHv1YbEDBxGkgfuSQgxsZX468F7kJympa0yoaOqXAghX5n0SjHo G7r/RIq/6q2lyHlRDtZfO2s3njaoQ/XFXIxunfNDvIKRuYEM+zQLnyLwLJ8jBA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937712; 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=0tG7j1AveKiidRx73Kwtf9T4LoVRTOjsmqfqYBAuXIs=; b=KqEQVdbBi6+TZNwmYNddp3+a7GKFP4SR1UyKQvrersQVbejsc/shmqYRjSpjx7LTOHl9cu oTpRdIsjfpUoqGIfcMZ8liVMmdqeMQco1ZYgM+jJuvRzgJMUD30c85pkbwbCXjPC2yvdoH tzsJBviEactO5BSAivhGfkmaDXzhRWuM/ty14meYLLb1jXHVqqF+dZ228Yw3040ZsWckNJ iLg4i2RulpQwk7NhA6EdN4lKCBdCJokhijUHYOi08AF8udmLU/bG8nlBxG/mkDtMqYJEdf 3gE16iLHVv0kAgJbjWmsOrVErDCPz2PQTWhtdPg3i/vE7ozQ238IHCwXg34gxg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679937712; a=rsa-sha256; cv=none; b=tsxsxZwVWISpmY4FrTqilfGwSXeHsi7AB937hxlV/qhKcZry1VRB6uA/WBSId6wxPiCM5j v15ZoL9w90S2u5J7MTYtBULAR2Ynrcl9M+nm5PW84nkfiJbXrUvqvQIBbhELGo7s4ltqz4 pwfUWYXWMmUxOd/bSfUlh9k1Sp/qYHCggpRGcVecDKSqIgU8D3X8bbceYqfwpiwhwf/VPf 8+oCyIin3aWlQw6zgzqZ2FumtcBEF1hqMTe0V1enI5PHmKH5L2BXuiPdskWfKeFOzaOGyh 4wxf5sk5B3nghEvTYMLZS5usLjCPUfjG8vNaIQgGKPJ/z0QIWFGERWtc5ai9VA== 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 4PlfkS0s3WzWG6; Mon, 27 Mar 2023 17:21:52 +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 32RHLqf4049635; Mon, 27 Mar 2023 17:21:52 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32RHLq0i049634; Mon, 27 Mar 2023 17:21:52 GMT (envelope-from git) Date: Mon, 27 Mar 2023 17:21:52 GMT Message-Id: <202303271721.32RHLq0i049634@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: a979e5ca0b9d - stable/13 - critical(9): small 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: a979e5ca0b9dee32d11428a7a69066e7b64576bc Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=a979e5ca0b9dee32d11428a7a69066e7b64576bc commit a979e5ca0b9dee32d11428a7a69066e7b64576bc Author: Mitchell Horne AuthorDate: 2023-03-20 19:50:50 +0000 Commit: Mitchell Horne CommitDate: 2023-03-27 17:17:13 +0000 critical(9): small updates - Document CRITICAL_ASSERT() in this man page. - Clarify that a thread may also handle interrupts in a critical section, not only faults/exceptions. - Note the negative effects of critical section abuse - Some other minor clarifications - Add short SEE ALSO Reviewed by: kib, markj, rpokala, Pau Amma MFC after: 1 week Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D39130 (cherry picked from commit 43db15b16aa6ee24613d0b25cbf50f2aef5850d1) --- share/man/man9/Makefile | 3 ++- share/man/man9/critical_enter.9 | 48 +++++++++++++++++++++++++++++++++-------- 2 files changed, 41 insertions(+), 10 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 6aa1bcae3c40..ed6de288cfa4 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -926,7 +926,8 @@ MLINKS+=cpuset.9 CPUSET_T_INITIALIZER.9 \ cpuset.9 CPU_OR_ATOMIC.9 \ cpuset.9 CPU_COPY_STORE_REL.9 MLINKS+=critical_enter.9 critical.9 \ - critical_enter.9 critical_exit.9 + critical_enter.9 critical_exit.9 \ + critical_enter.9 CRITICAL_ASSERT.9 MLINKS+=crypto_asym.9 crypto_kdispatch.9 \ crypto_asym.9 crypto_kdone.9 \ crypto_asym.9 crypto_kregister.9 \ diff --git a/share/man/man9/critical_enter.9 b/share/man/man9/critical_enter.9 index 3da3ac1d96a1..8a702e3c44fd 100644 --- a/share/man/man9/critical_enter.9 +++ b/share/man/man9/critical_enter.9 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 5, 2005 +.Dd March 20, 2023 .Dt CRITICAL_ENTER 9 .Os .Sh NAME @@ -37,15 +37,24 @@ .Fn critical_enter "void" .Ft void .Fn critical_exit "void" +.Fn CRITICAL_ASSERT "struct thread *td" .Sh DESCRIPTION These functions are used to prevent preemption in a critical region of code. All that is guaranteed is that the thread currently executing on a CPU will not be preempted. -Specifically, a thread in a critical region will not migrate to another -CPU while it is in a critical region. +Specifically, a thread in a critical region will not migrate to another CPU +while it is in a critical region, nor will the current CPU switch to a +different thread. The current CPU may still trigger faults and exceptions during a critical section; however, these faults are usually fatal. .Pp +The CPU might also receive and handle interrupts within a critical section. +When this occurs the interrupt exit will not result in a context switch, and +execution will continue in the critical section. +Thus, the net effect of a critical section on the current thread's execution is +similar to running with interrupts disabled, except that timer interrupts and +filtered interrupt handlers do not incur a latency penalty. +.Pp The .Fn critical_enter and @@ -56,18 +65,39 @@ while the current thread is in a critical section, then the preemption will be deferred until the current thread exits the outermost critical section. .Pp -Note that these functions are not required to provide any inter-CPU -synchronization, data protection, or memory ordering guarantees and thus -should +Note that these functions do not provide any inter-CPU synchronization, data +protection, or memory ordering guarantees, and thus should .Em not be used to protect shared data structures. .Pp -These functions should be used with care as an infinite loop within a -critical region will deadlock the CPU. +These functions should be used with care as an unbound or infinite loop within +a critical region will deadlock the CPU. Also, they should not be interlocked with operations on mutexes, sx locks, -semaphores, or other synchronization primitives. +semaphores, or other synchronization primitives, as these primitives may +require a context switch to operate. One exception to this is that spin mutexes include a critical section, so in certain cases critical sections may be interlocked with spin mutexes. +.Pp +Critical regions should be only as wide as necessary. +That is, code which does not require the critical section to operate correctly +should be excluded from its bounds whenever possible. +Abuse of critical sections has an effect on overall system latency and timer +precision, since disabling preemption will delay the execution of threaded +interrupt handlers and +.Xr callout 9 +events on the current CPU. +.Pp +The +.Fn CRITICAL_ASSERT +macro verifies that the provided thread +.Fa td +is currently executing in a critical section. +It is a wrapper around +.Xr KASSERT 9 . +.Sh SEE ALSO +.Xr callout 9 , +.Xr KASSERT 9 , +.Xr locking 9 .Sh HISTORY These functions were introduced in .Fx 5.0 .