Bump date.
[dragonfly.git] / share / man / man9 / crit_enter.9
CommitLineData
3af31f78
SW
1.\"
2.\" Copyright (c) 2006 The DragonFly Project. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\"
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in
12.\" the documentation and/or other materials provided with the
13.\" distribution.
14.\" 3. Neither the name of The DragonFly Project nor the names of its
15.\" contributors may be used to endorse or promote products derived
16.\" from this software without specific, prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
28.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
b8d65588 31.\" $DragonFly: src/share/man/man9/crit_enter.9,v 1.4 2008/02/19 12:34:55 nant Exp $
3af31f78 32.\"
b8d65588 33.Dd February 18, 2008
3af31f78
SW
34.Dt CRIT_ENTER 9
35.Os
36.Sh NAME
37.Nm crit_enter ,
38.Nm crit_enter_gd ,
39.Nm crit_enter_id ,
40.Nm crit_exit ,
41.Nm crit_exit_gd ,
42.Nm crit_exit_id
43.Nd enter and exit a critical section
44.Sh SYNOPSIS
45.In sys/thread2.h
46.Ft void
47.Fn crit_enter "void"
48.Ft void
49.Fn crit_exit "void"
50.Ft void
51.Fn crit_enter_gd "globaldata_t gd"
52.Ft void
53.Fn crit_exit_gd "globaldata_t gd"
54.Ft void
55.Fn crit_enter_id "const char *id"
56.Ft void
57.Fn crit_exit_id "const char *id"
58.Sh DESCRIPTION
59The
60.Fn crit_enter
61and
62.Fn crit_exit
63functions are used to enter and exit a critical section of code.
dca05b43
NA
64Entering a critical section will disallow preemption of the currently
65running thread on the current CPU for the duration of the critical section.
66While a critical section is active, interrupts and IPIs are also prevented
67from executing on the current CPU.
3af31f78 68Instead, the interrupt code marks the interrupt as deferred and immediately
dca05b43
NA
69returns (without scheduling any interrupt thread).
70If an interrupt or an IPI is deferred in this way, it will be processed upon
71leaving the critical section.
72.Pp
3af31f78
SW
73It is possible for a thread to sleep while holding a critical section,
74however this results in the critical section being given up for the time of
75the sleep and being reacquired after waking up.
76.Pp
77If the current CPU's globaldata pointer is available,
78.Fn crit_enter_gd
79and
80.Fn crit_exit_gd
81may be used to reduce the amount of generated code.
82.Pp
83Critical sections are per-CPU entities.
dca05b43 84They are typicaly used to interlock operations local to the CPU.
3af31f78 85A critical section on one CPU will not prevent an interrupt or IPI from
3221afbe 86occurring on some other CPU.
3af31f78
SW
87If cross-CPU interlocks are required the more heavy weight
88.Xr spinlock 9
89or
90.Xr serializer 9
91lock is recommended instead.
92.Pp
93Unlike spinlocks and serializer locks, critical sections can be nested.
94.Sh DEBUGGING CRITICAL SECTIONS
95Kernels compiled with
96.Dv DEBUG_CRIT_SECTIONS
97will report any
98.Fn crit_exit
99calls that are made from a different function than the
100.Fn crit_enter
101that they are unnesting.
102The
103.Fn crit_enter_id
104and
105.Fn crit_exit_id
106functions can be used to specify a fixed ID in cases where this is done
107on purpose.
108Identifiers must be string pointers but the debug code only checks the
109pointer address, it does not do a
110.Fn strcmp
111to validate the ID.
112.Sh SEE ALSO
113.Xr serializer 9 ,
114.Xr spinlock 9
115.Sh HISTORY
116These functions were introduced in
117.Dx 1.0 .