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