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 - 2015, 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   Initialize the state of the SoftwareEnable bit in the Local APIC
 232   Spurious Interrupt Vector register.
 233
 234   @param  Enable  If TRUE, then set SoftwareEnable to 1
 235                   If FALSE, then set SoftwareEnable to 0.
 236
 237 **/
 238 VOID
 239 EFIAPI
 240 InitializeLocalApicSoftwareEnable (
 241   IN BOOLEAN  Enable
 242   );
 243
 244 /**
 245   Programming Virtual Wire Mode.
 246
 247   This function programs the local APIC for virtual wire mode following
 248   the example described in chapter A.3 of the MP 1.4 spec.
 249
 250   IOxAPIC is not involved in this type of virtual wire mode.
 251 **/
 252 VOID
 253 EFIAPI
 254 ProgramVirtualWireMode (
 255   VOID
 256   );
 257
 258 /**
 259   Disable LINT0 & LINT1 interrupts.
 260
 261   This function sets the mask flag in the LVT LINT0 & LINT1 registers.
 262 **/
 263 VOID
 264 EFIAPI
 265 DisableLvtInterrupts (
 266   VOID
 267   );
 268
 269 /**
 270   Read the initial count value from the init-count register.
 271
 272   @return The initial count value read from the init-count register.
 273 **/
 274 UINT32
 275 EFIAPI
 276 GetApicTimerInitCount (
 277   VOID
 278   );
 279
 280 /**
 281   Read the current count value from the current-count register.
 282
 283   @return The current count value read from the current-count register.
 284 **/
 285 UINT32
 286 EFIAPI
 287 GetApicTimerCurrentCount (
 288   VOID
 289   );
 290
 291 /**
 292   Initialize the local APIC timer.
 293
 294   The local APIC timer is initialized and enabled.
 295
 296   @param DivideValue   The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 297                        If it is 0, then use the current divide value in the DCR.
 298   @param InitCount     The initial count value.
 299   @param PeriodicMode  If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 300   @param Vector        The timer interrupt vector number.
 301 **/
 302 VOID
 303 EFIAPI
 304 InitializeApicTimer (
 305   IN UINTN   DivideValue,
 306   IN UINT32  InitCount,
 307   IN BOOLEAN PeriodicMode,
 308   IN UINT8   Vector
 309   );
 310
 311 /**
 312   Get the state of the local APIC timer.
 313
 314   @param DivideValue   Return the divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 315   @param PeriodicMode  Return the timer mode. If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 316   @param Vector        Return the timer interrupt vector number.
 317 **/
 318 VOID
 319 EFIAPI
 320 GetApicTimerState (
 321   OUT UINTN    *DivideValue  OPTIONAL,
 322   OUT BOOLEAN  *PeriodicMode  OPTIONAL,
 323   OUT UINT8    *Vector  OPTIONAL
 324   );
 325
 326 /**
 327   Enable the local APIC timer interrupt.
 328 **/
 329 VOID
 330 EFIAPI
 331 EnableApicTimerInterrupt (
 332   VOID
 333   );
 334
 335 /**
 336   Disable the local APIC timer interrupt.
 337 **/
 338 VOID
 339 EFIAPI
 340 DisableApicTimerInterrupt (
 341   VOID
 342   );
 343
 344 /**
 345   Get the local APIC timer interrupt state.
 346
 347   @retval TRUE  The local APIC timer interrupt is enabled.
 348   @retval FALSE The local APIC timer interrupt is disabled.
 349 **/
 350 BOOLEAN
 351 EFIAPI
 352 GetApicTimerInterruptState (
 353   VOID
 354   );
 355
 356 /**
 357   Send EOI to the local APIC.
 358 **/
 359 VOID
 360 EFIAPI
 361 SendApicEoi (
 362   VOID
 363   );
 364
 365 /**
 366   Get the 32-bit address that a device should use to send a Message Signaled
 367   Interrupt (MSI) to the Local APIC of the currently executing processor.
 368
 369   @return 32-bit address used to send an MSI to the Local APIC.
 370 **/
 371 UINT32
 372 EFIAPI
 373 GetApicMsiAddress (
 374   VOID
 375   );
 376
 377 /**
 378   Get the 64-bit data value that a device should use to send a Message Signaled
 379   Interrupt (MSI) to the Local APIC of the currently executing processor.
 380
 381   If Vector is not in range 0x10..0xFE, then ASSERT().
 382   If DeliveryMode is not supported, then ASSERT().
 383
 384   @param  Vector          The 8-bit interrupt vector associated with the MSI.
 385                           Must be in the range 0x10..0xFE
 386   @param  DeliveryMode    A 3-bit value that specifies how the recept of the MSI
 387                           is handled.  The only supported values are:
 388                             0: LOCAL_APIC_DELIVERY_MODE_FIXED
 389                             1: LOCAL_APIC_DELIVERY_MODE_LOWEST_PRIORITY
 390                             2: LOCAL_APIC_DELIVERY_MODE_SMI
 391                             4: LOCAL_APIC_DELIVERY_MODE_NMI
 392                             5: LOCAL_APIC_DELIVERY_MODE_INIT
 393                             7: LOCAL_APIC_DELIVERY_MODE_EXTINT
 394
 395   @param  LevelTriggered  TRUE specifies a level triggered interrupt.
 396                           FALSE specifies an edge triggered interrupt.
 397   @param  AssertionLevel  Ignored if LevelTriggered is FALSE.
 398                           TRUE specifies a level triggered interrupt that active
 399                           when the interrupt line is asserted.
 400                           FALSE specifies a level triggered interrupt that active
 401                           when the interrupt line is deasserted.
 402
 403   @return 64-bit data value used to send an MSI to the Local APIC.
 404 **/
 405 UINT64
 406 EFIAPI
 407 GetApicMsiValue (
 408   IN UINT8    Vector,
 409   IN UINTN    DeliveryMode,
 410   IN BOOLEAN  LevelTriggered,
 411   IN BOOLEAN  AssertionLevel
 412   );
 413
 414 /**
 415   Get Package ID/Core ID/Thread ID of a processor.
 416
 417   The algorithm assumes the target system has symmetry across physical
 418   package  boundaries with respect to the number of logical processors
 419   per package,  number of cores per package.
 420
 421   @param[in]  InitialApicId  Initial APIC ID of the target logical processor.
 422   @param[out]  Package       Returns the processor package ID.
 423   @param[out]  Core          Returns the processor core ID.
 424   @param[out]  Thread        Returns the processor thread ID.
 425 **/
 426 VOID
 427 GetProcessorLocationByApicId (
 428   IN  UINT32  InitialApicId,
 429   OUT UINT32  *Package  OPTIONAL,
 430   OUT UINT32  *Core    OPTIONAL,
 431   OUT UINT32  *Thread  OPTIONAL
 432   );
 433
 434 #endif
 435