UefiCpuPkg/Include/Ppi/MpServices2.h

   1 /** @file
   2   This file declares EDKII Multi-processor service PPI.
   3
   4   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __EDKII_PEI_MP_SERVICES2_PPI_H__
  10 #define __EDKII_PEI_MP_SERVICES2_PPI_H__
  11
  12 #include <Ppi/MpServices.h>
  13
  14 #define EDKII_PEI_MP_SERVICES2_PPI_GUID \
  15   { \
  16     0x5cb9cb3d, 0x31a4, 0x480c, { 0x94, 0x98, 0x29, 0xd2, 0x69, 0xba, 0xcf, 0xba} \
  17   }
  18
  19 typedef struct _EDKII_PEI_MP_SERVICES2_PPI  EDKII_PEI_MP_SERVICES2_PPI;
  20
  21 /**
  22   Get the number of CPU's.
  23
  24   @param[in]  This                Pointer to this instance of the PPI.
  25   @param[out] NumberOfProcessors  Pointer to the total number of logical processors in
  26                                   the system, including the BSP and disabled APs.
  27   @param[out] NumberOfEnabledProcessors
  28                                   Number of processors in the system that are enabled.
  29
  30   @retval EFI_SUCCESS             The number of logical processors and enabled
  31                                   logical processors was retrieved.
  32   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  33   @retval EFI_INVALID_PARAMETER   NumberOfProcessors is NULL.
  34                                   NumberOfEnabledProcessors is NULL.
  35 **/
  36 typedef
  37 EFI_STATUS
  38 (EFIAPI *EDKII_PEI_MP_SERVICES_GET_NUMBER_OF_PROCESSORS) (
  39   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
  40   OUT UINTN                          *NumberOfProcessors,
  41   OUT UINTN                          *NumberOfEnabledProcessors
  42   );
  43
  44 /**
  45   Get information on a specific CPU.
  46
  47   @param[in]  This                Pointer to this instance of the PPI.
  48   @param[in]  ProcessorNumber     Pointer to the total number of logical processors in
  49                                   the system, including the BSP and disabled APs.
  50   @param[out] ProcessorInfoBuffer Number of processors in the system that are enabled.
  51
  52   @retval EFI_SUCCESS             Processor information was returned.
  53   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  54   @retval EFI_INVALID_PARAMETER   ProcessorInfoBuffer is NULL.
  55   @retval EFI_NOT_FOUND           The processor with the handle specified by
  56                                   ProcessorNumber does not exist in the platform.
  57 **/
  58 typedef
  59 EFI_STATUS
  60 (EFIAPI *EDKII_PEI_MP_SERVICES_GET_PROCESSOR_INFO) (
  61   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
  62   IN  UINTN                          ProcessorNumber,
  63   OUT EFI_PROCESSOR_INFORMATION     *ProcessorInfoBuffer
  64   );
  65
  66 /**
  67   Activate all of the application proessors.
  68
  69   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
  70   @param[in] Procedure            A pointer to the function to be run on enabled APs of
  71                                   the system.
  72   @param[in] SingleThread         If TRUE, then all the enabled APs execute the function
  73                                   specified by Procedure one by one, in ascending order
  74                                   of processor handle number. If FALSE, then all the
  75                                   enabled APs execute the function specified by Procedure
  76                                   simultaneously.
  77   @param[in] TimeoutInMicroSeconds
  78                                   Indicates the time limit in microseconds for APs to
  79                                   return from Procedure, for blocking mode only. Zero
  80                                   means infinity. If the timeout expires before all APs
  81                                   return from Procedure, then Procedure on the failed APs
  82                                   is terminated. All enabled APs are available for next
  83                                   function assigned by EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
  84                                   or EFI_PEI_MP_SERVICES_PPI.StartupThisAP(). If the
  85                                   timeout expires in blocking mode, BSP returns
  86                                   EFI_TIMEOUT.
  87   @param[in] ProcedureArgument    The parameter passed into Procedure for all APs.
  88
  89   @retval EFI_SUCCESS             In blocking mode, all APs have finished before the
  90                                   timeout expired.
  91   @retval EFI_DEVICE_ERROR        Caller processor is AP.
  92   @retval EFI_NOT_STARTED         No enabled APs exist in the system.
  93   @retval EFI_NOT_READY           Any enabled APs are busy.
  94   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before all
  95                                   enabled APs have finished.
  96   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
  97 **/
  98 typedef
  99 EFI_STATUS
 100 (EFIAPI *EDKII_PEI_MP_SERVICES_STARTUP_ALL_APS) (
 101   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 102   IN  EFI_AP_PROCEDURE               Procedure,
 103   IN  BOOLEAN                        SingleThread,
 104   IN  UINTN                          TimeoutInMicroSeconds,
 105   IN  VOID                           *ProcedureArgument      OPTIONAL
 106   );
 107
 108 /**
 109   Activate a specific application processor.
 110
 111   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 112   @param[in] Procedure            A pointer to the function to be run on enabled APs of
 113                                   the system.
 114   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 115                                   total number of logical processors minus 1. The total
 116                                   number of logical processors can be retrieved by
 117                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 118   @param[in] TimeoutInMicroSeconds
 119                                   Indicates the time limit in microseconds for APs to
 120                                   return from Procedure, for blocking mode only. Zero
 121                                   means infinity. If the timeout expires before all APs
 122                                   return from Procedure, then Procedure on the failed APs
 123                                   is terminated. All enabled APs are available for next
 124                                   function assigned by EFI_PEI_MP_SERVICES_PPI.StartupAllAPs()
 125                                   or EFI_PEI_MP_SERVICES_PPI.StartupThisAP(). If the
 126                                   timeout expires in blocking mode, BSP returns
 127                                   EFI_TIMEOUT.
 128   @param[in] ProcedureArgument    The parameter passed into Procedure for all APs.
 129
 130   @retval EFI_SUCCESS             In blocking mode, specified AP finished before the
 131                                   timeout expires.
 132   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 133   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before the
 134                                   specified AP has finished.
 135   @retval EFI_NOT_FOUND           The processor with the handle specified by
 136                                   ProcessorNumber does not exist.
 137   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP or disabled AP.
 138   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 139 **/
 140 typedef
 141 EFI_STATUS
 142 (EFIAPI *EDKII_PEI_MP_SERVICES_STARTUP_THIS_AP) (
 143   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 144   IN  EFI_AP_PROCEDURE               Procedure,
 145   IN  UINTN                          ProcessorNumber,
 146   IN  UINTN                          TimeoutInMicroseconds,
 147   IN  VOID                           *ProcedureArgument      OPTIONAL
 148   );
 149
 150 /**
 151   Switch the boot strap processor.
 152
 153   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 154   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 155                                   total number of logical processors minus 1. The total
 156                                   number of logical processors can be retrieved by
 157                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 158   @param[in] EnableOldBSP         If TRUE, then the old BSP will be listed as an enabled
 159                                   AP. Otherwise, it will be disabled.
 160
 161   @retval EFI_SUCCESS             BSP successfully switched.
 162   @retval EFI_UNSUPPORTED         Switching the BSP cannot be completed prior to this
 163                                   service returning.
 164   @retval EFI_UNSUPPORTED         Switching the BSP is not supported.
 165   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 166   @retval EFI_NOT_FOUND           The processor with the handle specified by
 167                                   ProcessorNumber does not exist.
 168   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the current BSP or a disabled
 169                                   AP.
 170   @retval EFI_NOT_READY           The specified AP is busy.
 171 **/
 172 typedef
 173 EFI_STATUS
 174 (EFIAPI *EDKII_PEI_MP_SERVICES_SWITCH_BSP) (
 175   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 176   IN  UINTN                          ProcessorNumber,
 177   IN  BOOLEAN                        EnableOldBSP
 178   );
 179
 180 /**
 181   Enable or disable an application processor.
 182
 183   @param[in] This                 A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 184   @param[in] ProcessorNumber      The handle number of the AP. The range is from 0 to the
 185                                   total number of logical processors minus 1. The total
 186                                   number of logical processors can be retrieved by
 187                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 188   @param[in] EnableAP             Specifies the new state for the processor for enabled,
 189                                   FALSE for disabled.
 190   @param[in] HealthFlag           If not NULL, a pointer to a value that specifies the
 191                                   new health status of the AP. This flag corresponds to
 192                                   StatusFlag defined in EFI_PEI_MP_SERVICES_PPI.GetProcessorInfo().
 193                                   Only the PROCESSOR_HEALTH_STATUS_BIT is used. All other
 194                                   bits are ignored. If it is NULL, this parameter is
 195                                   ignored.
 196
 197   @retval EFI_SUCCESS             The specified AP was enabled or disabled successfully.
 198   @retval EFI_UNSUPPORTED         Enabling or disabling an AP cannot be completed prior
 199                                   to this service returning.
 200   @retval EFI_UNSUPPORTED         Enabling or disabling an AP is not supported.
 201   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 202   @retval EFI_NOT_FOUND           Processor with the handle specified by ProcessorNumber
 203                                   does not exist.
 204   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 205 **/
 206 typedef
 207 EFI_STATUS
 208 (EFIAPI *EDKII_PEI_MP_SERVICES_ENABLEDISABLEAP) (
 209   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 210   IN  UINTN                          ProcessorNumber,
 211   IN  BOOLEAN                        EnableAP,
 212   IN  UINT32                         *HealthFlag      OPTIONAL
 213   );
 214
 215 /**
 216   Identify the currently executing processor.
 217
 218   @param[in]  This                A pointer to the EFI_PEI_MP_SERVICES_PPI instance.
 219   @param[out] ProcessorNumber     The handle number of the AP. The range is from 0 to the
 220                                   total number of logical processors minus 1. The total
 221                                   number of logical processors can be retrieved by
 222                                   EFI_PEI_MP_SERVICES_PPI.GetNumberOfProcessors().
 223
 224   @retval EFI_SUCCESS             The current processor handle number was returned in
 225                                   ProcessorNumber.
 226   @retval EFI_INVALID_PARAMETER   ProcessorNumber is NULL.
 227 **/
 228 typedef
 229 EFI_STATUS
 230 (EFIAPI *EDKII_PEI_MP_SERVICES_WHOAMI) (
 231   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 232   OUT UINTN                          *ProcessorNumber
 233   );
 234
 235
 236 /**
 237   Activate all of the application proessors.
 238
 239   @param[in] This                 A pointer to the EDKII_PEI_MP_SERVICES2_PPI instance.
 240   @param[in] Procedure            A pointer to the function to be run on enabled APs of
 241                                   the system.
 242   @param[in] TimeoutInMicroSeconds
 243                                   Indicates the time limit in microseconds for APs to
 244                                   return from Procedure, for blocking mode only. Zero
 245                                   means infinity.  If the timeout expires in blocking
 246                                   mode, BSP returns EFI_TIMEOUT.
 247   @param[in] ProcedureArgument    The parameter passed into Procedure for all CPUs.
 248
 249   @retval EFI_SUCCESS             In blocking mode, all APs have finished before the
 250                                   timeout expired.
 251   @retval EFI_DEVICE_ERROR        Caller processor is AP.
 252   @retval EFI_NOT_READY           Any enabled APs are busy.
 253   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before all
 254                                   enabled APs have finished.
 255   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 256 **/
 257 typedef
 258 EFI_STATUS
 259 (EFIAPI *EDKII_PEI_MP_SERVICES_STARTUP_ALL_CPUS) (
 260   IN  EDKII_PEI_MP_SERVICES2_PPI     *This,
 261   IN  EFI_AP_PROCEDURE               Procedure,
 262   IN  UINTN                          TimeoutInMicroSeconds,
 263   IN  VOID                           *ProcedureArgument      OPTIONAL
 264   );
 265
 266 struct _EDKII_PEI_MP_SERVICES2_PPI {
 267   EDKII_PEI_MP_SERVICES_GET_NUMBER_OF_PROCESSORS  GetNumberOfProcessors;
 268   EDKII_PEI_MP_SERVICES_GET_PROCESSOR_INFO        GetProcessorInfo;
 269   EDKII_PEI_MP_SERVICES_STARTUP_ALL_APS           StartupAllAPs;
 270   EDKII_PEI_MP_SERVICES_STARTUP_THIS_AP           StartupThisAP;
 271   EDKII_PEI_MP_SERVICES_SWITCH_BSP                SwitchBSP;
 272   EDKII_PEI_MP_SERVICES_ENABLEDISABLEAP           EnableDisableAP;
 273   EDKII_PEI_MP_SERVICES_WHOAMI                    WhoAmI;
 274   EDKII_PEI_MP_SERVICES_STARTUP_ALL_CPUS          StartupAllCPUs;
 275 };
 276
 277 extern EFI_GUID gEdkiiPeiMpServices2PpiGuid;
 278
 279 #endif