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