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