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