FspApi.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. /** @file
  2. Intel FSP API definition from Intel Firmware Support Package External
  3. Architecture Specification v1.1, April 2015, revision 001.
  4. Copyright (c) 2014 - 2015, Intel Corporation. All rights reserved.<BR>
  5. SPDX-License-Identifier: BSD-2-Clause-Patent
  6. **/
  7. #ifndef _FSP_API_H_
  8. #define _FSP_API_H_
  9. #define FSP_STATUS EFI_STATUS
  10. #define FSPAPI EFIAPI
  11. /**
  12. FSP Init continuation function prototype.
  13. Control will be returned to this callback function after FspInit API call.
  14. @param[in] Status Status of the FSP INIT API.
  15. @param[in] HobBufferPtr Pointer to the HOB data structure defined in the PI specification.
  16. **/
  17. typedef
  18. VOID
  19. (* CONTINUATION_PROC) (
  20. IN EFI_STATUS Status,
  21. IN VOID *HobListPtr
  22. );
  23. #pragma pack(1)
  24. typedef struct {
  25. ///
  26. /// Base address of the microcode region.
  27. ///
  28. UINT32 MicrocodeRegionBase;
  29. ///
  30. /// Length of the microcode region.
  31. ///
  32. UINT32 MicrocodeRegionLength;
  33. ///
  34. /// Base address of the cacheable flash region.
  35. ///
  36. UINT32 CodeRegionBase;
  37. ///
  38. /// Length of the cacheable flash region.
  39. ///
  40. UINT32 CodeRegionLength;
  41. } FSP_TEMP_RAM_INIT_PARAMS;
  42. typedef struct {
  43. ///
  44. /// Non-volatile storage buffer pointer.
  45. ///
  46. VOID *NvsBufferPtr;
  47. ///
  48. /// Runtime buffer pointer
  49. ///
  50. VOID *RtBufferPtr;
  51. ///
  52. /// Continuation function address
  53. ///
  54. CONTINUATION_PROC ContinuationFunc;
  55. } FSP_INIT_PARAMS;
  56. typedef struct {
  57. ///
  58. /// Stack top pointer used by the bootloader.
  59. /// The new stack frame will be set up at this location after FspInit API call.
  60. ///
  61. UINT32 *StackTop;
  62. ///
  63. /// Current system boot mode.
  64. ///
  65. UINT32 BootMode;
  66. ///
  67. /// User platform configuraiton data region pointer.
  68. ///
  69. VOID *UpdDataRgnPtr;
  70. //
  71. // Below field is added in FSP EAS v1.1
  72. //
  73. ///
  74. /// The size of memory to be reserved below the top of low usable memory (TOLUM)
  75. /// for BootLoader usage. This is optional and value can be zero. If non-zero, the
  76. /// size must be a multiple of 4KB.
  77. ///
  78. UINT32 BootLoaderTolumSize;
  79. ///
  80. /// Reserved
  81. ///
  82. UINT32 Reserved[6];
  83. } FSP_INIT_RT_COMMON_BUFFER;
  84. typedef enum {
  85. ///
  86. /// Notification code for post PCI enuermation
  87. ///
  88. EnumInitPhaseAfterPciEnumeration = 0x20,
  89. ///
  90. /// Notification code before transfering control to the payload
  91. ///
  92. EnumInitPhaseReadyToBoot = 0x40
  93. } FSP_INIT_PHASE;
  94. typedef struct {
  95. ///
  96. /// Notification phase used for NotifyPhase API
  97. ///
  98. FSP_INIT_PHASE Phase;
  99. } NOTIFY_PHASE_PARAMS;
  100. typedef struct {
  101. ///
  102. /// Non-volatile storage buffer pointer.
  103. ///
  104. VOID *NvsBufferPtr;
  105. ///
  106. /// Runtime buffer pointer
  107. ///
  108. VOID *RtBufferPtr;
  109. ///
  110. /// Pointer to the HOB data structure defined in the PI specification
  111. ///
  112. VOID **HobListPtr;
  113. } FSP_MEMORY_INIT_PARAMS;
  114. #pragma pack()
  115. /**
  116. This FSP API is called soon after coming out of reset and before memory and stack is
  117. available. This FSP API will load the microcode update, enable code caching for the
  118. region specified by the boot loader and also setup a temporary stack to be used until
  119. main memory is initialized.
  120. A hardcoded stack can be set up with the following values, and the "esp" register
  121. initialized to point to this hardcoded stack.
  122. 1. The return address where the FSP will return control after setting up a temporary
  123. stack.
  124. 2. A pointer to the input parameter structure
  125. However, since the stack is in ROM and not writeable, this FSP API cannot be called
  126. using the "call" instruction, but needs to be jumped to.
  127. @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.
  128. @retval EFI_SUCCESS Temp RAM was initialized successfully.
  129. @retval EFI_INVALID_PARAMETER Input parameters are invalid..
  130. @retval EFI_NOT_FOUND No valid microcode was found in the microcode region.
  131. @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
  132. @retval EFI_DEVICE_ERROR Temp RAM initialization failed.
  133. If this function is successful, the FSP initializes the ECX and EDX registers to point to
  134. a temporary but writeable memory range available to the boot loader and returns with
  135. FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
  136. memory range and EDX points to the end of the range. Boot loader is free to use the
  137. whole range described. Typically the boot loader can reload the ESP register to point
  138. to the end of this returned range so that it can be used as a standard stack.
  139. **/
  140. typedef
  141. EFI_STATUS
  142. (EFIAPI *FSP_TEMP_RAM_INIT) (
  143. IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr
  144. );
  145. /**
  146. This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,
  147. the CPU and the chipset to enable normal operation of these devices. This FSP API
  148. accepts a pointer to a data structure that will be platform dependent and defined for
  149. each FSP binary. This will be documented in the Integration Guide for each FSP
  150. release.
  151. The boot loader provides a continuation function as a parameter when calling FspInit.
  152. After FspInit completes its execution, it does not return to the boot loader from where
  153. it was called but instead returns control to the boot loader by calling the continuation
  154. function which is passed to FspInit as an argument.
  155. @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.
  156. @retval EFI_SUCCESS FSP execution environment was initialized successfully.
  157. @retval EFI_INVALID_PARAMETER Input parameters are invalid.
  158. @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
  159. @retval EFI_DEVICE_ERROR FSP initialization failed.
  160. **/
  161. typedef
  162. EFI_STATUS
  163. (EFIAPI *FSP_INIT) (
  164. IN OUT FSP_INIT_PARAMS *FspInitParamPtr
  165. );
  166. #define FSP_FSP_INIT FSP_INIT
  167. /**
  168. This FSP API is used to notify the FSP about the different phases in the boot process.
  169. This allows the FSP to take appropriate actions as needed during different initialization
  170. phases. The phases will be platform dependent and will be documented with the FSP
  171. release. The current FSP supports two notify phases:
  172. Post PCI enumeration
  173. Ready To Boot
  174. @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
  175. @retval EFI_SUCCESS The notification was handled successfully.
  176. @retval EFI_UNSUPPORTED The notification was not called in the proper order.
  177. @retval EFI_INVALID_PARAMETER The notification code is invalid.
  178. **/
  179. typedef
  180. EFI_STATUS
  181. (EFIAPI *FSP_NOTIFY_PHASE) (
  182. IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
  183. );
  184. /**
  185. This FSP API is called after TempRamInit and initializes the memory.
  186. This FSP API accepts a pointer to a data structure that will be platform dependent
  187. and defined for each FSP binary. This will be documented in Integration guide with
  188. each FSP release.
  189. After FspMemInit completes its execution, it passes the pointer to the HobList and
  190. returns to the boot loader from where it was called. BootLoader is responsible to
  191. migrate it's stack and data to Memory.
  192. FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
  193. complete the silicon initialization and provides bootloader an opportunity to get
  194. control after system memory is available and before the temporary RAM is torn down.
  195. These APIs are mutually exclusive to the FspInit API.
  196. @param[in][out] FspMemoryInitParamPtr Address pointer to the FSP_MEMORY_INIT_PARAMS
  197. structure.
  198. @retval EFI_SUCCESS FSP execution environment was initialized successfully.
  199. @retval EFI_INVALID_PARAMETER Input parameters are invalid.
  200. @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
  201. @retval EFI_DEVICE_ERROR FSP initialization failed.
  202. **/
  203. typedef
  204. EFI_STATUS
  205. (EFIAPI *FSP_MEMORY_INIT) (
  206. IN OUT FSP_MEMORY_INIT_PARAMS *FspMemoryInitParamPtr
  207. );
  208. /**
  209. This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
  210. memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
  211. that will be platform dependent and defined for each FSP binary. This will be
  212. documented in Integration Guide.
  213. FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
  214. complete the silicon initialization and provides bootloader an opportunity to get
  215. control after system memory is available and before the temporary RAM is torn down.
  216. These APIs are mutually exclusive to the FspInit API.
  217. @param[in][out] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
  218. This structure is normally defined in the Integration Guide.
  219. And if it is not defined in the Integration Guide, pass NULL.
  220. @retval EFI_SUCCESS FSP execution environment was initialized successfully.
  221. @retval EFI_INVALID_PARAMETER Input parameters are invalid.
  222. @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
  223. @retval EFI_DEVICE_ERROR FSP initialization failed.
  224. **/
  225. typedef
  226. EFI_STATUS
  227. (EFIAPI *FSP_TEMP_RAM_EXIT) (
  228. IN OUT VOID *TempRamExitParamPtr
  229. );
  230. /**
  231. This FSP API is called after TempRamExit API.
  232. FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
  233. silicon initialization.
  234. These APIs are mutually exclusive to the FspInit API.
  235. @param[in][out] FspSiliconInitParamPtr Pointer to the Silicon Init parameters structure.
  236. This structure is normally defined in the Integration Guide.
  237. And if it is not defined in the Integration Guide, pass NULL.
  238. @retval EFI_SUCCESS FSP execution environment was initialized successfully.
  239. @retval EFI_INVALID_PARAMETER Input parameters are invalid.
  240. @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
  241. @retval EFI_DEVICE_ERROR FSP initialization failed.
  242. **/
  243. typedef
  244. EFI_STATUS
  245. (EFIAPI *FSP_SILICON_INIT) (
  246. IN OUT VOID *FspSiliconInitParamPtr
  247. );
  248. ///
  249. /// FSP API Return Status Code for backward compatibility with v1.0
  250. ///@{
  251. #define FSP_SUCCESS EFI_SUCCESS
  252. #define FSP_INVALID_PARAMETER EFI_INVALID_PARAMETER
  253. #define FSP_UNSUPPORTED EFI_UNSUPPORTED
  254. #define FSP_NOT_READY EFI_NOT_READY
  255. #define FSP_DEVICE_ERROR EFI_DEVICE_ERROR
  256. #define FSP_OUT_OF_RESOURCES EFI_OUT_OF_RESOURCES
  257. #define FSP_VOLUME_CORRUPTED EFI_VOLUME_CORRUPTED
  258. #define FSP_NOT_FOUND EFI_NOT_FOUND
  259. #define FSP_TIMEOUT EFI_TIMEOUT
  260. #define FSP_ABORTED EFI_ABORTED
  261. #define FSP_INCOMPATIBLE_VERSION EFI_INCOMPATIBLE_VERSION
  262. #define FSP_SECURITY_VIOLATION EFI_SECURITY_VIOLATION
  263. #define FSP_CRC_ERROR EFI_CRC_ERROR
  264. ///@}
  265. #endif