UefiCpuPkg/Library/MpInitLib/MpLib.h

   1 /** @file
   2   Common header file for MP Initialize Library.
   3
   4   Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _MP_LIB_H_
  16 #define _MP_LIB_H_
  17
  18 #include <PiPei.h>
  19
  20 #include <Register/Cpuid.h>
  21 #include <Register/Msr.h>
  22 #include <Register/LocalApic.h>
  23 #include <Register/Microcode.h>
  24
  25 #include <Library/MpInitLib.h>
  26 #include <Library/BaseLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/DebugLib.h>
  30 #include <Library/LocalApicLib.h>
  31 #include <Library/CpuLib.h>
  32 #include <Library/UefiCpuLib.h>
  33 #include <Library/TimerLib.h>
  34 #include <Library/SynchronizationLib.h>
  35 #include <Library/MtrrLib.h>
  36 #include <Library/HobLib.h>
  37
  38 #define WAKEUP_AP_SIGNAL SIGNATURE_32 ('S', 'T', 'A', 'P')
  39
  40 #define CPU_INIT_MP_LIB_HOB_GUID \
  41   { \
  42     0x58eb6a19, 0x3699, 0x4c68, { 0xa8, 0x36, 0xda, 0xcd, 0x8e, 0xdc, 0xad, 0x4a } \
  43   }
  44
  45 //
  46 //  The MP data for switch BSP
  47 //
  48 #define CPU_SWITCH_STATE_IDLE   0
  49 #define CPU_SWITCH_STATE_STORED 1
  50 #define CPU_SWITCH_STATE_LOADED 2
  51
  52 //
  53 // CPU exchange information for switch BSP
  54 //
  55 typedef struct {
  56   UINT8             State;        // offset 0
  57   UINTN             StackPointer; // offset 4 / 8
  58   IA32_DESCRIPTOR   Gdtr;         // offset 8 / 16
  59   IA32_DESCRIPTOR   Idtr;         // offset 14 / 26
  60 } CPU_EXCHANGE_ROLE_INFO;
  61
  62 //
  63 // AP loop state when APs are in idle state
  64 // It's value is the same with PcdCpuApLoopMode
  65 //
  66 typedef enum {
  67   ApInHltLoop   = 1,
  68   ApInMwaitLoop = 2,
  69   ApInRunLoop   = 3
  70 } AP_LOOP_MODE;
  71
  72 //
  73 // AP initialization state during APs wakeup
  74 //
  75 typedef enum {
  76   ApInitConfig   = 1,
  77   ApInitReconfig = 2,
  78   ApInitDone     = 3
  79 } AP_INIT_STATE;
  80
  81 //
  82 // AP state
  83 //
  84 typedef enum {
  85   CpuStateIdle,
  86   CpuStateReady,
  87   CpuStateBusy,
  88   CpuStateFinished,
  89   CpuStateDisabled
  90 } CPU_STATE;
  91
  92 //
  93 // CPU volatile registers around INIT-SIPI-SIPI
  94 //
  95 typedef struct {
  96   UINTN                          Cr0;
  97   UINTN                          Cr3;
  98   UINTN                          Cr4;
  99   UINTN                          Dr0;
 100   UINTN                          Dr1;
 101   UINTN                          Dr2;
 102   UINTN                          Dr3;
 103   UINTN                          Dr6;
 104   UINTN                          Dr7;
 105   IA32_DESCRIPTOR                Gdtr;
 106   IA32_DESCRIPTOR                Idtr;
 107   UINT16                         Tr;
 108 } CPU_VOLATILE_REGISTERS;
 109
 110 //
 111 // AP related data
 112 //
 113 typedef struct {
 114   SPIN_LOCK                      ApLock;
 115   volatile UINT32                *StartupApSignal;
 116   volatile UINTN                 ApFunction;
 117   volatile UINTN                 ApFunctionArgument;
 118   BOOLEAN                        CpuHealthy;
 119   volatile CPU_STATE             State;
 120   CPU_VOLATILE_REGISTERS         VolatileRegisters;
 121   BOOLEAN                        Waiting;
 122   BOOLEAN                        *Finished;
 123   UINT64                         ExpectedTime;
 124   UINT64                         CurrentTime;
 125   UINT64                         TotalTime;
 126   EFI_EVENT                      WaitEvent;
 127 } CPU_AP_DATA;
 128
 129 //
 130 // Basic CPU information saved in Guided HOB.
 131 // Because the contents will be shard between PEI and DXE,
 132 // we need to make sure the each fields offset same in different
 133 // architecture.
 134 //
 135 #pragma pack (1)
 136 typedef struct {
 137   UINT32                         InitialApicId;
 138   UINT32                         ApicId;
 139   UINT32                         Health;
 140   UINT64                         ApTopOfStack;
 141 } CPU_INFO_IN_HOB;
 142 #pragma pack ()
 143
 144 //
 145 // AP reset code information including code address and size,
 146 // this structure will be shared be C code and assembly code.
 147 // It is natural aligned by design.
 148 //
 149 typedef struct {
 150   UINT8             *RendezvousFunnelAddress;
 151   UINTN             ModeEntryOffset;
 152   UINTN             RendezvousFunnelSize;
 153   UINT8             *RelocateApLoopFuncAddress;
 154   UINTN             RelocateApLoopFuncSize;
 155   UINTN             ModeTransitionOffset;
 156 } MP_ASSEMBLY_ADDRESS_MAP;
 157
 158 typedef struct _CPU_MP_DATA  CPU_MP_DATA;
 159
 160 #pragma pack(1)
 161
 162 //
 163 // MP CPU exchange information for AP reset code
 164 // This structure is required to be packed because fixed field offsets
 165 // into this structure are used in assembly code in this module
 166 //
 167 typedef struct {
 168   UINTN                 Lock;
 169   UINTN                 StackStart;
 170   UINTN                 StackSize;
 171   UINTN                 CFunction;
 172   IA32_DESCRIPTOR       GdtrProfile;
 173   IA32_DESCRIPTOR       IdtrProfile;
 174   UINTN                 BufferStart;
 175   UINTN                 ModeOffset;
 176   UINTN                 ApIndex;
 177   UINTN                 CodeSegment;
 178   UINTN                 DataSegment;
 179   UINTN                 EnableExecuteDisable;
 180   UINTN                 Cr3;
 181   UINTN                 InitFlag;
 182   CPU_INFO_IN_HOB       *CpuInfo;
 183   UINTN                 NumApsExecuting;
 184   CPU_MP_DATA           *CpuMpData;
 185   UINTN                 InitializeFloatingPointUnitsAddress;
 186   UINT32                ModeTransitionMemory;
 187   UINT16                ModeTransitionSegment;
 188   UINT32                ModeHighMemory;
 189   UINT16                ModeHighSegment;
 190 } MP_CPU_EXCHANGE_INFO;
 191
 192 #pragma pack()
 193
 194 //
 195 // CPU MP Data save in memory
 196 //
 197 struct _CPU_MP_DATA {
 198   UINT64                         CpuInfoInHob;
 199   UINT32                         CpuCount;
 200   UINT32                         BspNumber;
 201   //
 202   // The above fields data will be passed from PEI to DXE
 203   // Please make sure the fields offset same in the different
 204   // architecture.
 205   //
 206   SPIN_LOCK                      MpLock;
 207   UINTN                          Buffer;
 208   UINTN                          CpuApStackSize;
 209   MP_ASSEMBLY_ADDRESS_MAP        AddressMap;
 210   UINTN                          WakeupBuffer;
 211   UINTN                          WakeupBufferHigh;
 212   UINTN                          BackupBuffer;
 213   UINTN                          BackupBufferSize;
 214
 215   volatile UINT32                StartCount;
 216   volatile UINT32                FinishedCount;
 217   volatile UINT32                RunningCount;
 218   BOOLEAN                        SingleThread;
 219   EFI_AP_PROCEDURE               Procedure;
 220   VOID                           *ProcArguments;
 221   BOOLEAN                        *Finished;
 222   UINT64                         ExpectedTime;
 223   UINT64                         CurrentTime;
 224   UINT64                         TotalTime;
 225   EFI_EVENT                      WaitEvent;
 226   UINTN                          **FailedCpuList;
 227
 228   AP_INIT_STATE                  InitFlag;
 229   BOOLEAN                        X2ApicEnable;
 230   BOOLEAN                        SwitchBspFlag;
 231   UINTN                          NewBspNumber;
 232   CPU_EXCHANGE_ROLE_INFO         BSPInfo;
 233   CPU_EXCHANGE_ROLE_INFO         APInfo;
 234   MTRR_SETTINGS                  MtrrTable;
 235   UINT8                          ApLoopMode;
 236   UINT8                          ApTargetCState;
 237   UINT16                         PmCodeSegment;
 238   CPU_AP_DATA                    *CpuData;
 239   volatile MP_CPU_EXCHANGE_INFO  *MpCpuExchangeInfo;
 240
 241   UINT32                         CurrentTimerCount;
 242   UINTN                          DivideValue;
 243   UINT8                          Vector;
 244   BOOLEAN                        PeriodicMode;
 245   BOOLEAN                        TimerInterruptState;
 246   UINT64                         MicrocodePatchAddress;
 247   UINT64                         MicrocodePatchRegionSize;
 248
 249   UINT32                         ProcessorSignature;
 250   UINT32                         ProcessorFlags;
 251   UINT64                         MicrocodeDataAddress;
 252   UINT32                         MicrocodeRevision;
 253 };
 254
 255 extern EFI_GUID mCpuInitMpLibHobGuid;
 256
 257 /**
 258   Assembly code to place AP into safe loop mode.
 259
 260   Place AP into targeted C-State if MONITOR is supported, otherwise
 261   place AP into hlt state.
 262   Place AP in protected mode if the current is long mode. Due to AP maybe
 263   wakeup by some hardware event. It could avoid accessing page table that
 264   may not available during booting to OS.
 265
 266   @param[in] MwaitSupport    TRUE indicates MONITOR is supported.
 267                              FALSE indicates MONITOR is not supported.
 268   @param[in] ApTargetCState  Target C-State value.
 269   @param[in] PmCodeSegment   Protected mode code segment value.
 270 **/
 271 typedef
 272 VOID
 273 (EFIAPI * ASM_RELOCATE_AP_LOOP) (
 274   IN BOOLEAN                 MwaitSupport,
 275   IN UINTN                   ApTargetCState,
 276   IN UINTN                   PmCodeSegment,
 277   IN UINTN                   TopOfApStack,
 278   IN UINTN                   NumberToFinish
 279   );
 280
 281 /**
 282   Assembly code to get starting address and size of the rendezvous entry for APs.
 283   Information for fixing a jump instruction in the code is also returned.
 284
 285   @param[out] AddressMap  Output buffer for address map information.
 286 **/
 287 VOID
 288 EFIAPI
 289 AsmGetAddressMap (
 290   OUT MP_ASSEMBLY_ADDRESS_MAP    *AddressMap
 291   );
 292
 293 /**
 294   This function is called by both the BSP and the AP which is to become the BSP to
 295   Exchange execution context including stack between them. After return from this
 296   function, the BSP becomes AP and the AP becomes the BSP.
 297
 298   @param[in] MyInfo      Pointer to buffer holding the exchanging information for the executing processor.
 299   @param[in] OthersInfo  Pointer to buffer holding the exchanging information for the peer.
 300
 301 **/
 302 VOID
 303 EFIAPI
 304 AsmExchangeRole (
 305   IN CPU_EXCHANGE_ROLE_INFO    *MyInfo,
 306   IN CPU_EXCHANGE_ROLE_INFO    *OthersInfo
 307   );
 308
 309 /**
 310   Get the pointer to CPU MP Data structure.
 311
 312   @return  The pointer to CPU MP Data structure.
 313 **/
 314 CPU_MP_DATA *
 315 GetCpuMpData (
 316   VOID
 317   );
 318
 319 /**
 320   Save the pointer to CPU MP Data structure.
 321
 322   @param[in] CpuMpData  The pointer to CPU MP Data structure will be saved.
 323 **/
 324 VOID
 325 SaveCpuMpData (
 326   IN CPU_MP_DATA   *CpuMpData
 327   );
 328
 329
 330 /**
 331   Get available system memory below 1MB by specified size.
 332
 333   @param[in] WakeupBufferSize   Wakeup buffer size required
 334
 335   @retval other   Return wakeup buffer address below 1MB.
 336   @retval -1      Cannot find free memory below 1MB.
 337 **/
 338 UINTN
 339 GetWakeupBuffer (
 340   IN UINTN                WakeupBufferSize
 341   );
 342
 343 /**
 344   Get available EfiBootServicesCode memory below 4GB by specified size.
 345
 346   This buffer is required to safely transfer AP from real address mode to
 347   protected mode or long mode, due to the fact that the buffer returned by
 348   GetWakeupBuffer() may be marked as non-executable.
 349
 350   @param[in] BufferSize   Wakeup transition buffer size.
 351
 352   @retval other   Return wakeup transition buffer address below 4GB.
 353   @retval 0       Cannot find free memory below 4GB.
 354 **/
 355 UINTN
 356 GetModeTransitionBuffer (
 357   IN UINTN                BufferSize
 358   );
 359
 360 /**
 361   This function will be called by BSP to wakeup AP.
 362
 363   @param[in] CpuMpData          Pointer to CPU MP Data
 364   @param[in] Broadcast          TRUE:  Send broadcast IPI to all APs
 365                                 FALSE: Send IPI to AP by ApicId
 366   @param[in] ProcessorNumber    The handle number of specified processor
 367   @param[in] Procedure          The function to be invoked by AP
 368   @param[in] ProcedureArgument  The argument to be passed into AP function
 369 **/
 370 VOID
 371 WakeUpAP (
 372   IN CPU_MP_DATA               *CpuMpData,
 373   IN BOOLEAN                   Broadcast,
 374   IN UINTN                     ProcessorNumber,
 375   IN EFI_AP_PROCEDURE          Procedure,              OPTIONAL
 376   IN VOID                      *ProcedureArgument      OPTIONAL
 377   );
 378
 379 /**
 380   Initialize global data for MP support.
 381
 382   @param[in] CpuMpData  The pointer to CPU MP Data structure.
 383 **/
 384 VOID
 385 InitMpGlobalData (
 386   IN CPU_MP_DATA               *CpuMpData
 387   );
 388
 389 /**
 390   Worker function to execute a caller provided function on all enabled APs.
 391
 392   @param[in]  Procedure               A pointer to the function to be run on
 393                                       enabled APs of the system.
 394   @param[in]  SingleThread            If TRUE, then all the enabled APs execute
 395                                       the function specified by Procedure one by
 396                                       one, in ascending order of processor handle
 397                                       number.  If FALSE, then all the enabled APs
 398                                       execute the function specified by Procedure
 399                                       simultaneously.
 400   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 401                                       service.
 402   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 403                                       APs to return from Procedure, either for
 404                                       blocking or non-blocking mode.
 405   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 406                                       all APs.
 407   @param[out] FailedCpuList           If all APs finish successfully, then its
 408                                       content is set to NULL. If not all APs
 409                                       finish before timeout expires, then its
 410                                       content is set to address of the buffer
 411                                       holding handle numbers of the failed APs.
 412
 413   @retval EFI_SUCCESS             In blocking mode, all APs have finished before
 414                                   the timeout expired.
 415   @retval EFI_SUCCESS             In non-blocking mode, function has been dispatched
 416                                   to all enabled APs.
 417   @retval others                  Failed to Startup all APs.
 418
 419 **/
 420 EFI_STATUS
 421 StartupAllAPsWorker (
 422   IN  EFI_AP_PROCEDURE          Procedure,
 423   IN  BOOLEAN                   SingleThread,
 424   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 425   IN  UINTN                     TimeoutInMicroseconds,
 426   IN  VOID                      *ProcedureArgument      OPTIONAL,
 427   OUT UINTN                     **FailedCpuList         OPTIONAL
 428   );
 429
 430 /**
 431   Worker function to let the caller get one enabled AP to execute a caller-provided
 432   function.
 433
 434   @param[in]  Procedure               A pointer to the function to be run on
 435                                       enabled APs of the system.
 436   @param[in]  ProcessorNumber         The handle number of the AP.
 437   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 438                                       service.
 439   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 440                                       APs to return from Procedure, either for
 441                                       blocking or non-blocking mode.
 442   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 443                                       all APs.
 444   @param[out] Finished                If AP returns from Procedure before the
 445                                       timeout expires, its content is set to TRUE.
 446                                       Otherwise, the value is set to FALSE.
 447
 448   @retval EFI_SUCCESS             In blocking mode, specified AP finished before
 449                                   the timeout expires.
 450   @retval others                  Failed to Startup AP.
 451
 452 **/
 453 EFI_STATUS
 454 StartupThisAPWorker (
 455   IN  EFI_AP_PROCEDURE          Procedure,
 456   IN  UINTN                     ProcessorNumber,
 457   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 458   IN  UINTN                     TimeoutInMicroseconds,
 459   IN  VOID                      *ProcedureArgument      OPTIONAL,
 460   OUT BOOLEAN                   *Finished               OPTIONAL
 461   );
 462
 463 /**
 464   Worker function to switch the requested AP to be the BSP from that point onward.
 465
 466   @param[in] ProcessorNumber   The handle number of AP that is to become the new BSP.
 467   @param[in] EnableOldBSP      If TRUE, then the old BSP will be listed as an
 468                                enabled AP. Otherwise, it will be disabled.
 469
 470   @retval EFI_SUCCESS          BSP successfully switched.
 471   @retval others               Failed to switch BSP.
 472
 473 **/
 474 EFI_STATUS
 475 SwitchBSPWorker (
 476   IN UINTN                     ProcessorNumber,
 477   IN BOOLEAN                   EnableOldBSP
 478   );
 479
 480 /**
 481   Worker function to let the caller enable or disable an AP from this point onward.
 482   This service may only be called from the BSP.
 483
 484   @param[in] ProcessorNumber   The handle number of AP.
 485   @param[in] EnableAP          Specifies the new state for the processor for
 486                                enabled, FALSE for disabled.
 487   @param[in] HealthFlag        If not NULL, a pointer to a value that specifies
 488                                the new health status of the AP.
 489
 490   @retval EFI_SUCCESS          The specified AP was enabled or disabled successfully.
 491   @retval others               Failed to Enable/Disable AP.
 492
 493 **/
 494 EFI_STATUS
 495 EnableDisableApWorker (
 496   IN  UINTN                     ProcessorNumber,
 497   IN  BOOLEAN                   EnableAP,
 498   IN  UINT32                    *HealthFlag OPTIONAL
 499   );
 500
 501 /**
 502   Get pointer to CPU MP Data structure from GUIDed HOB.
 503
 504   @return  The pointer to CPU MP Data structure.
 505 **/
 506 CPU_MP_DATA *
 507 GetCpuMpDataFromGuidedHob (
 508   VOID
 509   );
 510
 511 /** Checks status of specified AP.
 512
 513   This function checks whether the specified AP has finished the task assigned
 514   by StartupThisAP(), and whether timeout expires.
 515
 516   @param[in]  ProcessorNumber       The handle number of processor.
 517
 518   @retval EFI_SUCCESS           Specified AP has finished task assigned by StartupThisAPs().
 519   @retval EFI_TIMEOUT           The timeout expires.
 520   @retval EFI_NOT_READY         Specified AP has not finished task and timeout has not expired.
 521 **/
 522 EFI_STATUS
 523 CheckThisAP (
 524   IN UINTN        ProcessorNumber
 525   );
 526
 527 /**
 528   Checks status of all APs.
 529
 530   This function checks whether all APs have finished task assigned by StartupAllAPs(),
 531   and whether timeout expires.
 532
 533   @retval EFI_SUCCESS           All APs have finished task assigned by StartupAllAPs().
 534   @retval EFI_TIMEOUT           The timeout expires.
 535   @retval EFI_NOT_READY         APs have not finished task and timeout has not expired.
 536 **/
 537 EFI_STATUS
 538 CheckAllAPs (
 539   VOID
 540   );
 541
 542 /**
 543   Checks APs status and updates APs status if needed.
 544
 545 **/
 546 VOID
 547 CheckAndUpdateApsStatus (
 548   VOID
 549   );
 550
 551 /**
 552   Detect whether specified processor can find matching microcode patch and load it.
 553
 554   @param[in]  CpuMpData    The pointer to CPU MP Data structure.
 555   @param[in]  IsBspCallIn  Indicate whether the caller is BSP or not.
 556 **/
 557 VOID
 558 MicrocodeDetect (
 559   IN CPU_MP_DATA             *CpuMpData,
 560   IN BOOLEAN                 IsBspCallIn
 561   );
 562
 563 /**
 564   Detect whether Mwait-monitor feature is supported.
 565
 566   @retval TRUE    Mwait-monitor feature is supported.
 567   @retval FALSE   Mwait-monitor feature is not supported.
 568 **/
 569 BOOLEAN
 570 IsMwaitSupport (
 571   VOID
 572   );
 573
 574 /**
 575   Enable Debug Agent to support source debugging on AP function.
 576
 577 **/
 578 VOID
 579 EnableDebugAgent (
 580   VOID
 581   );
 582
 583 #endif
 584