MdePkg/Include/Library/SynchronizationLib.h

   1 /** @file
   2   Provides synchronization functions.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __SYNCHRONIZATION_LIB__
  10 #define __SYNCHRONIZATION_LIB__
  11
  12 ///
  13 /// Definitions for SPIN_LOCK
  14 ///
  15 typedef volatile UINTN SPIN_LOCK;
  16
  17 /**
  18   Retrieves the architecture-specific spin lock alignment requirements for
  19   optimal spin lock performance.
  20
  21   This function retrieves the spin lock alignment requirements for optimal
  22   performance on a given CPU architecture. The spin lock alignment is byte alignment.
  23   It must be a power of two and is returned by this function. If there are no alignment
  24   requirements, then 1 must be returned. The spin lock synchronization
  25   functions must function correctly if the spin lock size and alignment values
  26   returned by this function are not used at all. These values are hints to the
  27   consumers of the spin lock synchronization functions to obtain optimal spin
  28   lock performance.
  29
  30   @return The architecture-specific spin lock alignment.
  31
  32 **/
  33 UINTN
  34 EFIAPI
  35 GetSpinLockProperties (
  36   VOID
  37   );
  38
  39 /**
  40   Initializes a spin lock to the released state and returns the spin lock.
  41
  42   This function initializes the spin lock specified by SpinLock to the released
  43   state, and returns SpinLock. Optimal performance can be achieved by calling
  44   GetSpinLockProperties() to determine the size and alignment requirements for
  45   SpinLock.
  46
  47   If SpinLock is NULL, then ASSERT().
  48
  49   @param  SpinLock  A pointer to the spin lock to initialize to the released
  50                     state.
  51
  52   @return SpinLock in release state.
  53
  54 **/
  55 SPIN_LOCK *
  56 EFIAPI
  57 InitializeSpinLock (
  58   OUT      SPIN_LOCK  *SpinLock
  59   );
  60
  61 /**
  62   Waits until a spin lock can be placed in the acquired state.
  63
  64   This function checks the state of the spin lock specified by SpinLock. If
  65   SpinLock is in the released state, then this function places SpinLock in the
  66   acquired state and returns SpinLock. Otherwise, this function waits
  67   indefinitely for the spin lock to be released, and then places it in the
  68   acquired state and returns SpinLock. All state transitions of SpinLock must
  69   be performed using MP safe mechanisms.
  70
  71   If SpinLock is NULL, then ASSERT().
  72   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
  73   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
  74   PcdSpinLockTimeout microseconds, then ASSERT().
  75
  76   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
  77
  78   @return SpinLock acquired lock.
  79
  80 **/
  81 SPIN_LOCK *
  82 EFIAPI
  83 AcquireSpinLock (
  84   IN OUT  SPIN_LOCK  *SpinLock
  85   );
  86
  87 /**
  88   Attempts to place a spin lock in the acquired state.
  89
  90   This function checks the state of the spin lock specified by SpinLock. If
  91   SpinLock is in the released state, then this function places SpinLock in the
  92   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
  93   transitions of SpinLock must be performed using MP safe mechanisms.
  94
  95   If SpinLock is NULL, then ASSERT().
  96   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
  97
  98   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
  99
 100   @retval TRUE  SpinLock was placed in the acquired state.
 101   @retval FALSE SpinLock could not be acquired.
 102
 103 **/
 104 BOOLEAN
 105 EFIAPI
 106 AcquireSpinLockOrFail (
 107   IN OUT  SPIN_LOCK  *SpinLock
 108   );
 109
 110 /**
 111   Releases a spin lock.
 112
 113   This function places the spin lock specified by SpinLock in the release state
 114   and returns SpinLock.
 115
 116   If SpinLock is NULL, then ASSERT().
 117   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 118
 119   @param  SpinLock  A pointer to the spin lock to release.
 120
 121   @return SpinLock released lock.
 122
 123 **/
 124 SPIN_LOCK *
 125 EFIAPI
 126 ReleaseSpinLock (
 127   IN OUT  SPIN_LOCK  *SpinLock
 128   );
 129
 130 /**
 131   Performs an atomic increment of a 32-bit unsigned integer.
 132
 133   Performs an atomic increment of the 32-bit unsigned integer specified by
 134   Value and returns the incremented value. The increment operation must be
 135   performed using MP safe mechanisms.
 136
 137   If Value is NULL, then ASSERT().
 138
 139   @param  Value A pointer to the 32-bit value to increment.
 140
 141   @return The incremented value.
 142
 143 **/
 144 UINT32
 145 EFIAPI
 146 InterlockedIncrement (
 147   IN      volatile UINT32  *Value
 148   );
 149
 150 /**
 151   Performs an atomic decrement of a 32-bit unsigned integer.
 152
 153   Performs an atomic decrement of the 32-bit unsigned integer specified by
 154   Value and returns the decremented value. The decrement operation must be
 155   performed using MP safe mechanisms.
 156
 157   If Value is NULL, then ASSERT().
 158
 159   @param  Value A pointer to the 32-bit value to decrement.
 160
 161   @return The decremented value.
 162
 163 **/
 164 UINT32
 165 EFIAPI
 166 InterlockedDecrement (
 167   IN      volatile UINT32  *Value
 168   );
 169
 170 /**
 171   Performs an atomic compare exchange operation on a 16-bit unsigned integer.
 172
 173   Performs an atomic compare exchange operation on the 16-bit unsigned integer
 174   specified by Value.  If Value is equal to CompareValue, then Value is set to
 175   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 176   then Value is returned.  The compare exchange operation must be performed using
 177   MP safe mechanisms.
 178
 179   If Value is NULL, then ASSERT().
 180
 181   @param  Value         A pointer to the 16-bit value for the compare exchange
 182                         operation.
 183   @param  CompareValue  16-bit value used in compare operation.
 184   @param  ExchangeValue 16-bit value used in exchange operation.
 185
 186   @return The original *Value before exchange.
 187 **/
 188 UINT16
 189 EFIAPI
 190 InterlockedCompareExchange16 (
 191   IN OUT  volatile UINT16  *Value,
 192   IN      UINT16           CompareValue,
 193   IN      UINT16           ExchangeValue
 194   );
 195
 196 /**
 197   Performs an atomic compare exchange operation on a 32-bit unsigned integer.
 198
 199   Performs an atomic compare exchange operation on the 32-bit unsigned integer
 200   specified by Value.  If Value is equal to CompareValue, then Value is set to
 201   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 202   then Value is returned.  The compare exchange operation must be performed using
 203   MP safe mechanisms.
 204
 205   If Value is NULL, then ASSERT().
 206
 207   @param  Value         A pointer to the 32-bit value for the compare exchange
 208                         operation.
 209   @param  CompareValue  32-bit value used in compare operation.
 210   @param  ExchangeValue 32-bit value used in exchange operation.
 211
 212   @return The original *Value before exchange.
 213
 214 **/
 215 UINT32
 216 EFIAPI
 217 InterlockedCompareExchange32 (
 218   IN OUT  volatile UINT32  *Value,
 219   IN      UINT32           CompareValue,
 220   IN      UINT32           ExchangeValue
 221   );
 222
 223 /**
 224   Performs an atomic compare exchange operation on a 64-bit unsigned integer.
 225
 226   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
 227   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
 228   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
 229   The compare exchange operation must be performed using MP safe mechanisms.
 230
 231   If Value is NULL, then ASSERT().
 232
 233   @param  Value         A pointer to the 64-bit value for the compare exchange
 234                         operation.
 235   @param  CompareValue  64-bit value used in compare operation.
 236   @param  ExchangeValue 64-bit value used in exchange operation.
 237
 238   @return The original *Value before exchange.
 239
 240 **/
 241 UINT64
 242 EFIAPI
 243 InterlockedCompareExchange64 (
 244   IN OUT  volatile UINT64  *Value,
 245   IN      UINT64           CompareValue,
 246   IN      UINT64           ExchangeValue
 247   );
 248
 249 /**
 250   Performs an atomic compare exchange operation on a pointer value.
 251
 252   Performs an atomic compare exchange operation on the pointer value specified
 253   by Value. If Value is equal to CompareValue, then Value is set to
 254   ExchangeValue and CompareValue is returned. If Value is not equal to
 255   CompareValue, then Value is returned. The compare exchange operation must be
 256   performed using MP safe mechanisms.
 257
 258   If Value is NULL, then ASSERT().
 259
 260   @param  Value         A pointer to the pointer value for the compare exchange
 261                         operation.
 262   @param  CompareValue  Pointer value used in compare operation.
 263   @param  ExchangeValue Pointer value used in exchange operation.
 264
 265   @return The original *Value before exchange.
 266 **/
 267 VOID *
 268 EFIAPI
 269 InterlockedCompareExchangePointer (
 270   IN OUT  VOID                      *volatile  *Value,
 271   IN      VOID                                 *CompareValue,
 272   IN      VOID                                 *ExchangeValue
 273   );
 274
 275 #endif