MdePkg/Include/Ppi/MpServices.h

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