UefiCpuPkg/CpuMpPei/CpuMpPei.h

   1 /** @file
   2   Definitions to install Multiple Processor PPI.
   3
   4   Copyright (c) 2015 - 2019, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _CPU_MP_PEI_H_
  10 #define _CPU_MP_PEI_H_
  11
  12 #include <PiPei.h>
  13
  14 #include <Ppi/MpServices.h>
  15 #include <Ppi/SecPlatformInformation.h>
  16 #include <Ppi/SecPlatformInformation2.h>
  17 #include <Ppi/EndOfPeiPhase.h>
  18 #include <Ppi/MpServices2.h>
  19
  20 #include <Library/BaseLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/HobLib.h>
  23 #include <Library/LocalApicLib.h>
  24 #include <Library/PeimEntryPoint.h>
  25 #include <Library/PeiServicesLib.h>
  26 #include <Library/ReportStatusCodeLib.h>
  27 #include <Library/CpuExceptionHandlerLib.h>
  28 #include <Library/MpInitLib.h>
  29 #include <Library/BaseMemoryLib.h>
  30
  31 extern EFI_PEI_PPI_DESCRIPTOR   mPeiCpuMpPpiDesc;
  32
  33 /**
  34   This service retrieves the number of logical processor in the platform
  35   and the number of those logical processors that are enabled on this boot.
  36   This service may only be called from the BSP.
  37
  38   This function is used to retrieve the following information:
  39     - The number of logical processors that are present in the system.
  40     - The number of enabled logical processors in the system at the instant
  41       this call is made.
  42
  43   Because MP Service Ppi provides services to enable and disable processors
  44   dynamically, the number of enabled logical processors may vary during the
  45   course of a boot session.
  46
  47   If this service is called from an AP, then EFI_DEVICE_ERROR is returned.
  48   If NumberOfProcessors or NumberOfEnabledProcessors is NULL, then
  49   EFI_INVALID_PARAMETER is returned. Otherwise, the total number of processors
  50   is returned in NumberOfProcessors, the number of currently enabled processor
  51   is returned in NumberOfEnabledProcessors, and EFI_SUCCESS is returned.
  52
  53   @param[in]  PeiServices         An indirect pointer to the PEI Services Table
  54                                   published by the PEI Foundation.
  55   @param[in]  This                Pointer to this instance of the PPI.
  56   @param[out] NumberOfProcessors  Pointer to the total number of logical processors in
  57                                   the system, including the BSP and disabled APs.
  58   @param[out] NumberOfEnabledProcessors
  59                                   Number of processors in the system that are enabled.
  60
  61   @retval EFI_SUCCESS             The number of logical processors and enabled
  62                                   logical processors was retrieved.
  63   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  64   @retval EFI_INVALID_PARAMETER   NumberOfProcessors is NULL.
  65                                   NumberOfEnabledProcessors is NULL.
  66 **/
  67 EFI_STATUS
  68 EFIAPI
  69 PeiGetNumberOfProcessors (
  70   IN  CONST EFI_PEI_SERVICES    **PeiServices,
  71   IN  EFI_PEI_MP_SERVICES_PPI   *This,
  72   OUT UINTN                     *NumberOfProcessors,
  73   OUT UINTN                     *NumberOfEnabledProcessors
  74   );
  75
  76 /**
  77   Gets detailed MP-related information on the requested processor at the
  78   instant this call is made. This service may only be called from the BSP.
  79
  80   This service retrieves detailed MP-related information about any processor
  81   on the platform. Note the following:
  82     - The processor information may change during the course of a boot session.
  83     - The information presented here is entirely MP related.
  84
  85   Information regarding the number of caches and their sizes, frequency of operation,
  86   slot numbers is all considered platform-related information and is not provided
  87   by this service.
  88
  89   @param[in]  PeiServices         An indirect pointer to the PEI Services Table
  90                                   published by the PEI Foundation.
  91   @param[in]  This                Pointer to this instance of the PPI.
  92   @param[in]  ProcessorNumber     Pointer to the total number of logical processors in
  93                                   the system, including the BSP and disabled APs.
  94   @param[out] ProcessorInfoBuffer Number of processors in the system that are enabled.
  95
  96   @retval EFI_SUCCESS             Processor information was returned.
  97   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  98   @retval EFI_INVALID_PARAMETER   ProcessorInfoBuffer is NULL.
  99   @retval EFI_NOT_FOUND           The processor with the handle specified by
 100                                   ProcessorNumber does not exist in the platform.
 101 **/
 102 EFI_STATUS
 103 EFIAPI
 104 PeiGetProcessorInfo (
 105   IN  CONST EFI_PEI_SERVICES     **PeiServices,
 106   IN  EFI_PEI_MP_SERVICES_PPI    *This,
 107   IN  UINTN                      ProcessorNumber,
 108   OUT EFI_PROCESSOR_INFORMATION  *ProcessorInfoBuffer
 109   );
 110
 111 /**
 112   This service executes a caller provided function on all enabled APs. APs can
 113   run either simultaneously or one at a time in sequence. This service supports
 114   both blocking requests only. This service may only
 115   be called from the BSP.
 116
 117   This function is used to dispatch all the enabled APs to the function specified
 118   by Procedure.  If any enabled AP is busy, then EFI_NOT_READY is returned
 119   immediately and Procedure is not started on any AP.
 120
 121   If SingleThread is TRUE, all the enabled APs execute the function specified by
 122   Procedure one by one, in ascending order of processor handle number. Otherwise,
 123   all the enabled APs execute the function specified by Procedure simultaneously.
 124
 125   If the timeout specified by TimeoutInMicroSeconds expires before all APs return
 126   from Procedure, then Procedure on the failed APs is terminated. All enabled APs
 127   are always available for further calls to EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
 128   and EFI_PEI_MP_SERVICES_PPI.StartupThisAP(). If FailedCpuList is not NULL, its
 129   content points to the list of processor handle numbers in which Procedure was
 130   terminated.
 131
 132   Note: It is the responsibility of the consumer of the EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
 133   to make sure that the nature of the code that is executed on the BSP and the
 134   dispatched APs is well controlled. The MP Services Ppi does not guarantee
 135   that the Procedure function is MP-safe. Hence, the tasks that can be run in
 136   parallel are limited to certain independent tasks and well-controlled exclusive
 137   code. PEI services and Ppis may not be called by APs unless otherwise
 138   specified.
 139
 140   In blocking execution mode, BSP waits until all APs finish or
 141   TimeoutInMicroSeconds expires.
 142
 143   @param[in] PeiServices          An indirect pointer to the PEI Services Table
 144                                   published by the PEI Foundation.
 145   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 146   @param[in] Procedure            A pointer to the function to be run on enabled APs of
 147                                   the system.
 148   @param[in] SingleThread         If TRUE, then all the enabled APs execute the function
 149                                   specified by Procedure one by one, in ascending order
 150                                   of processor handle number. If FALSE, then all the
 151                                   enabled APs execute the function specified by Procedure
 152                                   simultaneously.
 153   @param[in] TimeoutInMicroSeconds
 154                                   Indicates the time limit in microseconds for APs to
 155                                   return from Procedure, for blocking mode only. Zero
 156                                   means infinity. If the timeout expires before all APs
 157                                   return from Procedure, then Procedure on the failed APs
 158                                   is terminated. All enabled APs are available for next
 159                                   function assigned by EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
 160                                   or EFI_PEI_MP_SERVICES_PPI.StartupThisAP(). If the
 161                                   timeout expires in blocking mode, BSP returns
 162                                   EFI_TIMEOUT.
 163   @param[in] ProcedureArgument    The parameter passed into Procedure for all APs.
 164
 165   @retval EFI_SUCCESS             In blocking mode, all APs have finished before the
 166                                   timeout expired.
 167   @retval EFI_DEVICE_ERROR        Caller processor is AP.
 168   @retval EFI_NOT_STARTED         No enabled APs exist in the system.
 169   @retval EFI_NOT_READY           Any enabled APs are busy.
 170   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before all
 171                                   enabled APs have finished.
 172   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 173 **/
 174 EFI_STATUS
 175 EFIAPI
 176 PeiStartupAllAPs (
 177   IN  CONST EFI_PEI_SERVICES    **PeiServices,
 178   IN  EFI_PEI_MP_SERVICES_PPI   *This,
 179   IN  EFI_AP_PROCEDURE          Procedure,
 180   IN  BOOLEAN                   SingleThread,
 181   IN  UINTN                     TimeoutInMicroSeconds,
 182   IN  VOID                      *ProcedureArgument      OPTIONAL
 183   );
 184
 185 /**
 186   This service lets the caller get one enabled AP to execute a caller-provided
 187   function. The caller can request the BSP to wait for the completion
 188   of the AP. This service may only be called from the BSP.
 189
 190   This function is used to dispatch one enabled AP to the function specified by
 191   Procedure passing in the argument specified by ProcedureArgument.
 192   The execution is in blocking mode. The BSP waits until the AP finishes or
 193   TimeoutInMicroSecondss expires.
 194
 195   If the timeout specified by TimeoutInMicroseconds expires before the AP returns
 196   from Procedure, then execution of Procedure by the AP is terminated. The AP is
 197   available for subsequent calls to EFI_PEI_MP_SERVICES_PPI.StartupAllAPs() and
 198   EFI_PEI_MP_SERVICES_PPI.StartupThisAP().
 199
 200   @param[in] PeiServices          An indirect pointer to the PEI Services Table
 201                                   published by the PEI Foundation.
 202   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 203   @param[in] Procedure            A pointer to the function to be run on enabled APs of
 204                                   the system.
 205   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 206                                   total number of logical processors minus 1. The total
 207                                   number of logical processors can be retrieved by
 208                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 209   @param[in] TimeoutInMicroseconds
 210                                   Indicates the time limit in microseconds for APs to
 211                                   return from Procedure, for blocking mode only. Zero
 212                                   means infinity. If the timeout expires before all APs
 213                                   return from Procedure, then Procedure on the failed APs
 214                                   is terminated. All enabled APs are available for next
 215                                   function assigned by EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
 216                                   or EFI_PEI_MP_SERVICES_PPI.StartupThisAP(). If the
 217                                   timeout expires in blocking mode, BSP returns
 218                                   EFI_TIMEOUT.
 219   @param[in] ProcedureArgument    The parameter passed into Procedure for all APs.
 220
 221   @retval EFI_SUCCESS             In blocking mode, specified AP finished before the
 222                                   timeout expires.
 223   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 224   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before the
 225                                   specified AP has finished.
 226   @retval EFI_NOT_FOUND           The processor with the handle specified by
 227                                   ProcessorNumber does not exist.
 228   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP or disabled AP.
 229   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 230 **/
 231 EFI_STATUS
 232 EFIAPI
 233 PeiStartupThisAP (
 234   IN  CONST EFI_PEI_SERVICES    **PeiServices,
 235   IN  EFI_PEI_MP_SERVICES_PPI   *This,
 236   IN  EFI_AP_PROCEDURE          Procedure,
 237   IN  UINTN                     ProcessorNumber,
 238   IN  UINTN                     TimeoutInMicroseconds,
 239   IN  VOID                      *ProcedureArgument      OPTIONAL
 240   );
 241
 242 /**
 243   This service switches the requested AP to be the BSP from that point onward.
 244   This service changes the BSP for all purposes.   This call can only be performed
 245   by the current BSP.
 246
 247   This service switches the requested AP to be the BSP from that point onward.
 248   This service changes the BSP for all purposes. The new BSP can take over the
 249   execution of the old BSP and continue seamlessly from where the old one left
 250   off.
 251
 252   If the BSP cannot be switched prior to the return from this service, then
 253   EFI_UNSUPPORTED must be returned.
 254
 255   @param[in] PeiServices          An indirect pointer to the PEI Services Table
 256                                   published by the PEI Foundation.
 257   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 258   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 259                                   total number of logical processors minus 1. The total
 260                                   number of logical processors can be retrieved by
 261                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 262   @param[in] EnableOldBSP         If TRUE, then the old BSP will be listed as an enabled
 263                                   AP. Otherwise, it will be disabled.
 264
 265   @retval EFI_SUCCESS             BSP successfully switched.
 266   @retval EFI_UNSUPPORTED         Switching the BSP cannot be completed prior to this
 267                                   service returning.
 268   @retval EFI_UNSUPPORTED         Switching the BSP is not supported.
 269   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 270   @retval EFI_NOT_FOUND           The processor with the handle specified by
 271                                   ProcessorNumber does not exist.
 272   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the current BSP or a disabled
 273                                   AP.
 274   @retval EFI_NOT_READY           The specified AP is busy.
 275 **/
 276 EFI_STATUS
 277 EFIAPI
 278 PeiSwitchBSP (
 279   IN  CONST EFI_PEI_SERVICES   **PeiServices,
 280   IN  EFI_PEI_MP_SERVICES_PPI  *This,
 281   IN  UINTN                    ProcessorNumber,
 282   IN  BOOLEAN                  EnableOldBSP
 283   );
 284
 285 /**
 286   This service lets the caller enable or disable an AP from this point onward.
 287   This service may only be called from the BSP.
 288
 289   This service allows the caller enable or disable an AP from this point onward.
 290   The caller can optionally specify the health status of the AP by Health. If
 291   an AP is being disabled, then the state of the disabled AP is implementation
 292   dependent. If an AP is enabled, then the implementation must guarantee that a
 293   complete initialization sequence is performed on the AP, so the AP is in a state
 294   that is compatible with an MP operating system.
 295
 296   If the enable or disable AP operation cannot be completed prior to the return
 297   from this service, then EFI_UNSUPPORTED must be returned.
 298
 299   @param[in] PeiServices          An indirect pointer to the PEI Services Table
 300                                   published by the PEI Foundation.
 301   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 302   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 303                                   total number of logical processors minus 1. The total
 304                                   number of logical processors can be retrieved by
 305                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 306   @param[in] EnableAP             Specifies the new state for the processor for enabled,
 307                                   FALSE for disabled.
 308   @param[in] HealthFlag           If not NULL, a pointer to a value that specifies the
 309                                   new health status of the AP. This flag corresponds to
 310                                   StatusFlag defined in EFI_PEI_MP_SERVICES_PPI.GetProcessorInfo().
 311                                   Only the PROCESSOR_HEALTH_STATUS_BIT is used. All other
 312                                   bits are ignored. If it is NULL, this parameter is
 313                                   ignored.
 314
 315   @retval EFI_SUCCESS             The specified AP was enabled or disabled successfully.
 316   @retval EFI_UNSUPPORTED         Enabling or disabling an AP cannot be completed prior
 317                                   to this service returning.
 318   @retval EFI_UNSUPPORTED         Enabling or disabling an AP is not supported.
 319   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 320   @retval EFI_NOT_FOUND           Processor with the handle specified by ProcessorNumber
 321                                   does not exist.
 322   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 323 **/
 324 EFI_STATUS
 325 EFIAPI
 326 PeiEnableDisableAP (
 327   IN  CONST EFI_PEI_SERVICES    **PeiServices,
 328   IN  EFI_PEI_MP_SERVICES_PPI   *This,
 329   IN  UINTN                     ProcessorNumber,
 330   IN  BOOLEAN                   EnableAP,
 331   IN  UINT32                    *HealthFlag OPTIONAL
 332   );
 333
 334 /**
 335   This return the handle number for the calling processor.  This service may be
 336   called from the BSP and APs.
 337
 338   This service returns the processor handle number for the calling processor.
 339   The returned value is in the range from 0 to the total number of logical
 340   processors minus 1. The total number of logical processors can be retrieved
 341   with EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors(). This service may be
 342   called from the BSP and APs. If ProcessorNumber is NULL, then EFI_INVALID_PARAMETER
 343   is returned. Otherwise, the current processors handle number is returned in
 344   ProcessorNumber, and EFI_SUCCESS is returned.
 345
 346   @param[in]  PeiServices         An indirect pointer to the PEI Services Table
 347                                   published by the PEI Foundation.
 348   @param[in]  This                A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 349   @param[out] ProcessorNumber     The handle number of the AP. The range is from 0 to the
 350                                   total number of logical processors minus 1. The total
 351                                   number of logical processors can be retrieved by
 352                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 353
 354   @retval EFI_SUCCESS             The current processor handle number was returned in
 355                                   ProcessorNumber.
 356   @retval EFI_INVALID_PARAMETER   ProcessorNumber is NULL.
 357 **/
 358 EFI_STATUS
 359 EFIAPI
 360 PeiWhoAmI (
 361   IN  CONST EFI_PEI_SERVICES   **PeiServices,
 362   IN  EFI_PEI_MP_SERVICES_PPI  *This,
 363   OUT UINTN                    *ProcessorNumber
 364   );
 365
 366 /**
 367   Collects BIST data from PPI.
 368
 369   This function collects BIST data from Sec Platform Information2 PPI
 370   or SEC Platform Information PPI.
 371
 372   @param PeiServices         Pointer to PEI Services Table
 373
 374 **/
 375 VOID
 376 CollectBistDataFromPpi (
 377   IN CONST EFI_PEI_SERVICES             **PeiServices
 378   );
 379
 380 /**
 381   Implementation of the PlatformInformation2 service in EFI_SEC_PLATFORM_INFORMATION2_PPI.
 382
 383   @param  PeiServices                The pointer to the PEI Services Table.
 384   @param  StructureSize              The pointer to the variable describing size of the input buffer.
 385   @param  PlatformInformationRecord2 The pointer to the EFI_SEC_PLATFORM_INFORMATION_RECORD2.
 386
 387   @retval EFI_SUCCESS                The data was successfully returned.
 388   @retval EFI_BUFFER_TOO_SMALL       The buffer was too small. The current buffer size needed to
 389                                      hold the record is returned in StructureSize.
 390
 391 **/
 392 EFI_STATUS
 393 EFIAPI
 394 SecPlatformInformation2 (
 395   IN CONST EFI_PEI_SERVICES                   **PeiServices,
 396   IN OUT UINT64                               *StructureSize,
 397      OUT EFI_SEC_PLATFORM_INFORMATION_RECORD2 *PlatformInformationRecord2
 398   );
 399
 400 /**
 401   Initializes MP and exceptions handlers.
 402
 403   @param  PeiServices                The pointer to the PEI Services Table.
 404
 405   @retval EFI_SUCCESS     MP was successfully initialized.
 406   @retval others          Error occurred in MP initialization.
 407
 408 **/
 409 EFI_STATUS
 410 InitializeCpuMpWorker (
 411   IN CONST EFI_PEI_SERVICES     **PeiServices
 412   );
 413
 414 /**
 415   Enabl/setup stack guard for each processor if PcdCpuStackGuard is set to TRUE.
 416
 417   Doing this in the memory-discovered callback is to make sure the Stack Guard
 418   feature to cover as most PEI code as possible.
 419
 420   @param[in] PeiServices          General purpose services available to every PEIM.
 421   @param[in] NotifyDescriptor     The notification structure this PEIM registered on install.
 422   @param[in] Ppi                  The memory discovered PPI.  Not used.
 423
 424   @retval EFI_SUCCESS             The function completed successfully.
 425   @retval others                  There's error in MP initialization.
 426 **/
 427 EFI_STATUS
 428 EFIAPI
 429 MemoryDiscoveredPpiNotifyCallback (
 430   IN EFI_PEI_SERVICES           **PeiServices,
 431   IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyDescriptor,
 432   IN VOID                       *Ppi
 433   );
 434
 435 extern EFI_PEI_NOTIFY_DESCRIPTOR  mPostMemNotifyList[];
 436
 437 #endif