Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/critical_enter.9
Show All 17 Lines | ||||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | |||||||||
.\" | .\" | |||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | |||||||||
.\" | .\" | |||||||||
.Dd October 5, 2005 | .Dd March 20, 2023 | |||||||||
.Dt CRITICAL_ENTER 9 | .Dt CRITICAL_ENTER 9 | |||||||||
.Os | .Os | |||||||||
.Sh NAME | .Sh NAME | |||||||||
.Nm critical_enter , | .Nm critical_enter , | |||||||||
.Nm critical_exit | .Nm critical_exit | |||||||||
.Nd enter and exit a critical region | .Nd enter and exit a critical region | |||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | |||||||||
.In sys/param.h | .In sys/param.h | |||||||||
.In sys/systm.h | .In sys/systm.h | |||||||||
.Ft void | .Ft void | |||||||||
.Fn critical_enter "void" | .Fn critical_enter "void" | |||||||||
.Ft void | .Ft void | |||||||||
.Fn critical_exit "void" | .Fn critical_exit "void" | |||||||||
.Fn CRITICAL_ASSERT "struct thread *td" | ||||||||||
kib: FWIW kassert.h is included from systm.h | ||||||||||
Done Inline ActionsI restored it to systm.h in all cases. I could not find a way to cleanly communicate #include <sys/kassert.h> OR #include <sys/systm.h> in the synopsis section, or any existing example of this. Maybe someone has a suggestion. mhorne: I restored it to systm.h in all cases. I could not find a way to cleanly communicate… | ||||||||||
Not Done Inline ActionsI suggest adding a NOTE section saying that sys/kassert.h can be used instead of sys/systm.h kib: I suggest adding a NOTE section saying that sys/kassert.h can be used instead of sys/systm.h | ||||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | |||||||||
These functions are used to prevent preemption in a critical region of code. | 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 | All that is guaranteed is that the thread currently executing on a CPU will | |||||||||
not be preempted. | not be preempted. | |||||||||
Specifically, a thread in a critical region will not migrate to another | Specifically, a thread in a critical region will not migrate to another CPU | |||||||||
CPU while it is in a critical region. | 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 | The current CPU may still trigger faults and exceptions during a critical | |||||||||
section; however, these faults are usually fatal. | section; however, these faults are usually fatal. | |||||||||
.Pp | .Pp | |||||||||
Done Inline Actions... which do not result in a context switch on interrupt exit, instead the context switch is postponed to the critical section exit. kib: ... which do not result in a context switch on interrupt exit, instead the context switch is… | ||||||||||
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. | ||||||||||
Not Done Inline ActionsThe CPU might also receive and handle interrupts within a critical section. In that case, the signal handler will not result in a context switch, and will return to the critical section when complete. rpokala: ```
The CPU might also receive and handle interrupts within a critical section.
In that case… | ||||||||||
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 | The | |||||||||
.Fn critical_enter | .Fn critical_enter | |||||||||
and | and | |||||||||
.Fn critical_exit | .Fn critical_exit | |||||||||
functions manage a per-thread counter to handle nested critical sections. | functions manage a per-thread counter to handle nested critical sections. | |||||||||
If a thread is made runnable that would normally preempt the current thread | If a thread is made runnable that would normally preempt the current thread | |||||||||
while the current thread is in a critical section, | while the current thread is in a critical section, | |||||||||
then the preemption will be deferred until the current thread exits the | then the preemption will be deferred until the current thread exits the | |||||||||
outermost critical section. | outermost critical section. | |||||||||
.Pp | .Pp | |||||||||
Note that these functions are not required to provide any inter-CPU | Note that these functions do not provide any inter-CPU synchronization, data | |||||||||
Done Inline Actionss/are not required to provide/do not provide/ ? kib: s/are not required to provide/do not provide/ ? | ||||||||||
synchronization, data protection, or memory ordering guarantees and thus | protection, or memory ordering guarantees, and thus should | |||||||||
Not Done Inline Actions... guarantees, and thus ... rpokala: ... guarantees**,** and thus ... | ||||||||||
should | ||||||||||
.Em not | .Em not | |||||||||
be used to protect shared data structures. | be used to protect shared data structures. | |||||||||
.Pp | .Pp | |||||||||
These functions should be used with care as an infinite loop within a | These functions should be used with care as an unbound or infinite loop within | |||||||||
Done Inline Actions
kib: | ||||||||||
critical region will deadlock the CPU. | a critical region will deadlock the CPU. | |||||||||
Also, they should not be interlocked with operations on mutexes, sx locks, | 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. | ||||||||||
Done Inline Actions... which might need a context switch to operate. kib: ... which might need a context switch to operate. | ||||||||||
One exception to this is that spin mutexes include a critical section, | One exception to this is that spin mutexes include a critical section, | |||||||||
so in certain cases critical sections may be interlocked with spin mutexes. | 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 | .Sh HISTORY | |||||||||
These functions were introduced in | These functions were introduced in | |||||||||
.Fx 5.0 . | .Fx 5.0 . |
FWIW kassert.h is included from systm.h