2 Multiple-Processor initialization Library.
4 Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef __MP_INIT_LIB_H__
16 #define __MP_INIT_LIB_H__
18 #include <Ppi/SecPlatformInformation.h>
19 #include <Protocol/MpService.h>
22 MP Initialize Library initialization.
24 This service will allocate AP reset vector and wakeup all APs to do APs
27 This service must be invoked before all other MP Initialize Library
30 @retval EFI_SUCCESS MP initialization succeeds.
31 @retval Others MP initialization fails.
41 Retrieves the number of logical processor in the platform and the number of
42 those logical processors that are enabled on this boot. This service may only
43 be called from the BSP.
45 @param[out] NumberOfProcessors Pointer to the total number of logical
46 processors in the system, including the BSP
48 @param[out] NumberOfEnabledProcessors Pointer to the number of enabled logical
49 processors that exist in system, including
52 @retval EFI_SUCCESS The number of logical processors and enabled
53 logical processors was retrieved.
54 @retval EFI_DEVICE_ERROR The calling processor is an AP.
55 @retval EFI_INVALID_PARAMETER NumberOfProcessors is NULL and NumberOfEnabledProcessors
57 @retval EFI_NOT_READY MP Initialize Library is not initialized.
62 MpInitLibGetNumberOfProcessors (
63 OUT UINTN
*NumberOfProcessors
, OPTIONAL
64 OUT UINTN
*NumberOfEnabledProcessors OPTIONAL
68 Gets detailed MP-related information on the requested processor at the
69 instant this call is made. This service may only be called from the BSP.
71 @param[in] ProcessorNumber The handle number of processor.
72 @param[out] ProcessorInfoBuffer A pointer to the buffer where information for
73 the requested processor is deposited.
74 @param[out] HealthData Return processor health data.
76 @retval EFI_SUCCESS Processor information was returned.
77 @retval EFI_DEVICE_ERROR The calling processor is an AP.
78 @retval EFI_INVALID_PARAMETER ProcessorInfoBuffer is NULL.
79 @retval EFI_NOT_FOUND The processor with the handle specified by
80 ProcessorNumber does not exist in the platform.
81 @retval EFI_NOT_READY MP Initialize Library is not initialized.
86 MpInitLibGetProcessorInfo (
87 IN UINTN ProcessorNumber
,
88 OUT EFI_PROCESSOR_INFORMATION
*ProcessorInfoBuffer
,
89 OUT EFI_HEALTH_FLAGS
*HealthData OPTIONAL
93 This service executes a caller provided function on all enabled APs.
95 @param[in] Procedure A pointer to the function to be run on
96 enabled APs of the system. See type
98 @param[in] SingleThread If TRUE, then all the enabled APs execute
99 the function specified by Procedure one by
100 one, in ascending order of processor handle
101 number. If FALSE, then all the enabled APs
102 execute the function specified by Procedure
104 @param[in] WaitEvent The event created by the caller with CreateEvent()
105 service. If it is NULL, then execute in
106 blocking mode. BSP waits until all APs finish
107 or TimeoutInMicroSeconds expires. If it's
108 not NULL, then execute in non-blocking mode.
109 BSP requests the function specified by
110 Procedure to be started on all the enabled
111 APs, and go on executing immediately. If
112 all return from Procedure, or TimeoutInMicroSeconds
113 expires, this event is signaled. The BSP
114 can use the CheckEvent() or WaitForEvent()
115 services to check the state of event. Type
116 EFI_EVENT is defined in CreateEvent() in
117 the Unified Extensible Firmware Interface
119 @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for
120 APs to return from Procedure, either for
121 blocking or non-blocking mode. Zero means
122 infinity. If the timeout expires before
123 all APs return from Procedure, then Procedure
124 on the failed APs is terminated. All enabled
125 APs are available for next function assigned
126 by MpInitLibStartupAllAPs() or
127 MPInitLibStartupThisAP().
128 If the timeout expires in blocking mode,
129 BSP returns EFI_TIMEOUT. If the timeout
130 expires in non-blocking mode, WaitEvent
131 is signaled with SignalEvent().
132 @param[in] ProcedureArgument The parameter passed into Procedure for
134 @param[out] FailedCpuList If NULL, this parameter is ignored. Otherwise,
135 if all APs finish successfully, then its
136 content is set to NULL. If not all APs
137 finish before timeout expires, then its
138 content is set to address of the buffer
139 holding handle numbers of the failed APs.
140 The buffer is allocated by MP Initialization
141 library, and it's the caller's responsibility to
142 free the buffer with FreePool() service.
143 In blocking mode, it is ready for consumption
144 when the call returns. In non-blocking mode,
145 it is ready when WaitEvent is signaled. The
146 list of failed CPU is terminated by
149 @retval EFI_SUCCESS In blocking mode, all APs have finished before
151 @retval EFI_SUCCESS In non-blocking mode, function has been dispatched
153 @retval EFI_UNSUPPORTED A non-blocking mode request was made after the
154 UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
156 @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not
158 @retval EFI_DEVICE_ERROR Caller processor is AP.
159 @retval EFI_NOT_STARTED No enabled APs exist in the system.
160 @retval EFI_NOT_READY Any enabled APs are busy.
161 @retval EFI_NOT_READY MP Initialize Library is not initialized.
162 @retval EFI_TIMEOUT In blocking mode, the timeout expired before
163 all enabled APs have finished.
164 @retval EFI_INVALID_PARAMETER Procedure is NULL.
169 MpInitLibStartupAllAPs (
170 IN EFI_AP_PROCEDURE Procedure
,
171 IN BOOLEAN SingleThread
,
172 IN EFI_EVENT WaitEvent OPTIONAL
,
173 IN UINTN TimeoutInMicroseconds
,
174 IN VOID
*ProcedureArgument OPTIONAL
,
175 OUT UINTN
**FailedCpuList OPTIONAL
179 This service lets the caller get one enabled AP to execute a caller-provided
182 @param[in] Procedure A pointer to the function to be run on the
183 designated AP of the system. See type
185 @param[in] ProcessorNumber The handle number of the AP. The range is
186 from 0 to the total number of logical
187 processors minus 1. The total number of
188 logical processors can be retrieved by
189 MpInitLibGetNumberOfProcessors().
190 @param[in] WaitEvent The event created by the caller with CreateEvent()
191 service. If it is NULL, then execute in
192 blocking mode. BSP waits until this AP finish
193 or TimeoutInMicroSeconds expires. If it's
194 not NULL, then execute in non-blocking mode.
195 BSP requests the function specified by
196 Procedure to be started on this AP,
197 and go on executing immediately. If this AP
198 return from Procedure or TimeoutInMicroSeconds
199 expires, this event is signaled. The BSP
200 can use the CheckEvent() or WaitForEvent()
201 services to check the state of event. Type
202 EFI_EVENT is defined in CreateEvent() in
203 the Unified Extensible Firmware Interface
205 @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for
206 this AP to finish this Procedure, either for
207 blocking or non-blocking mode. Zero means
208 infinity. If the timeout expires before
209 this AP returns from Procedure, then Procedure
210 on the AP is terminated. The
211 AP is available for next function assigned
212 by MpInitLibStartupAllAPs() or
213 MpInitLibStartupThisAP().
214 If the timeout expires in blocking mode,
215 BSP returns EFI_TIMEOUT. If the timeout
216 expires in non-blocking mode, WaitEvent
217 is signaled with SignalEvent().
218 @param[in] ProcedureArgument The parameter passed into Procedure on the
220 @param[out] Finished If NULL, this parameter is ignored. In
221 blocking mode, this parameter is ignored.
222 In non-blocking mode, if AP returns from
223 Procedure before the timeout expires, its
224 content is set to TRUE. Otherwise, the
225 value is set to FALSE. The caller can
226 determine if the AP returned from Procedure
227 by evaluating this value.
229 @retval EFI_SUCCESS In blocking mode, specified AP finished before
231 @retval EFI_SUCCESS In non-blocking mode, the function has been
232 dispatched to specified AP.
233 @retval EFI_UNSUPPORTED A non-blocking mode request was made after the
234 UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
236 @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not
238 @retval EFI_DEVICE_ERROR The calling processor is an AP.
239 @retval EFI_TIMEOUT In blocking mode, the timeout expired before
240 the specified AP has finished.
241 @retval EFI_NOT_READY The specified AP is busy.
242 @retval EFI_NOT_READY MP Initialize Library is not initialized.
243 @retval EFI_NOT_FOUND The processor with the handle specified by
244 ProcessorNumber does not exist.
245 @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP or disabled AP.
246 @retval EFI_INVALID_PARAMETER Procedure is NULL.
251 MpInitLibStartupThisAP (
252 IN EFI_AP_PROCEDURE Procedure
,
253 IN UINTN ProcessorNumber
,
254 IN EFI_EVENT WaitEvent OPTIONAL
,
255 IN UINTN TimeoutInMicroseconds
,
256 IN VOID
*ProcedureArgument OPTIONAL
,
257 OUT BOOLEAN
*Finished OPTIONAL
261 This service switches the requested AP to be the BSP from that point onward.
262 This service changes the BSP for all purposes. This call can only be performed
265 @param[in] ProcessorNumber The handle number of AP that is to become the new
266 BSP. The range is from 0 to the total number of
267 logical processors minus 1. The total number of
268 logical processors can be retrieved by
269 MpInitLibGetNumberOfProcessors().
270 @param[in] EnableOldBSP If TRUE, then the old BSP will be listed as an
271 enabled AP. Otherwise, it will be disabled.
273 @retval EFI_SUCCESS BSP successfully switched.
274 @retval EFI_UNSUPPORTED Switching the BSP cannot be completed prior to
275 this service returning.
276 @retval EFI_UNSUPPORTED Switching the BSP is not supported.
277 @retval EFI_DEVICE_ERROR The calling processor is an AP.
278 @retval EFI_NOT_FOUND The processor with the handle specified by
279 ProcessorNumber does not exist.
280 @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the current BSP or
282 @retval EFI_NOT_READY The specified AP is busy.
283 @retval EFI_NOT_READY MP Initialize Library is not initialized.
289 IN UINTN ProcessorNumber
,
290 IN BOOLEAN EnableOldBSP
294 This service lets the caller enable or disable an AP from this point onward.
295 This service may only be called from the BSP.
297 @param[in] ProcessorNumber The handle number of AP.
298 The range is from 0 to the total number of
299 logical processors minus 1. The total number of
300 logical processors can be retrieved by
301 MpInitLibGetNumberOfProcessors().
302 @param[in] EnableAP Specifies the new state for the processor for
303 enabled, FALSE for disabled.
304 @param[in] HealthFlag If not NULL, a pointer to a value that specifies
305 the new health status of the AP. This flag
306 corresponds to StatusFlag defined in
307 EFI_MP_SERVICES_PROTOCOL.GetProcessorInfo(). Only
308 the PROCESSOR_HEALTH_STATUS_BIT is used. All other
309 bits are ignored. If it is NULL, this parameter
312 @retval EFI_SUCCESS The specified AP was enabled or disabled successfully.
313 @retval EFI_UNSUPPORTED Enabling or disabling an AP cannot be completed
314 prior to this service returning.
315 @retval EFI_UNSUPPORTED Enabling or disabling an AP is not supported.
316 @retval EFI_DEVICE_ERROR The calling processor is an AP.
317 @retval EFI_NOT_FOUND Processor with the handle specified by ProcessorNumber
319 @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP.
320 @retval EFI_NOT_READY MP Initialize Library is not initialized.
325 MpInitLibEnableDisableAP (
326 IN UINTN ProcessorNumber
,
328 IN UINT32
*HealthFlag OPTIONAL
332 This return the handle number for the calling processor. This service may be
333 called from the BSP and APs.
335 @param[out] ProcessorNumber Pointer to the handle number of AP.
336 The range is from 0 to the total number of
337 logical processors minus 1. The total number of
338 logical processors can be retrieved by
339 MpInitLibGetNumberOfProcessors().
341 @retval EFI_SUCCESS The current processor handle number was returned
343 @retval EFI_INVALID_PARAMETER ProcessorNumber is NULL.
344 @retval EFI_NOT_READY MP Initialize Library is not initialized.
350 OUT UINTN
*ProcessorNumber