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