[mirror_edk2.git] / UefiCpuPkg / Include / Library / LocalApicLib.h

/** @file\r
  Public include file for Local APIC library.\r
\r
  Local APIC library assumes local APIC is enabled. It does not\r
  handles cases where local APIC is disabled.\r
\r
  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
  This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef __LOCAL_APIC_LIB_H__\r
#define __LOCAL_APIC_LIB_H__\r
\r
#define LOCAL_APIC_MODE_XAPIC   0x1  ///< xAPIC mode.\r
#define LOCAL_APIC_MODE_X2APIC  0x2  ///< x2APIC mode.\r
\r
/**\r
  Get the current local APIC mode.\r
\r
  If local APIC is disabled, then ASSERT.\r
\r
  @retval LOCAL_APIC_MODE_XAPIC  current APIC mode is xAPIC.\r
  @retval LOCAL_APIC_MODE_X2APIC current APIC mode is x2APIC.\r
**/\r
UINTN\r
EFIAPI\r
GetApicMode (\r
  VOID\r
  );\r
\r
/**\r
  Set the current local APIC mode.\r
\r
  If the specified local APIC mode is not valid, then ASSERT.\r
  If the specified local APIC mode can't be set as current, then ASSERT.\r
\r
  @param ApicMode APIC mode to be set.\r
**/\r
VOID\r
EFIAPI\r
SetApicMode (\r
  IN UINTN  ApicMode\r
  );\r
\r
/**\r
  Get the initial local APIC ID of the executing processor assigned by hardware upon power on or reset.\r
\r
  In xAPIC mode, the initial local APIC ID is 8-bit, and may be different from current APIC ID.\r
  In x2APIC mode, the local APIC ID can't be changed and there is no concept of initial APIC ID. In this case, \r
  the 32-bit local APIC ID is returned as initial APIC ID.\r
\r
  @return  32-bit initial local APIC ID of the executing processor.\r
**/\r
UINT32\r
EFIAPI\r
GetInitialApicId (\r
  VOID\r
  );\r
\r
/**\r
  Get the local APIC ID of the executing processor.\r
\r
  @return  32-bit local APIC ID of the executing processor.\r
**/\r
UINT32\r
EFIAPI\r
GetApicId (\r
  VOID\r
  );\r
\r
/**\r
  Get the value of the local APIC version register.\r
\r
  @return  the value of the local APIC version register.\r
**/\r
UINT32\r
EFIAPI\r
GetApicVersion (\r
  VOID\r
  );\r
\r
/**\r
  Send a Fixed IPI to a specified target processor.\r
\r
  This function returns after the IPI has been accepted by the target processor. \r
\r
  @param  ApicId   The local APIC ID of the target processor.\r
  @param  Vector   The vector number of the interrupt being sent.\r
**/\r
VOID\r
EFIAPI\r
SendFixedIpi (\r
  IN UINT32          ApicId,\r
  IN UINT8           Vector\r
  );\r
\r
/**\r
  Send a Fixed IPI to all processors excluding self.\r
\r
  This function returns after the IPI has been accepted by the target processors. \r
\r
  @param  Vector   The vector number of the interrupt being sent.\r
**/\r
VOID\r
EFIAPI\r
SendFixedIpiAllExcludingSelf (\r
  IN UINT8           Vector\r
  );\r
\r
/**\r
  Send a SMI IPI to a specified target processor.\r
\r
  This function returns after the IPI has been accepted by the target processor. \r
\r
  @param  ApicId   Specify the local APIC ID of the target processor.\r
**/\r
VOID\r
EFIAPI\r
SendSmiIpi (\r
  IN UINT32          ApicId\r
  );\r
\r
/**\r
  Send a SMI IPI to all processors excluding self.\r
\r
  This function returns after the IPI has been accepted by the target processors. \r
**/\r
VOID\r
EFIAPI\r
SendSmiIpiAllExcludingSelf (\r
  VOID\r
  );\r
\r
/**\r
  Send an INIT IPI to a specified target processor.\r
\r
  This function returns after the IPI has been accepted by the target processor. \r
\r
  @param  ApicId   Specify the local APIC ID of the target processor.\r
**/\r
VOID\r
EFIAPI\r
SendInitIpi (\r
  IN UINT32          ApicId\r
  );\r
\r
/**\r
  Send an INIT IPI to all processors excluding self.\r
\r
  This function returns after the IPI has been accepted by the target processors. \r
**/\r
VOID\r
EFIAPI\r
SendInitIpiAllExcludingSelf (\r
  VOID\r
  );\r
\r
/**\r
  Send an INIT-Start-up-Start-up IPI sequence to a specified target processor.\r
\r
  This function returns after the IPI has been accepted by the target processor. \r
\r
  if StartupRoutine >= 1M, then ASSERT.\r
  if StartupRoutine is not multiple of 4K, then ASSERT.\r
\r
  @param  ApicId          Specify the local APIC ID of the target processor.\r
  @param  StartupRoutine  Points to a start-up routine which is below 1M physical\r
                          address and 4K aligned.\r
**/\r
VOID\r
EFIAPI\r
SendInitSipiSipi (\r
  IN UINT32          ApicId,\r
  IN UINT32          StartupRoutine\r
  );\r
\r
/**\r
  Send an INIT-Start-up-Start-up IPI sequence to all processors excluding self.\r
\r
  This function returns after the IPI has been accepted by the target processors. \r
\r
  if StartupRoutine >= 1M, then ASSERT.\r
  if StartupRoutine is not multiple of 4K, then ASSERT.\r
\r
  @param  StartupRoutine    Points to a start-up routine which is below 1M physical\r
                            address and 4K aligned.\r
**/\r
VOID\r
EFIAPI\r
SendInitSipiSipiAllExcludingSelf (\r
  IN UINT32          StartupRoutine\r
  );\r
\r
/**\r
  Programming Virtual Wire Mode.\r
\r
  This function programs the local APIC for virtual wire mode following\r
  the example described in chapter A.3 of the MP 1.4 spec.\r
\r
  IOxAPIC is not involved in this type of virtual wire mode.\r
**/\r
VOID\r
EFIAPI\r
ProgramVirtualWireMode (\r
  VOID\r
  );\r
\r
/**\r
  Read the initial count value from the init-count register.\r
\r
  @return The initial count value read from the init-count register.\r
**/\r
UINT32\r
EFIAPI\r
GetApicTimerInitCount (\r
  VOID\r
  );\r
\r
/**\r
  Read the current count value from the current-count register.\r
\r
  @return The current count value read from the current-count register.\r
**/\r
UINT32\r
EFIAPI\r
GetApicTimerCurrentCount (\r
  VOID\r
  );\r
\r
/**\r
  Initialize the local APIC timer.\r
\r
  The local APIC timer is initialized and enabled.\r
\r
  @param DivideValue   The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.\r
                       If it is 0, then use the current divide value in the DCR.\r
  @param InitCount     The initial count value.\r
  @param PeriodicMode  If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.\r
  @param Vector        The timer interrupt vector number.\r
**/\r
VOID\r
EFIAPI\r
InitializeApicTimer (\r
  IN UINTN   DivideValue,\r
  IN UINT32  InitCount,\r
  IN BOOLEAN PeriodicMode,\r
  IN UINT8   Vector\r
  );\r
\r
/**\r
  Get the state of the local APIC timer.\r
\r
  @param DivideValue   Return the divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.\r
  @param PeriodicMode  Return the timer mode. If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.\r
  @param Vector        Return the timer interrupt vector number.\r
**/\r
VOID\r
EFIAPI\r
GetApicTimerState (\r
  OUT UINTN    *DivideValue  OPTIONAL,\r
  OUT BOOLEAN  *PeriodicMode  OPTIONAL,\r
  OUT UINT8    *Vector  OPTIONAL\r
  );\r
\r
/**\r
  Enable the local APIC timer interrupt.\r
**/\r
VOID\r
EFIAPI\r
EnableApicTimerInterrupt (\r
  VOID\r
  );\r
\r
/**\r
  Disable the local APIC timer interrupt.\r
**/\r
VOID\r
EFIAPI\r
DisableApicTimerInterrupt (\r
  VOID\r
  );\r
\r
/**\r
  Get the local APIC timer interrupt state.\r
\r
  @retval TRUE  The local APIC timer interrupt is enabled.\r
  @retval FALSE The local APIC timer interrupt is disabled.\r
**/\r
BOOLEAN\r
EFIAPI\r
GetApicTimerInterruptState (\r
  VOID\r
  );\r
\r
/**\r
  Send EOI to the local APIC.\r
**/\r
VOID\r
EFIAPI\r
SendApicEoi (\r
  VOID\r
  );\r
\r
#endif\r
\r
Commit	Line	Data
bf73cc4b	1	/** @file\r
	2	Public include file for Local APIC library.\r
	3	\r
	4	Local APIC library assumes local APIC is enabled. It does not\r
	5	handles cases where local APIC is disabled.\r
	6	\r
	7	Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
	8	This program and the accompanying materials\r
	9	are licensed and made available under the terms and conditions of the BSD License\r
	10	which accompanies this distribution. The full text of the license may be found at\r
	11	http://opensource.org/licenses/bsd-license.php\r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	15	\r
	16	**/\r
	17	\r
	18	#ifndef __LOCAL_APIC_LIB_H__\r
	19	#define __LOCAL_APIC_LIB_H__\r
	20	\r
	21	#define LOCAL_APIC_MODE_XAPIC 0x1 ///< xAPIC mode.\r
	22	#define LOCAL_APIC_MODE_X2APIC 0x2 ///< x2APIC mode.\r
	23	\r
	24	/**\r
	25	Get the current local APIC mode.\r
	26	\r
	27	If local APIC is disabled, then ASSERT.\r
	28	\r
	29	@retval LOCAL_APIC_MODE_XAPIC current APIC mode is xAPIC.\r
	30	@retval LOCAL_APIC_MODE_X2APIC current APIC mode is x2APIC.\r
	31	**/\r
	32	UINTN\r
	33	EFIAPI\r
	34	GetApicMode (\r
	35	VOID\r
	36	);\r
	37	\r
	38	/**\r
	39	Set the current local APIC mode.\r
	40	\r
	41	If the specified local APIC mode is not valid, then ASSERT.\r
	42	If the specified local APIC mode can't be set as current, then ASSERT.\r
	43	\r
	44	@param ApicMode APIC mode to be set.\r
	45	**/\r
	46	VOID\r
	47	EFIAPI\r
	48	SetApicMode (\r
	49	IN UINTN ApicMode\r
	50	);\r
	51	\r
	52	/**\r
	53	Get the initial local APIC ID of the executing processor assigned by hardware upon power on or reset.\r
	54	\r
	55	In xAPIC mode, the initial local APIC ID is 8-bit, and may be different from current APIC ID.\r
	56	In x2APIC mode, the local APIC ID can't be changed and there is no concept of initial APIC ID. In this case, \r
	57	the 32-bit local APIC ID is returned as initial APIC ID.\r
	58	\r
	59	@return 32-bit initial local APIC ID of the executing processor.\r
	60	**/\r
	61	UINT32\r
	62	EFIAPI\r
	63	GetInitialApicId (\r
	64	VOID\r
65	);\r
66	\r
67	/**\r
68	Get the local APIC ID of the executing processor.\r
69	\r
70	@return 32-bit local APIC ID of the executing processor.\r
71	**/\r
72	UINT32\r
73	EFIAPI\r
74	GetApicId (\r
75	VOID\r
76	);\r
77	\r
ae40aef1	78	/**\r
	79	Get the value of the local APIC version register.\r
	80	\r
	81	@return the value of the local APIC version register.\r
	82	**/\r
	83	UINT32\r
	84	EFIAPI\r
	85	GetApicVersion (\r
	86	VOID\r
	87	);\r
	88	\r
	89	/**\r
	90	Send a Fixed IPI to a specified target processor.\r
	91	\r
	92	This function returns after the IPI has been accepted by the target processor. \r
	93	\r
	94	@param ApicId The local APIC ID of the target processor.\r
	95	@param Vector The vector number of the interrupt being sent.\r
	96	**/\r
	97	VOID\r
	98	EFIAPI\r
	99	SendFixedIpi (\r
	100	IN UINT32 ApicId,\r
	101	IN UINT8 Vector\r
	102	);\r
	103	\r
	104	/**\r
	105	Send a Fixed IPI to all processors excluding self.\r
	106	\r
	107	This function returns after the IPI has been accepted by the target processors. \r
	108	\r
	109	@param Vector The vector number of the interrupt being sent.\r
	110	**/\r
	111	VOID\r
	112	EFIAPI\r
	113	SendFixedIpiAllExcludingSelf (\r
	114	IN UINT8 Vector\r
	115	);\r
	116	\r
bf73cc4b	117	/**\r
	118	Send a SMI IPI to a specified target processor.\r
	119	\r
	120	This function returns after the IPI has been accepted by the target processor. \r
	121	\r
	122	@param ApicId Specify the local APIC ID of the target processor.\r
	123	**/\r
	124	VOID\r
	125	EFIAPI\r
	126	SendSmiIpi (\r
	127	IN UINT32 ApicId\r
	128	);\r
	129	\r
	130	/**\r
	131	Send a SMI IPI to all processors excluding self.\r
	132	\r
	133	This function returns after the IPI has been accepted by the target processors. \r
	134	**/\r
	135	VOID\r
	136	EFIAPI\r
	137	SendSmiIpiAllExcludingSelf (\r
	138	VOID\r
	139	);\r
	140	\r
	141	/**\r
	142	Send an INIT IPI to a specified target processor.\r
	143	\r
	144	This function returns after the IPI has been accepted by the target processor. \r
	145	\r
	146	@param ApicId Specify the local APIC ID of the target processor.\r
	147	**/\r
	148	VOID\r
	149	EFIAPI\r
	150	SendInitIpi (\r
	151	IN UINT32 ApicId\r
	152	);\r
	153	\r
	154	/**\r
	155	Send an INIT IPI to all processors excluding self.\r
	156	\r
	157	This function returns after the IPI has been accepted by the target processors. \r
	158	**/\r
	159	VOID\r
	160	EFIAPI\r
	161	SendInitIpiAllExcludingSelf (\r
	162	VOID\r
	163	);\r
	164	\r
	165	/**\r
	166	Send an INIT-Start-up-Start-up IPI sequence to a specified target processor.\r
	167	\r
	168	This function returns after the IPI has been accepted by the target processor. \r
	169	\r
	170	if StartupRoutine >= 1M, then ASSERT.\r
	171	if StartupRoutine is not multiple of 4K, then ASSERT.\r
	172	\r
	173	@param ApicId Specify the local APIC ID of the target processor.\r
	174	@param StartupRoutine Points to a start-up routine which is below 1M physical\r
	175	address and 4K aligned.\r
	176	**/\r
	177	VOID\r
	178	EFIAPI\r
	179	SendInitSipiSipi (\r
	180	IN UINT32 ApicId,\r
181	IN UINT32 StartupRoutine\r
182	);\r
183	\r
184	/**\r
185	Send an INIT-Start-up-Start-up IPI sequence to all processors excluding self.\r
186	\r
187	This function returns after the IPI has been accepted by the target processors. \r
188	\r
189	if StartupRoutine >= 1M, then ASSERT.\r
190	if StartupRoutine is not multiple of 4K, then ASSERT.\r
191	\r
192	@param StartupRoutine Points to a start-up routine which is below 1M physical\r
193	address and 4K aligned.\r
194	**/\r
195	VOID\r
196	EFIAPI\r
197	SendInitSipiSipiAllExcludingSelf (\r
198	IN UINT32 StartupRoutine\r
199	);\r
200	\r
201	/**\r
202	Programming Virtual Wire Mode.\r
203	\r
204	This function programs the local APIC for virtual wire mode following\r
205	the example described in chapter A.3 of the MP 1.4 spec.\r
206	\r
207	IOxAPIC is not involved in this type of virtual wire mode.\r
208	**/\r
209	VOID\r
210	EFIAPI\r
211	ProgramVirtualWireMode (\r
212	VOID\r
213	);\r
214	\r
bf73cc4b	215	/**\r
	216	Read the initial count value from the init-count register.\r
	217	\r
	218	@return The initial count value read from the init-count register.\r
	219	**/\r
	220	UINT32\r
	221	EFIAPI\r
	222	GetApicTimerInitCount (\r
	223	VOID\r
	224	);\r
	225	\r
	226	/**\r
	227	Read the current count value from the current-count register.\r
	228	\r
	229	@return The current count value read from the current-count register.\r
	230	**/\r
	231	UINT32\r
	232	EFIAPI\r
	233	GetApicTimerCurrentCount (\r
	234	VOID\r
	235	);\r
	236	\r
	237	/**\r
	238	Initialize the local APIC timer.\r
	239	\r
	240	The local APIC timer is initialized and enabled.\r
	241	\r
	242	@param DivideValue The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.\r
	243	If it is 0, then use the current divide value in the DCR.\r
	244	@param InitCount The initial count value.\r
	245	@param PeriodicMode If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.\r
	246	@param Vector The timer interrupt vector number.\r
	247	**/\r
	248	VOID\r
	249	EFIAPI\r
	250	InitializeApicTimer (\r
	251	IN UINTN DivideValue,\r
	252	IN UINT32 InitCount,\r
	253	IN BOOLEAN PeriodicMode,\r
	254	IN UINT8 Vector\r
	255	);\r
	256	\r
ae40aef1	257	/**\r
	258	Get the state of the local APIC timer.\r
	259	\r
	260	@param DivideValue Return the divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.\r
	261	@param PeriodicMode Return the timer mode. If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.\r
	262	@param Vector Return the timer interrupt vector number.\r
	263	**/\r
	264	VOID\r
	265	EFIAPI\r
	266	GetApicTimerState (\r
	267	OUT UINTN *DivideValue OPTIONAL,\r
	268	OUT BOOLEAN *PeriodicMode OPTIONAL,\r
	269	OUT UINT8 *Vector OPTIONAL\r
	270	);\r
	271	\r
bf73cc4b	272	/**\r
	273	Enable the local APIC timer interrupt.\r
	274	**/\r
	275	VOID\r
	276	EFIAPI\r
	277	EnableApicTimerInterrupt (\r
	278	VOID\r
	279	);\r
	280	\r
	281	/**\r
	282	Disable the local APIC timer interrupt.\r
	283	**/\r
	284	VOID\r
	285	EFIAPI\r
	286	DisableApicTimerInterrupt (\r
	287	VOID\r
	288	);\r
	289	\r
	290	/**\r
	291	Get the local APIC timer interrupt state.\r
	292	\r
	293	@retval TRUE The local APIC timer interrupt is enabled.\r
	294	@retval FALSE The local APIC timer interrupt is disabled.\r
	295	**/\r
	296	BOOLEAN\r
	297	EFIAPI\r
	298	GetApicTimerInterruptState (\r
	299	VOID\r
	300	);\r
	301	\r
	302	/**\r
	303	Send EOI to the local APIC.\r
	304	**/\r
	305	VOID\r
	306	EFIAPI\r
	307	SendApicEoi (\r
	308	VOID\r
	309	);\r
	310	\r
	311	#endif\r
	312	\r