UefiCpuPkg/Include/Library/LocalApicLib.h

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