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