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, 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   Send a SMI IPI to a specified target processor.
  80
  81   This function returns after the IPI has been accepted by the target processor.
  82
  83   @param  ApicId   Specify the local APIC ID of the target processor.
  84 **/
  85 VOID
  86 EFIAPI
  87 SendSmiIpi (
  88   IN UINT32          ApicId
  89   );
  90
  91 /**
  92   Send a SMI IPI to all processors excluding self.
  93
  94   This function returns after the IPI has been accepted by the target processors.
  95 **/
  96 VOID
  97 EFIAPI
  98 SendSmiIpiAllExcludingSelf (
  99   VOID
 100   );
 101
 102 /**
 103   Send an INIT IPI to a specified target processor.
 104
 105   This function returns after the IPI has been accepted by the target processor.
 106
 107   @param  ApicId   Specify the local APIC ID of the target processor.
 108 **/
 109 VOID
 110 EFIAPI
 111 SendInitIpi (
 112   IN UINT32          ApicId
 113   );
 114
 115 /**
 116   Send an INIT IPI to all processors excluding self.
 117
 118   This function returns after the IPI has been accepted by the target processors.
 119 **/
 120 VOID
 121 EFIAPI
 122 SendInitIpiAllExcludingSelf (
 123   VOID
 124   );
 125
 126 /**
 127   Send an INIT-Start-up-Start-up IPI sequence to a specified target processor.
 128
 129   This function returns after the IPI has been accepted by the target processor.
 130
 131   if StartupRoutine >= 1M, then ASSERT.
 132   if StartupRoutine is not multiple of 4K, then ASSERT.
 133
 134   @param  ApicId          Specify the local APIC ID of the target processor.
 135   @param  StartupRoutine  Points to a start-up routine which is below 1M physical
 136                           address and 4K aligned.
 137 **/
 138 VOID
 139 EFIAPI
 140 SendInitSipiSipi (
 141   IN UINT32          ApicId,
 142   IN UINT32          StartupRoutine
 143   );
 144
 145 /**
 146   Send an INIT-Start-up-Start-up IPI sequence to all processors excluding self.
 147
 148   This function returns after the IPI has been accepted by the target processors.
 149
 150   if StartupRoutine >= 1M, then ASSERT.
 151   if StartupRoutine is not multiple of 4K, then ASSERT.
 152
 153   @param  StartupRoutine    Points to a start-up routine which is below 1M physical
 154                             address and 4K aligned.
 155 **/
 156 VOID
 157 EFIAPI
 158 SendInitSipiSipiAllExcludingSelf (
 159   IN UINT32          StartupRoutine
 160   );
 161
 162 /**
 163   Programming Virtual Wire Mode.
 164
 165   This function programs the local APIC for virtual wire mode following
 166   the example described in chapter A.3 of the MP 1.4 spec.
 167
 168   IOxAPIC is not involved in this type of virtual wire mode.
 169 **/
 170 VOID
 171 EFIAPI
 172 ProgramVirtualWireMode (
 173   VOID
 174   );
 175
 176 /**
 177   Get the divide value from the DCR (Divide Configuration Register) by which
 178   the processor's bus clock is divided to form the time base for the APIC timer.
 179
 180   @return The divide value is one of 1,2,4,8,16,32,64,128.
 181 **/
 182 UINTN
 183 EFIAPI
 184 GetApicTimerDivisor (
 185   VOID
 186   );
 187
 188 /**
 189   Read the initial count value from the init-count register.
 190
 191   @return The initial count value read from the init-count register.
 192 **/
 193 UINT32
 194 EFIAPI
 195 GetApicTimerInitCount (
 196   VOID
 197   );
 198
 199 /**
 200   Read the current count value from the current-count register.
 201
 202   @return The current count value read from the current-count register.
 203 **/
 204 UINT32
 205 EFIAPI
 206 GetApicTimerCurrentCount (
 207   VOID
 208   );
 209
 210 /**
 211   Initialize the local APIC timer.
 212
 213   The local APIC timer is initialized and enabled.
 214
 215   @param DivideValue   The divide value for the DCR. It is one of 1,2,4,8,16,32,64,128.
 216                        If it is 0, then use the current divide value in the DCR.
 217   @param InitCount     The initial count value.
 218   @param PeriodicMode  If TRUE, timer mode is peridoic. Othewise, timer mode is one-shot.
 219   @param Vector        The timer interrupt vector number.
 220 **/
 221 VOID
 222 EFIAPI
 223 InitializeApicTimer (
 224   IN UINTN   DivideValue,
 225   IN UINT32  InitCount,
 226   IN BOOLEAN PeriodicMode,
 227   IN UINT8   Vector
 228   );
 229
 230 /**
 231   Enable the local APIC timer interrupt.
 232 **/
 233 VOID
 234 EFIAPI
 235 EnableApicTimerInterrupt (
 236   VOID
 237   );
 238
 239 /**
 240   Disable the local APIC timer interrupt.
 241 **/
 242 VOID
 243 EFIAPI
 244 DisableApicTimerInterrupt (
 245   VOID
 246   );
 247
 248 /**
 249   Get the local APIC timer interrupt state.
 250
 251   @retval TRUE  The local APIC timer interrupt is enabled.
 252   @retval FALSE The local APIC timer interrupt is disabled.
 253 **/
 254 BOOLEAN
 255 EFIAPI
 256 GetApicTimerInterruptState (
 257   VOID
 258   );
 259
 260 /**
 261   Send EOI to the local APIC.
 262 **/
 263 VOID
 264 EFIAPI
 265 SendApicEoi (
 266   VOID
 267   );
 268
 269 #endif
 270