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