CpuMp.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469
  1. /** @file
  2. CPU DXE MP support
  3. Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _CPU_MP_H_
  7. #define _CPU_MP_H_
  8. /**
  9. Initialize Multi-processor support.
  10. **/
  11. VOID
  12. InitializeMpSupport (
  13. VOID
  14. );
  15. /**
  16. This service retrieves the number of logical processor in the platform
  17. and the number of those logical processors that are enabled on this boot.
  18. This service may only be called from the BSP.
  19. This function is used to retrieve the following information:
  20. - The number of logical processors that are present in the system.
  21. - The number of enabled logical processors in the system at the instant
  22. this call is made.
  23. Because MP Service Protocol provides services to enable and disable processors
  24. dynamically, the number of enabled logical processors may vary during the
  25. course of a boot session.
  26. If this service is called from an AP, then EFI_DEVICE_ERROR is returned.
  27. If NumberOfProcessors or NumberOfEnabledProcessors is NULL, then
  28. EFI_INVALID_PARAMETER is returned. Otherwise, the total number of processors
  29. is returned in NumberOfProcessors, the number of currently enabled processor
  30. is returned in NumberOfEnabledProcessors, and EFI_SUCCESS is returned.
  31. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL
  32. instance.
  33. @param[out] NumberOfProcessors Pointer to the total number of logical
  34. processors in the system, including the BSP
  35. and disabled APs.
  36. @param[out] NumberOfEnabledProcessors Pointer to the number of enabled logical
  37. processors that exist in system, including
  38. the BSP.
  39. @retval EFI_SUCCESS The number of logical processors and enabled
  40. logical processors was retrieved.
  41. @retval EFI_DEVICE_ERROR The calling processor is an AP.
  42. @retval EFI_INVALID_PARAMETER NumberOfProcessors is NULL.
  43. @retval EFI_INVALID_PARAMETER NumberOfEnabledProcessors is NULL.
  44. **/
  45. EFI_STATUS
  46. EFIAPI
  47. GetNumberOfProcessors (
  48. IN EFI_MP_SERVICES_PROTOCOL *This,
  49. OUT UINTN *NumberOfProcessors,
  50. OUT UINTN *NumberOfEnabledProcessors
  51. );
  52. /**
  53. Gets detailed MP-related information on the requested processor at the
  54. instant this call is made. This service may only be called from the BSP.
  55. This service retrieves detailed MP-related information about any processor
  56. on the platform. Note the following:
  57. - The processor information may change during the course of a boot session.
  58. - The information presented here is entirely MP related.
  59. Information regarding the number of caches and their sizes, frequency of operation,
  60. slot numbers is all considered platform-related information and is not provided
  61. by this service.
  62. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL
  63. instance.
  64. @param[in] ProcessorNumber The handle number of processor.
  65. @param[out] ProcessorInfoBuffer A pointer to the buffer where information for
  66. the requested processor is deposited.
  67. @retval EFI_SUCCESS Processor information was returned.
  68. @retval EFI_DEVICE_ERROR The calling processor is an AP.
  69. @retval EFI_INVALID_PARAMETER ProcessorInfoBuffer is NULL.
  70. @retval EFI_NOT_FOUND The processor with the handle specified by
  71. ProcessorNumber does not exist in the platform.
  72. **/
  73. EFI_STATUS
  74. EFIAPI
  75. GetProcessorInfo (
  76. IN EFI_MP_SERVICES_PROTOCOL *This,
  77. IN UINTN ProcessorNumber,
  78. OUT EFI_PROCESSOR_INFORMATION *ProcessorInfoBuffer
  79. );
  80. /**
  81. This service executes a caller provided function on all enabled APs. APs can
  82. run either simultaneously or one at a time in sequence. This service supports
  83. both blocking and non-blocking requests. The non-blocking requests use EFI
  84. events so the BSP can detect when the APs have finished. This service may only
  85. be called from the BSP.
  86. This function is used to dispatch all the enabled APs to the function specified
  87. by Procedure. If any enabled AP is busy, then EFI_NOT_READY is returned
  88. immediately and Procedure is not started on any AP.
  89. If SingleThread is TRUE, all the enabled APs execute the function specified by
  90. Procedure one by one, in ascending order of processor handle number. Otherwise,
  91. all the enabled APs execute the function specified by Procedure simultaneously.
  92. If WaitEvent is NULL, execution is in blocking mode. The BSP waits until all
  93. APs finish or TimeoutInMicroseconds expires. Otherwise, execution is in non-blocking
  94. mode, and the BSP returns from this service without waiting for APs. If a
  95. non-blocking mode is requested after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT
  96. is signaled, then EFI_UNSUPPORTED must be returned.
  97. If the timeout specified by TimeoutInMicroseconds expires before all APs return
  98. from Procedure, then Procedure on the failed APs is terminated. All enabled APs
  99. are always available for further calls to EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
  100. and EFI_MP_SERVICES_PROTOCOL.StartupThisAP(). If FailedCpuList is not NULL, its
  101. content points to the list of processor handle numbers in which Procedure was
  102. terminated.
  103. Note: It is the responsibility of the consumer of the EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
  104. to make sure that the nature of the code that is executed on the BSP and the
  105. dispatched APs is well controlled. The MP Services Protocol does not guarantee
  106. that the Procedure function is MP-safe. Hence, the tasks that can be run in
  107. parallel are limited to certain independent tasks and well-controlled exclusive
  108. code. EFI services and protocols may not be called by APs unless otherwise
  109. specified.
  110. In blocking execution mode, BSP waits until all APs finish or
  111. TimeoutInMicroseconds expires.
  112. In non-blocking execution mode, BSP is freed to return to the caller and then
  113. proceed to the next task without having to wait for APs. The following
  114. sequence needs to occur in a non-blocking execution mode:
  115. -# The caller that intends to use this MP Services Protocol in non-blocking
  116. mode creates WaitEvent by calling the EFI CreateEvent() service. The caller
  117. invokes EFI_MP_SERVICES_PROTOCOL.StartupAllAPs(). If the parameter WaitEvent
  118. is not NULL, then StartupAllAPs() executes in non-blocking mode. It requests
  119. the function specified by Procedure to be started on all the enabled APs,
  120. and releases the BSP to continue with other tasks.
  121. -# The caller can use the CheckEvent() and WaitForEvent() services to check
  122. the state of the WaitEvent created in step 1.
  123. -# When the APs complete their task or TimeoutInMicroSeconds expires, the MP
  124. Service signals WaitEvent by calling the EFI SignalEvent() function. If
  125. FailedCpuList is not NULL, its content is available when WaitEvent is
  126. signaled. If all APs returned from Procedure prior to the timeout, then
  127. FailedCpuList is set to NULL. If not all APs return from Procedure before
  128. the timeout, then FailedCpuList is filled in with the list of the failed
  129. APs. The buffer is allocated by MP Service Protocol using AllocatePool().
  130. It is the caller's responsibility to free the buffer with FreePool() service.
  131. -# This invocation of SignalEvent() function informs the caller that invoked
  132. EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() that either all the APs completed
  133. the specified task or a timeout occurred. The contents of FailedCpuList
  134. can be examined to determine which APs did not complete the specified task
  135. prior to the timeout.
  136. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL
  137. instance.
  138. @param[in] Procedure A pointer to the function to be run on
  139. enabled APs of the system. See type
  140. EFI_AP_PROCEDURE.
  141. @param[in] SingleThread If TRUE, then all the enabled APs execute
  142. the function specified by Procedure one by
  143. one, in ascending order of processor handle
  144. number. If FALSE, then all the enabled APs
  145. execute the function specified by Procedure
  146. simultaneously.
  147. @param[in] WaitEvent The event created by the caller with CreateEvent()
  148. service. If it is NULL, then execute in
  149. blocking mode. BSP waits until all APs finish
  150. or TimeoutInMicroseconds expires. If it's
  151. not NULL, then execute in non-blocking mode.
  152. BSP requests the function specified by
  153. Procedure to be started on all the enabled
  154. APs, and go on executing immediately. If
  155. all return from Procedure, or TimeoutInMicroseconds
  156. expires, this event is signaled. The BSP
  157. can use the CheckEvent() or WaitForEvent()
  158. services to check the state of event. Type
  159. EFI_EVENT is defined in CreateEvent() in
  160. the Unified Extensible Firmware Interface
  161. Specification.
  162. @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for
  163. APs to return from Procedure, either for
  164. blocking or non-blocking mode. Zero means
  165. infinity. If the timeout expires before
  166. all APs return from Procedure, then Procedure
  167. on the failed APs is terminated. All enabled
  168. APs are available for next function assigned
  169. by EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
  170. or EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
  171. If the timeout expires in blocking mode,
  172. BSP returns EFI_TIMEOUT. If the timeout
  173. expires in non-blocking mode, WaitEvent
  174. is signaled with SignalEvent().
  175. @param[in] ProcedureArgument The parameter passed into Procedure for
  176. all APs.
  177. @param[out] FailedCpuList If NULL, this parameter is ignored. Otherwise,
  178. if all APs finish successfully, then its
  179. content is set to NULL. If not all APs
  180. finish before timeout expires, then its
  181. content is set to address of the buffer
  182. holding handle numbers of the failed APs.
  183. The buffer is allocated by MP Service Protocol,
  184. and it's the caller's responsibility to
  185. free the buffer with FreePool() service.
  186. In blocking mode, it is ready for consumption
  187. when the call returns. In non-blocking mode,
  188. it is ready when WaitEvent is signaled. The
  189. list of failed CPU is terminated by
  190. END_OF_CPU_LIST.
  191. @retval EFI_SUCCESS In blocking mode, all APs have finished before
  192. the timeout expired.
  193. @retval EFI_SUCCESS In non-blocking mode, function has been dispatched
  194. to all enabled APs.
  195. @retval EFI_UNSUPPORTED A non-blocking mode request was made after the
  196. UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
  197. signaled.
  198. @retval EFI_DEVICE_ERROR Caller processor is AP.
  199. @retval EFI_NOT_STARTED No enabled APs exist in the system.
  200. @retval EFI_NOT_READY Any enabled APs are busy.
  201. @retval EFI_TIMEOUT In blocking mode, the timeout expired before
  202. all enabled APs have finished.
  203. @retval EFI_INVALID_PARAMETER Procedure is NULL.
  204. **/
  205. EFI_STATUS
  206. EFIAPI
  207. StartupAllAPs (
  208. IN EFI_MP_SERVICES_PROTOCOL *This,
  209. IN EFI_AP_PROCEDURE Procedure,
  210. IN BOOLEAN SingleThread,
  211. IN EFI_EVENT WaitEvent OPTIONAL,
  212. IN UINTN TimeoutInMicroseconds,
  213. IN VOID *ProcedureArgument OPTIONAL,
  214. OUT UINTN **FailedCpuList OPTIONAL
  215. );
  216. /**
  217. This service lets the caller get one enabled AP to execute a caller-provided
  218. function. The caller can request the BSP to either wait for the completion
  219. of the AP or just proceed with the next task by using the EFI event mechanism.
  220. See EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() for more details on non-blocking
  221. execution support. This service may only be called from the BSP.
  222. This function is used to dispatch one enabled AP to the function specified by
  223. Procedure passing in the argument specified by ProcedureArgument. If WaitEvent
  224. is NULL, execution is in blocking mode. The BSP waits until the AP finishes or
  225. TimeoutInMicroSeconds expires. Otherwise, execution is in non-blocking mode.
  226. BSP proceeds to the next task without waiting for the AP. If a non-blocking mode
  227. is requested after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT is signaled,
  228. then EFI_UNSUPPORTED must be returned.
  229. If the timeout specified by TimeoutInMicroseconds expires before the AP returns
  230. from Procedure, then execution of Procedure by the AP is terminated. The AP is
  231. available for subsequent calls to EFI_MP_SERVICES_PROTOCOL.StartupAllAPs() and
  232. EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
  233. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL
  234. instance.
  235. @param[in] Procedure A pointer to the function to be run on
  236. enabled APs of the system. See type
  237. EFI_AP_PROCEDURE.
  238. @param[in] ProcessorNumber The handle number of the AP. The range is
  239. from 0 to the total number of logical
  240. processors minus 1. The total number of
  241. logical processors can be retrieved by
  242. EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
  243. @param[in] WaitEvent The event created by the caller with CreateEvent()
  244. service. If it is NULL, then execute in
  245. blocking mode. BSP waits until all APs finish
  246. or TimeoutInMicroseconds expires. If it's
  247. not NULL, then execute in non-blocking mode.
  248. BSP requests the function specified by
  249. Procedure to be started on all the enabled
  250. APs, and go on executing immediately. If
  251. all return from Procedure or TimeoutInMicroseconds
  252. expires, this event is signaled. The BSP
  253. can use the CheckEvent() or WaitForEvent()
  254. services to check the state of event. Type
  255. EFI_EVENT is defined in CreateEvent() in
  256. the Unified Extensible Firmware Interface
  257. Specification.
  258. @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for
  259. APs to return from Procedure, either for
  260. blocking or non-blocking mode. Zero means
  261. infinity. If the timeout expires before
  262. all APs return from Procedure, then Procedure
  263. on the failed APs is terminated. All enabled
  264. APs are available for next function assigned
  265. by EFI_MP_SERVICES_PROTOCOL.StartupAllAPs()
  266. or EFI_MP_SERVICES_PROTOCOL.StartupThisAP().
  267. If the timeout expires in blocking mode,
  268. BSP returns EFI_TIMEOUT. If the timeout
  269. expires in non-blocking mode, WaitEvent
  270. is signaled with SignalEvent().
  271. @param[in] ProcedureArgument The parameter passed into Procedure for
  272. all APs.
  273. @param[out] Finished If NULL, this parameter is ignored. In
  274. blocking mode, this parameter is ignored.
  275. In non-blocking mode, if AP returns from
  276. Procedure before the timeout expires, its
  277. content is set to TRUE. Otherwise, the
  278. value is set to FALSE. The caller can
  279. determine if the AP returned from Procedure
  280. by evaluating this value.
  281. @retval EFI_SUCCESS In blocking mode, specified AP finished before
  282. the timeout expires.
  283. @retval EFI_SUCCESS In non-blocking mode, the function has been
  284. dispatched to specified AP.
  285. @retval EFI_UNSUPPORTED A non-blocking mode request was made after the
  286. UEFI event EFI_EVENT_GROUP_READY_TO_BOOT was
  287. signaled.
  288. @retval EFI_DEVICE_ERROR The calling processor is an AP.
  289. @retval EFI_TIMEOUT In blocking mode, the timeout expired before
  290. the specified AP has finished.
  291. @retval EFI_NOT_READY The specified AP is busy.
  292. @retval EFI_NOT_FOUND The processor with the handle specified by
  293. ProcessorNumber does not exist.
  294. @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP or disabled AP.
  295. @retval EFI_INVALID_PARAMETER Procedure is NULL.
  296. **/
  297. EFI_STATUS
  298. EFIAPI
  299. StartupThisAP (
  300. IN EFI_MP_SERVICES_PROTOCOL *This,
  301. IN EFI_AP_PROCEDURE Procedure,
  302. IN UINTN ProcessorNumber,
  303. IN EFI_EVENT WaitEvent OPTIONAL,
  304. IN UINTN TimeoutInMicroseconds,
  305. IN VOID *ProcedureArgument OPTIONAL,
  306. OUT BOOLEAN *Finished OPTIONAL
  307. );
  308. /**
  309. This service switches the requested AP to be the BSP from that point onward.
  310. This service changes the BSP for all purposes. This call can only be performed
  311. by the current BSP.
  312. This service switches the requested AP to be the BSP from that point onward.
  313. This service changes the BSP for all purposes. The new BSP can take over the
  314. execution of the old BSP and continue seamlessly from where the old one left
  315. off. This service may not be supported after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT
  316. is signaled.
  317. If the BSP cannot be switched prior to the return from this service, then
  318. EFI_UNSUPPORTED must be returned.
  319. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
  320. @param[in] ProcessorNumber The handle number of AP that is to become the new
  321. BSP. The range is from 0 to the total number of
  322. logical processors minus 1. The total number of
  323. logical processors can be retrieved by
  324. EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
  325. @param[in] EnableOldBSP If TRUE, then the old BSP will be listed as an
  326. enabled AP. Otherwise, it will be disabled.
  327. @retval EFI_SUCCESS BSP successfully switched.
  328. @retval EFI_UNSUPPORTED Switching the BSP cannot be completed prior to
  329. this service returning.
  330. @retval EFI_UNSUPPORTED Switching the BSP is not supported.
  331. @retval EFI_DEVICE_ERROR The calling processor is an AP.
  332. @retval EFI_NOT_FOUND The processor with the handle specified by
  333. ProcessorNumber does not exist.
  334. @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the current BSP or
  335. a disabled AP.
  336. @retval EFI_NOT_READY The specified AP is busy.
  337. **/
  338. EFI_STATUS
  339. EFIAPI
  340. SwitchBSP (
  341. IN EFI_MP_SERVICES_PROTOCOL *This,
  342. IN UINTN ProcessorNumber,
  343. IN BOOLEAN EnableOldBSP
  344. );
  345. /**
  346. This service lets the caller enable or disable an AP from this point onward.
  347. This service may only be called from the BSP.
  348. This service allows the caller enable or disable an AP from this point onward.
  349. The caller can optionally specify the health status of the AP by Health. If
  350. an AP is being disabled, then the state of the disabled AP is implementation
  351. dependent. If an AP is enabled, then the implementation must guarantee that a
  352. complete initialization sequence is performed on the AP, so the AP is in a state
  353. that is compatible with an MP operating system. This service may not be supported
  354. after the UEFI Event EFI_EVENT_GROUP_READY_TO_BOOT is signaled.
  355. If the enable or disable AP operation cannot be completed prior to the return
  356. from this service, then EFI_UNSUPPORTED must be returned.
  357. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
  358. @param[in] ProcessorNumber The handle number of AP that is to become the new
  359. BSP. The range is from 0 to the total number of
  360. logical processors minus 1. The total number of
  361. logical processors can be retrieved by
  362. EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
  363. @param[in] EnableAP Specifies the new state for the processor for
  364. enabled, FALSE for disabled.
  365. @param[in] HealthFlag If not NULL, a pointer to a value that specifies
  366. the new health status of the AP. This flag
  367. corresponds to StatusFlag defined in
  368. EFI_MP_SERVICES_PROTOCOL.GetProcessorInfo(). Only
  369. the PROCESSOR_HEALTH_STATUS_BIT is used. All other
  370. bits are ignored. If it is NULL, this parameter
  371. is ignored.
  372. @retval EFI_SUCCESS The specified AP was enabled or disabled successfully.
  373. @retval EFI_UNSUPPORTED Enabling or disabling an AP cannot be completed
  374. prior to this service returning.
  375. @retval EFI_UNSUPPORTED Enabling or disabling an AP is not supported.
  376. @retval EFI_DEVICE_ERROR The calling processor is an AP.
  377. @retval EFI_NOT_FOUND Processor with the handle specified by ProcessorNumber
  378. does not exist.
  379. @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the BSP.
  380. **/
  381. EFI_STATUS
  382. EFIAPI
  383. EnableDisableAP (
  384. IN EFI_MP_SERVICES_PROTOCOL *This,
  385. IN UINTN ProcessorNumber,
  386. IN BOOLEAN EnableAP,
  387. IN UINT32 *HealthFlag OPTIONAL
  388. );
  389. /**
  390. This return the handle number for the calling processor. This service may be
  391. called from the BSP and APs.
  392. This service returns the processor handle number for the calling processor.
  393. The returned value is in the range from 0 to the total number of logical
  394. processors minus 1. The total number of logical processors can be retrieved
  395. with EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors(). This service may be
  396. called from the BSP and APs. If ProcessorNumber is NULL, then EFI_INVALID_PARAMETER
  397. is returned. Otherwise, the current processors handle number is returned in
  398. ProcessorNumber, and EFI_SUCCESS is returned.
  399. @param[in] This A pointer to the EFI_MP_SERVICES_PROTOCOL instance.
  400. @param[out] ProcessorNumber The handle number of AP that is to become the new
  401. BSP. The range is from 0 to the total number of
  402. logical processors minus 1. The total number of
  403. logical processors can be retrieved by
  404. EFI_MP_SERVICES_PROTOCOL.GetNumberOfProcessors().
  405. @retval EFI_SUCCESS The current processor handle number was returned
  406. in ProcessorNumber.
  407. @retval EFI_INVALID_PARAMETER ProcessorNumber is NULL.
  408. **/
  409. EFI_STATUS
  410. EFIAPI
  411. WhoAmI (
  412. IN EFI_MP_SERVICES_PROTOCOL *This,
  413. OUT UINTN *ProcessorNumber
  414. );
  415. #endif // _CPU_MP_H_