1 /** @file 2 Multiple-Processor initialization Library. 3 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 9 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. 12 13 **/ 14 15 #ifndef __MP_INIT_LIB_H__ 16 #define __MP_INIT_LIB_H__ 17 18 #include <Ppi/SecPlatformInformation.h> 19 #include <Protocol/MpService.h> 20 21 /** 22 MP Initialize Library initialization. 23 24 This service will allocate AP reset vector and wakeup all APs to do APs 25 initialization. 26 27 This service must be invoked before all other MP Initialize Library 28 service are invoked. 29 30 @retval EFI_SUCCESS MP initialization succeeds. 31 @retval Others MP initialization fails. 32 33 **/ 34 EFI_STATUS 35 EFIAPI 36 MpInitLibInitialize ( 37 VOID 38 ); 39 40 /** 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. 44 45 @param[out] NumberOfProcessors Pointer to the total number of logical 46 processors in the system, including the BSP 47 and disabled APs. 48 @param[out] NumberOfEnabledProcessors Pointer to the number of enabled logical 49 processors that exist in system, including 50 the BSP. 51 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 56 is NULL. 57 @retval EFI_NOT_READY MP Initialize Library is not initialized. 58 59 **/ 60 EFI_STATUS 61 EFIAPI 62 MpInitLibGetNumberOfProcessors ( 63 OUT UINTN *NumberOfProcessors, OPTIONAL 64 OUT UINTN *NumberOfEnabledProcessors OPTIONAL 65 ); 66 67 /** 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. 70 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. 75 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. 82 83 **/ 84 EFI_STATUS 85 EFIAPI 86 MpInitLibGetProcessorInfo ( 87 IN UINTN ProcessorNumber, 88 OUT EFI_PROCESSOR_INFORMATION *ProcessorInfoBuffer, 89 OUT EFI_HEALTH_FLAGS *HealthData OPTIONAL 90 ); 91 92 /** 93 This service executes a caller provided function on all enabled APs. 94 95 @param[in] Procedure A pointer to the function to be run on 96 enabled APs of the system. See type 97 EFI_AP_PROCEDURE. 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 103 simultaneously. 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 118 Specification. 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 133 all APs. 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 147 END_OF_CPU_LIST. 148 149 @retval EFI_SUCCESS In blocking mode, all APs have finished before 150 the timeout expired. 151 @retval EFI_SUCCESS In non-blocking mode, function has been dispatched 152 to all enabled APs. 153 @retval EFI_UNSUPPORTED A non-blocking mode request was made after the 154 UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was 155 signaled. 156 @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not 157 supported. 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. 165 166 **/ 167 EFI_STATUS 168 EFIAPI 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 176 ); 177 178 /** 179 This service lets the caller get one enabled AP to execute a caller-provided 180 function. 181 182 @param[in] Procedure A pointer to the function to be run on the 183 designated AP of the system. See type 184 EFI_AP_PROCEDURE. 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 204 Specification. 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 219 specified AP. 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. 228 229 @retval EFI_SUCCESS In blocking mode, specified AP finished before 230 the timeout expires. 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 235 signaled. 236 @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not 237 supported. 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. 247 248 **/ 249 EFI_STATUS 250 EFIAPI 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 258 ); 259 260 /** 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 263 by the current BSP. 264 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. 272 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 281 a disabled AP. 282 @retval EFI_NOT_READY The specified AP is busy. 283 @retval EFI_NOT_READY MP Initialize Library is not initialized. 284 285 **/ 286 EFI_STATUS 287 EFIAPI 288 MpInitLibSwitchBSP ( 289 IN UINTN ProcessorNumber, 290 IN BOOLEAN EnableOldBSP 291 ); 292 293 /** 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. 296 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 310 is ignored. 311 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 318 does not exist. 319 @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP. 320 @retval EFI_NOT_READY MP Initialize Library is not initialized. 321 322 **/ 323 EFI_STATUS 324 EFIAPI 325 MpInitLibEnableDisableAP ( 326 IN UINTN ProcessorNumber, 327 IN BOOLEAN EnableAP, 328 IN UINT32 *HealthFlag OPTIONAL 329 ); 330 331 /** 332 This return the handle number for the calling processor. This service may be 333 called from the BSP and APs. 334 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(). 340 341 @retval EFI_SUCCESS The current processor handle number was returned 342 in ProcessorNumber. 343 @retval EFI_INVALID_PARAMETER ProcessorNumber is NULL. 344 @retval EFI_NOT_READY MP Initialize Library is not initialized. 345 346 **/ 347 EFI_STATUS 348 EFIAPI 349 MpInitLibWhoAmI ( 350 OUT UINTN *ProcessorNumber 351 ); 352 353 #endif 354