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