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