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