UefiCpuPkg/Library/MpInitLib/MpLib.h

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