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
This commit is contained in:
parent
b54391a1f8
commit
43db15b16a
@ -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 \
|
||||
|
@ -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 .
|
||||
|
Loading…
Reference in New Issue
Block a user