MpInitLib.h 20 KB

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