UefiCpuPkg/Library/MpInitLib/MpLib.h

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