UefiCpuPkg/PiSmmCpuDxeSmm/SmmMp.h

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