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 - 2012, 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   Retrieve the base address of local APIC.
  26
  27   @return The base address of local APIC.
  28
  29 **/
  30 UINTN
  31 EFIAPI
  32 GetLocalApicBaseAddress (
  33   VOID
  34   );
  35
  36 /**
  37   Set the base address of local APIC.
  38
  39   If BaseAddress is not aligned on a 4KB boundary, then ASSERT().
  40
  41   @param[in] BaseAddress   Local APIC base address to be set.
  42
  43 **/
  44 VOID
  45 EFIAPI
  46 SetLocalApicBaseAddress (
  47   IN UINTN                BaseAddress
  48   );
  49
  50 /**
  51   Get the current local APIC mode.
  52
  53   If local APIC is disabled, then ASSERT.
  54
  55   @retval LOCAL_APIC_MODE_XAPIC  current APIC mode is xAPIC.
  56   @retval LOCAL_APIC_MODE_X2APIC current APIC mode is x2APIC.
  57 **/
  58 UINTN
  59 EFIAPI
  60 GetApicMode (
  61   VOID
  62   );
  63
  64 /**
  65   Set the current local APIC mode.
  66
  67   If the specified local APIC mode is not valid, then ASSERT.
  68   If the specified local APIC mode can't be set as current, then ASSERT.
  69
  70   @param ApicMode APIC mode to be set.
  71 **/
  72 VOID
  73 EFIAPI
  74 SetApicMode (
  75   IN UINTN  ApicMode
  76   );
  77
  78 /**
  79   Get the initial local APIC ID of the executing processor assigned by hardware upon power on or reset.
  80
  81   In xAPIC mode, the initial local APIC ID is 8-bit, and may be different from current APIC ID.
  82   In x2APIC mode, the local APIC ID can't be changed and there is no concept of initial APIC ID. In this case,
  83   the 32-bit local APIC ID is returned as initial APIC ID.
  84
  85   @return  32-bit initial local APIC ID of the executing processor.
  86 **/
  87 UINT32
  88 EFIAPI
  89 GetInitialApicId (
  90   VOID
  91   );
  92
  93 /**
  94   Get the local APIC ID of the executing processor.
  95
  96   @return  32-bit local APIC ID of the executing processor.
  97 **/
  98 UINT32
  99 EFIAPI
 100 GetApicId (
 101   VOID
 102   );
 103
 104 /**
 105   Get the value of the local APIC version register.
 106
 107   @return  the value of the local APIC version register.
 108 **/
 109 UINT32
 110 EFIAPI
 111 GetApicVersion (
 112   VOID
 113   );
 114
 115 /**
 116   Send a Fixed IPI to a specified target processor.
 117
 118   This function returns after the IPI has been accepted by the target processor.
 119
 120   @param  ApicId   The local APIC ID of the target processor.
 121   @param  Vector   The vector number of the interrupt being sent.
 122 **/
 123 VOID
 124 EFIAPI
 125 SendFixedIpi (
 126   IN UINT32          ApicId,
 127   IN UINT8           Vector
 128   );
 129
 130 /**
 131   Send a Fixed IPI to all processors excluding self.
 132
 133   This function returns after the IPI has been accepted by the target processors.
 134
 135   @param  Vector   The vector number of the interrupt being sent.
 136 **/
 137 VOID
 138 EFIAPI
 139 SendFixedIpiAllExcludingSelf (
 140   IN UINT8           Vector
 141   );
 142
 143 /**
 144   Send a SMI IPI to a specified target processor.
 145
 146   This function returns after the IPI has been accepted by the target processor.
 147
 148   @param  ApicId   Specify the local APIC ID of the target processor.
 149 **/
 150 VOID
 151 EFIAPI
 152 SendSmiIpi (
 153   IN UINT32          ApicId
 154   );
 155
 156 /**
 157   Send a SMI IPI to all processors excluding self.
 158
 159   This function returns after the IPI has been accepted by the target processors.
 160 **/
 161 VOID
 162 EFIAPI
 163 SendSmiIpiAllExcludingSelf (
 164   VOID
 165   );
 166
 167 /**
 168   Send an INIT IPI to a specified target processor.
 169
 170   This function returns after the IPI has been accepted by the target processor.
 171
 172   @param  ApicId   Specify the local APIC ID of the target processor.
 173 **/
 174 VOID
 175 EFIAPI
 176 SendInitIpi (
 177   IN UINT32          ApicId
 178   );
 179
 180 /**
 181   Send an INIT IPI to all processors excluding self.
 182
 183   This function returns after the IPI has been accepted by the target processors.
 184 **/
 185 VOID
 186 EFIAPI
 187 SendInitIpiAllExcludingSelf (
 188   VOID
 189   );
 190
 191 /**
 192   Send an INIT-Start-up-Start-up IPI sequence to a specified target processor.
 193
 194   This function returns after the IPI has been accepted by the target processor.
 195
 196   if StartupRoutine >= 1M, then ASSERT.
 197   if StartupRoutine is not multiple of 4K, then ASSERT.
 198
 199   @param  ApicId          Specify the local APIC ID of the target processor.
 200   @param  StartupRoutine  Points to a start-up routine which is below 1M physical
 201                           address and 4K aligned.
 202 **/
 203 VOID
 204 EFIAPI
 205 SendInitSipiSipi (
 206   IN UINT32          ApicId,
 207   IN UINT32          StartupRoutine
 208   );
 209
 210 /**
 211   Send an INIT-Start-up-Start-up IPI sequence to all processors excluding self.
 212
 213   This function returns after the IPI has been accepted by the target processors.
 214
 215   if StartupRoutine >= 1M, then ASSERT.
 216   if StartupRoutine is not multiple of 4K, then ASSERT.
 217
 218   @param  StartupRoutine    Points to a start-up routine which is below 1M physical
 219                             address and 4K aligned.
 220 **/
 221 VOID
 222 EFIAPI
 223 SendInitSipiSipiAllExcludingSelf (
 224   IN UINT32          StartupRoutine
 225   );
 226
 227 /**
 228   Programming Virtual Wire Mode.
 229
 230   This function programs the local APIC for virtual wire mode following
 231   the example described in chapter A.3 of the MP 1.4 spec.
 232
 233   IOxAPIC is not involved in this type of virtual wire mode.
 234 **/
 235 VOID
 236 EFIAPI
 237 ProgramVirtualWireMode (
 238   VOID
 239   );
 240
 241 /**
 242   Disable LINT0 & LINT1 interrupts.
 243
 244   This function sets the mask flag in the LVT LINT0 & LINT1 registers.
 245 **/
 246 VOID
 247 EFIAPI
 248 DisableLvtInterrupts (
 249   VOID
 250   );
 251
 252 /**
 253   Read the initial count value from the init-count register.
 254
 255   @return The initial count value read from the init-count register.
 256 **/
 257 UINT32
 258 EFIAPI
 259 GetApicTimerInitCount (
 260   VOID
 261   );
 262
 263 /**
 264   Read the current count value from the current-count register.
 265
 266   @return The current count value read from the current-count register.
 267 **/
 268 UINT32
 269 EFIAPI
 270 GetApicTimerCurrentCount (
 271   VOID
 272   );
 273
 274 /**
 275   Initialize the local APIC timer.
 276
 277   The local APIC timer is initialized and enabled.
 278
 279   @param DivideValue   The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 280                        If it is 0, then use the current divide value in the DCR.
 281   @param InitCount     The initial count value.
 282   @param PeriodicMode  If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 283   @param Vector        The timer interrupt vector number.
 284 **/
 285 VOID
 286 EFIAPI
 287 InitializeApicTimer (
 288   IN UINTN   DivideValue,
 289   IN UINT32  InitCount,
 290   IN BOOLEAN PeriodicMode,
 291   IN UINT8   Vector
 292   );
 293
 294 /**
 295   Get the state of the local APIC timer.
 296
 297   @param DivideValue   Return the divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 298   @param PeriodicMode  Return the timer mode. If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 299   @param Vector        Return the timer interrupt vector number.
 300 **/
 301 VOID
 302 EFIAPI
 303 GetApicTimerState (
 304   OUT UINTN    *DivideValue  OPTIONAL,
 305   OUT BOOLEAN  *PeriodicMode  OPTIONAL,
 306   OUT UINT8    *Vector  OPTIONAL
 307   );
 308
 309 /**
 310   Enable the local APIC timer interrupt.
 311 **/
 312 VOID
 313 EFIAPI
 314 EnableApicTimerInterrupt (
 315   VOID
 316   );
 317
 318 /**
 319   Disable the local APIC timer interrupt.
 320 **/
 321 VOID
 322 EFIAPI
 323 DisableApicTimerInterrupt (
 324   VOID
 325   );
 326
 327 /**
 328   Get the local APIC timer interrupt state.
 329
 330   @retval TRUE  The local APIC timer interrupt is enabled.
 331   @retval FALSE The local APIC timer interrupt is disabled.
 332 **/
 333 BOOLEAN
 334 EFIAPI
 335 GetApicTimerInterruptState (
 336   VOID
 337   );
 338
 339 /**
 340   Send EOI to the local APIC.
 341 **/
 342 VOID
 343 EFIAPI
 344 SendApicEoi (
 345   VOID
 346   );
 347
 348 /**
 349   Get the 32-bit address that a device should use to send a Message Signaled
 350   Interrupt (MSI) to the Local APIC of the currently executing processor.
 351
 352   @return 32-bit address used to send an MSI to the Local APIC.
 353 **/
 354 UINT32
 355 EFIAPI
 356 GetApicMsiAddress (
 357   VOID
 358   );
 359
 360 /**
 361   Get the 64-bit data value that a device should use to send a Message Signaled
 362   Interrupt (MSI) to the Local APIC of the currently executing processor.
 363
 364   If Vector is not in range 0x10..0xFE, then ASSERT().
 365   If DeliveryMode is not supported, then ASSERT().
 366
 367   @param  Vector          The 8-bit interrupt vector associated with the MSI.
 368                           Must be in the range 0x10..0xFE
 369   @param  DeliveryMode    A 3-bit value that specifies how the recept of the MSI
 370                           is handled.  The only supported values are:
 371                             0: LOCAL_APIC_DELIVERY_MODE_FIXED
 372                             1: LOCAL_APIC_DELIVERY_MODE_LOWEST_PRIORITY
 373                             2: LOCAL_APIC_DELIVERY_MODE_SMI
 374                             4: LOCAL_APIC_DELIVERY_MODE_NMI
 375                             5: LOCAL_APIC_DELIVERY_MODE_INIT
 376                             7: LOCAL_APIC_DELIVERY_MODE_EXTINT
 377
 378   @param  LevelTriggered  TRUE specifies a level triggered interrupt.
 379                           FALSE specifies an edge triggered interrupt.
 380   @param  AssertionLevel  Ignored if LevelTriggered is FALSE.
 381                           TRUE specifies a level triggered interrupt that active
 382                           when the interrupt line is asserted.
 383                           FALSE specifies a level triggered interrupt that active
 384                           when the interrupt line is deasserted.
 385
 386   @return 64-bit data value used to send an MSI to the Local APIC.
 387 **/
 388 UINT64
 389 EFIAPI
 390 GetApicMsiValue (
 391   IN UINT8    Vector,
 392   IN UINTN    DeliveryMode,
 393   IN BOOLEAN  LevelTriggered,
 394   IN BOOLEAN  AssertionLevel
 395   );
 396
 397 #endif
 398