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 - 2011, 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   Disable LINT0 & LINT1 interrupts.
 217
 218   This function sets the mask flag in the LVT LINT0 & LINT1 registers.
 219 **/
 220 VOID
 221 EFIAPI
 222 DisableLvtInterrupts (
 223   VOID
 224   );
 225
 226 /**
 227   Read the initial count value from the init-count register.
 228
 229   @return The initial count value read from the init-count register.
 230 **/
 231 UINT32
 232 EFIAPI
 233 GetApicTimerInitCount (
 234   VOID
 235   );
 236
 237 /**
 238   Read the current count value from the current-count register.
 239
 240   @return The current count value read from the current-count register.
 241 **/
 242 UINT32
 243 EFIAPI
 244 GetApicTimerCurrentCount (
 245   VOID
 246   );
 247
 248 /**
 249   Initialize the local APIC timer.
 250
 251   The local APIC timer is initialized and enabled.
 252
 253   @param DivideValue   The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 254                        If it is 0, then use the current divide value in the DCR.
 255   @param InitCount     The initial count value.
 256   @param PeriodicMode  If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 257   @param Vector        The timer interrupt vector number.
 258 **/
 259 VOID
 260 EFIAPI
 261 InitializeApicTimer (
 262   IN UINTN   DivideValue,
 263   IN UINT32  InitCount,
 264   IN BOOLEAN PeriodicMode,
 265   IN UINT8   Vector
 266   );
 267
 268 /**
 269   Get the state of the local APIC timer.
 270
 271   @param DivideValue   Return the divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 272   @param PeriodicMode  Return the timer mode. If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 273   @param Vector        Return the timer interrupt vector number.
 274 **/
 275 VOID
 276 EFIAPI
 277 GetApicTimerState (
 278   OUT UINTN    *DivideValue  OPTIONAL,
 279   OUT BOOLEAN  *PeriodicMode  OPTIONAL,
 280   OUT UINT8    *Vector  OPTIONAL
 281   );
 282
 283 /**
 284   Enable the local APIC timer interrupt.
 285 **/
 286 VOID
 287 EFIAPI
 288 EnableApicTimerInterrupt (
 289   VOID
 290   );
 291
 292 /**
 293   Disable the local APIC timer interrupt.
 294 **/
 295 VOID
 296 EFIAPI
 297 DisableApicTimerInterrupt (
 298   VOID
 299   );
 300
 301 /**
 302   Get the local APIC timer interrupt state.
 303
 304   @retval TRUE  The local APIC timer interrupt is enabled.
 305   @retval FALSE The local APIC timer interrupt is disabled.
 306 **/
 307 BOOLEAN
 308 EFIAPI
 309 GetApicTimerInterruptState (
 310   VOID
 311   );
 312
 313 /**
 314   Send EOI to the local APIC.
 315 **/
 316 VOID
 317 EFIAPI
 318 SendApicEoi (
 319   VOID
 320   );
 321
 322 /**
 323   Get the 32-bit address that a device should use to send a Message Signaled
 324   Interrupt (MSI) to the Local APIC of the currently executing processor.
 325
 326   @return 32-bit address used to send an MSI to the Local APIC.
 327 **/
 328 UINT32
 329 EFIAPI
 330 GetApicMsiAddress (
 331   VOID
 332   );
 333
 334 /**
 335   Get the 64-bit data value that a device should use to send a Message Signaled
 336   Interrupt (MSI) to the Local APIC of the currently executing processor.
 337
 338   If Vector is not in range 0x10..0xFE, then ASSERT().
 339   If DeliveryMode is not supported, then ASSERT().
 340
 341   @param  Vector          The 8-bit interrupt vector associated with the MSI.
 342                           Must be in the range 0x10..0xFE
 343   @param  DeliveryMode    A 3-bit value that specifies how the recept of the MSI
 344                           is handled.  The only supported values are:
 345                             0: LOCAL_APIC_DELIVERY_MODE_FIXED
 346                             1: LOCAL_APIC_DELIVERY_MODE_LOWEST_PRIORITY
 347                             2: LOCAL_APIC_DELIVERY_MODE_SMI
 348                             4: LOCAL_APIC_DELIVERY_MODE_NMI
 349                             5: LOCAL_APIC_DELIVERY_MODE_INIT
 350                             7: LOCAL_APIC_DELIVERY_MODE_EXTINT
 351
 352   @param  LevelTriggered  TRUE specifies a level triggered interrupt.
 353                           FALSE specifies an edge triggered interrupt.
 354   @param  AssertionLevel  Ignored if LevelTriggered is FALSE.
 355                           TRUE specifies a level triggered interrupt that active
 356                           when the interrupt line is asserted.
 357                           FALSE specifies a level triggered interrupt that active
 358                           when the interrupt line is deasserted.
 359
 360   @return 64-bit data value used to send an MSI to the Local APIC.
 361 **/
 362 UINT64
 363 EFIAPI
 364 GetApicMsiValue (
 365   IN UINT8    Vector,
 366   IN UINTN    DeliveryMode,
 367   IN BOOLEAN  LevelTriggered,
 368   IN BOOLEAN  AssertionLevel
 369   );
 370
 371 #endif
 372