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
 134     Cycle++;
 135
 136     while (!AcquireSpinLockOrFail (SpinLock)) {
 137       CpuPause ();
 138       Previous = Current;
 139       Current  = GetPerformanceCounter ();
 140       Delta    = (INT64)(Current - Previous);
 141       if (Start > End) {
 142         Delta = -Delta;
 143       }
 144
 145       if (Delta < 0) {
 146         Delta += Cycle;
 147       }
 148
 149       Total += Delta;
 150       ASSERT (Total < Timeout);
 151     }
 152   }
 153
 154   return SpinLock;
 155 }
 156
 157 /**
 158   Attempts to place a spin lock in the acquired state.
 159
 160   This function checks the state of the spin lock specified by SpinLock. If
 161   SpinLock is in the released state, then this function places SpinLock in the
 162   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
 163   transitions of SpinLock must be performed using MP safe mechanisms.
 164
 165   If SpinLock is NULL, then ASSERT().
 166   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 167
 168   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
 169
 170   @retval TRUE  SpinLock was placed in the acquired state.
 171   @retval FALSE SpinLock could not be acquired.
 172
 173 **/
 174 BOOLEAN
 175 EFIAPI
 176 AcquireSpinLockOrFail (
 177   IN OUT  SPIN_LOCK  *SpinLock
 178   )
 179 {
 180   SPIN_LOCK  LockValue;
 181
 182   ASSERT (SpinLock != NULL);
 183
 184   LockValue = *SpinLock;
 185   ASSERT (SPIN_LOCK_ACQUIRED == LockValue || SPIN_LOCK_RELEASED == LockValue);
 186
 187   return (BOOLEAN)(
 188                    InterlockedCompareExchangePointer (
 189                      (VOID **)SpinLock,
 190                      (VOID *)SPIN_LOCK_RELEASED,
 191                      (VOID *)SPIN_LOCK_ACQUIRED
 192                      ) == (VOID *)SPIN_LOCK_RELEASED
 193                    );
 194 }
 195
 196 /**
 197   Releases a spin lock.
 198
 199   This function places the spin lock specified by SpinLock in the release state
 200   and returns SpinLock.
 201
 202   If SpinLock is NULL, then ASSERT().
 203   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
 204
 205   @param  SpinLock  A pointer to the spin lock to release.
 206
 207   @return SpinLock released lock.
 208
 209 **/
 210 SPIN_LOCK *
 211 EFIAPI
 212 ReleaseSpinLock (
 213   IN OUT  SPIN_LOCK  *SpinLock
 214   )
 215 {
 216   SPIN_LOCK  LockValue;
 217
 218   ASSERT (SpinLock != NULL);
 219
 220   LockValue = *SpinLock;
 221   ASSERT (SPIN_LOCK_ACQUIRED == LockValue || SPIN_LOCK_RELEASED == LockValue);
 222
 223   *SpinLock = SPIN_LOCK_RELEASED;
 224   return SpinLock;
 225 }
 226
 227 /**
 228   Performs an atomic increment of an 32-bit unsigned integer.
 229
 230   Performs an atomic increment of the 32-bit unsigned integer specified by
 231   Value and returns the incremented value. The increment operation must be
 232   performed using MP safe mechanisms.
 233
 234   If Value is NULL, then ASSERT().
 235
 236   @param  Value A pointer to the 32-bit value to increment.
 237
 238   @return The incremented value.
 239
 240 **/
 241 UINT32
 242 EFIAPI
 243 InterlockedIncrement (
 244   IN      volatile UINT32  *Value
 245   )
 246 {
 247   ASSERT (Value != NULL);
 248   return InternalSyncIncrement (Value);
 249 }
 250
 251 /**
 252   Performs an atomic decrement of an 32-bit unsigned integer.
 253
 254   Performs an atomic decrement of the 32-bit unsigned integer specified by
 255   Value and returns the decremented value. The decrement operation must be
 256   performed using MP safe mechanisms.
 257
 258   If Value is NULL, then ASSERT().
 259
 260   @param  Value A pointer to the 32-bit value to decrement.
 261
 262   @return The decremented value.
 263
 264 **/
 265 UINT32
 266 EFIAPI
 267 InterlockedDecrement (
 268   IN      volatile UINT32  *Value
 269   )
 270 {
 271   ASSERT (Value != NULL);
 272   return InternalSyncDecrement (Value);
 273 }
 274
 275 /**
 276   Performs an atomic compare exchange operation on a 16-bit unsigned integer.
 277
 278   Performs an atomic compare exchange operation on the 16-bit unsigned integer
 279   specified by Value.  If Value is equal to CompareValue, then Value is set to
 280   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 281   then Value is returned.  The compare exchange operation must be performed using
 282   MP safe mechanisms.
 283
 284   If Value is NULL, then ASSERT().
 285
 286   @param  Value         A pointer to the 16-bit value for the compare exchange
 287                         operation.
 288   @param  CompareValue  16-bit value used in compare operation.
 289   @param  ExchangeValue 16-bit value used in exchange operation.
 290
 291   @return The original *Value before exchange.
 292
 293 **/
 294 UINT16
 295 EFIAPI
 296 InterlockedCompareExchange16 (
 297   IN OUT  volatile UINT16  *Value,
 298   IN      UINT16           CompareValue,
 299   IN      UINT16           ExchangeValue
 300   )
 301 {
 302   ASSERT (Value != NULL);
 303   return InternalSyncCompareExchange16 (Value, CompareValue, ExchangeValue);
 304 }
 305
 306 /**
 307   Performs an atomic compare exchange operation on a 32-bit unsigned integer.
 308
 309   Performs an atomic compare exchange operation on the 32-bit unsigned integer
 310   specified by Value.  If Value is equal to CompareValue, then Value is set to
 311   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
 312   then Value is returned.  The compare exchange operation must be performed using
 313   MP safe mechanisms.
 314
 315   If Value is NULL, then ASSERT().
 316
 317   @param  Value         A pointer to the 32-bit value for the compare exchange
 318                         operation.
 319   @param  CompareValue  32-bit value used in compare operation.
 320   @param  ExchangeValue 32-bit value used in exchange operation.
 321
 322   @return The original *Value before exchange.
 323
 324 **/
 325 UINT32
 326 EFIAPI
 327 InterlockedCompareExchange32 (
 328   IN OUT  volatile UINT32  *Value,
 329   IN      UINT32           CompareValue,
 330   IN      UINT32           ExchangeValue
 331   )
 332 {
 333   ASSERT (Value != NULL);
 334   return InternalSyncCompareExchange32 (Value, CompareValue, ExchangeValue);
 335 }
 336
 337 /**
 338   Performs an atomic compare exchange operation on a 64-bit unsigned integer.
 339
 340   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
 341   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
 342   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
 343   The compare exchange operation must be performed using MP safe mechanisms.
 344
 345   If Value is NULL, then ASSERT().
 346
 347   @param  Value         A pointer to the 64-bit value for the compare exchange
 348                         operation.
 349   @param  CompareValue  64-bit value used in compare operation.
 350   @param  ExchangeValue 64-bit value used in exchange operation.
 351
 352   @return The original *Value before exchange.
 353
 354 **/
 355 UINT64
 356 EFIAPI
 357 InterlockedCompareExchange64 (
 358   IN OUT  volatile UINT64  *Value,
 359   IN      UINT64           CompareValue,
 360   IN      UINT64           ExchangeValue
 361   )
 362 {
 363   ASSERT (Value != NULL);
 364   return InternalSyncCompareExchange64 (Value, CompareValue, ExchangeValue);
 365 }
 366
 367 /**
 368   Performs an atomic compare exchange operation on a pointer value.
 369
 370   Performs an atomic compare exchange operation on the pointer value specified
 371   by Value. If Value is equal to CompareValue, then Value is set to
 372   ExchangeValue and CompareValue is returned. If Value is not equal to
 373   CompareValue, then Value is returned. The compare exchange operation must be
 374   performed using MP safe mechanisms.
 375
 376   If Value is NULL, then ASSERT().
 377
 378   @param  Value         A pointer to the pointer value for the compare exchange
 379                         operation.
 380   @param  CompareValue  Pointer value used in compare operation.
 381   @param  ExchangeValue Pointer value used in exchange operation.
 382
 383   @return The original *Value before exchange.
 384 **/
 385 VOID *
 386 EFIAPI
 387 InterlockedCompareExchangePointer (
 388   IN OUT  VOID                      *volatile  *Value,
 389   IN      VOID                                 *CompareValue,
 390   IN      VOID                                 *ExchangeValue
 391   )
 392 {
 393   UINT8  SizeOfValue;
 394
 395   SizeOfValue = sizeof (*Value);
 396
 397   switch (SizeOfValue) {
 398     case sizeof (UINT32):
 399       return (VOID *)(UINTN)InterlockedCompareExchange32 (
 400                               (volatile UINT32 *)Value,
 401                               (UINT32)(UINTN)CompareValue,
 402                               (UINT32)(UINTN)ExchangeValue
 403                               );
 404     case sizeof (UINT64):
 405       return (VOID *)(UINTN)InterlockedCompareExchange64 (
 406                               (volatile UINT64 *)Value,
 407                               (UINT64)(UINTN)CompareValue,
 408                               (UINT64)(UINTN)ExchangeValue
 409                               );
 410     default:
 411       ASSERT (FALSE);
 412       return NULL;
 413   }
 414 }