Page MenuHomeFreeBSD
Files F102653121

D39130.diff
No OneTemporary
Actions

D39130.diff
View Options

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -929,7 +929,8 @@
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
--- 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 @@
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 .

File Metadata

Mime Type
text/plain
Expires
Sat, Nov 16, 9:30 AM (21 h, 47 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
14656590
Default Alt Text
D39130.diff (3 KB)

Event Timeline