git: 43db15b16aa6 - main - critical(9): small updates

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=43db15b16aa6ee24613d0b25cbf50f2aef5850d1

commit 43db15b16aa6ee24613d0b25cbf50f2aef5850d1
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-03-20 19:50:50 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-03-20 20:12:11 +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
---
 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 2d8d0e94c71b..fdd81ba18b11 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -929,7 +929,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_buffer.9 crypto_apply.9 \
 	crypto_buffer.9 crypto_apply_buf.9 \
 	crypto_buffer.9 crypto_buffer_contiguous_segment.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 .