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