git: a979e5ca0b9d - stable/13 - critical(9): small updates

From: Mitchell Horne <>
Date: Mon, 27 Mar 2023 17:21:52 UTC
The branch stable/13 has been updated by mhorne:


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:
    (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
@@ -37,15 +37,24 @@
 .Fn critical_enter "void"
 .Ft void
 .Fn critical_exit "void"
+.Fn CRITICAL_ASSERT "struct thread *td"
 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.
+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.
 .Fn critical_enter
@@ -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.
-Note that these functions are not required to provide any inter-CPU
-synchronization, data protection, or memory ordering guarantees and thus
+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.
-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.
+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.
+macro verifies that the provided thread
+.Fa td
+is currently executing in a critical section.
+It is a wrapper around
+.Xr KASSERT 9 .
+.Xr callout 9 ,
+.Xr KASSERT 9 ,
+.Xr locking 9
 These functions were introduced in
 .Fx 5.0 .