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