SmmMp.h 18 KB

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