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