MdePkg/Include/Library/SynchronizationLib.h - edk2 - Git at Google

 /** @file
   Provides synchronization functions.

 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
 SPDX-License-Identifier: BSD-2-Clause-Patent

 **/

 #ifndef __SYNCHRONIZATION_LIB__
 #define __SYNCHRONIZATION_LIB__

 ///
 /// Definitions for SPIN_LOCK
 ///
 typedef volatile UINTN SPIN_LOCK;

 /**
   Retrieves the architecture-specific spin lock alignment requirements for
   optimal spin lock performance.

   This function retrieves the spin lock alignment requirements for optimal
   performance on a given CPU architecture. The spin lock alignment is byte alignment.
   It must be a power of two and is returned by this function. If there are no alignment
   requirements, then 1 must be returned. The spin lock synchronization
   functions must function correctly if the spin lock size and alignment values
   returned by this function are not used at all. These values are hints to the
   consumers of the spin lock synchronization functions to obtain optimal spin
   lock performance.

   @return The architecture-specific spin lock alignment.

 **/
 UINTN
 EFIAPI
 GetSpinLockProperties (
   VOID
   );

 /**
   Initializes a spin lock to the released state and returns the spin lock.

   This function initializes the spin lock specified by SpinLock to the released
   state, and returns SpinLock. Optimal performance can be achieved by calling
   GetSpinLockProperties() to determine the size and alignment requirements for
   SpinLock.

   If SpinLock is NULL, then ASSERT().

   @param  SpinLock  A pointer to the spin lock to initialize to the released
                     state.

   @return SpinLock in release state.

 **/
 SPIN_LOCK *
 EFIAPI
 InitializeSpinLock (
   OUT      SPIN_LOCK  *SpinLock
   );

 /**
   Waits until a spin lock can be placed in the acquired state.

   This function checks the state of the spin lock specified by SpinLock. If
   SpinLock is in the released state, then this function places SpinLock in the
   acquired state and returns SpinLock. Otherwise, this function waits
   indefinitely for the spin lock to be released, and then places it in the
   acquired state and returns SpinLock. All state transitions of SpinLock must
   be performed using MP safe mechanisms.

   If SpinLock is NULL, then ASSERT().
   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
   PcdSpinLockTimeout microseconds, then ASSERT().

   @param  SpinLock  A pointer to the spin lock to place in the acquired state.

   @return SpinLock acquired lock.

 **/
 SPIN_LOCK *
 EFIAPI
 AcquireSpinLock (
   IN OUT  SPIN_LOCK  *SpinLock
   );

 /**
   Attempts to place a spin lock in the acquired state.

   This function checks the state of the spin lock specified by SpinLock. If
   SpinLock is in the released state, then this function places SpinLock in the
   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
   transitions of SpinLock must be performed using MP safe mechanisms.

   If SpinLock is NULL, then ASSERT().
   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().

   @param  SpinLock  A pointer to the spin lock to place in the acquired state.

   @retval TRUE  SpinLock was placed in the acquired state.
   @retval FALSE SpinLock could not be acquired.

 **/
 BOOLEAN
 EFIAPI
 AcquireSpinLockOrFail (
   IN OUT  SPIN_LOCK  *SpinLock
   );

 /**
   Releases a spin lock.

   This function places the spin lock specified by SpinLock in the release state
   and returns SpinLock.

   If SpinLock is NULL, then ASSERT().
   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().

   @param  SpinLock  A pointer to the spin lock to release.

   @return SpinLock released lock.

 **/
 SPIN_LOCK *
 EFIAPI
 ReleaseSpinLock (
   IN OUT  SPIN_LOCK  *SpinLock
   );

 /**
   Performs an atomic increment of a 32-bit unsigned integer.

   Performs an atomic increment of the 32-bit unsigned integer specified by
   Value and returns the incremented value. The increment operation must be
   performed using MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value A pointer to the 32-bit value to increment.

   @return The incremented value.

 **/
 UINT32
 EFIAPI
 InterlockedIncrement (
   IN      volatile UINT32  *Value
   );

 /**
   Performs an atomic decrement of a 32-bit unsigned integer.

   Performs an atomic decrement of the 32-bit unsigned integer specified by
   Value and returns the decremented value. The decrement operation must be
   performed using MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value A pointer to the 32-bit value to decrement.

   @return The decremented value.

 **/
 UINT32
 EFIAPI
 InterlockedDecrement (
   IN      volatile UINT32  *Value
   );

 /**
   Performs an atomic compare exchange operation on a 16-bit unsigned integer.

   Performs an atomic compare exchange operation on the 16-bit unsigned integer
   specified by Value.  If Value is equal to CompareValue, then Value is set to
   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
   then Value is returned.  The compare exchange operation must be performed using
   MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value         A pointer to the 16-bit value for the compare exchange
                         operation.
   @param  CompareValue  16-bit value used in compare operation.
   @param  ExchangeValue 16-bit value used in exchange operation.

   @return The original *Value before exchange.
 **/
 UINT16
 EFIAPI
 InterlockedCompareExchange16 (
   IN OUT  volatile UINT16  *Value,
   IN      UINT16           CompareValue,
   IN      UINT16           ExchangeValue
   );

 /**
   Performs an atomic compare exchange operation on a 32-bit unsigned integer.

   Performs an atomic compare exchange operation on the 32-bit unsigned integer
   specified by Value.  If Value is equal to CompareValue, then Value is set to
   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
   then Value is returned.  The compare exchange operation must be performed using
   MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value         A pointer to the 32-bit value for the compare exchange
                         operation.
   @param  CompareValue  32-bit value used in compare operation.
   @param  ExchangeValue 32-bit value used in exchange operation.

   @return The original *Value before exchange.

 **/
 UINT32
 EFIAPI
 InterlockedCompareExchange32 (
   IN OUT  volatile UINT32  *Value,
   IN      UINT32           CompareValue,
   IN      UINT32           ExchangeValue
   );

 /**
   Performs an atomic compare exchange operation on a 64-bit unsigned integer.

   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
   The compare exchange operation must be performed using MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value         A pointer to the 64-bit value for the compare exchange
                         operation.
   @param  CompareValue  64-bit value used in compare operation.
   @param  ExchangeValue 64-bit value used in exchange operation.

   @return The original *Value before exchange.

 **/
 UINT64
 EFIAPI
 InterlockedCompareExchange64 (
   IN OUT  volatile UINT64  *Value,
   IN      UINT64           CompareValue,
   IN      UINT64           ExchangeValue
   );

 /**
   Performs an atomic compare exchange operation on a pointer value.

   Performs an atomic compare exchange operation on the pointer value specified
   by Value. If Value is equal to CompareValue, then Value is set to
   ExchangeValue and CompareValue is returned. If Value is not equal to
   CompareValue, then Value is returned. The compare exchange operation must be
   performed using MP safe mechanisms.

   If Value is NULL, then ASSERT().

   @param  Value         A pointer to the pointer value for the compare exchange
                         operation.
   @param  CompareValue  Pointer value used in compare operation.
   @param  ExchangeValue Pointer value used in exchange operation.

   @return The original *Value before exchange.
 **/
 VOID *
 EFIAPI
 InterlockedCompareExchangePointer (
   IN OUT  VOID                      *volatile  *Value,
   IN      VOID                                 *CompareValue,
   IN      VOID                                 *ExchangeValue
   );

 #endif
	/** @file
	Provides synchronization functions.

	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
	SPDX-License-Identifier: BSD-2-Clause-Patent

	**/

	#ifndef __SYNCHRONIZATION_LIB__
	#define __SYNCHRONIZATION_LIB__

	///
	/// Definitions for SPIN_LOCK
	///
	typedef volatile UINTN SPIN_LOCK;

	/**
	Retrieves the architecture-specific spin lock alignment requirements for
	optimal spin lock performance.

	This function retrieves the spin lock alignment requirements for optimal
	performance on a given CPU architecture. The spin lock alignment is byte alignment.
	It must be a power of two and is returned by this function. If there are no alignment
	requirements, then 1 must be returned. The spin lock synchronization
	functions must function correctly if the spin lock size and alignment values
	returned by this function are not used at all. These values are hints to the
	consumers of the spin lock synchronization functions to obtain optimal spin
	lock performance.

	@return The architecture-specific spin lock alignment.

	**/
	UINTN
	EFIAPI
	GetSpinLockProperties (
	VOID
	);

	/**
	Initializes a spin lock to the released state and returns the spin lock.

	This function initializes the spin lock specified by SpinLock to the released
	state, and returns SpinLock. Optimal performance can be achieved by calling
	GetSpinLockProperties() to determine the size and alignment requirements for
	SpinLock.

	If SpinLock is NULL, then ASSERT().

	@param SpinLock A pointer to the spin lock to initialize to the released
	state.

	@return SpinLock in release state.

	**/
	SPIN_LOCK *
	EFIAPI
	InitializeSpinLock (
	OUT SPIN_LOCK *SpinLock
	);

	/**
	Waits until a spin lock can be placed in the acquired state.

	This function checks the state of the spin lock specified by SpinLock. If
	SpinLock is in the released state, then this function places SpinLock in the
	acquired state and returns SpinLock. Otherwise, this function waits
	indefinitely for the spin lock to be released, and then places it in the
	acquired state and returns SpinLock. All state transitions of SpinLock must
	be performed using MP safe mechanisms.

	If SpinLock is NULL, then ASSERT().
	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
	If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
	PcdSpinLockTimeout microseconds, then ASSERT().

	@param SpinLock A pointer to the spin lock to place in the acquired state.

	@return SpinLock acquired lock.

	**/
	SPIN_LOCK *
	EFIAPI
	AcquireSpinLock (
	IN OUT SPIN_LOCK *SpinLock
	);

	/**
	Attempts to place a spin lock in the acquired state.

	This function checks the state of the spin lock specified by SpinLock. If
	SpinLock is in the released state, then this function places SpinLock in the
	acquired state and returns TRUE. Otherwise, FALSE is returned. All state
	transitions of SpinLock must be performed using MP safe mechanisms.

	If SpinLock is NULL, then ASSERT().
	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().

	@param SpinLock A pointer to the spin lock to place in the acquired state.

	@retval TRUE SpinLock was placed in the acquired state.
	@retval FALSE SpinLock could not be acquired.

	**/
	BOOLEAN
	EFIAPI
	AcquireSpinLockOrFail (
	IN OUT SPIN_LOCK *SpinLock
	);

	/**
	Releases a spin lock.

	This function places the spin lock specified by SpinLock in the release state
	and returns SpinLock.

	If SpinLock is NULL, then ASSERT().
	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().

	@param SpinLock A pointer to the spin lock to release.

	@return SpinLock released lock.

	**/
	SPIN_LOCK *
	EFIAPI
	ReleaseSpinLock (
	IN OUT SPIN_LOCK *SpinLock
	);

	/**
	Performs an atomic increment of a 32-bit unsigned integer.

	Performs an atomic increment of the 32-bit unsigned integer specified by
	Value and returns the incremented value. The increment operation must be
	performed using MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the 32-bit value to increment.

	@return The incremented value.

	**/
	UINT32
	EFIAPI
	InterlockedIncrement (
	IN volatile UINT32 *Value
	);

	/**
	Performs an atomic decrement of a 32-bit unsigned integer.

	Performs an atomic decrement of the 32-bit unsigned integer specified by
	Value and returns the decremented value. The decrement operation must be
	performed using MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the 32-bit value to decrement.

	@return The decremented value.

	**/
	UINT32
	EFIAPI
	InterlockedDecrement (
	IN volatile UINT32 *Value
	);

	/**
	Performs an atomic compare exchange operation on a 16-bit unsigned integer.

	Performs an atomic compare exchange operation on the 16-bit unsigned integer
	specified by Value. If Value is equal to CompareValue, then Value is set to
	ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
	then Value is returned. The compare exchange operation must be performed using
	MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the 16-bit value for the compare exchange
	operation.
	@param CompareValue 16-bit value used in compare operation.
	@param ExchangeValue 16-bit value used in exchange operation.

	@return The original *Value before exchange.
	**/
	UINT16
	EFIAPI
	InterlockedCompareExchange16 (
	IN OUT volatile UINT16 *Value,
	IN UINT16 CompareValue,
	IN UINT16 ExchangeValue
	);

	/**
	Performs an atomic compare exchange operation on a 32-bit unsigned integer.

	Performs an atomic compare exchange operation on the 32-bit unsigned integer
	specified by Value. If Value is equal to CompareValue, then Value is set to
	ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
	then Value is returned. The compare exchange operation must be performed using
	MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the 32-bit value for the compare exchange
	operation.
	@param CompareValue 32-bit value used in compare operation.
	@param ExchangeValue 32-bit value used in exchange operation.

	@return The original *Value before exchange.

	**/
	UINT32
	EFIAPI
	InterlockedCompareExchange32 (
	IN OUT volatile UINT32 *Value,
	IN UINT32 CompareValue,
	IN UINT32 ExchangeValue
	);

	/**
	Performs an atomic compare exchange operation on a 64-bit unsigned integer.

	Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
	by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
	CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
	The compare exchange operation must be performed using MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the 64-bit value for the compare exchange
	operation.
	@param CompareValue 64-bit value used in compare operation.
	@param ExchangeValue 64-bit value used in exchange operation.

	@return The original *Value before exchange.

	**/
	UINT64
	EFIAPI
	InterlockedCompareExchange64 (
	IN OUT volatile UINT64 *Value,
	IN UINT64 CompareValue,
	IN UINT64 ExchangeValue
	);

	/**
	Performs an atomic compare exchange operation on a pointer value.

	Performs an atomic compare exchange operation on the pointer value specified
	by Value. If Value is equal to CompareValue, then Value is set to
	ExchangeValue and CompareValue is returned. If Value is not equal to
	CompareValue, then Value is returned. The compare exchange operation must be
	performed using MP safe mechanisms.

	If Value is NULL, then ASSERT().

	@param Value A pointer to the pointer value for the compare exchange
	operation.
	@param CompareValue Pointer value used in compare operation.
	@param ExchangeValue Pointer value used in exchange operation.

	@return The original *Value before exchange.
	**/
	VOID *
	EFIAPI
	InterlockedCompareExchangePointer (
	IN OUT VOID volatile Value,
	IN VOID *CompareValue,
	IN VOID *ExchangeValue
	);

	#endif