IntelFrameworkPkg/Include/Protocol/FrameworkMpService.h

   1 /** @file
   2   When installed, the Framework MP Services Protocol produces a collection of
   3   services that are needed for MP management, such as initialization and management
   4   of application processors.
   5
   6   @par Note:
   7     This protocol has been deprecated and has been replaced by the MP Services
   8     Protocol from the UEFI Platform Initialization Specification 1.2, Volume 2:
   9     Driver Execution Environment Core Interface.
  10
  11   The MP Services Protocol provides a generalized way of performing following tasks:
  12     - Retrieving information of multi-processor environment and MP-related status of
  13       specific processors.
  14     - Dispatching user-provided function to APs.
  15     - Maintain MP-related processor status.
  16
  17   The MP Services Protocol must be produced on any system with more than one logical
  18   processor.
  19
  20   The Protocol is available only during boot time.
  21
  22   MP Services Protocol is hardware-independent. Most of the logic of this protocol
  23   is architecturally neutral. It abstracts the multi-processor environment and
  24   status of processors, and provides interfaces to retrieve information, maintain,
  25   and dispatch.
  26
  27   MP Services Protocol may be consumed by ACPI module. The ACPI module may use this
  28   protocol to retrieve data that are needed for an MP platform and report them to OS.
  29   MP Services Protocol may also be used to program and configure processors, such
  30   as MTRR synchronization for memory space attributes setting in DXE Services.
  31   MP Services Protocol may be used by non-CPU DXE drivers to speed up platform boot
  32   by taking advantage of the processing capabilities of the APs, for example, using
  33   APs to help test system memory in parallel with other device initialization.
  34   Diagnostics applications may also use this protocol for multi-processor.
  35
  36   Copyright (c) 1999 - 2002, 2009, Intel Corporation.<BR>
  37   All rights reserved. This program and the accompanying materials
  38   are licensed and made available under the terms and conditions of the BSD License
  39   which accompanies this distribution.  The full text of the license may be found at<BR>
  40   http://opensource.org/licenses/bsd-license.php
  41
  42   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  43   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  44
  45 --*/
  46
  47 #ifndef _FRAMEWORK_MP_SERVICE_PROTOCOL_H_
  48 #define _FRAMEWORK_MP_SERVICE_PROTOCOL_H_
  49
  50 ///
  51 /// Global ID for the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
  52 ///
  53 #define FRAMEWORK_EFI_MP_SERVICES_PROTOCOL_GUID \
  54   { \
  55     0xf33261e7, 0x23cb, 0x11d5, {0xbd, 0x5c, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81} \
  56   }
  57
  58 ///
  59 /// Forward declaration for the EFI_MP_SERVICES_PROTOCOL
  60 ///
  61 typedef struct _FRAMEWORK_EFI_MP_SERVICES_PROTOCOL FRAMEWORK_EFI_MP_SERVICES_PROTOCOL;
  62
  63 ///
  64 /// Fixed delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  65 ///
  66 #define DELIVERY_MODE_FIXED           0x0
  67
  68 ///
  69 /// Lowest priority delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  70 ///
  71 #define DELIVERY_MODE_LOWEST_PRIORITY 0x1
  72
  73 ///
  74 /// SMI delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  75 ///
  76 #define DELIVERY_MODE_SMI             0x2
  77
  78 ///
  79 /// Remote read delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  80 ///
  81 #define DELIVERY_MODE_REMOTE_READ     0x3
  82
  83 ///
  84 /// NMI delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  85 ///
  86 #define DELIVERY_MODE_NMI             0x4
  87
  88 ///
  89 /// INIT delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  90 ///
  91 #define DELIVERY_MODE_INIT            0x5
  92
  93 ///
  94 /// Startup IPI delivery mode that may be used as the DeliveryMode parameter in SendIpi()
  95 ///
  96 #define DELIVERY_MODE_SIPI            0x6
  97
  98 ///
  99 /// The DeliveryMode parameter in SendIpi() bust be less than this maximum value
 100 ///
 101 #define DELIVERY_MODE_MAX             0x7
 102
 103 ///
 104 /// IPF specific value for the state field of the Self Test State Parameter
 105 ///
 106 #define EFI_MP_HEALTH_FLAGS_STATUS_HEALTHY                  0x0
 107
 108 ///
 109 /// IPF specific value for the state field of the Self Test State Parameter
 110 ///
 111 #define EFI_MP_HEALTH_FLAGS_STATUS_PERFORMANCE_RESTRICTED   0x1
 112
 113 ///
 114 /// IPF specific value for the state field of the Self Test State Parameter
 115 ///
 116 #define EFI_MP_HEALTH_FLAGS_STATUS_FUNCTIONALLY_RESTRICTED  0x2
 117
 118 typedef union {
 119   ///
 120   /// Bitfield structure for the IPF Self Test State Parameter
 121   ///
 122   struct {
 123     UINT32  Status:2;
 124     UINT32  Tested:1;
 125     UINT32  Reserved1:13;
 126     UINT32  VirtualMemoryUnavailable:1;
 127     UINT32  Ia32ExecutionUnavailable:1;
 128     UINT32  FloatingPointUnavailable:1;
 129     UINT32  MiscFeaturesUnavailable:1;
 130     UINT32  Reserved2:12;
 131   } Bits;
 132   ///
 133   /// IA32 and X64 BIST data of the processor
 134   ///
 135   UINT32  Uint32;
 136 } EFI_MP_HEALTH_FLAGS;
 137
 138 typedef struct {
 139   ///
 140   /// @par IA32, X64:
 141   ///   BIST (built-in self test) data of the processor.
 142   ///
 143   /// @par IPF:
 144   ///   Lower 32 bits of self test state parameter. For definition of self test
 145   ///   state parameter, please refer to Intel(R) Itanium(R) Architecture Software
 146   ///   Developer's Manual, Volume 2: System Architecture.
 147   ///
 148   EFI_MP_HEALTH_FLAGS  Flags;
 149   ///
 150   /// @par IA32, X64:
 151   ///   Not used.
 152   ///
 153   /// @par IPF:
 154   ///   Higher 32 bits of self test state parameter.
 155   ///
 156   UINT32               TestStatus;
 157 } EFI_MP_HEALTH;
 158
 159 typedef enum {
 160   EfiCpuAP                = 0,  ///< The CPU is an AP (Application Processor)
 161   EfiCpuBSP,                    ///< The CPU is the BSP (Boot-Strap Processor)
 162   EfiCpuDesignationMaximum
 163 } EFI_CPU_DESIGNATION;
 164
 165 typedef struct {
 166   ///
 167   /// @par IA32, X64:
 168   ///   The lower 8 bits contains local APIC ID, and higher bits are reserved.
 169   ///
 170   /// @par IPF:
 171   ///   The lower 16 bits contains id/eid as physical address of local SAPIC
 172   ///   unit, and higher bits are reserved.
 173   ///
 174   UINT32               ApicID;
 175   ///
 176   /// This field indicates whether the processor is enabled.  If the value is
 177   /// TRUE, then the processor is enabled. Otherwise, it is disabled.
 178   ///
 179   BOOLEAN              Enabled;
 180   ///
 181   /// This field indicates whether the processor is playing the role of BSP.
 182   /// If the value is EfiCpuAP, then the processor is AP. If the value is
 183   /// EfiCpuBSP, then the processor is BSP.
 184   ///
 185   EFI_CPU_DESIGNATION  Designation;
 186   ///
 187   /// @par IA32, X64:
 188   ///   The Flags field of this EFI_MP_HEALTH data structure holds BIST (built-in
 189   ///   self test) data of the processor. The TestStatus field is not used, and
 190   ///   the value is always zero.
 191   ///
 192   /// @par IPF:
 193   ///   Bit format of this field is the same as the definition of self-test state
 194   ///   parameter, in Intel?Itanium?Architecture Software Developer\92s Manual,
 195   ///   Volume 2: System Architecture.
 196   ///
 197   EFI_MP_HEALTH        Health;
 198   ///
 199   /// Zero-based physical package number that identifies the cartridge of the
 200   /// processor.
 201   ///
 202   UINTN                PackageNumber;
 203   ///
 204   /// Zero-based physical core number within package of the processor.
 205   ///
 206   UINTN                NumberOfCores;
 207   ///
 208   /// Zero-based logical thread number within core of the processor.
 209   ///
 210   UINTN                NumberOfThreads;
 211   ///
 212   /// This field is reserved.
 213   ///
 214   UINT64               ProcessorPALCompatibilityFlags;
 215   ///
 216   /// @par IA32, X64:
 217   ///   This field is not used, and the value is always zero.
 218   ///
 219   /// @par IPF:
 220   ///   This field is a mask number that is handed off by the PAL about which
 221   ///   processor tests are performed and which are masked.
 222   ///
 223   UINT64               ProcessorTestMask;
 224 } EFI_MP_PROC_CONTEXT;
 225
 226 /**
 227   This service retrieves general information of multiprocessors in the system.
 228
 229   This function is used to get the following information:
 230     - Number of logical processors in system
 231     - Maximal number of logical processors supported by system
 232     - Number of enabled logical processors.
 233     - Rendezvous interrupt number (IPF-specific)
 234     - Length of the rendezvous procedure.
 235
 236   @param[in]  This                   Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 237                                      instance.
 238   @param[out] NumberOfCPUs           Pointer to the total number of logical processors
 239                                      in the system, including the BSP and disabled
 240                                      APs.  If NULL, this parameter is ignored.
 241   @param[out] MaximumNumberOfCPUs    Pointer to the maximum number of processors
 242                                      supported by the system.  If NULL, this
 243                                      parameter is ignored.
 244   @param[out] NumberOfEnabledCPUs    Pointer to the number of enabled logical
 245                                      processors that exist in system, including
 246                                      the BSP.  If NULL, this parameter is ignored.
 247   @param[out] RendezvousIntNumber    This parameter is only meaningful for IPF.
 248                                      - IA32, X64: The returned value is zero.
 249                                      If NULL, this parameter is ignored.
 250                                      - IPF: Pointer to the rendezvous interrupt
 251                                      number that is used for AP wake-up.
 252   @param[out] RendezvousProcLength   Pointer to the length of rendezvous procedure.
 253                                      - IA32, X64: The returned value is 0x1000.
 254                                      If NULL, this parameter is ignored.
 255                                      - IPF: The returned value is zero.
 256
 257   @retval EFI_SUCCESS   Multiprocessor general information successfully retrieved.
 258
 259 **/
 260 typedef
 261 EFI_STATUS
 262 (EFIAPI *EFI_MP_SERVICES_GET_GENERAL_MP_INFO)(
 263   IN  FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 264   OUT UINTN                               *NumberOfCPUs          OPTIONAL,
 265   OUT UINTN                               *MaximumNumberOfCPUs   OPTIONAL,
 266   OUT UINTN                               *NumberOfEnabledCPUs   OPTIONAL,
 267   OUT UINTN                               *RendezvousIntNumber   OPTIONAL,
 268   OUT UINTN                               *RendezvousProcLength  OPTIONAL
 269   );
 270
 271 /**
 272   This service gets detailed MP-related information of the requested processor.
 273
 274   This service gets detailed MP-related information of the requested processor
 275   at the instant this call is made. Note the following:
 276     - The processor information may change during the course of a boot session.
 277     - The data of information presented here is entirely MP related.
 278   Information regarding the number of caches and their sizes, frequency of operation,
 279   slot numbers is all considered platform-related information and will not be
 280   presented here.
 281
 282   @param[in]  This                     Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 283                                        instance.
 284   @param[in]  ProcessorNumber          The handle number of the processor. The range
 285                                        is from 0 to the total number of logical
 286                                        processors minus 1. The total number of
 287                                        logical processors can be retrieved by
 288                                        GetGeneralMPInfo().
 289   @param[in,out] BufferLength          On input, pointer to the size in bytes of
 290                                        ProcessorContextBuffer.  On output, if the
 291                                        size of ProcessorContextBuffer is not large
 292                                        enough, the value pointed by this parameter
 293                                        is updated to size in bytes that is needed.
 294                                        If the size of ProcessorContextBuffer is
 295                                        sufficient, the value is not changed from
 296                                        input.
 297   @param[out] ProcessorContextBuffer   Pointer to the buffer where the data of
 298                                        requested processor will be deposited.
 299                                        The buffer is allocated by caller.
 300
 301   @retval EFI_SUCCESS             Processor information successfully returned.
 302   @retval EFI_BUFFER_TOO_SMALL    The size of ProcessorContextBuffer is too small.
 303                                   Value pointed by BufferLength has been updated
 304                                   to size in bytes that is needed.
 305   @retval EFI_INVALID_PARAMETER   IA32, X64:BufferLength is NULL.
 306   @retval EFI_INVALID_PARAMETER   IA32, X64:ProcessorContextBuffer is NULL.
 307   @retval EFI_INVALID_PARAMETER   IA32, X64:Processor with the handle specified by
 308                                   ProcessorNumber does not exist
 309   @retval EFI_NOT_FOUND           IPF: Processor with the handle specified by
 310                                   ProcessorNumber does not exist
 311
 312 **/
 313 typedef
 314 EFI_STATUS
 315 (EFIAPI *EFI_MP_SERVICES_GET_PROCESSOR_CONTEXT)(
 316   IN     FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 317   IN     UINTN                               ProcessorNumber,
 318   IN OUT UINTN                               *BufferLength,
 319   OUT    EFI_MP_PROC_CONTEXT                 *ProcessorContextBuffer
 320   );
 321
 322 /**
 323   This function is used to dispatch all enabled APs to the function specified
 324   by Procedure. APs can run either simultaneously or one by one. The caller can
 325   also configure the BSP to either wait for APs or just proceed with the next
 326   task.  It is the responsibility of the caller of the StartupAllAPs() to make
 327   sure that the nature of the code that will be run on the BSP and the dispatched
 328   APs is well controlled. The MP Services Protocol does not guarantee that the
 329   function that either processor is executing is MP-safe. Hence, the tasks that
 330   can be run in parallel are limited to certain independent tasks and well-
 331   controlled exclusive code. EFI services and protocols may not be called by APs
 332   unless otherwise specified.
 333
 334   @param[in]  This                    Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 335                                       instance.
 336   @param[in]  Procedure               A pointer to the function to be run on enabled
 337                                       APs of the system.
 338   @param[in]  SingleThread            Flag that requests APs to execute one at a
 339                                       time or simultaneously.
 340                                       - IA32, X64:
 341                                       If TRUE, then all the enabled APs execute
 342                                       the function specified by Procedure one by
 343                                       one, in ascending order of processor handle
 344                                       number.  If FALSE, then all the enabled APs
 345                                       execute the function specified by Procedure
 346                                       simultaneously.
 347                                       - IPF:
 348                                       If TRUE, then all the enabled APs execute
 349                                       the function specified by Procedure simultaneously.
 350                                       If FALSE, then all the enabled APs execute the
 351                                       function specified by Procedure one by one, in
 352                                       ascending order of processor handle number. The
 353                                       time interval of AP dispatching is determined
 354                                       by WaitEvent and TimeoutInMicrosecs.
 355   @param[in]  WaitEvent               Event to signal when APs have finished.
 356                                       - IA32, X64:
 357                                       If not NULL, when all APs finish after timeout
 358                                       expires, the event will be signaled.  If NULL,
 359                                       the parameter is ignored.
 360                                       - IPF:
 361                                       If SingleThread is TRUE, this parameter
 362                                       is ignored.  If SingleThread is FALSE (i.e.
 363                                       dispatch APs one by one), this parameter
 364                                       determines whether the BSP waits after each
 365                                       AP is dispatched. If it is NULL, the BSP
 366                                       does not wait after each AP is dispatched.
 367                                       If it is not NULL, the BSP waits after each
 368                                       AP is dispatched, and the time interval is
 369                                       determined by TimeoutInMicrosecs.  Type
 370                                       EFI_EVENT is defined in CreateEvent() in
 371                                       the Unified Extensible Firmware Interface
 372                                       Specification.
 373   @param[in]  TimeoutInMicrosecsond   Time to wait for APs to finish.
 374                                       - IA32, X64:
 375                                       If the value is zero, it means no timeout
 376                                       limit. The BSP waits until all APs finish.
 377                                       If the value is not zero, the BSP waits
 378                                       until all APs finish or timeout expires.
 379                                       If timeout expires, EFI_TIMEOUT is returned,
 380                                       and the BSP will then check APs?status
 381                                       periodically, with time interval of 16
 382                                       microseconds.
 383                                       - IPF:
 384                                       If SingleThread is TRUE and FailedCPUList
 385                                       is NULL, this parameter is ignored.  If
 386                                       SingleThread is TRUE and FailedCPUList is
 387                                       not NULL, this parameter determines whether
 388                                       the BSP waits until all APs finish their
 389                                       procedure. If it is zero, the BSP does not
 390                                       wait for APs. If it is non-zero, it waits
 391                                       until all APs finish.  If SingleThread is
 392                                       FALSE and WaitEvent is NULL, this parameter
 393                                       is ignored.  If SingleThread is FALSE and
 394                                       WaitEvent is not NULL, the BSP waits after
 395                                       each AP is dispatched and this value
 396                                       determines time interval. If the value is
 397                                       zero, the length of time interval is 10ms.
 398                                       If the value is non-zero, the BSP waits
 399                                       until dispatched AP finishes and then
 400                                       dispatch the next.
 401   @param[in]  ProcedureArgument       Pointer to the optional parameter of the
 402                                       function specified by Procedure.
 403   @param[out] FailedCPUList           List of APs that did not finish.
 404                                       - IA32, X64:
 405                                       If not NULL, it records handle numbers of
 406                                       all logical processors that fail to accept
 407                                       caller-provided function (busy or disabled).
 408                                       If NULL, this parameter is ignored.
 409                                       - IPF:
 410                                       If not NULL, it records status of all
 411                                       logical processors, with processor handle
 412                                       number as index. If a logical processor
 413                                       fails to accept caller-provided function
 414                                       because it is busy, the status is EFI_NOT_READY.
 415                                       If it fails to accept function due to other
 416                                       reasons, the status is EFI_NOT_AVAILABLE_YET.
 417                                       If timeout expires, the status is EFI_TIMEOUT.
 418                                       Otherwise, the value is EFI_SUCCESS.  If NULL,
 419                                       this parameter is ignored.
 420
 421   @retval EFI_SUCCESS               IA32, X64: All dispatched APs have finished
 422                                   before the timeout expires.
 423   @retval EFI_SUCCESS               IA32, X64: Only 1 logical processor exists
 424                                   in system.
 425   @retval EFI_INVALID_PARAMETER   IA32, X64: Procedure is NULL.
 426   @retval EFI_TIMEOUT               IA32, X64: The timeout expires before all
 427                                   dispatched APs have finished.
 428   @retval EFI_SUCCESS               IPF: This function always returns EFI_SUCCESS.
 429
 430 **/
 431 typedef
 432 EFI_STATUS
 433 (EFIAPI *FRAMEWORK_EFI_MP_SERVICES_STARTUP_ALL_APS)(
 434   IN  FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 435   IN  FRAMEWORK_EFI_AP_PROCEDURE          Procedure,
 436   IN  BOOLEAN                             SingleThread,
 437   IN  EFI_EVENT                           WaitEvent           OPTIONAL,
 438   IN  UINTN                               TimeoutInMicroSecs,
 439   IN  VOID                                *ProcArguments      OPTIONAL,
 440   OUT UINTN                               *FailedCPUList      OPTIONAL
 441   );
 442
 443 /**
 444   This function is used to dispatch one enabled AP to the function provided by
 445   the caller. The caller can request the BSP to either wait for the AP or just
 446   proceed with the next task.
 447
 448   @param[in] This                    Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 449                                      instance.
 450   @param[in] Procedure               A pointer to the function to be run on the
 451                                      designated AP.
 452   @param[in] ProcessorNumber         The handle number of AP. The range is from
 453                                      0 to the total number of logical processors
 454                                      minus 1.  The total number of logical
 455                                      processors can be retrieved by GetGeneralMPInfo().
 456   @param[in] WaitEvent               Event to signal when APs have finished.
 457                                      - IA32, X64:
 458                                      If not NULL, when the AP finishes after timeout
 459                                      expires, the event will be signaled.  If NULL,
 460                                      the parameter is ignored.
 461                                      - IPF:
 462                                      This parameter determines whether the BSP
 463                                      waits after the AP is dispatched. If it is
 464                                      NULL, the BSP does not wait after the AP
 465                                      is dispatched. If it is not NULL, the BSP
 466                                      waits after the AP is dispatched, and the
 467                                      time interval is determined by TimeoutInMicrosecs.
 468                                      Type EFI_EVENT is defined in CreateEvent()
 469                                      in the Unified Extensible Firmware Interface
 470                                      Specification.
 471   @param[in] TimeoutInMicrosecsond   Time to wait for APs to finish.
 472                                      - IA32, X64:
 473                                      If the value is zero, it means no timeout
 474                                      limit. The BSP waits until the AP finishes.
 475                                      If the value is not zero, the BSP waits until
 476                                      the AP finishes or timeout expires. If timeout
 477                                      expires, EFI_TIMEOUT is returned, and the
 478                                      BSP will then check the AP\92s status periodically,
 479                                      with time interval of 16 microseconds.
 480                                      - IPF:
 481                                      If WaitEvent is NULL, this parameter is ignored.
 482                                      If WaitEvent is not NULL, the BSP waits after
 483                                      the AP is dispatched and this value determines
 484                                      time interval. If the value is zero, the length
 485                                      of time interval is 10ms. If the value is
 486                                      non-zero, the BSP waits until the AP finishes.
 487   @param[in] ProcedureArgument       Pointer to the optional parameter of the
 488                                      function specified by Procedure.
 489
 490   @retval EFI_SUCCESS             Specified AP has finished before the timeout
 491                                   expires.
 492   @retval EFI_TIMEOUT             The timeout expires before specified AP has
 493                                   finished.
 494   @retval EFI_INVALID_PARAMETER   IA32, X64: Processor with the handle specified
 495                                   by ProcessorNumber does not exist.
 496   @retval EFI_INVALID_PARAMETER   IA32, X64: Specified AP is busy or disabled.
 497   @retval EFI_INVALID_PARAMETER   IA32, X64: Procedure is NULL.
 498   @retval EFI_INVALID_PARAMETER   IA32, X64: ProcessorNumber specifies the BSP
 499   @retval EFI_NOT_READY           IPF: Specified AP is busy
 500   @retval EFI_NOT_AVAILABLE_YET   IPF: ProcessorNumber specifies the BSP
 501   @retval EFI_NOT_AVAILABLE_YET   IPF: Specified AP is disabled.
 502   @retval EFI_NOT_AVAILABLE_YET   IPF: Specified AP is unhealthy or untested.
 503
 504 **/
 505 typedef
 506 EFI_STATUS
 507 (EFIAPI *FRAMEWORK_EFI_MP_SERVICES_STARTUP_THIS_AP)(
 508   IN FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 509   IN FRAMEWORK_EFI_AP_PROCEDURE          Procedure,
 510   IN UINTN                               ProcessorNumber,
 511   IN EFI_EVENT                           WaitEvent            OPTIONAL,
 512   IN UINTN                               TimeoutInMicroSecs,
 513   IN OUT VOID                            *ProcArguments       OPTIONAL
 514   );
 515
 516 /**
 517   This service switches the requested AP to be the BSP from that point onward.
 518   The new BSP can take over the execution of the old BSP and continue seamlessly
 519   from where the old one left off.  This call can only be performed by the
 520   current BSP.
 521
 522   @param[in] This              Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 523                                instance.
 524   @param[in] ProcessorNumber   The handle number of AP. The range is from 0 to
 525                                the total number of logical processors minus 1.
 526                                The total number of logical processors can be
 527                                retrieved by GetGeneralMPInfo().
 528   @param[in] EnableOldBSP      If TRUE, then the old BSP will be listed as an
 529                                enabled AP. Otherwise, it will be disabled.
 530
 531   @retval EFI_SUCCESS             BSP successfully switched.
 532   @retval EFI_INVALID_PARAMETER   Processor with the handle specified by
 533                                   ProcessorNumber does not exist.
 534   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 535   @retval EFI_NOT_READY           IA32, X64: Specified AP is busy or disabled.
 536   @retval EFI_INVALID_PARAMETER   IPF: Specified AP is disabled.
 537   @retval EFI_INVALID_PARAMETER   IPF: Specified AP is unhealthy or untested.
 538   @retval EFI_NOT_READY           IPF: Specified AP is busy.
 539
 540 **/
 541 typedef
 542 EFI_STATUS
 543 (EFIAPI *FRAMEWORK_EFI_MP_SERVICES_SWITCH_BSP)(
 544   IN FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 545   IN UINTN                               ProcessorNumber,
 546   IN BOOLEAN                             EnableOldBSP
 547   );
 548
 549 /**
 550   This service sends an IPI to a specified AP. Caller can specify vector number
 551   and delivery mode of the interrupt.
 552
 553   @param[in] This              Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 554                                instance.
 555   @param[in] ProcessorNumber   The handle number of AP. The range is from 0 to
 556                                the total number of logical processors minus 1.
 557                                The total number of logical processors can be
 558                                retrieved by GetGeneralMPInfo().
 559   @param[in] VectorNumber      Vector number of the interrupt.
 560   @param[in] DeliveryMode      Delivery mode of the interrupt.
 561
 562   @retval EFI_SUCCESS             IPI is successfully sent.
 563   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 564   @retval EFI_INVALID_PARAMETER   IA32, X64: Processor with the handle specified
 565                                   by ProcessorNumber does not exist.
 566   @retval EFI_INVALID_PARAMETER   IA32, X64: VectorNumber is greater than 255.
 567   @retval EFI_INVALID_PARAMETER   IA32, X64: DeliveryMode is greater than or equal
 568                                   to DELIVERY_MODE_MAX.
 569   @retval EFI_NOT_READY           IA32, X64: IPI is not accepted by the target
 570                                   processor within 10 microseconds.
 571   @retval EFI_INVALID_PARAMETER   IPF: Specified AP is disabled.
 572   @retval EFI_INVALID_PARAMETER   IPF: Specified AP is unhealthy or untested.
 573   @retval EFI_NOT_READY           IPF: Specified AP is busy.
 574
 575 **/
 576 typedef
 577 EFI_STATUS
 578 (EFIAPI *EFI_MP_SERVICES_SEND_IPI)(
 579   IN FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 580   IN UINTN                               ProcessorNumber,
 581   IN UINTN                               VectorNumber,
 582   IN UINTN                               DeliveryMode
 583   );
 584
 585 /**
 586   This service lets the caller enable or disable an AP.  The caller can optionally
 587   specify the health status of the AP by Health. It is usually used to update the
 588   health status of the processor after some processor test.
 589
 590   @param[in] This              Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 591                                instance.
 592   @param[in] ProcessorNumber   The handle number of AP. The range is from 0 to
 593                                the total number of logical processors minus 1.
 594                                The total number of logical processors can be
 595                                retrieved by GetGeneralMPInfo().
 596   @param[in] NewAPState        Indicates whether the new, desired state of the
 597                                AP is enabled or disabled. TRUE for enabling,
 598                                FALSE otherwise.
 599   @param[in] HealthState       If not NULL, it points to the value that specifies
 600                                the new health status of the AP.  If it is NULL,
 601                                this parameter is ignored.
 602
 603   @retval EFI_SUCCESS             AP successfully enabled or disabled.
 604   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the BSP.
 605   @retval EFI_INVALID_PARAMETER   IA32, X64: Processor with the handle specified
 606                                   by ProcessorNumber does not exist.
 607   @retval EFI_INVALID_PARAMETER   IPF: If an unhealthy or untested AP is to be
 608                                   enabled.
 609
 610 **/
 611 typedef
 612 EFI_STATUS
 613 (EFIAPI *FRAMEWORK_EFI_MP_SERVICES_ENABLEDISABLEAP)(
 614   IN FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 615   IN UINTN                               ProcessorNumber,
 616   IN BOOLEAN                             NewAPState,
 617   IN EFI_MP_HEALTH                       *HealthState  OPTIONAL
 618   );
 619
 620 /**
 621   This service lets the caller processor get its handle number, with which any
 622   processor in the system can be uniquely identified. The range is from 0 to the
 623   total number of logical processors minus 1. The total number of logical
 624   processors can be retrieved by GetGeneralMPInfo(). This service may be called
 625   from the BSP and APs.
 626
 627   @param[in]  This              Pointer to the FRAMEWORK_EFI_MP_SERVICES_PROTOCOL
 628                                 instance.
 629   @param[out] ProcessorNumber   A pointer to the handle number of AP. The range is
 630                                 from 0 to the total number of logical processors
 631                                 minus 1. The total number of logical processors
 632                                 can be retrieved by GetGeneralMPInfo().
 633
 634 @retval EFI_SUCCESS   This function always returns EFI_SUCCESS.
 635
 636 **/
 637 typedef
 638 EFI_STATUS
 639 (EFIAPI *FRAMEWORK_EFI_MP_SERVICES_WHOAMI)(
 640   IN  FRAMEWORK_EFI_MP_SERVICES_PROTOCOL  *This,
 641   OUT UINTN                               *ProcessorNumber
 642   );
 643
 644 ///
 645 /// Framework MP Services Protocol structure
 646 ///
 647 typedef struct _FRAMEWORK_EFI_MP_SERVICES_PROTOCOL {
 648   EFI_MP_SERVICES_GET_GENERAL_MP_INFO              GetGeneralMPInfo;
 649   EFI_MP_SERVICES_GET_PROCESSOR_CONTEXT            GetProcessorContext;
 650   FRAMEWORK_EFI_MP_SERVICES_STARTUP_ALL_APS        StartupAllAPs;
 651   FRAMEWORK_EFI_MP_SERVICES_STARTUP_THIS_AP        StartupThisAP;
 652   FRAMEWORK_EFI_MP_SERVICES_SWITCH_BSP             SwitchBSP;
 653   EFI_MP_SERVICES_SEND_IPI                         SendIPI;
 654   FRAMEWORK_EFI_MP_SERVICES_ENABLEDISABLEAP        EnableDisableAP;
 655   FRAMEWORK_EFI_MP_SERVICES_WHOAMI                 WhoAmI;
 656 };
 657
 658 extern EFI_GUID gFrameworkEfiMpServiceProtocolGuid;
 659
 660 #endif