Date: Mon, 27 Mar 2023 17:21:52 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: a979e5ca0b9d - stable/13 - critical(9): small updates Message-ID: <202303271721.32RHLq0i049634@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=a979e5ca0b9dee32d11428a7a69066e7b64576bc commit a979e5ca0b9dee32d11428a7a69066e7b64576bc Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-03-20 19:50:50 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> 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 <pauamma@gundo.com> 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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202303271721.32RHLq0i049634>