UefiCpuPkg/Include/Library/MpInitLib.h

   1 /** @file
   2   Multiple-Processor initialization Library.
   3
   4   Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __MP_INIT_LIB_H__
  10 #define __MP_INIT_LIB_H__
  11
  12 #include <Ppi/SecPlatformInformation.h>
  13 #include <Protocol/MpService.h>
  14
  15 /**
  16   MP Initialize Library initialization.
  17
  18   This service will allocate AP reset vector and wakeup all APs to do APs
  19   initialization.
  20
  21   This service must be invoked before all other MP Initialize Library
  22   service are invoked.
  23
  24   @retval  EFI_SUCCESS           MP initialization succeeds.
  25   @retval  Others                MP initialization fails.
  26
  27 **/
  28 EFI_STATUS
  29 EFIAPI
  30 MpInitLibInitialize (
  31   VOID
  32   );
  33
  34 /**
  35   Retrieves the number of logical processor in the platform and the number of
  36   those logical processors that are enabled on this boot. This service may only
  37   be called from the BSP.
  38
  39   @param[out] NumberOfProcessors          Pointer to the total number of logical
  40                                           processors in the system, including the BSP
  41                                           and disabled APs.
  42   @param[out] NumberOfEnabledProcessors   Pointer to the number of enabled logical
  43                                           processors that exist in system, including
  44                                           the BSP.
  45
  46   @retval EFI_SUCCESS             The number of logical processors and enabled
  47                                   logical processors was retrieved.
  48   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  49   @retval EFI_INVALID_PARAMETER   NumberOfProcessors is NULL and NumberOfEnabledProcessors
  50                                   is NULL.
  51   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
  52
  53 **/
  54 EFI_STATUS
  55 EFIAPI
  56 MpInitLibGetNumberOfProcessors (
  57   OUT UINTN                     *NumberOfProcessors,       OPTIONAL
  58   OUT UINTN                     *NumberOfEnabledProcessors OPTIONAL
  59   );
  60
  61 /**
  62   Gets detailed MP-related information on the requested processor at the
  63   instant this call is made. This service may only be called from the BSP.
  64
  65   @param[in]  ProcessorNumber       The handle number of processor.
  66   @param[out] ProcessorInfoBuffer   A pointer to the buffer where information for
  67                                     the requested processor is deposited.
  68   @param[out] HealthData            Return processor health data.
  69
  70   @retval EFI_SUCCESS             Processor information was returned.
  71   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  72   @retval EFI_INVALID_PARAMETER   ProcessorInfoBuffer is NULL.
  73   @retval EFI_NOT_FOUND           The processor with the handle specified by
  74                                   ProcessorNumber does not exist in the platform.
  75   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
  76
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 MpInitLibGetProcessorInfo (
  81   IN  UINTN                      ProcessorNumber,
  82   OUT EFI_PROCESSOR_INFORMATION  *ProcessorInfoBuffer,
  83   OUT EFI_HEALTH_FLAGS           *HealthData  OPTIONAL
  84   );
  85
  86 /**
  87   This service executes a caller provided function on all enabled APs.
  88
  89   @param[in]  Procedure               A pointer to the function to be run on
  90                                       enabled APs of the system. See type
  91                                       EFI_AP_PROCEDURE.
  92   @param[in]  SingleThread            If TRUE, then all the enabled APs execute
  93                                       the function specified by Procedure one by
  94                                       one, in ascending order of processor handle
  95                                       number.  If FALSE, then all the enabled APs
  96                                       execute the function specified by Procedure
  97                                       simultaneously.
  98   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
  99                                       service.  If it is NULL, then execute in
 100                                       blocking mode. BSP waits until all APs finish
 101                                       or TimeoutInMicroSeconds expires.  If it's
 102                                       not NULL, then execute in non-blocking mode.
 103                                       BSP requests the function specified by
 104                                       Procedure to be started on all the enabled
 105                                       APs, and go on executing immediately. If
 106                                       all return from Procedure, or TimeoutInMicroSeconds
 107                                       expires, this event is signaled. The BSP
 108                                       can use the CheckEvent() or WaitForEvent()
 109                                       services to check the state of event.  Type
 110                                       EFI_EVENT is defined in CreateEvent() in
 111                                       the Unified Extensible Firmware Interface
 112                                       Specification.
 113   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 114                                       APs to return from Procedure, either for
 115                                       blocking or non-blocking mode. Zero means
 116                                       infinity.  If the timeout expires before
 117                                       all APs return from Procedure, then Procedure
 118                                       on the failed APs is terminated. All enabled
 119                                       APs are available for next function assigned
 120                                       by MpInitLibStartupAllAPs() or
 121                                       MPInitLibStartupThisAP().
 122                                       If the timeout expires in blocking mode,
 123                                       BSP returns EFI_TIMEOUT.  If the timeout
 124                                       expires in non-blocking mode, WaitEvent
 125                                       is signaled with SignalEvent().
 126   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 127                                       all APs.
 128   @param[out] FailedCpuList           If NULL, this parameter is ignored. Otherwise,
 129                                       if all APs finish successfully, then its
 130                                       content is set to NULL. If not all APs
 131                                       finish before timeout expires, then its
 132                                       content is set to address of the buffer
 133                                       holding handle numbers of the failed APs.
 134                                       The buffer is allocated by MP Initialization
 135                                       library, and it's the caller's responsibility to
 136                                       free the buffer with FreePool() service.
 137                                       In blocking mode, it is ready for consumption
 138                                       when the call returns. In non-blocking mode,
 139                                       it is ready when WaitEvent is signaled.  The
 140                                       list of failed CPU is terminated by
 141                                       END_OF_CPU_LIST.
 142
 143   @retval EFI_SUCCESS             In blocking mode, all APs have finished before
 144                                   the timeout expired.
 145   @retval EFI_SUCCESS             In non-blocking mode, function has been dispatched
 146                                   to all enabled APs.
 147   @retval EFI_UNSUPPORTED         A non-blocking mode request was made after the
 148                                   UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
 149                                   signaled.
 150   @retval EFI_UNSUPPORTED         WaitEvent is not NULL if non-blocking mode is not
 151                                   supported.
 152   @retval EFI_DEVICE_ERROR        Caller processor is AP.
 153   @retval EFI_NOT_STARTED         No enabled APs exist in the system.
 154   @retval EFI_NOT_READY           Any enabled APs are busy.
 155   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
 156   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before
 157                                   all enabled APs have finished.
 158   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 159
 160 **/
 161 EFI_STATUS
 162 EFIAPI
 163 MpInitLibStartupAllAPs (
 164   IN  EFI_AP_PROCEDURE          Procedure,
 165   IN  BOOLEAN                   SingleThread,
 166   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 167   IN  UINTN                     TimeoutInMicroseconds,
 168   IN  VOID                      *ProcedureArgument      OPTIONAL,
 169   OUT UINTN                     **FailedCpuList         OPTIONAL
 170   );
 171
 172 /**
 173   This service lets the caller get one enabled AP to execute a caller-provided
 174   function.
 175
 176   @param[in]  Procedure               A pointer to the function to be run on the
 177                                       designated AP of the system. See type
 178                                       EFI_AP_PROCEDURE.
 179   @param[in]  ProcessorNumber         The handle number of the AP. The range is
 180                                       from 0 to the total number of logical
 181                                       processors minus 1. The total number of
 182                                       logical processors can be retrieved by
 183                                       MpInitLibGetNumberOfProcessors().
 184   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 185                                       service.  If it is NULL, then execute in
 186                                       blocking mode. BSP waits until this AP finish
 187                                       or TimeoutInMicroSeconds expires.  If it's
 188                                       not NULL, then execute in non-blocking mode.
 189                                       BSP requests the function specified by
 190                                       Procedure to be started on this AP,
 191                                       and go on executing immediately. If this AP
 192                                       return from Procedure or TimeoutInMicroSeconds
 193                                       expires, this event is signaled. The BSP
 194                                       can use the CheckEvent() or WaitForEvent()
 195                                       services to check the state of event.  Type
 196                                       EFI_EVENT is defined in CreateEvent() in
 197                                       the Unified Extensible Firmware Interface
 198                                       Specification.
 199   @param[in]  TimeoutInMicroseconds   Indicates the time limit in microseconds for
 200                                       this AP to finish this Procedure, either for
 201                                       blocking or non-blocking mode. Zero means
 202                                       infinity.  If the timeout expires before
 203                                       this AP returns from Procedure, then Procedure
 204                                       on the AP is terminated. The
 205                                       AP is available for next function assigned
 206                                       by MpInitLibStartupAllAPs() or
 207                                       MpInitLibStartupThisAP().
 208                                       If the timeout expires in blocking mode,
 209                                       BSP returns EFI_TIMEOUT.  If the timeout
 210                                       expires in non-blocking mode, WaitEvent
 211                                       is signaled with SignalEvent().
 212   @param[in]  ProcedureArgument       The parameter passed into Procedure on the
 213                                       specified AP.
 214   @param[out] Finished                If NULL, this parameter is ignored.  In
 215                                       blocking mode, this parameter is ignored.
 216                                       In non-blocking mode, if AP returns from
 217                                       Procedure before the timeout expires, its
 218                                       content is set to TRUE. Otherwise, the
 219                                       value is set to FALSE. The caller can
 220                                       determine if the AP returned from Procedure
 221                                       by evaluating this value.
 222
 223   @retval EFI_SUCCESS             In blocking mode, specified AP finished before
 224                                   the timeout expires.
 225   @retval EFI_SUCCESS             In non-blocking mode, the function has been
 226                                   dispatched to specified AP.
 227   @retval EFI_UNSUPPORTED         A non-blocking mode request was made after the
 228                                   UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
 229                                   signaled.
 230   @retval EFI_UNSUPPORTED         WaitEvent is not NULL if non-blocking mode is not
 231                                   supported.
 232   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 233   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before
 234                                   the specified AP has finished.
 235   @retval EFI_NOT_READY           The specified AP is busy.
 236   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
 237   @retval EFI_NOT_FOUND           The processor with the handle specified by
 238                                   ProcessorNumber does not exist.
 239   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP or disabled AP.
 240   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 241
 242 **/
 243 EFI_STATUS
 244 EFIAPI
 245 MpInitLibStartupThisAP (
 246   IN  EFI_AP_PROCEDURE          Procedure,
 247   IN  UINTN                     ProcessorNumber,
 248   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 249   IN  UINTN                     TimeoutInMicroseconds,
 250   IN  VOID                      *ProcedureArgument      OPTIONAL,
 251   OUT BOOLEAN                   *Finished               OPTIONAL
 252   );
 253
 254 /**
 255   This service switches the requested AP to be the BSP from that point onward.
 256   This service changes the BSP for all purposes. This call can only be performed
 257   by the current BSP.
 258
 259   @param[in] ProcessorNumber   The handle number of AP that is to become the new
 260                                BSP. The range is from 0 to the total number of
 261                                logical processors minus 1. The total number of
 262                                logical processors can be retrieved by
 263                                MpInitLibGetNumberOfProcessors().
 264   @param[in] EnableOldBSP      If TRUE, then the old BSP will be listed as an
 265                                enabled AP. Otherwise, it will be disabled.
 266
 267   @retval EFI_SUCCESS             BSP successfully switched.
 268   @retval EFI_UNSUPPORTED         Switching the BSP cannot be completed prior to
 269                                   this service returning.
 270   @retval EFI_UNSUPPORTED         Switching the BSP is not supported.
 271   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 272   @retval EFI_NOT_FOUND           The processor with the handle specified by
 273                                   ProcessorNumber does not exist.
 274   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the current BSP or
 275                                   a disabled AP.
 276   @retval EFI_NOT_READY           The specified AP is busy.
 277   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
 278
 279 **/
 280 EFI_STATUS
 281 EFIAPI
 282 MpInitLibSwitchBSP (
 283   IN UINTN                     ProcessorNumber,
 284   IN BOOLEAN                   EnableOldBSP
 285   );
 286
 287 /**
 288   This service lets the caller enable or disable an AP from this point onward.
 289   This service may only be called from the BSP.
 290
 291   @param[in] ProcessorNumber   The handle number of AP.
 292                                The range is from 0 to the total number of
 293                                logical processors minus 1. The total number of
 294                                logical processors can be retrieved by
 295                                MpInitLibGetNumberOfProcessors().
 296   @param[in] EnableAP          Specifies the new state for the processor for
 297                                enabled, FALSE for disabled.
 298   @param[in] HealthFlag        If not NULL, a pointer to a value that specifies
 299                                the new health status of the AP. This flag
 300                                corresponds to StatusFlag defined in
 301                                EFI_MP_SERVICES_PROTOCOL.GetProcessorInfo(). Only
 302                                the PROCESSOR_HEALTH_STATUS_BIT is used. All other
 303                                bits are ignored.  If it is NULL, this parameter
 304                                is ignored.
 305
 306   @retval EFI_SUCCESS             The specified AP was enabled or disabled successfully.
 307   @retval EFI_UNSUPPORTED         Enabling or disabling an AP cannot be completed
 308                                   prior to this service returning.
 309   @retval EFI_UNSUPPORTED         Enabling or disabling an AP is not supported.
 310   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 311   @retval EFI_NOT_FOUND           Processor with the handle specified by ProcessorNumber
 312                                   does not exist.
 313   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 314   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
 315
 316 **/
 317 EFI_STATUS
 318 EFIAPI
 319 MpInitLibEnableDisableAP (
 320   IN  UINTN                     ProcessorNumber,
 321   IN  BOOLEAN                   EnableAP,
 322   IN  UINT32                    *HealthFlag OPTIONAL
 323   );
 324
 325 /**
 326   This return the handle number for the calling processor.  This service may be
 327   called from the BSP and APs.
 328
 329   @param[out] ProcessorNumber  Pointer to the handle number of AP.
 330                                The range is from 0 to the total number of
 331                                logical processors minus 1. The total number of
 332                                logical processors can be retrieved by
 333                                MpInitLibGetNumberOfProcessors().
 334
 335   @retval EFI_SUCCESS             The current processor handle number was returned
 336                                   in ProcessorNumber.
 337   @retval EFI_INVALID_PARAMETER   ProcessorNumber is NULL.
 338   @retval EFI_NOT_READY           MP Initialize Library is not initialized.
 339
 340 **/
 341 EFI_STATUS
 342 EFIAPI
 343 MpInitLibWhoAmI (
 344   OUT UINTN                    *ProcessorNumber
 345   );
 346
 347 #endif