UefiCpuPkg/Library/MpInitLib/MpLib.h

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