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