MdePkg/Include/Protocol/MmMp.h

   1 /** @file
   2   EFI MM MP Protocol is defined in the PI 1.5 specification.
   3
   4   The MM MP protocol provides a set of functions to allow execution of procedures on processors that
   5   have entered MM. This protocol has the following properties:
   6   1. The caller can only invoke execution of a procedure on a processor, other than the caller, that
   7      has also entered MM.
   8   2. It is possible to invoke a procedure on multiple processors. Supports blocking and non-blocking
   9      modes of operation.
  10
  11   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
  12   SPDX-License-Identifier: BSD-2-Clause-Patent
  13
  14 **/
  15
  16 #ifndef _MM_MP_H_
  17 #define _MM_MP_H_
  18
  19 #include <Pi/PiMmCis.h>
  20
  21 #define EFI_MM_MP_PROTOCOL_GUID \
  22   { \
  23     0x5d5450d7, 0x990c, 0x4180, {0xa8, 0x3, 0x8e, 0x63, 0xf0, 0x60, 0x83, 0x7  }  \
  24   }
  25
  26 //
  27 // Revision definition.
  28 //
  29 #define EFI_MM_MP_PROTOCOL_REVISION    0x00
  30
  31 //
  32 // Attribute flags
  33 //
  34 #define EFI_MM_MP_TIMEOUT_SUPPORTED    0x01
  35
  36 //
  37 // Completion token
  38 //
  39 typedef VOID* MM_COMPLETION;
  40
  41 typedef struct {
  42   MM_COMPLETION  Completion;
  43   EFI_STATUS     Status;
  44 } MM_DISPATCH_COMPLETION_TOKEN;
  45
  46 typedef struct _EFI_MM_MP_PROTOCOL  EFI_MM_MP_PROTOCOL;
  47
  48 /**
  49   Service to retrieves the number of logical processor in the platform.
  50
  51   @param[in]  This                The EFI_MM_MP_PROTOCOL instance.
  52   @param[out] NumberOfProcessors  Pointer to the total number of logical processors in the system,
  53                                   including the BSP and all APs.
  54
  55   @retval EFI_SUCCESS             The number of processors was retrieved successfully
  56   @retval EFI_INVALID_PARAMETER   NumberOfProcessors is NULL
  57 **/
  58 typedef
  59 EFI_STATUS
  60 (EFIAPI *EFI_MM_GET_NUMBER_OF_PROCESSORS) (
  61   IN CONST EFI_MM_MP_PROTOCOL  *This,
  62   OUT      UINTN               *NumberOfProcessors
  63 );
  64
  65
  66 /**
  67   This service allows the caller to invoke a procedure one of the application processors (AP). This
  68   function uses an optional token parameter to support blocking and non-blocking modes. If the token
  69   is passed into the call, the function will operate in a non-blocking fashion and the caller can
  70   check for completion with CheckOnProcedure or WaitForProcedure.
  71
  72   @param[in]     This                   The EFI_MM_MP_PROTOCOL instance.
  73   @param[in]     Procedure              A pointer to the procedure to be run on the designated target
  74                                         AP of the system. Type EFI_AP_PROCEDURE2 is defined below in
  75                                         related definitions.
  76   @param[in]     CpuNumber              The zero-based index of the processor number of the target
  77                                         AP, on which the code stream is supposed to run. If the number
  78                                         points to the calling processor then it will not run the
  79                                         supplied code.
  80   @param[in]     TimeoutInMicroseconds  Indicates the time limit in microseconds for this AP to
  81                                         finish execution of Procedure, either for blocking or
  82                                         non-blocking mode. Zero means infinity. If the timeout
  83                                         expires before this AP returns from Procedure, then Procedure
  84                                         on the AP is terminated. If the timeout expires in blocking
  85                                         mode, the call returns EFI_TIMEOUT. If the timeout expires
  86                                         in non-blocking mode, the timeout determined can be through
  87                                         CheckOnProcedure or WaitForProcedure.
  88                                         Note that timeout support is optional. Whether an
  89                                         implementation supports this feature, can be determined via
  90                                         the Attributes data member.
  91   @param[in,out] ProcedureArguments     Allows the caller to pass a list of parameters to the code
  92                                         that is run by the AP. It is an optional common mailbox
  93                                         between APs and the caller to share information.
  94   @param[in,out] Token                  This is parameter is broken into two components:
  95                                         1.Token->Completion is an optional parameter that allows the
  96                                         caller to execute the procedure in a blocking or non-blocking
  97                                         fashion. If it is NULL the call is blocking, and the call will
  98                                         not return until the AP has completed the procedure. If the
  99                                         token is not NULL, the call will return immediately. The caller
 100                                         can check whether the procedure has completed with
 101                                         CheckOnProcedure or WaitForProcedure.
 102                                         2.Token->Status The implementation updates the address pointed
 103                                         at by this variable with the status code returned by Procedure
 104                                         when it completes execution on the target AP, or with EFI_TIMEOUT
 105                                         if the Procedure fails to complete within the optional timeout.
 106                                         The implementation will update this variable with EFI_NOT_READY
 107                                         prior to starting Procedure on the target AP.
 108   @param[in,out] CPUStatus              This optional pointer may be used to get the status code returned
 109                                         by Procedure when it completes execution on the target AP, or with
 110                                         EFI_TIMEOUT if the Procedure fails to complete within the optional
 111                                         timeout. The implementation will update this variable with
 112                                         EFI_NOT_READY prior to starting Procedure on the target AP.
 113
 114   @retval EFI_SUCCESS                   In the blocking case, this indicates that Procedure has completed
 115                                         execution on the target AP.
 116                                         In the non-blocking case this indicates that the procedure has
 117                                         been successfully scheduled for execution on the target AP.
 118   @retval EFI_INVALID_PARAMETER         The input arguments are out of range. Either the target AP is the
 119                                         caller of the function, or the Procedure or Token is NULL
 120   @retval EFI_NOT_READY                 If the target AP is busy executing another procedure
 121   @retval EFI_ALREADY_STARTED           Token is already in use for another procedure
 122   @retval EFI_TIMEOUT                   In blocking mode, the timeout expired before the specified AP
 123                                         has finished
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *EFI_MM_DISPATCH_PROCEDURE) (
 128   IN CONST EFI_MM_MP_PROTOCOL            *This,
 129   IN       EFI_AP_PROCEDURE2             Procedure,
 130   IN       UINTN                         CpuNumber,
 131   IN       UINTN                         TimeoutInMicroseconds,
 132   IN OUT   VOID                          *ProcedureArguments OPTIONAL,
 133   IN OUT   MM_COMPLETION                 *Token,
 134   IN OUT   EFI_STATUS                    *CPUStatus
 135 );
 136
 137 /**
 138   This service allows the caller to invoke a procedure on all running application processors (AP)
 139   except the caller. This function uses an optional token parameter to support blocking and
 140   nonblocking modes. If the token is passed into the call, the function will operate in a non-blocking
 141   fashion and the caller can check for completion with CheckOnProcedure or WaitForProcedure.
 142
 143   It is not necessary for the implementation to run the procedure on every processor on the platform.
 144   Processors that are powered down in such a way that they cannot respond to interrupts, may be
 145   excluded from the broadcast.
 146
 147
 148   @param[in]     This                   The EFI_MM_MP_PROTOCOL instance.
 149   @param[in]     Procedure              A pointer to the code stream to be run on the APs that have
 150                                         entered MM. Type EFI_AP_PROCEDURE is defined below in related
 151                                         definitions.
 152   @param[in]     TimeoutInMicroseconds  Indicates the time limit in microseconds for the APs to finish
 153                                         execution of Procedure, either for blocking or non-blocking mode.
 154                                         Zero means infinity. If the timeout expires before all APs return
 155                                         from Procedure, then Procedure on the failed APs is terminated. If
 156                                         the timeout expires in blocking mode, the call returns EFI_TIMEOUT.
 157                                         If the timeout expires in non-blocking mode, the timeout determined
 158                                         can be through CheckOnProcedure or WaitForProcedure.
 159                                         Note that timeout support is optional. Whether an implementation
 160                                         supports this feature can be determined via the Attributes data
 161                                         member.
 162   @param[in,out] ProcedureArguments     Allows the caller to pass a list of parameters to the code
 163                                         that is run by the AP. It is an optional common mailbox
 164                                         between APs and the caller to share information.
 165   @param[in,out] Token                  This is parameter is broken into two components:
 166                                         1.Token->Completion is an optional parameter that allows the
 167                                         caller to execute the procedure in a blocking or non-blocking
 168                                         fashion. If it is NULL the call is blocking, and the call will
 169                                         not return until the AP has completed the procedure. If the
 170                                         token is not NULL, the call will return immediately. The caller
 171                                         can check whether the procedure has completed with
 172                                         CheckOnProcedure or WaitForProcedure.
 173                                         2.Token->Status The implementation updates the address pointed
 174                                         at by this variable with the status code returned by Procedure
 175                                         when it completes execution on the target AP, or with EFI_TIMEOUT
 176                                         if the Procedure fails to complete within the optional timeout.
 177                                         The implementation will update this variable with EFI_NOT_READY
 178                                         prior to starting Procedure on the target AP
 179   @param[in,out] CPUStatus              This optional pointer may be used to get the individual status
 180                                         returned by every AP that participated in the broadcast. This
 181                                         parameter if used provides the base address of an array to hold
 182                                         the EFI_STATUS value of each AP in the system. The size of the
 183                                         array can be ascertained by the GetNumberOfProcessors function.
 184                                         As mentioned above, the broadcast may not include every processor
 185                                         in the system. Some implementations may exclude processors that
 186                                         have been powered down in such a way that they are not responsive
 187                                         to interrupts. Additionally the broadcast excludes the processor
 188                                         which is making the BroadcastProcedure call. For every excluded
 189                                         processor, the array entry must contain a value of EFI_NOT_STARTED
 190
 191   @retval EFI_SUCCESS                   In the blocking case, this indicates that Procedure has completed
 192                                         execution on the APs. In the non-blocking case this indicates that
 193                                         the procedure has been successfully scheduled for execution on the
 194                                         APs.
 195   @retval EFI_INVALID_PARAMETER         Procedure or Token is NULL.
 196   @retval EFI_NOT_READY                 If a target AP is busy executing another procedure.
 197   @retval EFI_TIMEOUT                   In blocking mode, the timeout expired before all enabled APs have
 198                                         finished.
 199   @retval EFI_ALREADY_STARTED           Before the AP procedure associated with the Token is finished, the
 200                                         same Token cannot be used to dispatch or broadcast another procedure.
 201
 202 **/
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *EFI_MM_BROADCAST_PROCEDURE) (
 206   IN CONST EFI_MM_MP_PROTOCOL            *This,
 207   IN       EFI_AP_PROCEDURE2             Procedure,
 208   IN       UINTN                         TimeoutInMicroseconds,
 209   IN OUT   VOID                          *ProcedureArguments OPTIONAL,
 210   IN OUT   MM_COMPLETION                 *Token,
 211   IN OUT   EFI_STATUS                    *CPUStatus
 212 );
 213
 214
 215 /**
 216   This service allows the caller to set a startup procedure that will be executed when an AP powers
 217   up from a state where core configuration and context is lost. The procedure is execution has the
 218   following properties:
 219   1. The procedure executes before the processor is handed over to the operating system.
 220   2. All processors execute the same startup procedure.
 221   3. The procedure may run in parallel with other procedures invoked through the functions in this
 222   protocol, or with processors that are executing an MM handler or running in the operating system.
 223
 224
 225   @param[in]      This                 The EFI_MM_MP_PROTOCOL instance.
 226   @param[in]      Procedure            A pointer to the code stream to be run on the designated target AP
 227                                        of the system. Type EFI_AP_PROCEDURE is defined below in Volume 2
 228                                        with the related definitions of
 229                                        EFI_MP_SERVICES_PROTOCOL.StartupAllAPs.
 230                                        If caller may pass a value of NULL to deregister any existing
 231                                        startup procedure.
 232   @param[in,out]  ProcedureArguments   Allows the caller to pass a list of parameters to the code that is
 233                                        run by the AP. It is an optional common mailbox between APs and
 234                                        the caller to share information
 235
 236   @retval EFI_SUCCESS                  The Procedure has been set successfully.
 237   @retval EFI_INVALID_PARAMETER        The Procedure is NULL.
 238 **/
 239 typedef
 240 EFI_STATUS
 241 (EFIAPI *EFI_MM_SET_STARTUP_PROCEDURE) (
 242   IN CONST EFI_MM_MP_PROTOCOL *This,
 243   IN       EFI_AP_PROCEDURE   Procedure,
 244   IN OUT   VOID               *ProcedureArguments OPTIONAL
 245 );
 246
 247 /**
 248   When non-blocking execution of a procedure on an AP is invoked with DispatchProcedure,
 249   via the use of a token, this function can be used to check for completion of the procedure on the AP.
 250   The function takes the token that was passed into the DispatchProcedure call. If the procedure
 251   is complete, and therefore it is now possible to run another procedure on the same AP, this function
 252   returns EFI_SUCESS. In this case the status returned by the procedure that executed on the AP is
 253   returned in the token's Status field. If the procedure has not yet completed, then this function
 254   returns EFI_NOT_READY.
 255
 256   When a non-blocking execution of a procedure is invoked with BroadcastProcedure, via the
 257   use of a token, this function can be used to check for completion of the procedure on all the
 258   broadcast APs. The function takes the token that was passed into the BroadcastProcedure
 259   call. If the procedure is complete on all broadcast APs this function returns EFI_SUCESS. In this
 260   case the Status field in the token passed into the function reflects the overall result of the
 261   invocation, which may be EFI_SUCCESS, if all executions succeeded, or the first observed failure.
 262   If the procedure has not yet completed on the broadcast APs, the function returns
 263   EFI_NOT_READY.
 264
 265   @param[in]      This                 The EFI_MM_MP_PROTOCOL instance.
 266   @param[in]      Token                This parameter describes the token that was passed into
 267                                        DispatchProcedure or BroadcastProcedure.
 268
 269   @retval EFI_SUCCESS                  Procedure has completed.
 270   @retval EFI_NOT_READY                The Procedure has not completed.
 271   @retval EFI_INVALID_PARAMETER        Token or Token->Completion is NULL
 272   @retval EFI_NOT_FOUND                Token is not currently in use for a non-blocking call
 273
 274 **/
 275 typedef
 276 EFI_STATUS
 277 (EFIAPI *EFI_CHECK_FOR_PROCEDURE) (
 278   IN CONST EFI_MM_MP_PROTOCOL            *This,
 279   IN       MM_COMPLETION                 Token
 280 );
 281
 282 /**
 283   When a non-blocking execution of a procedure on an AP is invoked via DispatchProcedure,
 284   this function will block the caller until the remote procedure has completed on the designated AP.
 285   The non-blocking procedure invocation is identified by the Token parameter, which must match the
 286   token that used when DispatchProcedure was called. Upon completion the status returned by
 287   the procedure that executed on the AP is used to update the token's Status field.
 288
 289   When a non-blocking execution of a procedure on an AP is invoked via BroadcastProcedure
 290   this function will block the caller until the remote procedure has completed on all of the APs that
 291   entered MM. The non-blocking procedure invocation is identified by the Token parameter, which
 292   must match the token that used when BroadcastProcedure was called. Upon completion the
 293   overall status returned by the procedures that executed on the broadcast AP is used to update the
 294   token's Status field. The overall status may be EFI_SUCCESS, if all executions succeeded, or the
 295   first observed failure.
 296
 297
 298   @param[in]      This                 The EFI_MM_MP_PROTOCOL instance.
 299   @param[in]      Token                This parameter describes the token that was passed into
 300                                        DispatchProcedure or BroadcastProcedure.
 301
 302   @retval EFI_SUCCESS                  Procedure has completed.
 303   @retval EFI_INVALID_PARAMETER        Token or Token->Completion is NULL
 304   @retval EFI_NOT_FOUND                Token is not currently in use for a non-blocking call
 305
 306 **/
 307 typedef
 308 EFI_STATUS
 309 (EFIAPI *EFI_WAIT_FOR_PROCEDURE) (
 310   IN CONST EFI_MM_MP_PROTOCOL            *This,
 311   IN       MM_COMPLETION                 Token
 312 );
 313
 314
 315
 316 ///
 317 /// The MM MP protocol provides a set of functions to allow execution of procedures on processors that
 318 /// have entered MM.
 319 ///
 320 struct _EFI_MM_MP_PROTOCOL {
 321   UINT32                            Revision;
 322   UINT32                            Attributes;
 323   EFI_MM_GET_NUMBER_OF_PROCESSORS   GetNumberOfProcessors;
 324   EFI_MM_DISPATCH_PROCEDURE         DispatchProcedure;
 325   EFI_MM_BROADCAST_PROCEDURE        BroadcastProcedure;
 326   EFI_MM_SET_STARTUP_PROCEDURE      SetStartupProcedure;
 327   EFI_CHECK_FOR_PROCEDURE           CheckForProcedure;
 328   EFI_WAIT_FOR_PROCEDURE            WaitForProcedure;
 329 };
 330
 331 extern EFI_GUID gEfiMmMpProtocolGuid;
 332
 333 #endif