UefiCpuPkg/Library/MpInitLib/MpLib.h

   1 /** @file
   2   Common header file for MP Initialize Library.
   3
   4   Copyright (c) 2016 - 2017, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _MP_LIB_H_
  16 #define _MP_LIB_H_
  17
  18 #include <PiPei.h>
  19
  20 #include <Register/Cpuid.h>
  21 #include <Register/Msr.h>
  22 #include <Register/LocalApic.h>
  23 #include <Register/Microcode.h>
  24
  25 #include <Library/MpInitLib.h>
  26 #include <Library/BaseLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/DebugLib.h>
  30 #include <Library/LocalApicLib.h>
  31 #include <Library/CpuLib.h>
  32 #include <Library/UefiCpuLib.h>
  33 #include <Library/TimerLib.h>
  34 #include <Library/SynchronizationLib.h>
  35 #include <Library/MtrrLib.h>
  36 #include <Library/HobLib.h>
  37
  38 #define WAKEUP_AP_SIGNAL SIGNATURE_32 ('S', 'T', 'A', 'P')
  39
  40 #define CPU_INIT_MP_LIB_HOB_GUID \
  41   { \
  42     0x58eb6a19, 0x3699, 0x4c68, { 0xa8, 0x36, 0xda, 0xcd, 0x8e, 0xdc, 0xad, 0x4a } \
  43   }
  44
  45 //
  46 //  The MP data for switch BSP
  47 //
  48 #define CPU_SWITCH_STATE_IDLE   0
  49 #define CPU_SWITCH_STATE_STORED 1
  50 #define CPU_SWITCH_STATE_LOADED 2
  51
  52 //
  53 // CPU exchange information for switch BSP
  54 //
  55 typedef struct {
  56   UINT8             State;        // offset 0
  57   UINTN             StackPointer; // offset 4 / 8
  58   IA32_DESCRIPTOR   Gdtr;         // offset 8 / 16
  59   IA32_DESCRIPTOR   Idtr;         // offset 14 / 26
  60 } CPU_EXCHANGE_ROLE_INFO;
  61
  62 //
  63 // AP loop state when APs are in idle state
  64 // It's value is the same with PcdCpuApLoopMode
  65 //
  66 typedef enum {
  67   ApInHltLoop   = 1,
  68   ApInMwaitLoop = 2,
  69   ApInRunLoop   = 3
  70 } AP_LOOP_MODE;
  71
  72 //
  73 // AP initialization state during APs wakeup
  74 //
  75 typedef enum {
  76   ApInitConfig   = 1,
  77   ApInitReconfig = 2,
  78   ApInitDone     = 3
  79 } AP_INIT_STATE;
  80
  81 //
  82 // AP state
  83 //
  84 typedef enum {
  85   CpuStateIdle,
  86   CpuStateReady,
  87   CpuStateBusy,
  88   CpuStateFinished,
  89   CpuStateDisabled
  90 } CPU_STATE;
  91
  92 //
  93 // CPU volatile registers around INIT-SIPI-SIPI
  94 //
  95 typedef struct {
  96   UINTN                          Cr0;
  97   UINTN                          Cr3;
  98   UINTN                          Cr4;
  99   UINTN                          Dr0;
 100   UINTN                          Dr1;
 101   UINTN                          Dr2;
 102   UINTN                          Dr3;
 103   UINTN                          Dr6;
 104   UINTN                          Dr7;
 105 } CPU_VOLATILE_REGISTERS;
 106
 107 //
 108 // AP related data
 109 //
 110 typedef struct {
 111   SPIN_LOCK                      ApLock;
 112   volatile UINT32                *StartupApSignal;
 113   volatile UINTN                 ApFunction;
 114   volatile UINTN                 ApFunctionArgument;
 115   BOOLEAN                        CpuHealthy;
 116   volatile CPU_STATE             State;
 117   CPU_VOLATILE_REGISTERS         VolatileRegisters;
 118   BOOLEAN                        Waiting;
 119   BOOLEAN                        *Finished;
 120   UINT64                         ExpectedTime;
 121   UINT64                         CurrentTime;
 122   UINT64                         TotalTime;
 123   EFI_EVENT                      WaitEvent;
 124 } CPU_AP_DATA;
 125
 126 //
 127 // Basic CPU information saved in Guided HOB.
 128 // Because the contents will be shard between PEI and DXE,
 129 // we need to make sure the each fields offset same in different
 130 // architecture.
 131 //
 132 #pragma pack (1)
 133 typedef struct {
 134   UINT32                         InitialApicId;
 135   UINT32                         ApicId;
 136   UINT32                         Health;
 137   UINT64                         ApTopOfStack;
 138 } CPU_INFO_IN_HOB;
 139 #pragma pack ()
 140
 141 //
 142 // AP reset code information including code address and size,
 143 // this structure will be shared be C code and assembly code.
 144 // It is natural aligned by design.
 145 //
 146 typedef struct {
 147   UINT8             *RendezvousFunnelAddress;
 148   UINTN             ModeEntryOffset;
 149   UINTN             RendezvousFunnelSize;
 150   UINT8             *RelocateApLoopFuncAddress;
 151   UINTN             RelocateApLoopFuncSize;
 152 } MP_ASSEMBLY_ADDRESS_MAP;
 153
 154 typedef struct _CPU_MP_DATA  CPU_MP_DATA;
 155
 156 #pragma pack(1)
 157
 158 //
 159 // MP CPU exchange information for AP reset code
 160 // This structure is required to be packed because fixed field offsets
 161 // into this structure are used in assembly code in this module
 162 //
 163 typedef struct {
 164   UINTN                 Lock;
 165   UINTN                 StackStart;
 166   UINTN                 StackSize;
 167   UINTN                 CFunction;
 168   IA32_DESCRIPTOR       GdtrProfile;
 169   IA32_DESCRIPTOR       IdtrProfile;
 170   UINTN                 BufferStart;
 171   UINTN                 ModeOffset;
 172   UINTN                 NumApsExecuting;
 173   UINTN                 CodeSegment;
 174   UINTN                 DataSegment;
 175   UINTN                 EnableExecuteDisable;
 176   UINTN                 Cr3;
 177   UINTN                 InitFlag;
 178   CPU_INFO_IN_HOB       *CpuInfo;
 179   CPU_MP_DATA           *CpuMpData;
 180   UINTN                 InitializeFloatingPointUnitsAddress;
 181 } MP_CPU_EXCHANGE_INFO;
 182
 183 #pragma pack()
 184
 185 //
 186 // CPU MP Data save in memory
 187 //
 188 struct _CPU_MP_DATA {
 189   UINT64                         CpuInfoInHob;
 190   UINT32                         CpuCount;
 191   UINT32                         BspNumber;
 192   //
 193   // The above fields data will be passed from PEI to DXE
 194   // Please make sure the fields offset same in the different
 195   // architecture.
 196   //
 197   SPIN_LOCK                      MpLock;
 198   UINTN                          Buffer;
 199   UINTN                          CpuApStackSize;
 200   MP_ASSEMBLY_ADDRESS_MAP        AddressMap;
 201   UINTN                          WakeupBuffer;
 202   UINTN                          BackupBuffer;
 203   UINTN                          BackupBufferSize;
 204   BOOLEAN                        SaveRestoreFlag;
 205
 206   volatile UINT32                StartCount;
 207   volatile UINT32                FinishedCount;
 208   volatile UINT32                RunningCount;
 209   BOOLEAN                        SingleThread;
 210   EFI_AP_PROCEDURE               Procedure;
 211   VOID                           *ProcArguments;
 212   BOOLEAN                        *Finished;
 213   UINT64                         ExpectedTime;
 214   UINT64                         CurrentTime;
 215   UINT64                         TotalTime;
 216   EFI_EVENT                      WaitEvent;
 217   UINTN                          **FailedCpuList;
 218
 219   AP_INIT_STATE                  InitFlag;
 220   BOOLEAN                        X2ApicEnable;
 221   BOOLEAN                        SwitchBspFlag;
 222   UINTN                          NewBspNumber;
 223   CPU_EXCHANGE_ROLE_INFO         BSPInfo;
 224   CPU_EXCHANGE_ROLE_INFO         APInfo;
 225   MTRR_SETTINGS                  MtrrTable;
 226   UINT8                          ApLoopMode;
 227   UINT8                          ApTargetCState;
 228   UINT16                         PmCodeSegment;
 229   CPU_AP_DATA                    *CpuData;
 230   volatile MP_CPU_EXCHANGE_INFO  *MpCpuExchangeInfo;
 231
 232   UINT32                         CurrentTimerCount;
 233   UINTN                          DivideValue;
 234   UINT8                          Vector;
 235   BOOLEAN                        PeriodicMode;
 236   BOOLEAN                        TimerInterruptState;
 237 };
 238
 239 extern EFI_GUID mCpuInitMpLibHobGuid;
 240
 241 /**
 242   Assembly code to place AP into safe loop mode.
 243
 244   Place AP into targeted C-State if MONITOR is supported, otherwise
 245   place AP into hlt state.
 246   Place AP in protected mode if the current is long mode. Due to AP maybe
 247   wakeup by some hardware event. It could avoid accessing page table that
 248   may not available during booting to OS.
 249
 250   @param[in] MwaitSupport    TRUE indicates MONITOR is supported.
 251                              FALSE indicates MONITOR is not supported.
 252   @param[in] ApTargetCState  Target C-State value.
 253   @param[in] PmCodeSegment   Protected mode code segment value.
 254 **/
 255 typedef
 256 VOID
 257 (EFIAPI * ASM_RELOCATE_AP_LOOP) (
 258   IN BOOLEAN                 MwaitSupport,
 259   IN UINTN                   ApTargetCState,
 260   IN UINTN                   PmCodeSegment,
 261   IN UINTN                   TopOfApStack,
 262   IN UINTN                   NumberToFinish
 263   );
 264
 265 /**
 266   Assembly code to get starting address and size of the rendezvous entry for APs.
 267   Information for fixing a jump instruction in the code is also returned.
 268
 269   @param[out] AddressMap  Output buffer for address map information.
 270 **/
 271 VOID
 272 EFIAPI
 273 AsmGetAddressMap (
 274   OUT MP_ASSEMBLY_ADDRESS_MAP    *AddressMap
 275   );
 276
 277 /**
 278   This function is called by both the BSP and the AP which is to become the BSP to
 279   Exchange execution context including stack between them. After return from this
 280   function, the BSP becomes AP and the AP becomes the BSP.
 281
 282   @param[in] MyInfo      Pointer to buffer holding the exchanging information for the executing processor.
 283   @param[in] OthersInfo  Pointer to buffer holding the exchanging information for the peer.
 284
 285 **/
 286 VOID
 287 EFIAPI
 288 AsmExchangeRole (
 289   IN CPU_EXCHANGE_ROLE_INFO    *MyInfo,
 290   IN CPU_EXCHANGE_ROLE_INFO    *OthersInfo
 291   );
 292
 293 /**
 294   Get the pointer to CPU MP Data structure.
 295
 296   @return  The pointer to CPU MP Data structure.
 297 **/
 298 CPU_MP_DATA *
 299 GetCpuMpData (
 300   VOID
 301   );
 302
 303 /**
 304   Save the pointer to CPU MP Data structure.
 305
 306   @param[in] CpuMpData  The pointer to CPU MP Data structure will be saved.
 307 **/
 308 VOID
 309 SaveCpuMpData (
 310   IN CPU_MP_DATA   *CpuMpData
 311   );
 312
 313 /**
 314   Allocate reset vector buffer.
 315
 316   @param[in, out]  CpuMpData  The pointer to CPU MP Data structure.
 317 **/
 318 VOID
 319 AllocateResetVector (
 320   IN OUT CPU_MP_DATA          *CpuMpData
 321   );
 322
 323 /**
 324   Free AP reset vector buffer.
 325
 326   @param[in]  CpuMpData  The pointer to CPU MP Data structure.
 327 **/
 328 VOID
 329 FreeResetVector (
 330   IN CPU_MP_DATA              *CpuMpData
 331   );
 332
 333 /**
 334   This function will be called by BSP to wakeup AP.
 335
 336   @param[in] CpuMpData          Pointer to CPU MP Data
 337   @param[in] Broadcast          TRUE:  Send broadcast IPI to all APs
 338                                 FALSE: Send IPI to AP by ApicId
 339   @param[in] ProcessorNumber    The handle number of specified processor
 340   @param[in] Procedure          The function to be invoked by AP
 341   @param[in] ProcedureArgument  The argument to be passed into AP function
 342 **/
 343 VOID
 344 WakeUpAP (
 345   IN CPU_MP_DATA               *CpuMpData,
 346   IN BOOLEAN                   Broadcast,
 347   IN UINTN                     ProcessorNumber,
 348   IN EFI_AP_PROCEDURE          Procedure,              OPTIONAL
 349   IN VOID                      *ProcedureArgument      OPTIONAL
 350   );
 351
 352 /**
 353   Initialize global data for MP support.
 354
 355   @param[in] CpuMpData  The pointer to CPU MP Data structure.
 356 **/
 357 VOID
 358 InitMpGlobalData (
 359   IN CPU_MP_DATA               *CpuMpData
 360   );
 361
 362 /**
 363   Worker function to execute a caller provided function on all enabled APs.
 364
 365   @param[in]  Procedure               A pointer to the function to be run on
 366                                       enabled APs of the system.
 367   @param[in]  SingleThread            If TRUE, then all the enabled APs execute
 368                                       the function specified by Procedure one by
 369                                       one, in ascending order of processor handle
 370                                       number.  If FALSE, then all the enabled APs
 371                                       execute the function specified by Procedure
 372                                       simultaneously.
 373   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 374                                       service.
 375   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 376                                       APs to return from Procedure, either for
 377                                       blocking or non-blocking mode.
 378   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 379                                       all APs.
 380   @param[out] FailedCpuList           If all APs finish successfully, then its
 381                                       content is set to NULL. If not all APs
 382                                       finish before timeout expires, then its
 383                                       content is set to address of the buffer
 384                                       holding handle numbers of the failed APs.
 385
 386   @retval EFI_SUCCESS             In blocking mode, all APs have finished before
 387                                   the timeout expired.
 388   @retval EFI_SUCCESS             In non-blocking mode, function has been dispatched
 389                                   to all enabled APs.
 390   @retval others                  Failed to Startup all APs.
 391
 392 **/
 393 EFI_STATUS
 394 StartupAllAPsWorker (
 395   IN  EFI_AP_PROCEDURE          Procedure,
 396   IN  BOOLEAN                   SingleThread,
 397   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 398   IN  UINTN                     TimeoutInMicroseconds,
 399   IN  VOID                      *ProcedureArgument      OPTIONAL,
 400   OUT UINTN                     **FailedCpuList         OPTIONAL
 401   );
 402
 403 /**
 404   Worker function to let the caller get one enabled AP to execute a caller-provided
 405   function.
 406
 407   @param[in]  Procedure               A pointer to the function to be run on
 408                                       enabled APs of the system.
 409   @param[in]  ProcessorNumber         The handle number of the AP.
 410   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 411                                       service.
 412   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 413                                       APs to return from Procedure, either for
 414                                       blocking or non-blocking mode.
 415   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 416                                       all APs.
 417   @param[out] Finished                If AP returns from Procedure before the
 418                                       timeout expires, its content is set to TRUE.
 419                                       Otherwise, the value is set to FALSE.
 420
 421   @retval EFI_SUCCESS             In blocking mode, specified AP finished before
 422                                   the timeout expires.
 423   @retval others                  Failed to Startup AP.
 424
 425 **/
 426 EFI_STATUS
 427 StartupThisAPWorker (
 428   IN  EFI_AP_PROCEDURE          Procedure,
 429   IN  UINTN                     ProcessorNumber,
 430   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 431   IN  UINTN                     TimeoutInMicroseconds,
 432   IN  VOID                      *ProcedureArgument      OPTIONAL,
 433   OUT BOOLEAN                   *Finished               OPTIONAL
 434   );
 435
 436 /**
 437   Worker function to switch the requested AP to be the BSP from that point onward.
 438
 439   @param[in] ProcessorNumber   The handle number of AP that is to become the new BSP.
 440   @param[in] EnableOldBSP      If TRUE, then the old BSP will be listed as an
 441                                enabled AP. Otherwise, it will be disabled.
 442
 443   @retval EFI_SUCCESS          BSP successfully switched.
 444   @retval others               Failed to switch BSP.
 445
 446 **/
 447 EFI_STATUS
 448 SwitchBSPWorker (
 449   IN UINTN                     ProcessorNumber,
 450   IN BOOLEAN                   EnableOldBSP
 451   );
 452
 453 /**
 454   Worker function to let the caller enable or disable an AP from this point onward.
 455   This service may only be called from the BSP.
 456
 457   @param[in] ProcessorNumber   The handle number of AP.
 458   @param[in] EnableAP          Specifies the new state for the processor for
 459                                enabled, FALSE for disabled.
 460   @param[in] HealthFlag        If not NULL, a pointer to a value that specifies
 461                                the new health status of the AP.
 462
 463   @retval EFI_SUCCESS          The specified AP was enabled or disabled successfully.
 464   @retval others               Failed to Enable/Disable AP.
 465
 466 **/
 467 EFI_STATUS
 468 EnableDisableApWorker (
 469   IN  UINTN                     ProcessorNumber,
 470   IN  BOOLEAN                   EnableAP,
 471   IN  UINT32                    *HealthFlag OPTIONAL
 472   );
 473
 474 /**
 475   Get pointer to CPU MP Data structure from GUIDed HOB.
 476
 477   @return  The pointer to CPU MP Data structure.
 478 **/
 479 CPU_MP_DATA *
 480 GetCpuMpDataFromGuidedHob (
 481   VOID
 482   );
 483
 484 /** Checks status of specified AP.
 485
 486   This function checks whether the specified AP has finished the task assigned
 487   by StartupThisAP(), and whether timeout expires.
 488
 489   @param[in]  ProcessorNumber       The handle number of processor.
 490
 491   @retval EFI_SUCCESS           Specified AP has finished task assigned by StartupThisAPs().
 492   @retval EFI_TIMEOUT           The timeout expires.
 493   @retval EFI_NOT_READY         Specified AP has not finished task and timeout has not expired.
 494 **/
 495 EFI_STATUS
 496 CheckThisAP (
 497   IN UINTN        ProcessorNumber
 498   );
 499
 500 /**
 501   Checks status of all APs.
 502
 503   This function checks whether all APs have finished task assigned by StartupAllAPs(),
 504   and whether timeout expires.
 505
 506   @retval EFI_SUCCESS           All APs have finished task assigned by StartupAllAPs().
 507   @retval EFI_TIMEOUT           The timeout expires.
 508   @retval EFI_NOT_READY         APs have not finished task and timeout has not expired.
 509 **/
 510 EFI_STATUS
 511 CheckAllAPs (
 512   VOID
 513   );
 514
 515 /**
 516   Checks APs status and updates APs status if needed.
 517
 518 **/
 519 VOID
 520 CheckAndUpdateApsStatus (
 521   VOID
 522   );
 523
 524 /**
 525   Detect whether specified processor can find matching microcode patch and load it.
 526
 527   @param[in]  CpuMpData  The pointer to CPU MP Data structure.
 528 **/
 529 VOID
 530 MicrocodeDetect (
 531   IN CPU_MP_DATA             *CpuMpData
 532   );
 533
 534 /**
 535   Detect whether Mwait-monitor feature is supported.
 536
 537   @retval TRUE    Mwait-monitor feature is supported.
 538   @retval FALSE   Mwait-monitor feature is not supported.
 539 **/
 540 BOOLEAN
 541 IsMwaitSupport (
 542   VOID
 543   );
 544
 545 /**
 546   Get available system memory below 1MB by specified size.
 547
 548   @param[in]  CpuMpData  The pointer to CPU MP Data structure.
 549 **/
 550 VOID
 551 BackupAndPrepareWakeupBuffer(
 552   IN CPU_MP_DATA              *CpuMpData
 553   );
 554
 555 /**
 556   Restore wakeup buffer data.
 557
 558   @param[in]  CpuMpData  The pointer to CPU MP Data structure.
 559 **/
 560 VOID
 561 RestoreWakeupBuffer(
 562   IN CPU_MP_DATA              *CpuMpData
 563   );
 564
 565 /**
 566   Enable Debug Agent to support source debugging on AP function.
 567
 568 **/
 569 VOID
 570 EnableDebugAgent (
 571   VOID
 572   );
 573
 574 #endif
 575