share/man/man9/crit_enter.9

   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.1 2006/07/05 18:32:20 swildner Exp $
  32 .\"
  33 .Dd July 5, 2006
  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
  59 The
  60 .Fn crit_enter
  61 and
  62 .Fn crit_exit
  63 functions are used to enter and exit a critical section of code.
  64 While a critical section is active, interrupts and IPIs are prevented from
  65 executing on the current CPU.
  66 Instead, the interrupt code marks the interrupt as deferred and immediately
  67 returns.
  68 It is possible for a thread to sleep while holding a critical section,
  69 however this results in the critical section being given up for the time of
  70 the sleep and being reacquired after waking up.
  71 .Pp
  72 If the current CPU's globaldata pointer is available,
  73 .Fn crit_enter_gd
  74 and
  75 .Fn crit_exit_gd
  76 may be used to reduce the amount of generated code.
  77 .Pp
  78 Critical sections are per-CPU entities.
  79 A critical section on one CPU will not prevent an interrupt or IPI from
  80 occuring on some other CPU.
  81 If cross-CPU interlocks are required the more heavy weight
  82 .Xr spinlock 9
  83 or
  84 .Xr serializer 9
  85 lock is recommended instead.
  86 .Pp
  87 Unlike spinlocks and serializer locks, critical sections can be nested.
  88 .Sh DEBUGGING CRITICAL SECTIONS
  89 Kernels compiled with
  90 .Dv DEBUG_CRIT_SECTIONS
  91 will report any
  92 .Fn crit_exit
  93 calls that are made from a different function than the
  94 .Fn crit_enter
  95 that they are unnesting.
  96 The
  97 .Fn crit_enter_id
  98 and
  99 .Fn crit_exit_id
 100 functions can be used to specify a fixed ID in cases where this is done
 101 on purpose.
 102 Identifiers must be string pointers but the debug code only checks the
 103 pointer address, it does not do a
 104 .Fn strcmp
 105 to validate the ID.
 106 .Sh SEE ALSO
 107 .Xr serializer 9 ,
 108 .Xr spinlock 9
 109 .Sh HISTORY
 110 These functions were introduced in
 111 .Dx 1.0 .