| | 1 | /** @file\r |
| | 2 | Multiple-Processor initialization Library.\r |
| | 3 | \r |
| | 4 | Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>\r |
| | 5 | SPDX-License-Identifier: BSD-2-Clause-Patent\r |
| | 6 | \r |
| | 7 | **/\r |
| | 8 | \r |
| | 9 | #ifndef __MP_INIT_LIB_H__\r |
| | 10 | #define __MP_INIT_LIB_H__\r |
| | 11 | \r |
| | 12 | #include <Ppi/SecPlatformInformation.h>\r |
| | 13 | #include <Protocol/MpService.h>\r |
| | 14 | \r |
| | 15 | /**\r |
| | 16 | MP Initialize Library initialization.\r |
| | 17 | \r |
| | 18 | This service will allocate AP reset vector and wakeup all APs to do APs\r |
| | 19 | initialization.\r |
| | 20 | \r |
| | 21 | This service must be invoked before all other MP Initialize Library\r |
| | 22 | service are invoked.\r |
| | 23 | \r |
| | 24 | @retval EFI_SUCCESS MP initialization succeeds.\r |
| | 25 | @retval Others MP initialization fails.\r |
| | 26 | \r |
| | 27 | **/\r |
| | 28 | EFI_STATUS\r |
| | 29 | EFIAPI\r |
| | 30 | MpInitLibInitialize (\r |
| | 31 | VOID\r |
| | 32 | );\r |
| | 33 | \r |
| | 34 | /**\r |
| | 35 | Retrieves the number of logical processor in the platform and the number of\r |
| | 36 | those logical processors that are enabled on this boot. This service may only\r |
| | 37 | be called from the BSP.\r |
| | 38 | \r |
| | 39 | @param[out] NumberOfProcessors Pointer to the total number of logical\r |
| | 40 | processors in the system, including the BSP\r |
| | 41 | and disabled APs.\r |
| | 42 | @param[out] NumberOfEnabledProcessors Pointer to the number of enabled logical\r |
| | 43 | processors that exist in system, including\r |
| | 44 | the BSP.\r |
| | 45 | \r |
| | 46 | @retval EFI_SUCCESS The number of logical processors and enabled\r |
| | 47 | logical processors was retrieved.\r |
| | 48 | @retval EFI_DEVICE_ERROR The calling processor is an AP.\r |
| | 49 | @retval EFI_INVALID_PARAMETER NumberOfProcessors is NULL and NumberOfEnabledProcessors\r |
| | 50 | is NULL.\r |
| | 51 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 52 | \r |
| | 53 | **/\r |
| | 54 | EFI_STATUS\r |
| | 55 | EFIAPI\r |
| | 56 | MpInitLibGetNumberOfProcessors (\r |
| | 57 | OUT UINTN *NumberOfProcessors, OPTIONAL\r |
| | 58 | OUT UINTN *NumberOfEnabledProcessors OPTIONAL\r |
| | 59 | );\r |
| | 60 | \r |
| | 61 | /**\r |
| | 62 | Gets detailed MP-related information on the requested processor at the\r |
| | 63 | instant this call is made. This service may only be called from the BSP.\r |
| | 64 | \r |
| | 65 | @param[in] ProcessorNumber The handle number of processor.\r |
| | 66 | @param[out] ProcessorInfoBuffer A pointer to the buffer where information for\r |
| | 67 | the requested processor is deposited.\r |
| | 68 | @param[out] HealthData Return processor health data.\r |
| | 69 | \r |
| | 70 | @retval EFI_SUCCESS Processor information was returned.\r |
| | 71 | @retval EFI_DEVICE_ERROR The calling processor is an AP.\r |
| | 72 | @retval EFI_INVALID_PARAMETER ProcessorInfoBuffer is NULL.\r |
| | 73 | @retval EFI_NOT_FOUND The processor with the handle specified by\r |
| | 74 | ProcessorNumber does not exist in the platform.\r |
| | 75 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 76 | \r |
| | 77 | **/\r |
| | 78 | EFI_STATUS\r |
| | 79 | EFIAPI\r |
| | 80 | MpInitLibGetProcessorInfo (\r |
| | 81 | IN UINTN ProcessorNumber,\r |
| | 82 | OUT EFI_PROCESSOR_INFORMATION *ProcessorInfoBuffer,\r |
| | 83 | OUT EFI_HEALTH_FLAGS *HealthData OPTIONAL\r |
| | 84 | );\r |
| | 85 | \r |
| | 86 | /**\r |
| | 87 | This service executes a caller provided function on all enabled APs.\r |
| | 88 | \r |
| | 89 | @param[in] Procedure A pointer to the function to be run on\r |
| | 90 | enabled APs of the system. See type\r |
| | 91 | EFI_AP_PROCEDURE.\r |
| | 92 | @param[in] SingleThread If TRUE, then all the enabled APs execute\r |
| | 93 | the function specified by Procedure one by\r |
| | 94 | one, in ascending order of processor handle\r |
| | 95 | number. If FALSE, then all the enabled APs\r |
| | 96 | execute the function specified by Procedure\r |
| | 97 | simultaneously.\r |
| | 98 | @param[in] WaitEvent The event created by the caller with CreateEvent()\r |
| | 99 | service. If it is NULL, then execute in\r |
| | 100 | blocking mode. BSP waits until all APs finish\r |
| | 101 | or TimeoutInMicroSeconds expires. If it's\r |
| | 102 | not NULL, then execute in non-blocking mode.\r |
| | 103 | BSP requests the function specified by\r |
| | 104 | Procedure to be started on all the enabled\r |
| | 105 | APs, and go on executing immediately. If\r |
| | 106 | all return from Procedure, or TimeoutInMicroSeconds\r |
| | 107 | expires, this event is signaled. The BSP\r |
| | 108 | can use the CheckEvent() or WaitForEvent()\r |
| | 109 | services to check the state of event. Type\r |
| | 110 | EFI_EVENT is defined in CreateEvent() in\r |
| | 111 | the Unified Extensible Firmware Interface\r |
| | 112 | Specification.\r |
| | 113 | @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for\r |
| | 114 | APs to return from Procedure, either for\r |
| | 115 | blocking or non-blocking mode. Zero means\r |
| | 116 | infinity. If the timeout expires before\r |
| | 117 | all APs return from Procedure, then Procedure\r |
| | 118 | on the failed APs is terminated. All enabled\r |
| | 119 | APs are available for next function assigned\r |
| | 120 | by MpInitLibStartupAllAPs() or\r |
| | 121 | MPInitLibStartupThisAP().\r |
| | 122 | If the timeout expires in blocking mode,\r |
| | 123 | BSP returns EFI_TIMEOUT. If the timeout\r |
| | 124 | expires in non-blocking mode, WaitEvent\r |
| | 125 | is signaled with SignalEvent().\r |
| | 126 | @param[in] ProcedureArgument The parameter passed into Procedure for\r |
| | 127 | all APs.\r |
| | 128 | @param[out] FailedCpuList If NULL, this parameter is ignored. Otherwise,\r |
| | 129 | if all APs finish successfully, then its\r |
| | 130 | content is set to NULL. If not all APs\r |
| | 131 | finish before timeout expires, then its\r |
| | 132 | content is set to address of the buffer\r |
| | 133 | holding handle numbers of the failed APs.\r |
| | 134 | The buffer is allocated by MP Initialization\r |
| | 135 | library, and it's the caller's responsibility to\r |
| | 136 | free the buffer with FreePool() service.\r |
| | 137 | In blocking mode, it is ready for consumption\r |
| | 138 | when the call returns. In non-blocking mode,\r |
| | 139 | it is ready when WaitEvent is signaled. The\r |
| | 140 | list of failed CPU is terminated by\r |
| | 141 | END_OF_CPU_LIST.\r |
| | 142 | \r |
| | 143 | @retval EFI_SUCCESS In blocking mode, all APs have finished before\r |
| | 144 | the timeout expired.\r |
| | 145 | @retval EFI_SUCCESS In non-blocking mode, function has been dispatched\r |
| | 146 | to all enabled APs.\r |
| | 147 | @retval EFI_UNSUPPORTED A non-blocking mode request was made after the\r |
| | 148 | UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was\r |
| | 149 | signaled.\r |
| | 150 | @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not\r |
| | 151 | supported.\r |
| | 152 | @retval EFI_DEVICE_ERROR Caller processor is AP.\r |
| | 153 | @retval EFI_NOT_STARTED No enabled APs exist in the system.\r |
| | 154 | @retval EFI_NOT_READY Any enabled APs are busy.\r |
| | 155 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 156 | @retval EFI_TIMEOUT In blocking mode, the timeout expired before\r |
| | 157 | all enabled APs have finished.\r |
| | 158 | @retval EFI_INVALID_PARAMETER Procedure is NULL.\r |
| | 159 | \r |
| | 160 | **/\r |
| | 161 | EFI_STATUS\r |
| | 162 | EFIAPI\r |
| | 163 | MpInitLibStartupAllAPs (\r |
| | 164 | IN EFI_AP_PROCEDURE Procedure,\r |
| | 165 | IN BOOLEAN SingleThread,\r |
| | 166 | IN EFI_EVENT WaitEvent OPTIONAL,\r |
| | 167 | IN UINTN TimeoutInMicroseconds,\r |
| | 168 | IN VOID *ProcedureArgument OPTIONAL,\r |
| | 169 | OUT UINTN **FailedCpuList OPTIONAL\r |
| | 170 | );\r |
| | 171 | \r |
| | 172 | /**\r |
| | 173 | This service lets the caller get one enabled AP to execute a caller-provided\r |
| | 174 | function.\r |
| | 175 | \r |
| | 176 | @param[in] Procedure A pointer to the function to be run on the\r |
| | 177 | designated AP of the system. See type\r |
| | 178 | EFI_AP_PROCEDURE.\r |
| | 179 | @param[in] ProcessorNumber The handle number of the AP. The range is\r |
| | 180 | from 0 to the total number of logical\r |
| | 181 | processors minus 1. The total number of\r |
| | 182 | logical processors can be retrieved by\r |
| | 183 | MpInitLibGetNumberOfProcessors().\r |
| | 184 | @param[in] WaitEvent The event created by the caller with CreateEvent()\r |
| | 185 | service. If it is NULL, then execute in\r |
| | 186 | blocking mode. BSP waits until this AP finish\r |
| | 187 | or TimeoutInMicroSeconds expires. If it's\r |
| | 188 | not NULL, then execute in non-blocking mode.\r |
| | 189 | BSP requests the function specified by\r |
| | 190 | Procedure to be started on this AP,\r |
| | 191 | and go on executing immediately. If this AP\r |
| | 192 | return from Procedure or TimeoutInMicroSeconds\r |
| | 193 | expires, this event is signaled. The BSP\r |
| | 194 | can use the CheckEvent() or WaitForEvent()\r |
| | 195 | services to check the state of event. Type\r |
| | 196 | EFI_EVENT is defined in CreateEvent() in\r |
| | 197 | the Unified Extensible Firmware Interface\r |
| | 198 | Specification.\r |
| | 199 | @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for\r |
| | 200 | this AP to finish this Procedure, either for\r |
| | 201 | blocking or non-blocking mode. Zero means\r |
| | 202 | infinity. If the timeout expires before\r |
| | 203 | this AP returns from Procedure, then Procedure\r |
| | 204 | on the AP is terminated. The\r |
| | 205 | AP is available for next function assigned\r |
| | 206 | by MpInitLibStartupAllAPs() or\r |
| | 207 | MpInitLibStartupThisAP().\r |
| | 208 | If the timeout expires in blocking mode,\r |
| | 209 | BSP returns EFI_TIMEOUT. If the timeout\r |
| | 210 | expires in non-blocking mode, WaitEvent\r |
| | 211 | is signaled with SignalEvent().\r |
| | 212 | @param[in] ProcedureArgument The parameter passed into Procedure on the\r |
| | 213 | specified AP.\r |
| | 214 | @param[out] Finished If NULL, this parameter is ignored. In\r |
| | 215 | blocking mode, this parameter is ignored.\r |
| | 216 | In non-blocking mode, if AP returns from\r |
| | 217 | Procedure before the timeout expires, its\r |
| | 218 | content is set to TRUE. Otherwise, the\r |
| | 219 | value is set to FALSE. The caller can\r |
| | 220 | determine if the AP returned from Procedure\r |
| | 221 | by evaluating this value.\r |
| | 222 | \r |
| | 223 | @retval EFI_SUCCESS In blocking mode, specified AP finished before\r |
| | 224 | the timeout expires.\r |
| | 225 | @retval EFI_SUCCESS In non-blocking mode, the function has been\r |
| | 226 | dispatched to specified AP.\r |
| | 227 | @retval EFI_UNSUPPORTED A non-blocking mode request was made after the\r |
| | 228 | UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was\r |
| | 229 | signaled.\r |
| | 230 | @retval EFI_UNSUPPORTED WaitEvent is not NULL if non-blocking mode is not\r |
| | 231 | supported.\r |
| | 232 | @retval EFI_DEVICE_ERROR The calling processor is an AP.\r |
| | 233 | @retval EFI_TIMEOUT In blocking mode, the timeout expired before\r |
| | 234 | the specified AP has finished.\r |
| | 235 | @retval EFI_NOT_READY The specified AP is busy.\r |
| | 236 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 237 | @retval EFI_NOT_FOUND The processor with the handle specified by\r |
| | 238 | ProcessorNumber does not exist.\r |
| | 239 | @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP or disabled AP.\r |
| | 240 | @retval EFI_INVALID_PARAMETER Procedure is NULL.\r |
| | 241 | \r |
| | 242 | **/\r |
| | 243 | EFI_STATUS\r |
| | 244 | EFIAPI\r |
| | 245 | MpInitLibStartupThisAP (\r |
| | 246 | IN EFI_AP_PROCEDURE Procedure,\r |
| | 247 | IN UINTN ProcessorNumber,\r |
| | 248 | IN EFI_EVENT WaitEvent OPTIONAL,\r |
| | 249 | IN UINTN TimeoutInMicroseconds,\r |
| | 250 | IN VOID *ProcedureArgument OPTIONAL,\r |
| | 251 | OUT BOOLEAN *Finished OPTIONAL\r |
| | 252 | );\r |
| | 253 | \r |
| | 254 | /**\r |
| | 255 | This service switches the requested AP to be the BSP from that point onward.\r |
| | 256 | This service changes the BSP for all purposes. This call can only be performed\r |
| | 257 | by the current BSP.\r |
| | 258 | \r |
| | 259 | @param[in] ProcessorNumber The handle number of AP that is to become the new\r |
| | 260 | BSP. The range is from 0 to the total number of\r |
| | 261 | logical processors minus 1. The total number of\r |
| | 262 | logical processors can be retrieved by\r |
| | 263 | MpInitLibGetNumberOfProcessors().\r |
| | 264 | @param[in] EnableOldBSP If TRUE, then the old BSP will be listed as an\r |
| | 265 | enabled AP. Otherwise, it will be disabled.\r |
| | 266 | \r |
| | 267 | @retval EFI_SUCCESS BSP successfully switched.\r |
| | 268 | @retval EFI_UNSUPPORTED Switching the BSP cannot be completed prior to\r |
| | 269 | this service returning.\r |
| | 270 | @retval EFI_UNSUPPORTED Switching the BSP is not supported.\r |
| | 271 | @retval EFI_DEVICE_ERROR The calling processor is an AP.\r |
| | 272 | @retval EFI_NOT_FOUND The processor with the handle specified by\r |
| | 273 | ProcessorNumber does not exist.\r |
| | 274 | @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the current BSP or\r |
| | 275 | a disabled AP.\r |
| | 276 | @retval EFI_NOT_READY The specified AP is busy.\r |
| | 277 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 278 | \r |
| | 279 | **/\r |
| | 280 | EFI_STATUS\r |
| | 281 | EFIAPI\r |
| | 282 | MpInitLibSwitchBSP (\r |
| | 283 | IN UINTN ProcessorNumber,\r |
| | 284 | IN BOOLEAN EnableOldBSP\r |
| | 285 | );\r |
| | 286 | \r |
| | 287 | /**\r |
| | 288 | This service lets the caller enable or disable an AP from this point onward.\r |
| | 289 | This service may only be called from the BSP.\r |
| | 290 | \r |
| | 291 | @param[in] ProcessorNumber The handle number of AP.\r |
| | 292 | The range is from 0 to the total number of\r |
| | 293 | logical processors minus 1. The total number of\r |
| | 294 | logical processors can be retrieved by\r |
| | 295 | MpInitLibGetNumberOfProcessors().\r |
| | 296 | @param[in] EnableAP Specifies the new state for the processor for\r |
| | 297 | enabled, FALSE for disabled.\r |
| | 298 | @param[in] HealthFlag If not NULL, a pointer to a value that specifies\r |
| | 299 | the new health status of the AP. This flag\r |
| | 300 | corresponds to StatusFlag defined in\r |
| | 301 | EFI_MP_SERVICES_PROTOCOL.GetProcessorInfo(). Only\r |
| | 302 | the PROCESSOR_HEALTH_STATUS_BIT is used. All other\r |
| | 303 | bits are ignored. If it is NULL, this parameter\r |
| | 304 | is ignored.\r |
| | 305 | \r |
| | 306 | @retval EFI_SUCCESS The specified AP was enabled or disabled successfully.\r |
| | 307 | @retval EFI_UNSUPPORTED Enabling or disabling an AP cannot be completed\r |
| | 308 | prior to this service returning.\r |
| | 309 | @retval EFI_UNSUPPORTED Enabling or disabling an AP is not supported.\r |
| | 310 | @retval EFI_DEVICE_ERROR The calling processor is an AP.\r |
| | 311 | @retval EFI_NOT_FOUND Processor with the handle specified by ProcessorNumber\r |
| | 312 | does not exist.\r |
| | 313 | @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP.\r |
| | 314 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 315 | \r |
| | 316 | **/\r |
| | 317 | EFI_STATUS\r |
| | 318 | EFIAPI\r |
| | 319 | MpInitLibEnableDisableAP (\r |
| | 320 | IN UINTN ProcessorNumber,\r |
| | 321 | IN BOOLEAN EnableAP,\r |
| | 322 | IN UINT32 *HealthFlag OPTIONAL\r |
| | 323 | );\r |
| | 324 | \r |
| | 325 | /**\r |
| | 326 | This return the handle number for the calling processor. This service may be\r |
| | 327 | called from the BSP and APs.\r |
| | 328 | \r |
| | 329 | @param[out] ProcessorNumber Pointer to the handle number of AP.\r |
| | 330 | The range is from 0 to the total number of\r |
| | 331 | logical processors minus 1. The total number of\r |
| | 332 | logical processors can be retrieved by\r |
| | 333 | MpInitLibGetNumberOfProcessors().\r |
| | 334 | \r |
| | 335 | @retval EFI_SUCCESS The current processor handle number was returned\r |
| | 336 | in ProcessorNumber.\r |
| | 337 | @retval EFI_INVALID_PARAMETER ProcessorNumber is NULL.\r |
| | 338 | @retval EFI_NOT_READY MP Initialize Library is not initialized.\r |
| | 339 | \r |
| | 340 | **/\r |
| | 341 | EFI_STATUS\r |
| | 342 | EFIAPI\r |
| | 343 | MpInitLibWhoAmI (\r |
| | 344 | OUT UINTN *ProcessorNumber\r |
| | 345 | );\r |
| | 346 | \r |
| | 347 | #endif\r |
projects / mirror_edk2.git / blame_incremental