1 /** @file 2 Intel FSP API definition from Intel Firmware Support Package External 3 Architecture Specification v2.0. 4 5 Copyright (c) 2014 - 2016, 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 /// 20 /// FSP Reset Status code 21 /// These are defined in FSP EAS v2.0 section 11.2.2 - OEM Status Code 22 /// @{ 23 #define FSP_STATUS_RESET_REQUIRED_COLD 0x40000001 24 #define FSP_STATUS_RESET_REQUIRED_WARM 0x40000002 25 #define FSP_STATUS_RESET_REQUIRED_3 0x40000003 26 #define FSP_STATUS_RESET_REQUIRED_4 0x40000004 27 #define FSP_STATUS_RESET_REQUIRED_5 0x40000005 28 #define FSP_STATUS_RESET_REQUIRED_6 0x40000006 29 #define FSP_STATUS_RESET_REQUIRED_7 0x40000007 30 #define FSP_STATUS_RESET_REQUIRED_8 0x40000008 31 /// @} 32 33 #pragma pack(1) 34 /// 35 /// FSP_UPD_HEADER Configuration. 36 /// 37 typedef struct { 38 /// 39 /// UPD Region Signature. This signature will be 40 /// "XXXXXX_T" for FSP-T 41 /// "XXXXXX_M" for FSP-M 42 /// "XXXXXX_S" for FSP-S 43 /// Where XXXXXX is an unique signature 44 /// 45 UINT64 Signature; 46 /// 47 /// Revision of the Data structure. For FSP v2.0 value is 1. 48 /// 49 UINT8 Revision; 50 UINT8 Reserved[23]; 51 } FSP_UPD_HEADER; 52 53 /// 54 /// FSPM_ARCH_UPD Configuration. 55 /// 56 typedef struct { 57 /// 58 /// Revision of the structure. For FSP v2.0 value is 1. 59 /// 60 UINT8 Revision; 61 UINT8 Reserved[3]; 62 /// 63 /// Pointer to the non-volatile storage (NVS) data buffer. 64 /// If it is NULL it indicates the NVS data is not available. 65 /// 66 VOID *NvsBufferPtr; 67 /// 68 /// Pointer to the temporary stack base address to be 69 /// consumed inside FspMemoryInit() API. 70 /// 71 VOID *StackBase; 72 /// 73 /// Temporary stack size to be consumed inside 74 /// FspMemoryInit() API. 75 /// 76 UINT32 StackSize; 77 /// 78 /// Size of memory to be reserved by FSP below "top 79 /// of low usable memory" for bootloader usage. 80 /// 81 UINT32 BootLoaderTolumSize; 82 /// 83 /// Current boot mode. 84 /// 85 UINT32 BootMode; 86 UINT8 Reserved1[8]; 87 } FSPM_ARCH_UPD; 88 89 /// 90 /// FSPT_UPD_COMMON Configuration. 91 /// 92 typedef struct { 93 /// 94 /// FSP_UPD_HEADER Configuration. 95 /// 96 FSP_UPD_HEADER FspUpdHeader; 97 } FSPT_UPD_COMMON; 98 99 /// 100 /// FSPM_UPD_COMMON Configuration. 101 /// 102 typedef struct { 103 /// 104 /// FSP_UPD_HEADER Configuration. 105 /// 106 FSP_UPD_HEADER FspUpdHeader; 107 /// 108 /// FSPM_ARCH_UPD Configuration. 109 /// 110 FSPM_ARCH_UPD FspmArchUpd; 111 } FSPM_UPD_COMMON; 112 113 /// 114 /// FSPS_UPD_COMMON Configuration. 115 /// 116 typedef struct { 117 /// 118 /// FSP_UPD_HEADER Configuration. 119 /// 120 FSP_UPD_HEADER FspUpdHeader; 121 } FSPS_UPD_COMMON; 122 123 /// 124 /// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE. 125 /// 126 typedef enum { 127 /// 128 /// This stage is notified when the bootloader completes the 129 /// PCI enumeration and the resource allocation for the 130 /// PCI devices is complete. 131 /// 132 EnumInitPhaseAfterPciEnumeration = 0x20, 133 /// 134 /// This stage is notified just before the bootloader hand-off 135 /// to the OS loader. 136 /// 137 EnumInitPhaseReadyToBoot = 0x40, 138 /// 139 /// This stage is notified just before the firmware/Preboot 140 /// environment transfers management of all system resources 141 /// to the OS or next level execution environment. 142 /// 143 EnumInitPhaseEndOfFirmware = 0xF0 144 } FSP_INIT_PHASE; 145 146 /// 147 /// Definition of NOTIFY_PHASE_PARAMS. 148 /// 149 typedef struct { 150 /// 151 /// Notification phase used for NotifyPhase API 152 /// 153 FSP_INIT_PHASE Phase; 154 } NOTIFY_PHASE_PARAMS; 155 156 #pragma pack() 157 158 /** 159 This FSP API is called soon after coming out of reset and before memory and stack is 160 available. This FSP API will load the microcode update, enable code caching for the 161 region specified by the boot loader and also setup a temporary stack to be used until 162 main memory is initialized. 163 164 A hardcoded stack can be set up with the following values, and the "esp" register 165 initialized to point to this hardcoded stack. 166 1. The return address where the FSP will return control after setting up a temporary 167 stack. 168 2. A pointer to the input parameter structure 169 170 However, since the stack is in ROM and not writeable, this FSP API cannot be called 171 using the "call" instruction, but needs to be jumped to. 172 173 @param[in] FsptUpdDataPtr Pointer to the FSPT_UPD data structure. 174 175 @retval EFI_SUCCESS Temporary RAM was initialized successfully. 176 @retval EFI_INVALID_PARAMETER Input parameters are invalid. 177 @retval EFI_UNSUPPORTED The FSP calling conditions were not met. 178 @retval EFI_DEVICE_ERROR Temp RAM initialization failed. 179 180 If this function is successful, the FSP initializes the ECX and EDX registers to point to 181 a temporary but writeable memory range available to the boot loader and returns with 182 FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary 183 memory range and EDX points to the end of the range. Boot loader is free to use the 184 whole range described. Typically the boot loader can reload the ESP register to point 185 to the end of this returned range so that it can be used as a standard stack. 186 **/ 187 typedef 188 EFI_STATUS 189 (EFIAPI *FSP_TEMP_RAM_INIT) ( 190 IN VOID *FsptUpdDataPtr 191 ); 192 193 /** 194 This FSP API is used to notify the FSP about the different phases in the boot process. 195 This allows the FSP to take appropriate actions as needed during different initialization 196 phases. The phases will be platform dependent and will be documented with the FSP 197 release. The current FSP supports two notify phases: 198 Post PCI enumeration 199 Ready To Boot 200 201 @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS 202 203 @retval EFI_SUCCESS The notification was handled successfully. 204 @retval EFI_UNSUPPORTED The notification was not called in the proper order. 205 @retval EFI_INVALID_PARAMETER The notification code is invalid. 206 **/ 207 typedef 208 EFI_STATUS 209 (EFIAPI *FSP_NOTIFY_PHASE) ( 210 IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr 211 ); 212 213 /** 214 This FSP API is called after TempRamInit and initializes the memory. 215 This FSP API accepts a pointer to a data structure that will be platform dependent 216 and defined for each FSP binary. This will be documented in Integration guide with 217 each FSP release. 218 After FspMemInit completes its execution, it passes the pointer to the HobList and 219 returns to the boot loader from where it was called. BootLoader is responsible to 220 migrate it's stack and data to Memory. 221 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to 222 complete the silicon initialization and provides bootloader an opportunity to get 223 control after system memory is available and before the temporary RAM is torn down. 224 225 @param[in] FspmUpdDataPtr Pointer to the FSPM_UPD data sructure. 226 @param[out] HobListPtr Pointer to receive the address of the HOB list. 227 228 @retval EFI_SUCCESS FSP execution environment was initialized successfully. 229 @retval EFI_INVALID_PARAMETER Input parameters are invalid. 230 @retval EFI_UNSUPPORTED The FSP calling conditions were not met. 231 @retval EFI_DEVICE_ERROR FSP initialization failed. 232 @retval EFI_OUT_OF_RESOURCES Stack range requested by FSP is not met. 233 @retval FSP_STATUS_RESET_REQUIREDx A reset is reuired. These status codes will not be returned during S3. 234 **/ 235 typedef 236 EFI_STATUS 237 (EFIAPI *FSP_MEMORY_INIT) ( 238 IN VOID *FspmUpdDataPtr, 239 OUT VOID **HobListPtr 240 ); 241 242 243 /** 244 This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary 245 memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure 246 that will be platform dependent and defined for each FSP binary. This will be 247 documented in Integration Guide. 248 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to 249 complete the silicon initialization and provides bootloader an opportunity to get 250 control after system memory is available and before the temporary RAM is torn down. 251 252 @param[in] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure. 253 This structure is normally defined in the Integration Guide. 254 And if it is not defined in the Integration Guide, pass NULL. 255 256 @retval EFI_SUCCESS FSP execution environment was initialized successfully. 257 @retval EFI_INVALID_PARAMETER Input parameters are invalid. 258 @retval EFI_UNSUPPORTED The FSP calling conditions were not met. 259 @retval EFI_DEVICE_ERROR FSP initialization failed. 260 **/ 261 typedef 262 EFI_STATUS 263 (EFIAPI *FSP_TEMP_RAM_EXIT) ( 264 IN VOID *TempRamExitParamPtr 265 ); 266 267 268 /** 269 This FSP API is called after TempRamExit API. 270 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the 271 silicon initialization. 272 273 @param[in] FspsUpdDataPtr Pointer to the FSPS_UPD data structure. 274 If NULL, FSP will use the default parameters. 275 276 @retval EFI_SUCCESS FSP execution environment was initialized successfully. 277 @retval EFI_INVALID_PARAMETER Input parameters are invalid. 278 @retval EFI_UNSUPPORTED The FSP calling conditions were not met. 279 @retval EFI_DEVICE_ERROR FSP initialization failed. 280 @retval FSP_STATUS_RESET_REQUIREDx A reset is reuired. These status codes will not be returned during S3. 281 **/ 282 typedef 283 EFI_STATUS 284 (EFIAPI *FSP_SILICON_INIT) ( 285 IN VOID *FspsUpdDataPtr 286 ); 287 288 #endif 289