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