MdePkg/Include/Protocol/MpService.h

   1 /** @file
   2   When installed, the MP Services Protocol produces a collection of services
   3   that are needed for MP management.
   4
   5   The MP Services Protocol provides a generalized way of performing following tasks:
   6     - Retrieving information of multi-processor environment and MP-related status of
   7       specific processors.
   8     - Dispatching user-provided function to APs.
   9     - Maintain MP-related processor status.
  10
  11   The MP Services Protocol must be produced on any system with more than one logical
  12   processor.
  13
  14   The Protocol is available only during boot time.
  15
  16   MP Services Protocol is hardware-independent. Most of the logic of this protocol
  17   is architecturally neutral. It abstracts the multi-processor environment and
  18   status of processors, and provides interfaces to retrieve information, maintain,
  19   and dispatch.
  20
  21   MP Services Protocol may be consumed by ACPI module. The ACPI module may use this
  22   protocol to retrieve data that are needed for an MP platform and report them to OS.
  23   MP Services Protocol may also be used to program and configure processors, such
  24   as MTRR synchronization for memory space attributes setting in DXE Services.
  25   MP Services Protocol may be used by non-CPU DXE drivers to speed up platform boot
  26   by taking advantage of the processing capabilities of the APs, for example, using
  27   APs to help test system memory in parallel with other device initialization.
  28   Diagnostics applications may also use this protocol for multi-processor.
  29
  30 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
  31 SPDX-License-Identifier: BSD-2-Clause-Patent
  32
  33   @par Revision Reference:
  34   This Protocol is defined in the UEFI Platform Initialization Specification 1.2,
  35   Volume 2:Driver Execution Environment Core Interface.
  36
  37 **/
  38
  39 #ifndef _MP_SERVICE_PROTOCOL_H_
  40 #define _MP_SERVICE_PROTOCOL_H_
  41
  42 ///
  43 /// Global ID for the EFI_MP_SERVICES_PROTOCOL.
  44 ///
  45 #define EFI_MP_SERVICES_PROTOCOL_GUID \
  46   { \
  47     0x3fdda605, 0xa76e, 0x4f46, {0xad, 0x29, 0x12, 0xf4, 0x53, 0x1b, 0x3d, 0x08} \
  48   }
  49
  50 ///
  51 /// Value used in the NumberProcessors parameter of the GetProcessorInfo function
  52 ///
  53 #define CPU_V2_EXTENDED_TOPOLOGY BIT24
  54
  55 ///
  56 /// Forward declaration for the EFI_MP_SERVICES_PROTOCOL.
  57 ///
  58 typedef struct _EFI_MP_SERVICES_PROTOCOL EFI_MP_SERVICES_PROTOCOL;
  59
  60 ///
  61 /// Terminator for a list of failed CPUs returned by StartAllAPs().
  62 ///
  63 #define END_OF_CPU_LIST    0xffffffff
  64
  65 ///
  66 /// This bit is used in the StatusFlag field of EFI_PROCESSOR_INFORMATION and
  67 /// indicates whether the processor is playing the role of BSP. If the bit is 1,
  68 /// then the processor is BSP. Otherwise, it is AP.
  69 ///
  70 #define PROCESSOR_AS_BSP_BIT         0x00000001
  71
  72 ///
  73 /// This bit is used in the StatusFlag field of EFI_PROCESSOR_INFORMATION and
  74 /// indicates whether the processor is enabled. If the bit is 1, then the
  75 /// processor is enabled. Otherwise, it is disabled.
  76 ///
  77 #define PROCESSOR_ENABLED_BIT        0x00000002
  78
  79 ///
  80 /// This bit is used in the StatusFlag field of EFI_PROCESSOR_INFORMATION and
  81 /// indicates whether the processor is healthy. If the bit is 1, then the
  82 /// processor is healthy. Otherwise, some fault has been detected for the processor.
  83 ///
  84 #define PROCESSOR_HEALTH_STATUS_BIT  0x00000004
  85
  86 ///
  87 /// Structure that describes the pyhiscal location of a logical CPU.
  88 ///
  89 typedef struct {
  90   ///
  91   /// Zero-based physical package number that identifies the cartridge of the processor.
  92   ///
  93   UINT32  Package;
  94   ///
  95   /// Zero-based physical core number within package of the processor.
  96   ///
  97   UINT32  Core;
  98   ///
  99   /// Zero-based logical thread number within core of the processor.
 100   ///
 101   UINT32  Thread;
 102 } EFI_CPU_PHYSICAL_LOCATION;
 103
 104 ///
 105 ///  Structure that defines the 6-level physical location of the processor
 106 ///
 107 typedef struct {
 108 ///
 109 ///    Package     Zero-based physical package number that identifies the cartridge of the processor.
 110 ///
 111 UINT32  Package;
 112 ///
 113 ///    Module      Zero-based physical module number within package of the processor.
 114 ///
 115 UINT32  Module;
 116 ///
 117 ///    Tile        Zero-based physical tile number within module of the processor.
 118 ///
 119 UINT32  Tile;
 120 ///
 121 ///    Die         Zero-based physical die number within tile of the processor.
 122 ///
 123 UINT32  Die;
 124 ///
 125 ///     Core        Zero-based physical core number within die of the processor.
 126 ///
 127 UINT32  Core;
 128 ///
 129 ///     Thread      Zero-based logical thread number within core of the processor.
 130 ///
 131 UINT32  Thread;
 132 } EFI_CPU_PHYSICAL_LOCATION2;
 133
 134
 135 typedef union {
 136   /// The 6-level physical location of the processor, including the
 137   /// physical package number that identifies the cartridge, the physical
 138   /// module number within package, the physical tile number within the module,
 139   /// the physical die number within the tile, the physical core number within
 140   /// package, and logical thread number within core.
 141   EFI_CPU_PHYSICAL_LOCATION2  Location2;
 142 } EXTENDED_PROCESSOR_INFORMATION;
 143
 144
 145 ///
 146 /// Structure that describes information about a logical CPU.
 147 ///
 148 typedef struct {
 149   ///
 150   /// The unique processor ID determined by system hardware.  For IA32 and X64,
 151   /// the processor ID is the same as the Local APIC ID. Only the lower 8 bits
 152   /// are used, and higher bits are reserved.  For IPF, the lower 16 bits contains
 153   /// id/eid, and higher bits are reserved.
 154   ///
 155   UINT64                     ProcessorId;
 156   ///
 157   /// Flags indicating if the processor is BSP or AP, if the processor is enabled
 158   /// or disabled, and if the processor is healthy. Bits 3..31 are reserved and
 159   /// must be 0.
 160   ///
 161   /// <pre>
 162   /// BSP  ENABLED  HEALTH  Description
 163   /// ===  =======  ======  ===================================================
 164   ///  0      0       0     Unhealthy Disabled AP.
 165   ///  0      0       1     Healthy Disabled AP.
 166   ///  0      1       0     Unhealthy Enabled AP.
 167   ///  0      1       1     Healthy Enabled AP.
 168   ///  1      0       0     Invalid. The BSP can never be in the disabled state.
 169   ///  1      0       1     Invalid. The BSP can never be in the disabled state.
 170   ///  1      1       0     Unhealthy Enabled BSP.
 171   ///  1      1       1     Healthy Enabled BSP.
 172   /// </pre>
 173   ///
 174   UINT32                     StatusFlag;
 175   ///
 176   /// The physical location of the processor, including the physical package number
 177   /// that identifies the cartridge, the physical core number within package, and
 178   /// logical thread number within core.
 179   ///
 180   EFI_CPU_PHYSICAL_LOCATION  Location;
 181   ///
 182   /// The extended information of the processor. This field is filled only when
 183   /// CPU_V2_EXTENDED_TOPOLOGY is set in parameter ProcessorNumber.
 184   EXTENDED_PROCESSOR_INFORMATION ExtendedInformation;
 185 } EFI_PROCESSOR_INFORMATION;
 186
 187 /**
 188   This service retrieves the number of logical processor in the platform
 189   and the number of those logical processors that are enabled on this boot.
 190   This service may only be called from the BSP.
 191
 192   This function is used to retrieve the following information:
 193     - The number of logical processors that are present in the system.
 194     - The number of enabled logical processors in the system at the instant
 195       this call is made.
 196
 197   Because MP Service Protocol provides services to enable and disable processors
 198   dynamically, the number of enabled logical processors may vary during the
 199   course of a boot session.
 200
 201   If this service is called from an AP, then EFI_DEVICE_ERROR is returned.
 202   If NumberOfProcessors or NumberOfEnabledProcessors is NULL, then
 203   EFI_INVALID_PARAMETER is returned. Otherwise, the total number of processors
 204   is returned in NumberOfProcessors, the number of currently enabled processor
 205   is returned in NumberOfEnabledProcessors, and EFI_SUCCESS is returned.
 206
 207   @param[in]  This                        A pointer to the EFI_MP_SERVICES_PROTOCOL
 208                                           instance.
 209   @param[out] NumberOfProcessors          Pointer to the total number of logical
 210                                           processors in the system, including the BSP
 211                                           and disabled APs.
 212   @param[out] NumberOfEnabledProcessors   Pointer to the number of enabled logical
 213                                           processors that exist in system, including
 214                                           the BSP.
 215
 216   @retval EFI_SUCCESS             The number of logical processors and enabled
 217                                   logical processors was retrieved.
 218   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 219   @retval EFI_INVALID_PARAMETER   NumberOfProcessors is NULL.
 220   @retval EFI_INVALID_PARAMETER   NumberOfEnabledProcessors is NULL.
 221
 222 **/
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *EFI_MP_SERVICES_GET_NUMBER_OF_PROCESSORS)(
 226   IN  EFI_MP_SERVICES_PROTOCOL  *This,
 227   OUT UINTN                     *NumberOfProcessors,
 228   OUT UINTN                     *NumberOfEnabledProcessors
 229   );
 230
 231 /**
 232   Gets detailed MP-related information on the requested processor at the
 233   instant this call is made. This service may only be called from the BSP.
 234
 235   This service retrieves detailed MP-related information about any processor
 236   on the platform. Note the following:
 237     - The processor information may change during the course of a boot session.
 238     - The information presented here is entirely MP related.
 239
 240   Information regarding the number of caches and their sizes, frequency of operation,
 241   slot numbers is all considered platform-related information and is not provided
 242   by this service.
 243
 244   @param[in]  This                  A pointer to the EFI_MP_SERVICES_PROTOCOL
 245                                     instance.
 246   @param[in]  ProcessorNumber       The handle number of processor.
 247   @param[out] ProcessorInfoBuffer   A pointer to the buffer where information for
 248                                     the requested processor is deposited.
 249
 250   @retval EFI_SUCCESS             Processor information was returned.
 251   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 252   @retval EFI_INVALID_PARAMETER   ProcessorInfoBuffer is NULL.
 253   @retval EFI_NOT_FOUND           The processor with the handle specified by
 254                                   ProcessorNumber does not exist in the platform.
 255
 256 **/
 257 typedef
 258 EFI_STATUS
 259 (EFIAPI *EFI_MP_SERVICES_GET_PROCESSOR_INFO)(
 260   IN  EFI_MP_SERVICES_PROTOCOL   *This,
 261   IN  UINTN                      ProcessorNumber,
 262   OUT EFI_PROCESSOR_INFORMATION  *ProcessorInfoBuffer
 263   );
 264
 265 /**
 266   This service executes a caller provided function on all enabled APs. APs can
 267   run either simultaneously or one at a time in sequence. This service supports
 268   both blocking and non-blocking requests. The non-blocking requests use EFI
 269   events so the BSP can detect when the APs have finished. This service may only
 270   be called from the BSP.
 271
 272   This function is used to dispatch all the enabled APs to the function specified
 273   by Procedure.  If any enabled AP is busy, then EFI_NOT_READY is returned
 274   immediately and Procedure is not started on any AP.
 275
 276   If SingleThread is TRUE, all the enabled APs execute the function specified by
 277   Procedure one by one, in ascending order of processor handle number. Otherwise,
 278   all the enabled APs execute the function specified by Procedure simultaneously.
 279
 280   If WaitEvent is NULL, execution is in blocking mode. The BSP waits until all
 281   APs finish or TimeoutInMicroSecs expires. Otherwise, execution is in non-blocking
 282   mode, and the BSP returns from this service without waiting for APs. If a
 283   non-blocking mode is requested after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT
 284   is signaled, then EFI_UNSUPPORTED must be returned.
 285
 286   If the timeout specified by TimeoutInMicroseconds expires before all APs return
 287   from Procedure, then Procedure on the failed APs is terminated. All enabled APs
 288   are always available for further calls to EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
 289   and EFI_MP_SERVICES_PROTOCOL.StartupThisAP(). If FailedCpuList is not NULL, its
 290   content points to the list of processor handle numbers in which Procedure was
 291   terminated.
 292
 293   Note: It is the responsibility of the consumer of the EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
 294   to make sure that the nature of the code that is executed on the BSP and the
 295   dispatched APs is well controlled. The MP Services Protocol does not guarantee
 296   that the Procedure function is MP-safe. Hence, the tasks that can be run in
 297   parallel are limited to certain independent tasks and well-controlled exclusive
 298   code. EFI services and protocols may not be called by APs unless otherwise
 299   specified.
 300
 301   In blocking execution mode, BSP waits until all APs finish or
 302   TimeoutInMicroSeconds expires.
 303
 304   In non-blocking execution mode, BSP is freed to return to the caller and then
 305   proceed to the next task without having to wait for APs. The following
 306   sequence needs to occur in a non-blocking execution mode:
 307
 308     -# The caller that intends to use this MP Services Protocol in non-blocking
 309        mode creates WaitEvent by calling the EFI CreateEvent() service.  The caller
 310        invokes EFI_MP_SERVICES_PROTOCOL.StartupAllAPs(). If the parameter WaitEvent
 311        is not NULL, then StartupAllAPs() executes in non-blocking mode. It requests
 312        the function specified by Procedure to be started on all the enabled APs,
 313        and releases the BSP to continue with other tasks.
 314     -# The caller can use the CheckEvent() and WaitForEvent() services to check
 315        the state of the WaitEvent created in step 1.
 316     -# When the APs complete their task or TimeoutInMicroSecondss expires, the MP
 317        Service signals WaitEvent by calling the EFI SignalEvent() function. If
 318        FailedCpuList is not NULL, its content is available when WaitEvent is
 319        signaled. If all APs returned from Procedure prior to the timeout, then
 320        FailedCpuList is set to NULL. If not all APs return from Procedure before
 321        the timeout, then FailedCpuList is filled in with the list of the failed
 322        APs. The buffer is allocated by MP Service Protocol using AllocatePool().
 323        It is the caller's responsibility to free the buffer with FreePool() service.
 324     -# This invocation of SignalEvent() function informs the caller that invoked
 325        EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() that either all the APs completed
 326        the specified task or a timeout occurred. The contents of FailedCpuList
 327        can be examined to determine which APs did not complete the specified task
 328        prior to the timeout.
 329
 330   @param[in]  This                    A pointer to the EFI_MP_SERVICES_PROTOCOL
 331                                       instance.
 332   @param[in]  Procedure               A pointer to the function to be run on
 333                                       enabled APs of the system. See type
 334                                       EFI_AP_PROCEDURE.
 335   @param[in]  SingleThread            If TRUE, then all the enabled APs execute
 336                                       the function specified by Procedure one by
 337                                       one, in ascending order of processor handle
 338                                       number.  If FALSE, then all the enabled APs
 339                                       execute the function specified by Procedure
 340                                       simultaneously.
 341   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 342                                       service.  If it is NULL, then execute in
 343                                       blocking mode. BSP waits until all APs finish
 344                                       or TimeoutInMicroSeconds expires.  If it's
 345                                       not NULL, then execute in non-blocking mode.
 346                                       BSP requests the function specified by
 347                                       Procedure to be started on all the enabled
 348                                       APs, and go on executing immediately. If
 349                                       all return from Procedure, or TimeoutInMicroSeconds
 350                                       expires, this event is signaled. The BSP
 351                                       can use the CheckEvent() or WaitForEvent()
 352                                       services to check the state of event.  Type
 353                                       EFI_EVENT is defined in CreateEvent() in
 354                                       the Unified Extensible Firmware Interface
 355                                       Specification.
 356   @param[in]  TimeoutInMicrosecsond   Indicates the time limit in microseconds for
 357                                       APs to return from Procedure, either for
 358                                       blocking or non-blocking mode. Zero means
 359                                       infinity.  If the timeout expires before
 360                                       all APs return from Procedure, then Procedure
 361                                       on the failed APs is terminated. All enabled
 362                                       APs are available for next function assigned
 363                                       by EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
 364                                       or EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
 365                                       If the timeout expires in blocking mode,
 366                                       BSP returns EFI_TIMEOUT.  If the timeout
 367                                       expires in non-blocking mode, WaitEvent
 368                                       is signaled with SignalEvent().
 369   @param[in]  ProcedureArgument       The parameter passed into Procedure for
 370                                       all APs.
 371   @param[out] FailedCpuList           If NULL, this parameter is ignored. Otherwise,
 372                                       if all APs finish successfully, then its
 373                                       content is set to NULL. If not all APs
 374                                       finish before timeout expires, then its
 375                                       content is set to address of the buffer
 376                                       holding handle numbers of the failed APs.
 377                                       The buffer is allocated by MP Service Protocol,
 378                                       and it's the caller's responsibility to
 379                                       free the buffer with FreePool() service.
 380                                       In blocking mode, it is ready for consumption
 381                                       when the call returns. In non-blocking mode,
 382                                       it is ready when WaitEvent is signaled.  The
 383                                       list of failed CPU is terminated by
 384                                       END_OF_CPU_LIST.
 385
 386   @retval EFI_SUCCESS             In blocking mode, all APs have finished before
 387                                   the timeout expired.
 388   @retval EFI_SUCCESS             In non-blocking mode, function has been dispatched
 389                                   to all enabled APs.
 390   @retval EFI_UNSUPPORTED         A non-blocking mode request was made after the
 391                                   UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
 392                                   signaled.
 393   @retval EFI_DEVICE_ERROR        Caller processor is AP.
 394   @retval EFI_NOT_STARTED         No enabled APs exist in the system.
 395   @retval EFI_NOT_READY           Any enabled APs are busy.
 396   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before
 397                                   all enabled APs have finished.
 398   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 399
 400 **/
 401 typedef
 402 EFI_STATUS
 403 (EFIAPI *EFI_MP_SERVICES_STARTUP_ALL_APS)(
 404   IN  EFI_MP_SERVICES_PROTOCOL  *This,
 405   IN  EFI_AP_PROCEDURE          Procedure,
 406   IN  BOOLEAN                   SingleThread,
 407   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 408   IN  UINTN                     TimeoutInMicroSeconds,
 409   IN  VOID                      *ProcedureArgument      OPTIONAL,
 410   OUT UINTN                     **FailedCpuList         OPTIONAL
 411   );
 412
 413 /**
 414   This service lets the caller get one enabled AP to execute a caller-provided
 415   function. The caller can request the BSP to either wait for the completion
 416   of the AP or just proceed with the next task by using the EFI event mechanism.
 417   See EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() for more details on non-blocking
 418   execution support.  This service may only be called from the BSP.
 419
 420   This function is used to dispatch one enabled AP to the function specified by
 421   Procedure passing in the argument specified by ProcedureArgument.  If WaitEvent
 422   is NULL, execution is in blocking mode. The BSP waits until the AP finishes or
 423   TimeoutInMicroSecondss expires. Otherwise, execution is in non-blocking mode.
 424   BSP proceeds to the next task without waiting for the AP. If a non-blocking mode
 425   is requested after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT is signaled,
 426   then EFI_UNSUPPORTED must be returned.
 427
 428   If the timeout specified by TimeoutInMicroseconds expires before the AP returns
 429   from Procedure, then execution of Procedure by the AP is terminated. The AP is
 430   available for subsequent calls to EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() and
 431   EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
 432
 433   @param[in]  This                    A pointer to the EFI_MP_SERVICES_PROTOCOL
 434                                       instance.
 435   @param[in]  Procedure               A pointer to the function to be run on the
 436                                       designated AP of the system. See type
 437                                       EFI_AP_PROCEDURE.
 438   @param[in]  ProcessorNumber         The handle number of the AP. The range is
 439                                       from 0 to the total number of logical
 440                                       processors minus 1. The total number of
 441                                       logical processors can be retrieved by
 442                                       EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
 443   @param[in]  WaitEvent               The event created by the caller with CreateEvent()
 444                                       service.  If it is NULL, then execute in
 445                                       blocking mode. BSP waits until this AP finish
 446                                       or TimeoutInMicroSeconds expires.  If it's
 447                                       not NULL, then execute in non-blocking mode.
 448                                       BSP requests the function specified by
 449                                       Procedure to be started on this AP,
 450                                       and go on executing immediately. If this AP
 451                                       return from Procedure or TimeoutInMicroSeconds
 452                                       expires, this event is signaled. The BSP
 453                                       can use the CheckEvent() or WaitForEvent()
 454                                       services to check the state of event.  Type
 455                                       EFI_EVENT is defined in CreateEvent() in
 456                                       the Unified Extensible Firmware Interface
 457                                       Specification.
 458   @param[in]  TimeoutInMicrosecsond   Indicates the time limit in microseconds for
 459                                       this AP to finish this Procedure, either for
 460                                       blocking or non-blocking mode. Zero means
 461                                       infinity.  If the timeout expires before
 462                                       this AP returns from Procedure, then Procedure
 463                                       on the AP is terminated. The
 464                                       AP is available for next function assigned
 465                                       by EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
 466                                       or EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
 467                                       If the timeout expires in blocking mode,
 468                                       BSP returns EFI_TIMEOUT.  If the timeout
 469                                       expires in non-blocking mode, WaitEvent
 470                                       is signaled with SignalEvent().
 471   @param[in]  ProcedureArgument       The parameter passed into Procedure on the
 472                                       specified AP.
 473   @param[out] Finished                If NULL, this parameter is ignored.  In
 474                                       blocking mode, this parameter is ignored.
 475                                       In non-blocking mode, if AP returns from
 476                                       Procedure before the timeout expires, its
 477                                       content is set to TRUE. Otherwise, the
 478                                       value is set to FALSE. The caller can
 479                                       determine if the AP returned from Procedure
 480                                       by evaluating this value.
 481
 482   @retval EFI_SUCCESS             In blocking mode, specified AP finished before
 483                                   the timeout expires.
 484   @retval EFI_SUCCESS             In non-blocking mode, the function has been
 485                                   dispatched to specified AP.
 486   @retval EFI_UNSUPPORTED         A non-blocking mode request was made after the
 487                                   UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
 488                                   signaled.
 489   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 490   @retval EFI_TIMEOUT             In blocking mode, the timeout expired before
 491                                   the specified AP has finished.
 492   @retval EFI_NOT_READY           The specified AP is busy.
 493   @retval EFI_NOT_FOUND           The processor with the handle specified by
 494                                   ProcessorNumber does not exist.
 495   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP or disabled AP.
 496   @retval EFI_INVALID_PARAMETER   Procedure is NULL.
 497
 498 **/
 499 typedef
 500 EFI_STATUS
 501 (EFIAPI *EFI_MP_SERVICES_STARTUP_THIS_AP)(
 502   IN  EFI_MP_SERVICES_PROTOCOL  *This,
 503   IN  EFI_AP_PROCEDURE          Procedure,
 504   IN  UINTN                     ProcessorNumber,
 505   IN  EFI_EVENT                 WaitEvent               OPTIONAL,
 506   IN  UINTN                     TimeoutInMicroseconds,
 507   IN  VOID                      *ProcedureArgument      OPTIONAL,
 508   OUT BOOLEAN                   *Finished               OPTIONAL
 509   );
 510
 511 /**
 512   This service switches the requested AP to be the BSP from that point onward.
 513   This service changes the BSP for all purposes.   This call can only be performed
 514   by the current BSP.
 515
 516   This service switches the requested AP to be the BSP from that point onward.
 517   This service changes the BSP for all purposes. The new BSP can take over the
 518   execution of the old BSP and continue seamlessly from where the old one left
 519   off. This service may not be supported after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT
 520   is signaled.
 521
 522   If the BSP cannot be switched prior to the return from this service, then
 523   EFI_UNSUPPORTED must be returned.
 524
 525   @param[in] This              A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
 526   @param[in] ProcessorNumber   The handle number of AP that is to become the new
 527                                BSP. The range is from 0 to the total number of
 528                                logical processors minus 1. The total number of
 529                                logical processors can be retrieved by
 530                                EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
 531   @param[in] EnableOldBSP      If TRUE, then the old BSP will be listed as an
 532                                enabled AP. Otherwise, it will be disabled.
 533
 534   @retval EFI_SUCCESS             BSP successfully switched.
 535   @retval EFI_UNSUPPORTED         Switching the BSP cannot be completed prior to
 536                                   this service returning.
 537   @retval EFI_UNSUPPORTED         Switching the BSP is not supported.
 538   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 539   @retval EFI_NOT_FOUND           The processor with the handle specified by
 540                                   ProcessorNumber does not exist.
 541   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the current BSP or
 542                                   a disabled AP.
 543   @retval EFI_NOT_READY           The specified AP is busy.
 544
 545 **/
 546 typedef
 547 EFI_STATUS
 548 (EFIAPI *EFI_MP_SERVICES_SWITCH_BSP)(
 549   IN EFI_MP_SERVICES_PROTOCOL  *This,
 550   IN  UINTN                    ProcessorNumber,
 551   IN  BOOLEAN                  EnableOldBSP
 552   );
 553
 554 /**
 555   This service lets the caller enable or disable an AP from this point onward.
 556   This service may only be called from the BSP.
 557
 558   This service allows the caller enable or disable an AP from this point onward.
 559   The caller can optionally specify the health status of the AP by Health. If
 560   an AP is being disabled, then the state of the disabled AP is implementation
 561   dependent. If an AP is enabled, then the implementation must guarantee that a
 562   complete initialization sequence is performed on the AP, so the AP is in a state
 563   that is compatible with an MP operating system. This service may not be supported
 564   after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT is signaled.
 565
 566   If the enable or disable AP operation cannot be completed prior to the return
 567   from this service, then EFI_UNSUPPORTED must be returned.
 568
 569   @param[in] This              A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
 570   @param[in] ProcessorNumber   The handle number of AP.
 571                                The range is from 0 to the total number of
 572                                logical processors minus 1. The total number of
 573                                logical processors can be retrieved by
 574                                EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
 575   @param[in] EnableAP          Specifies the new state for the processor for
 576                                enabled, FALSE for disabled.
 577   @param[in] HealthFlag        If not NULL, a pointer to a value that specifies
 578                                the new health status of the AP. This flag
 579                                corresponds to StatusFlag defined in
 580                                EFI_MP_SERVICES_PROTOCOL.GetProcessorInfo(). Only
 581                                the PROCESSOR_HEALTH_STATUS_BIT is used. All other
 582                                bits are ignored.  If it is NULL, this parameter
 583                                is ignored.
 584
 585   @retval EFI_SUCCESS             The specified AP was enabled or disabled successfully.
 586   @retval EFI_UNSUPPORTED         Enabling or disabling an AP cannot be completed
 587                                   prior to this service returning.
 588   @retval EFI_UNSUPPORTED         Enabling or disabling an AP is not supported.
 589   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
 590   @retval EFI_NOT_FOUND           Processor with the handle specified by ProcessorNumber
 591                                   does not exist.
 592   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 593
 594 **/
 595 typedef
 596 EFI_STATUS
 597 (EFIAPI *EFI_MP_SERVICES_ENABLEDISABLEAP)(
 598   IN  EFI_MP_SERVICES_PROTOCOL  *This,
 599   IN  UINTN                     ProcessorNumber,
 600   IN  BOOLEAN                   EnableAP,
 601   IN  UINT32                    *HealthFlag OPTIONAL
 602   );
 603
 604 /**
 605   This return the handle number for the calling processor.  This service may be
 606   called from the BSP and APs.
 607
 608   This service returns the processor handle number for the calling processor.
 609   The returned value is in the range from 0 to the total number of logical
 610   processors minus 1. The total number of logical processors can be retrieved
 611   with EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors(). This service may be
 612   called from the BSP and APs. If ProcessorNumber is NULL, then EFI_INVALID_PARAMETER
 613   is returned. Otherwise, the current processors handle number is returned in
 614   ProcessorNumber, and EFI_SUCCESS is returned.
 615
 616   @param[in] This              A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
 617   @param[in] ProcessorNumber   Pointer to the handle number of AP.
 618                                The range is from 0 to the total number of
 619                                logical processors minus 1. The total number of
 620                                logical processors can be retrieved by
 621                                EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
 622
 623   @retval EFI_SUCCESS             The current processor handle number was returned
 624                                   in ProcessorNumber.
 625   @retval EFI_INVALID_PARAMETER   ProcessorNumber is NULL.
 626
 627 **/
 628 typedef
 629 EFI_STATUS
 630 (EFIAPI *EFI_MP_SERVICES_WHOAMI)(
 631   IN EFI_MP_SERVICES_PROTOCOL  *This,
 632   OUT UINTN                    *ProcessorNumber
 633   );
 634
 635 ///
 636 /// When installed, the MP Services Protocol produces a collection of services
 637 /// that are needed for MP management.
 638 ///
 639 /// Before the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled, the module
 640 /// that produces this protocol is required to place all APs into an idle state
 641 /// whenever the APs are disabled or the APs are not executing code as requested
 642 /// through the StartupAllAPs() or StartupThisAP() services. The idle state of
 643 /// an AP before the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled is
 644 /// implementation dependent.
 645 ///
 646 /// After the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled, all the APs
 647 /// must be placed in the OS compatible CPU state as defined by the UEFI
 648 /// Specification. Implementations of this protocol may use the UEFI event
 649 /// EFI_EVENT_GROUP_READY_TO_BOOT to force APs into the OS compatible state as
 650 /// defined by the UEFI Specification. Modules that use this protocol must
 651 /// guarantee that all non-blocking mode requests on all APs have been completed
 652 /// before the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled. Since the
 653 /// order that event notification functions in the same event group are executed
 654 /// is not deterministic, an event of type EFI_EVENT_GROUP_READY_TO_BOOT cannot
 655 /// be used to guarantee that APs have completed their non-blocking mode requests.
 656 ///
 657 /// When the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled, the StartAllAPs()
 658 /// and StartupThisAp() services must no longer support non-blocking mode requests.
 659 /// The support for SwitchBSP() and EnableDisableAP() may no longer be supported
 660 /// after this event is signaled. Since UEFI Applications and UEFI OS Loaders
 661 /// execute after the UEFI event EFI_EVENT_GROUP_READY_TO_BOOT is signaled, these
 662 /// UEFI images must be aware that the functionality of this protocol may be reduced.
 663 ///
 664 struct _EFI_MP_SERVICES_PROTOCOL {
 665   EFI_MP_SERVICES_GET_NUMBER_OF_PROCESSORS  GetNumberOfProcessors;
 666   EFI_MP_SERVICES_GET_PROCESSOR_INFO        GetProcessorInfo;
 667   EFI_MP_SERVICES_STARTUP_ALL_APS           StartupAllAPs;
 668   EFI_MP_SERVICES_STARTUP_THIS_AP           StartupThisAP;
 669   EFI_MP_SERVICES_SWITCH_BSP                SwitchBSP;
 670   EFI_MP_SERVICES_ENABLEDISABLEAP           EnableDisableAP;
 671   EFI_MP_SERVICES_WHOAMI                    WhoAmI;
 672 };
 673
 674 extern EFI_GUID gEfiMpServiceProtocolGuid;
 675
 676 #endif