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