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