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.\" 31.\" $DragonFly: src/share/man/man9/crit_enter.9,v 1.5 2008/04/14 08:17:09 swildner Exp $ 32.\" 33.Dd February 18, 2008 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. 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. 68Instead, the interrupt code marks the interrupt as deferred and immediately 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 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. 84They are typically used to interlock operations local to the CPU. 85A critical section on one CPU will not prevent an interrupt or IPI from 86occurring on some other CPU. 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 . 118