MdePkg/Library/BaseSynchronizationLib/Synchronization.c

   1 /** @file
   2   Implementation of synchronization functions.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #include "BaseSynchronizationLibInternals.h"
  10
  11 #define SPIN_LOCK_RELEASED          ((UINTN) 1)
  12 #define SPIN_LOCK_ACQUIRED          ((UINTN) 2)
  13
  14 /**
  15   Retrieves the architecture specific spin lock alignment requirements for
  16   optimal spin lock performance.
  17
  18   This function retrieves the spin lock alignment requirements for optimal
  19   performance on a given CPU architecture. The spin lock alignment is byte alignment.
  20   It must be a power of two and is returned by this function. If there are no alignment
  21   requirements, then 1 must be returned. The spin lock synchronization
  22   functions must function correctly if the spin lock size and alignment values
  23   returned by this function are not used at all. These values are hints to the
  24   consumers of the spin lock synchronization functions to obtain optimal spin
  25   lock performance.
  26
  27   @return The architecture specific spin lock alignment.
  28
  29 **/
  30 UINTN
  31 EFIAPI
  32 GetSpinLockProperties (
  33   VOID
  34   )
  35 {
  36   return 32;
  37 }
  38
  39 /**
  40   Initializes a spin lock to the released state and returns the spin lock.
  41
  42   This function initializes the spin lock specified by SpinLock to the released
  43   state, and returns SpinLock. Optimal performance can be achieved by calling
  44   GetSpinLockProperties() to determine the size and alignment requirements for
  45   SpinLock.
  46
  47   If SpinLock is NULL, then ASSERT().
  48
  49   @param  SpinLock  A pointer to the spin lock to initialize to the released
  50                     state.
  51
  52   @return SpinLock is in release state.
  53
  54 **/
  55 SPIN_LOCK *
  56 EFIAPI
  57 InitializeSpinLock (
  58   OUT      SPIN_LOCK                 *SpinLock
  59   )
  60 {
  61   ASSERT (SpinLock != NULL);
  62   *SpinLock = SPIN_LOCK_RELEASED;
  63   return SpinLock;
  64 }
  65
  66 /**
  67   Waits until a spin lock can be placed in the acquired state.
  68
  69   This function checks the state of the spin lock specified by SpinLock. If
  70   SpinLock is in the released state, then this function places SpinLock in the
  71   acquired state and returns SpinLock. Otherwise, this function waits
  72   indefinitely for the spin lock to be released, and then places it in the
  73   acquired state and returns SpinLock. All state transitions of SpinLock must
  74   be performed using MP safe mechanisms.
  75
  76   If SpinLock is NULL, then ASSERT().
  77   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
  78   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
  79   PcdSpinLockTimeout microseconds, then ASSERT().
  80
  81   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
  82
  83   @return SpinLock acquired the lock.
  84
  85 **/
  86 SPIN_LOCK *
  87 EFIAPI
  88 AcquireSpinLock (
  89   IN OUT  SPIN_LOCK                 *SpinLock
  90   )
  91 {
  92   UINT64  Current;
  93   UINT64  Previous;
  94   UINT64  Total;
  95   UINT64  Start;
  96   UINT64  End;
  97   UINT64  Timeout;
  98   INT64   Cycle;
  99   INT64   Delta;
 100
 101   if (PcdGet32 (PcdSpinLockTimeout) == 0) {
 102     while (!AcquireSpinLockOrFail (SpinLock)) {
 103       CpuPause ();
 104     }
 105   } else if (!AcquireSpinLockOrFail (SpinLock)) {
 106     //
 107     // Get the current timer value
 108     //
 109     Current = GetPerformanceCounter();
 110
 111     //
 112     // Initialize local variables
 113     //
 114     Start = 0;
 115     End   = 0;
 116     Total = 0;
 117
 118     //
 119     // Retrieve the performance counter properties and compute the number of performance
 120     // counter ticks required to reach the timeout
 121     //
 122     Timeout = DivU64x32 (
 123                 MultU64x32 (
 124                   GetPerformanceCounterProperties (&Start, &End),
 125                   PcdGet32 (PcdSpinLockTimeout)
 126                   ),
 127                 1000000
 128                 );
 129     Cycle = End - Start;
 130     if (Cycle < 0) {
 131       Cycle = -Cycle;
 132     }
 133     Cycle++;
 134
 135     while (!AcquireSpinLockOrFail (SpinLock)) {
 136       CpuPause ();
 137       Previous = Current;
 138       Current  = GetPerformanceCounter();
 139       Delta = (INT64) (Current - Previous);
 140       if (Start > End) {
 141         Delta = -Delta;
 142       }
 143       if (Delta < 0) {
 144         Delta += Cycle;
 145       }
 146       Total += Delta;
 147       ASSERT (Total < Timeout);
 148     }
 149   }
 150   return SpinLock;
 151 }
 152
 153 /**
 154   Attempts to place a spin lock in the acquired state.
 155
 156   This function checks the state of the spin lock specified by SpinLock. If
 157   SpinLock is in the released state, then this function places SpinLock in the
 158   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
 159   transitions of SpinLock must be performed using MP safe mechanisms.
 160
 161   If SpinLock is NULL, then ASSERT().
 162   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 163
 164   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
 165
 166   @retval TRUE  SpinLock was placed in the acquired state.
 167   @retval FALSE SpinLock could not be acquired.
 168
 169 **/
 170 BOOLEAN
 171 EFIAPI
 172 AcquireSpinLockOrFail (
 173   IN OUT  SPIN_LOCK                 *SpinLock
 174   )
 175 {
 176   SPIN_LOCK    LockValue;
 177
 178   ASSERT (SpinLock != NULL);
 179
 180   LockValue = *SpinLock;
 181   ASSERT (SPIN_LOCK_ACQUIRED == LockValue || SPIN_LOCK_RELEASED == LockValue);
 182
 183   return (BOOLEAN)(
 184            InterlockedCompareExchangePointer (
 185              (VOID**)SpinLock,
 186              (VOID*)SPIN_LOCK_RELEASED,
 187              (VOID*)SPIN_LOCK_ACQUIRED
 188              ) == (VOID*)SPIN_LOCK_RELEASED
 189            );
 190 }
 191
 192 /**
 193   Releases a spin lock.
 194
 195   This function places the spin lock specified by SpinLock in the release state
 196   and returns SpinLock.
 197
 198   If SpinLock is NULL, then ASSERT().
 199   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 200
 201   @param  SpinLock  A pointer to the spin lock to release.
 202
 203   @return SpinLock released lock.
 204
 205 **/
 206 SPIN_LOCK *
 207 EFIAPI
 208 ReleaseSpinLock (
 209   IN OUT  SPIN_LOCK                 *SpinLock
 210   )
 211 {
 212   SPIN_LOCK    LockValue;
 213
 214   ASSERT (SpinLock != NULL);
 215
 216   LockValue = *SpinLock;
 217   ASSERT (SPIN_LOCK_ACQUIRED == LockValue || SPIN_LOCK_RELEASED == LockValue);
 218
 219   *SpinLock = SPIN_LOCK_RELEASED;
 220   return SpinLock;
 221 }
 222
 223 /**
 224   Performs an atomic increment of an 32-bit unsigned integer.
 225
 226   Performs an atomic increment of the 32-bit unsigned integer specified by
 227   Value and returns the incremented value. The increment operation must be
 228   performed using MP safe mechanisms.
 229
 230   If Value is NULL, then ASSERT().
 231
 232   @param  Value A pointer to the 32-bit value to increment.
 233
 234   @return The incremented value.
 235
 236 **/
 237 UINT32
 238 EFIAPI
 239 InterlockedIncrement (
 240   IN      volatile UINT32           *Value
 241   )
 242 {
 243   ASSERT (Value != NULL);
 244   return InternalSyncIncrement (Value);
 245 }
 246
 247 /**
 248   Performs an atomic decrement of an 32-bit unsigned integer.
 249
 250   Performs an atomic decrement of the 32-bit unsigned integer specified by
 251   Value and returns the decremented value. The decrement operation must be
 252   performed using MP safe mechanisms.
 253
 254   If Value is NULL, then ASSERT().
 255
 256   @param  Value A pointer to the 32-bit value to decrement.
 257
 258   @return The decremented value.
 259
 260 **/
 261 UINT32
 262 EFIAPI
 263 InterlockedDecrement (
 264   IN      volatile UINT32           *Value
 265   )
 266 {
 267   ASSERT (Value != NULL);
 268   return InternalSyncDecrement (Value);
 269 }
 270
 271 /**
 272   Performs an atomic compare exchange operation on a 16-bit unsigned integer.
 273
 274   Performs an atomic compare exchange operation on the 16-bit unsigned integer
 275   specified by Value.  If Value is equal to CompareValue, then Value is set to
 276   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 277   then Value is returned.  The compare exchange operation must be performed using
 278   MP safe mechanisms.
 279
 280   If Value is NULL, then ASSERT().
 281
 282   @param  Value         A pointer to the 16-bit value for the compare exchange
 283                         operation.
 284   @param  CompareValue  16-bit value used in compare operation.
 285   @param  ExchangeValue 16-bit value used in exchange operation.
 286
 287   @return The original *Value before exchange.
 288
 289 **/
 290 UINT16
 291 EFIAPI
 292 InterlockedCompareExchange16 (
 293   IN OUT  volatile UINT16           *Value,
 294   IN      UINT16                    CompareValue,
 295   IN      UINT16                    ExchangeValue
 296   )
 297 {
 298   ASSERT (Value != NULL);
 299   return InternalSyncCompareExchange16 (Value, CompareValue, ExchangeValue);
 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  volatile 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  volatile 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   @return The original *Value before exchange.
 380 **/
 381 VOID *
 382 EFIAPI
 383 InterlockedCompareExchangePointer (
 384   IN OUT  VOID                      * volatile *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                              (volatile UINT32 *)Value,
 397                              (UINT32)(UINTN)CompareValue,
 398                              (UINT32)(UINTN)ExchangeValue
 399                              );
 400     case sizeof (UINT64):
 401       return (VOID*)(UINTN)InterlockedCompareExchange64 (
 402                              (volatile UINT64 *)Value,
 403                              (UINT64)(UINTN)CompareValue,
 404                              (UINT64)(UINTN)ExchangeValue
 405                              );
 406     default:
 407       ASSERT (FALSE);
 408       return NULL;
 409   }
 410 }