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 .