[mirror_edk2.git] / MdePkg / Include / Library / SynchronizationLib.h

/** @file\r
  Provides synchronization functions.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __SYNCHRONIZATION_LIB__\r
#define __SYNCHRONIZATION_LIB__\r
\r
///\r
/// Definitions for SPIN_LOCK\r
///\r
typedef volatile UINTN              SPIN_LOCK;\r
\r
\r
/**\r
  Retrieves the architecture-specific spin lock alignment requirements for\r
  optimal spin lock performance.\r
\r
  This function retrieves the spin lock alignment requirements for optimal\r
  performance on a given CPU architecture. The spin lock alignment is byte alignment.\r
  It must be a power of two and is returned by this function. If there are no alignment\r
  requirements, then 1 must be returned. The spin lock synchronization\r
  functions must function correctly if the spin lock size and alignment values\r
  returned by this function are not used at all. These values are hints to the\r
  consumers of the spin lock synchronization functions to obtain optimal spin\r
  lock performance.\r
\r
  @return The architecture-specific spin lock alignment.\r
\r
**/\r
UINTN\r
EFIAPI\r
GetSpinLockProperties (\r
  VOID\r
  );\r
\r
\r
/**\r
  Initializes a spin lock to the released state and returns the spin lock.\r
\r
  This function initializes the spin lock specified by SpinLock to the released\r
  state, and returns SpinLock. Optimal performance can be achieved by calling\r
  GetSpinLockProperties() to determine the size and alignment requirements for\r
  SpinLock.\r
\r
  If SpinLock is NULL, then ASSERT().\r
\r
  @param  SpinLock  A pointer to the spin lock to initialize to the released\r
                    state.\r
\r
  @return SpinLock in release state.\r
\r
**/\r
SPIN_LOCK *\r
EFIAPI\r
InitializeSpinLock (\r
  OUT      SPIN_LOCK                 *SpinLock\r
  );\r
\r
\r
/**\r
  Waits until a spin lock can be placed in the acquired state.\r
\r
  This function checks the state of the spin lock specified by SpinLock. If\r
  SpinLock is in the released state, then this function places SpinLock in the\r
  acquired state and returns SpinLock. Otherwise, this function waits\r
  indefinitely for the spin lock to be released, and then places it in the\r
  acquired state and returns SpinLock. All state transitions of SpinLock must\r
  be performed using MP safe mechanisms.\r
\r
  If SpinLock is NULL, then ASSERT().\r
  If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
  If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in\r
  PcdSpinLockTimeout microseconds, then ASSERT().\r
\r
  @param  SpinLock  A pointer to the spin lock to place in the acquired state.\r
\r
  @return SpinLock acquired lock.\r
\r
**/\r
SPIN_LOCK *\r
EFIAPI\r
AcquireSpinLock (\r
  IN OUT  SPIN_LOCK                 *SpinLock\r
  );\r
\r
\r
/**\r
  Attempts to place a spin lock in the acquired state.\r
\r
  This function checks the state of the spin lock specified by SpinLock. If\r
  SpinLock is in the released state, then this function places SpinLock in the\r
  acquired state and returns TRUE. Otherwise, FALSE is returned. All state\r
  transitions of SpinLock must be performed using MP safe mechanisms.\r
\r
  If SpinLock is NULL, then ASSERT().\r
  If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
\r
  @param  SpinLock  A pointer to the spin lock to place in the acquired state.\r
\r
  @retval TRUE  SpinLock was placed in the acquired state.\r
  @retval FALSE SpinLock could not be acquired.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
AcquireSpinLockOrFail (\r
  IN OUT  SPIN_LOCK                 *SpinLock\r
  );\r
\r
\r
/**\r
  Releases a spin lock.\r
\r
  This function places the spin lock specified by SpinLock in the release state\r
  and returns SpinLock.\r
\r
  If SpinLock is NULL, then ASSERT().\r
  If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
\r
  @param  SpinLock  A pointer to the spin lock to release.\r
\r
  @return SpinLock released lock.\r
\r
**/\r
SPIN_LOCK *\r
EFIAPI\r
ReleaseSpinLock (\r
  IN OUT  SPIN_LOCK                 *SpinLock\r
  );\r
\r
\r
/**\r
  Performs an atomic increment of a 32-bit unsigned integer.\r
\r
  Performs an atomic increment of the 32-bit unsigned integer specified by\r
  Value and returns the incremented value. The increment operation must be\r
  performed using MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value A pointer to the 32-bit value to increment.\r
\r
  @return The incremented value.\r
\r
**/\r
UINT32\r
EFIAPI\r
InterlockedIncrement (\r
  IN      volatile UINT32           *Value\r
  );\r
\r
\r
/**\r
  Performs an atomic decrement of a 32-bit unsigned integer.\r
\r
  Performs an atomic decrement of the 32-bit unsigned integer specified by\r
  Value and returns the decremented value. The decrement operation must be\r
  performed using MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value A pointer to the 32-bit value to decrement.\r
\r
  @return The decremented value.\r
\r
**/\r
UINT32\r
EFIAPI\r
InterlockedDecrement (\r
  IN      volatile UINT32           *Value\r
  );\r
\r
\r
/**\r
  Performs an atomic compare exchange operation on a 16-bit unsigned integer.\r
\r
  Performs an atomic compare exchange operation on the 16-bit unsigned integer\r
  specified by Value.  If Value is equal to CompareValue, then Value is set to\r
  ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,\r
  then Value is returned.  The compare exchange operation must be performed using\r
  MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value         A pointer to the 16-bit value for the compare exchange\r
                        operation.\r
  @param  CompareValue  16-bit value used in compare operation.\r
  @param  ExchangeValue 16-bit value used in exchange operation.\r
\r
  @return The original *Value before exchange.\r
**/\r
UINT16\r
EFIAPI\r
InterlockedCompareExchange16 (\r
  IN OUT  volatile UINT16           *Value,\r
  IN      UINT16                    CompareValue,\r
  IN      UINT16                    ExchangeValue\r
  );\r
\r
/**\r
  Performs an atomic compare exchange operation on a 32-bit unsigned integer.\r
\r
  Performs an atomic compare exchange operation on the 32-bit unsigned integer\r
  specified by Value.  If Value is equal to CompareValue, then Value is set to\r
  ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,\r
  then Value is returned.  The compare exchange operation must be performed using\r
  MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value         A pointer to the 32-bit value for the compare exchange\r
                        operation.\r
  @param  CompareValue  32-bit value used in compare operation.\r
  @param  ExchangeValue 32-bit value used in exchange operation.\r
\r
  @return The original *Value before exchange.\r
\r
**/\r
UINT32\r
EFIAPI\r
InterlockedCompareExchange32 (\r
  IN OUT  volatile UINT32           *Value,\r
  IN      UINT32                    CompareValue,\r
  IN      UINT32                    ExchangeValue\r
  );\r
\r
\r
/**\r
  Performs an atomic compare exchange operation on a 64-bit unsigned integer.\r
\r
  Performs an atomic compare exchange operation on the 64-bit unsigned integer specified\r
  by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and\r
  CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.\r
  The compare exchange operation must be performed using MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value         A pointer to the 64-bit value for the compare exchange\r
                        operation.\r
  @param  CompareValue  64-bit value used in compare operation.\r
  @param  ExchangeValue 64-bit value used in exchange operation.\r
\r
  @return The original *Value before exchange.\r
\r
**/\r
UINT64\r
EFIAPI\r
InterlockedCompareExchange64 (\r
  IN OUT  volatile UINT64           *Value,\r
  IN      UINT64                    CompareValue,\r
  IN      UINT64                    ExchangeValue\r
  );\r
\r
\r
/**\r
  Performs an atomic compare exchange operation on a pointer value.\r
\r
  Performs an atomic compare exchange operation on the pointer value specified\r
  by Value. If Value is equal to CompareValue, then Value is set to\r
  ExchangeValue and CompareValue is returned. If Value is not equal to\r
  CompareValue, then Value is returned. The compare exchange operation must be\r
  performed using MP safe mechanisms.\r
\r
  If Value is NULL, then ASSERT().\r
\r
  @param  Value         A pointer to the pointer value for the compare exchange\r
                        operation.\r
  @param  CompareValue  Pointer value used in compare operation.\r
  @param  ExchangeValue Pointer value used in exchange operation.\r
\r
  @return The original *Value before exchange.\r
**/\r
VOID *\r
EFIAPI\r
InterlockedCompareExchangePointer (\r
  IN OUT  VOID                      * volatile *Value,\r
  IN      VOID                      *CompareValue,\r
  IN      VOID                      *ExchangeValue\r
  );\r
\r
#endif\r
\r
\r
Commit	Line	Data
720d3c5f	1	/** @file\r
	2	Provides synchronization functions.\r
	3	\r
9095d37b	4	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
9344f092	5	SPDX-License-Identifier: BSD-2-Clause-Patent\r
720d3c5f	6	\r
	7	**/\r
	8	\r
	9	#ifndef __SYNCHRONIZATION_LIB__\r
	10	#define __SYNCHRONIZATION_LIB__\r
	11	\r
	12	///\r
	13	/// Definitions for SPIN_LOCK\r
	14	///\r
	15	typedef volatile UINTN SPIN_LOCK;\r
	16	\r
	17	\r
	18	/**\r
1a2f870c	19	Retrieves the architecture-specific spin lock alignment requirements for\r
720d3c5f	20	optimal spin lock performance.\r
	21	\r
	22	This function retrieves the spin lock alignment requirements for optimal\r
9095d37b	23	performance on a given CPU architecture. The spin lock alignment is byte alignment.\r
744265eb	24	It must be a power of two and is returned by this function. If there are no alignment\r
720d3c5f	25	requirements, then 1 must be returned. The spin lock synchronization\r
	26	functions must function correctly if the spin lock size and alignment values\r
	27	returned by this function are not used at all. These values are hints to the\r
	28	consumers of the spin lock synchronization functions to obtain optimal spin\r
	29	lock performance.\r
	30	\r
1a2f870c	31	@return The architecture-specific spin lock alignment.\r
720d3c5f	32	\r
	33	**/\r
	34	UINTN\r
	35	EFIAPI\r
	36	GetSpinLockProperties (\r
	37	VOID\r
	38	);\r
	39	\r
	40	\r
	41	/**\r
	42	Initializes a spin lock to the released state and returns the spin lock.\r
	43	\r
	44	This function initializes the spin lock specified by SpinLock to the released\r
	45	state, and returns SpinLock. Optimal performance can be achieved by calling\r
	46	GetSpinLockProperties() to determine the size and alignment requirements for\r
	47	SpinLock.\r
	48	\r
	49	If SpinLock is NULL, then ASSERT().\r
	50	\r
	51	@param SpinLock A pointer to the spin lock to initialize to the released\r
	52	state.\r
	53	\r
	54	@return SpinLock in release state.\r
	55	\r
	56	**/\r
	57	SPIN_LOCK *\r
	58	EFIAPI\r
	59	InitializeSpinLock (\r
	60	OUT SPIN_LOCK *SpinLock\r
	61	);\r
	62	\r
	63	\r
	64	/**\r
	65	Waits until a spin lock can be placed in the acquired state.\r
	66	\r
	67	This function checks the state of the spin lock specified by SpinLock. If\r
	68	SpinLock is in the released state, then this function places SpinLock in the\r
	69	acquired state and returns SpinLock. Otherwise, this function waits\r
	70	indefinitely for the spin lock to be released, and then places it in the\r
	71	acquired state and returns SpinLock. All state transitions of SpinLock must\r
	72	be performed using MP safe mechanisms.\r
	73	\r
	74	If SpinLock is NULL, then ASSERT().\r
	75	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
	76	If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in\r
	77	PcdSpinLockTimeout microseconds, then ASSERT().\r
	78	\r
	79	@param SpinLock A pointer to the spin lock to place in the acquired state.\r
	80	\r
	81	@return SpinLock acquired lock.\r
	82	\r
	83	**/\r
	84	SPIN_LOCK *\r
	85	EFIAPI\r
	86	AcquireSpinLock (\r
	87	IN OUT SPIN_LOCK *SpinLock\r
	88	);\r
	89	\r
	90	\r
	91	/**\r
	92	Attempts to place a spin lock in the acquired state.\r
	93	\r
	94	This function checks the state of the spin lock specified by SpinLock. If\r
	95	SpinLock is in the released state, then this function places SpinLock in the\r
96	acquired state and returns TRUE. Otherwise, FALSE is returned. All state\r
97	transitions of SpinLock must be performed using MP safe mechanisms.\r
98	\r
99	If SpinLock is NULL, then ASSERT().\r
100	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
101	\r
102	@param SpinLock A pointer to the spin lock to place in the acquired state.\r
103	\r
104	@retval TRUE SpinLock was placed in the acquired state.\r
105	@retval FALSE SpinLock could not be acquired.\r
106	\r
107	**/\r
108	BOOLEAN\r
109	EFIAPI\r
110	AcquireSpinLockOrFail (\r
111	IN OUT SPIN_LOCK *SpinLock\r
112	);\r
113	\r
114	\r
115	/**\r
116	Releases a spin lock.\r
117	\r
118	This function places the spin lock specified by SpinLock in the release state\r
119	and returns SpinLock.\r
120	\r
121	If SpinLock is NULL, then ASSERT().\r
122	If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
123	\r
124	@param SpinLock A pointer to the spin lock to release.\r
125	\r
126	@return SpinLock released lock.\r
127	\r
128	**/\r
129	SPIN_LOCK *\r
130	EFIAPI\r
131	ReleaseSpinLock (\r
132	IN OUT SPIN_LOCK *SpinLock\r
133	);\r
134	\r
135	\r
136	/**\r
1a2f870c	137	Performs an atomic increment of a 32-bit unsigned integer.\r
720d3c5f	138	\r
	139	Performs an atomic increment of the 32-bit unsigned integer specified by\r
	140	Value and returns the incremented value. The increment operation must be\r
17634d02	141	performed using MP safe mechanisms.\r
720d3c5f	142	\r
	143	If Value is NULL, then ASSERT().\r
	144	\r
	145	@param Value A pointer to the 32-bit value to increment.\r
	146	\r
	147	@return The incremented value.\r
	148	\r
	149	**/\r
	150	UINT32\r
	151	EFIAPI\r
	152	InterlockedIncrement (\r
7375f3f1	153	IN volatile UINT32 *Value\r
720d3c5f	154	);\r
	155	\r
	156	\r
	157	/**\r
1a2f870c	158	Performs an atomic decrement of a 32-bit unsigned integer.\r
720d3c5f	159	\r
	160	Performs an atomic decrement of the 32-bit unsigned integer specified by\r
	161	Value and returns the decremented value. The decrement operation must be\r
17634d02	162	performed using MP safe mechanisms.\r
720d3c5f	163	\r
	164	If Value is NULL, then ASSERT().\r
	165	\r
	166	@param Value A pointer to the 32-bit value to decrement.\r
	167	\r
	168	@return The decremented value.\r
	169	\r
	170	**/\r
	171	UINT32\r
	172	EFIAPI\r
	173	InterlockedDecrement (\r
7375f3f1	174	IN volatile UINT32 *Value\r
720d3c5f	175	);\r
	176	\r
	177	\r
9b89163e AB	178	/**\r
	179	Performs an atomic compare exchange operation on a 16-bit unsigned integer.\r
	180	\r
	181	Performs an atomic compare exchange operation on the 16-bit unsigned integer\r
	182	specified by Value. If Value is equal to CompareValue, then Value is set to\r
	183	ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,\r
	184	then Value is returned. The compare exchange operation must be performed using\r
	185	MP safe mechanisms.\r
	186	\r
	187	If Value is NULL, then ASSERT().\r
	188	\r
	189	@param Value A pointer to the 16-bit value for the compare exchange\r
	190	operation.\r
	191	@param CompareValue 16-bit value used in compare operation.\r
	192	@param ExchangeValue 16-bit value used in exchange operation.\r
	193	\r
	194	@return The original *Value before exchange.\r
	195	**/\r
	196	UINT16\r
	197	EFIAPI\r
	198	InterlockedCompareExchange16 (\r
7375f3f1	199	IN OUT volatile UINT16 *Value,\r
9b89163e AB	200	IN UINT16 CompareValue,\r
	201	IN UINT16 ExchangeValue\r
	202	);\r
	203	\r
720d3c5f	204	/**\r
	205	Performs an atomic compare exchange operation on a 32-bit unsigned integer.\r
	206	\r
	207	Performs an atomic compare exchange operation on the 32-bit unsigned integer\r
	208	specified by Value. If Value is equal to CompareValue, then Value is set to\r
	209	ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,\r
	210	then Value is returned. The compare exchange operation must be performed using\r
	211	MP safe mechanisms.\r
	212	\r
	213	If Value is NULL, then ASSERT().\r
	214	\r
	215	@param Value A pointer to the 32-bit value for the compare exchange\r
	216	operation.\r
	217	@param CompareValue 32-bit value used in compare operation.\r
	218	@param ExchangeValue 32-bit value used in exchange operation.\r
	219	\r
	220	@return The original *Value before exchange.\r
	221	\r
	222	**/\r
	223	UINT32\r
	224	EFIAPI\r
	225	InterlockedCompareExchange32 (\r
7375f3f1	226	IN OUT volatile UINT32 *Value,\r
720d3c5f	227	IN UINT32 CompareValue,\r
	228	IN UINT32 ExchangeValue\r
	229	);\r
	230	\r
	231	\r
	232	/**\r
	233	Performs an atomic compare exchange operation on a 64-bit unsigned integer.\r
	234	\r
	235	Performs an atomic compare exchange operation on the 64-bit unsigned integer specified\r
	236	by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and\r
	237	CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.\r
	238	The compare exchange operation must be performed using MP safe mechanisms.\r
	239	\r
	240	If Value is NULL, then ASSERT().\r
	241	\r
	242	@param Value A pointer to the 64-bit value for the compare exchange\r
	243	operation.\r
	244	@param CompareValue 64-bit value used in compare operation.\r
	245	@param ExchangeValue 64-bit value used in exchange operation.\r
	246	\r
	247	@return The original *Value before exchange.\r
	248	\r
	249	**/\r
	250	UINT64\r
	251	EFIAPI\r
	252	InterlockedCompareExchange64 (\r
7375f3f1	253	IN OUT volatile UINT64 *Value,\r
720d3c5f	254	IN UINT64 CompareValue,\r
	255	IN UINT64 ExchangeValue\r
	256	);\r
	257	\r
	258	\r
	259	/**\r
	260	Performs an atomic compare exchange operation on a pointer value.\r
	261	\r
	262	Performs an atomic compare exchange operation on the pointer value specified\r
	263	by Value. If Value is equal to CompareValue, then Value is set to\r
	264	ExchangeValue and CompareValue is returned. If Value is not equal to\r
	265	CompareValue, then Value is returned. The compare exchange operation must be\r
	266	performed using MP safe mechanisms.\r
	267	\r
	268	If Value is NULL, then ASSERT().\r
	269	\r
	270	@param Value A pointer to the pointer value for the compare exchange\r
	271	operation.\r
	272	@param CompareValue Pointer value used in compare operation.\r
	273	@param ExchangeValue Pointer value used in exchange operation.\r
	274	\r
	275	@return The original *Value before exchange.\r
	276	**/\r
	277	VOID *\r
	278	EFIAPI\r
	279	InterlockedCompareExchangePointer (\r
7375f3f1	280	IN OUT VOID * volatile *Value,\r
720d3c5f	281	IN VOID *CompareValue,\r
	282	IN VOID *ExchangeValue\r
	283	);\r
	284	\r
	285	#endif\r
	286	\r
	287	\r