MdePkg/Library/BaseLib/SynchronizationMsc.c

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