MdePkg/Library/BaseLib/Synchronization.c

   1 /** @file
   2   Implementation of synchronization functions.
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   Module Name:  Synchronization.c
  14
  15 **/
  16
  17 //
  18 // Include common header file for this module.
  19 //
  20 #include "CommonHeader.h"
  21
  22 #include "BaseLibInternals.h"
  23
  24 #define SPIN_LOCK_RELEASED          ((UINTN) 1)
  25 #define SPIN_LOCK_ACQUIRED          ((UINTN) 2)
  26
  27 /**
  28   Retrieves the architecture specific spin lock alignment requirements for
  29   optimal spin lock performance.
  30
  31   This function retrieves the spin lock alignment requirements for optimal
  32   performance on a given CPU architecture. The spin lock alignment must be a
  33   power of two and is returned by this function. If there are no alignment
  34   requirements, then 1 must be returned. The spin lock synchronization
  35   functions must function correctly if the spin lock size and alignment values
  36   returned by this function are not used at all. These values are hints to the
  37   consumers of the spin lock synchronization functions to obtain optimal spin
  38   lock performance.
  39
  40   @return The architecture specific spin lock alignment.
  41
  42 **/
  43 UINTN
  44 EFIAPI
  45 GetSpinLockProperties (
  46   VOID
  47   )
  48 {
  49   // @bug May use a PCD entry to determine this alignment.
  50   return 32;
  51 }
  52
  53 /**
  54   Initializes a spin lock to the released state and returns the spin lock.
  55
  56   This function initializes the spin lock specified by SpinLock to the released
  57   state, and returns SpinLock. Optimal performance can be achieved by calling
  58   GetSpinLockProperties() to determine the size and alignment requirements for
  59   SpinLock.
  60
  61   If SpinLock is NULL, then ASSERT().
  62
  63   @param  SpinLock  A pointer to the spin lock to initialize to the released
  64                     state.
  65
  66   @return SpinLock
  67
  68 **/
  69 SPIN_LOCK *
  70 EFIAPI
  71 InitializeSpinLock (
  72   OUT     SPIN_LOCK                 *SpinLock
  73   )
  74 {
  75   ASSERT (SpinLock != NULL);
  76   *SpinLock = SPIN_LOCK_RELEASED;
  77   return SpinLock;
  78 }
  79
  80 /**
  81   Waits until a spin lock can be placed in the acquired state.
  82
  83   This function checks the state of the spin lock specified by SpinLock. If
  84   SpinLock is in the released state, then this function places SpinLock in the
  85   acquired state and returns SpinLock. Otherwise, this function waits
  86   indefinitely for the spin lock to be released, and then places it in the
  87   acquired state and returns SpinLock. All state transitions of SpinLock must
  88   be performed using MP safe mechanisms.
  89
  90   If SpinLock is NULL, then ASSERT().
  91   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
  92   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
  93   PcdSpinLockTimeout microseconds, then ASSERT().
  94
  95   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
  96
  97   @return SpinLock
  98
  99 **/
 100 SPIN_LOCK *
 101 EFIAPI
 102 AcquireSpinLock (
 103   IN OUT  SPIN_LOCK                 *SpinLock
 104   )
 105 {
 106   UINT64                            Tick;
 107   UINT64                            Start, End;
 108   UINT64                            Timeout;
 109
 110   Tick = 0;
 111   Start = 0;
 112   End = 0;
 113   if (PcdGet32 (PcdSpinLockTimeout) > 0) {
 114     Tick = GetPerformanceCounter ();
 115     Timeout = DivU64x32 (
 116                 MultU64x32 (
 117                   GetPerformanceCounterProperties (&Start, &End),
 118                   PcdGet32 (PcdSpinLockTimeout)
 119                   ),
 120                 1000000
 121                 );
 122     if (Start < End) {
 123       Tick += Timeout;
 124     } else {
 125       Tick -= Timeout;
 126     }
 127   }
 128
 129   while (!AcquireSpinLockOrFail (SpinLock)) {
 130     CpuPause ();
 131     ASSERT ((Start < End) ^ (Tick <= GetPerformanceCounter ()));
 132   }
 133   return SpinLock;
 134 }
 135
 136 /**
 137   Attempts to place a spin lock in the acquired state.
 138
 139   This function checks the state of the spin lock specified by SpinLock. If
 140   SpinLock is in the released state, then this function places SpinLock in the
 141   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
 142   transitions of SpinLock must be performed using MP safe mechanisms.
 143
 144   If SpinLock is NULL, then ASSERT().
 145   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 146
 147   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
 148
 149   @retval TRUE  SpinLock was placed in the acquired state.
 150   @retval FALSE SpinLock could not be acquired.
 151
 152 **/
 153 BOOLEAN
 154 EFIAPI
 155 AcquireSpinLockOrFail (
 156   IN OUT  SPIN_LOCK                 *SpinLock
 157   )
 158 {
 159   SPIN_LOCK    LockValue;
 160
 161   ASSERT (SpinLock != NULL);
 162
 163   LockValue = *SpinLock;
 164   ASSERT (LockValue == SPIN_LOCK_ACQUIRED || LockValue == SPIN_LOCK_RELEASED);
 165
 166   return (BOOLEAN)(
 167            InterlockedCompareExchangePointer (
 168              (VOID**)SpinLock,
 169              (VOID*)SPIN_LOCK_RELEASED,
 170              (VOID*)SPIN_LOCK_ACQUIRED
 171              ) == (VOID*)SPIN_LOCK_RELEASED
 172            );
 173 }
 174
 175 /**
 176   Releases a spin lock.
 177
 178   This function places the spin lock specified by SpinLock in the release state
 179   and returns SpinLock.
 180
 181   If SpinLock is NULL, then ASSERT().
 182   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 183
 184   @param  SpinLock  A pointer to the spin lock to release.
 185
 186   @return SpinLock
 187
 188 **/
 189 SPIN_LOCK *
 190 EFIAPI
 191 ReleaseSpinLock (
 192   IN OUT  SPIN_LOCK                 *SpinLock
 193   )
 194 {
 195   SPIN_LOCK    LockValue;
 196
 197   ASSERT (SpinLock != NULL);
 198
 199   LockValue = *SpinLock;
 200   ASSERT (LockValue == SPIN_LOCK_ACQUIRED || LockValue == SPIN_LOCK_RELEASED);
 201
 202   *SpinLock = SPIN_LOCK_RELEASED;
 203   return SpinLock;
 204 }
 205
 206 /**
 207   Performs an atomic increment of an 32-bit unsigned integer.
 208
 209   Performs an atomic increment of the 32-bit unsigned integer specified by
 210   Value and returns the incremented value. The increment operation must be
 211   performed using MP safe mechanisms. The state of the return value is not
 212   guaranteed to be MP safe.
 213
 214   If Value is NULL, then ASSERT().
 215
 216   @param  Value A pointer to the 32-bit value to increment.
 217
 218   @return The incremented value.
 219
 220 **/
 221 UINT32
 222 EFIAPI
 223 InterlockedIncrement (
 224   IN      UINT32                    *Value
 225   )
 226 {
 227   ASSERT (Value != NULL);
 228   return InternalSyncIncrement (Value);
 229 }
 230
 231 /**
 232   Performs an atomic decrement of an 32-bit unsigned integer.
 233
 234   Performs an atomic decrement of the 32-bit unsigned integer specified by
 235   Value and returns the decremented value. The decrement operation must be
 236   performed using MP safe mechanisms. The state of the return value is not
 237   guaranteed to be MP safe.
 238
 239   If Value is NULL, then ASSERT().
 240
 241   @param  Value A pointer to the 32-bit value to decrement.
 242
 243   @return The decremented value.
 244
 245 **/
 246 UINT32
 247 EFIAPI
 248 InterlockedDecrement (
 249   IN      UINT32                    *Value
 250   )
 251 {
 252   ASSERT (Value != NULL);
 253   return InternalSyncDecrement (Value);
 254 }
 255
 256 /**
 257   Performs an atomic compare exchange operation on a 32-bit unsigned integer.
 258
 259   Performs an atomic compare exchange operation on the 32-bit unsigned integer
 260   specified by Value.  If Value is equal to CompareValue, then Value is set to
 261   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 262   then Value is returned.  The compare exchange operation must be performed using
 263   MP safe mechanisms.
 264
 265   If Value is NULL, then ASSERT().
 266
 267   @param  Value         A pointer to the 32-bit value for the compare exchange
 268                         operation.
 269   @param  CompareValue  32-bit value used in compare operation.
 270   @param  ExchangeValue 32-bit value used in exchange operation.
 271
 272   @return The original *Value before exchange.
 273
 274 **/
 275 UINT32
 276 EFIAPI
 277 InterlockedCompareExchange32 (
 278   IN OUT  UINT32                    *Value,
 279   IN      UINT32                    CompareValue,
 280   IN      UINT32                    ExchangeValue
 281   )
 282 {
 283   ASSERT (Value != NULL);
 284   return InternalSyncCompareExchange32 (Value, CompareValue, ExchangeValue);
 285 }
 286
 287 /**
 288   Performs an atomic compare exchange operation on a 64-bit unsigned integer.
 289
 290   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
 291   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
 292   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
 293   The compare exchange operation must be performed using MP safe mechanisms.
 294
 295   If Value is NULL, then ASSERT().
 296
 297   @param  Value         A pointer to the 64-bit value for the compare exchange
 298                         operation.
 299   @param  CompareValue  64-bit value used in compare operation.
 300   @param  ExchangeValue 64-bit value used in exchange operation.
 301
 302   @return The original *Value before exchange.
 303
 304 **/
 305 UINT64
 306 EFIAPI
 307 InterlockedCompareExchange64 (
 308   IN OUT  UINT64                    *Value,
 309   IN      UINT64                    CompareValue,
 310   IN      UINT64                    ExchangeValue
 311   )
 312 {
 313   ASSERT (Value != NULL);
 314   return InternalSyncCompareExchange64 (Value, CompareValue, ExchangeValue);
 315 }
 316
 317 /**
 318   Performs an atomic compare exchange operation on a pointer value.
 319
 320   Performs an atomic compare exchange operation on the pointer value specified
 321   by Value. If Value is equal to CompareValue, then Value is set to
 322   ExchangeValue and CompareValue is returned. If Value is not equal to
 323   CompareValue, then Value is returned. The compare exchange operation must be
 324   performed using MP safe mechanisms.
 325
 326   If Value is NULL, then ASSERT().
 327
 328   @param  Value         A pointer to the pointer value for the compare exchange
 329                         operation.
 330   @param  CompareValue  Pointer value used in compare operation.
 331   @param  ExchangeValue Pointer value used in exchange operation.
 332
 333 **/
 334 VOID *
 335 EFIAPI
 336 InterlockedCompareExchangePointer (
 337   IN OUT  VOID                      **Value,
 338   IN      VOID                      *CompareValue,
 339   IN      VOID                      *ExchangeValue
 340   )
 341 {
 342   UINT8  SizeOfValue;
 343
 344   SizeOfValue = sizeof (*Value);
 345
 346   switch (SizeOfValue) {
 347     case sizeof (UINT32):
 348       return (VOID*)(UINTN)InterlockedCompareExchange32 (
 349                              (UINT32*)Value,
 350                              (UINT32)(UINTN)CompareValue,
 351                              (UINT32)(UINTN)ExchangeValue
 352                              );
 353     case sizeof (UINT64):
 354       return (VOID*)(UINTN)InterlockedCompareExchange64 (
 355                              (UINT64*)Value,
 356                              (UINT64)(UINTN)CompareValue,
 357                              (UINT64)(UINTN)ExchangeValue
 358                              );
 359     default:
 360       ASSERT (FALSE);
 361       return NULL;
 362   }
 363 }