UefiCpuPkg/Library/MpInitLib/MpLib.h

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