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