IntelFspPkg/Include/FspApi.h

   1 /** @file
   2   Intel FSP API definition from Intel Firmware Support Package External
   3   Architecture Specification, April 2014, 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   /// Reserved
  88   ///
  89   UINT32              Reserved[7];
  90 } FSP_INIT_RT_COMMON_BUFFER;
  91
  92 typedef enum {
  93   ///
  94   /// Notification code for post PCI enuermation
  95   ///
  96   EnumInitPhaseAfterPciEnumeration = 0x20,
  97   ///
  98   /// Notification code before transfering control to the payload
  99   ///
 100   EnumInitPhaseReadyToBoot         = 0x40
 101 } FSP_INIT_PHASE;
 102
 103 typedef struct {
 104   ///
 105   /// Notification phase used for NotifyPhase API
 106   ///
 107   FSP_INIT_PHASE     Phase;
 108 } NOTIFY_PHASE_PARAMS;
 109
 110 typedef struct {
 111   ///
 112   /// Non-volatile storage buffer pointer.
 113   ///
 114   VOID               *NvsBufferPtr;
 115   ///
 116   /// Runtime buffer pointer
 117   ///
 118   VOID               *RtBufferPtr;
 119   ///
 120   /// Pointer to the HOB data structure defined in the PI specification
 121   ///
 122   VOID               **HobListPtr;
 123 } FSP_MEMORY_INIT_PARAMS;
 124
 125 #pragma pack()
 126
 127 /**
 128   This FSP API is called soon after coming out of reset and before memory and stack is
 129   available. This FSP API will load the microcode update, enable code caching for the
 130   region specified by the boot loader and also setup a temporary stack to be used until
 131   main memory is initialized.
 132
 133   A hardcoded stack can be set up with the following values, and the "esp" register
 134   initialized to point to this hardcoded stack.
 135   1. The return address where the FSP will return control after setting up a temporary
 136      stack.
 137   2. A pointer to the input parameter structure
 138
 139   However, since the stack is in ROM and not writeable, this FSP API cannot be called
 140   using the "call" instruction, but needs to be jumped to.
 141
 142   @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.
 143
 144   @retval EFI_SUCCESS           Temp RAM was initialized successfully.
 145   @retval EFI_INVALID_PARAMETER Input parameters are invalid..
 146   @retval EFI_NOT_FOUND         No valid microcode was found in the microcode region.
 147   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 148   @retval EFI_DEVICE_ERROR      Temp RAM initialization failed.
 149
 150   If this function is successful, the FSP initializes the ECX and EDX registers to point to
 151   a temporary but writeable memory range available to the boot loader and returns with
 152   FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
 153   memory range and EDX points to the end of the range. Boot loader is free to use the
 154   whole range described. Typically the boot loader can reload the ESP register to point
 155   to the end of this returned range so that it can be used as a standard stack.
 156 **/
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI *FSP_TEMP_RAM_INIT) (
 160   IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr
 161   );
 162
 163 /**
 164   This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,
 165   the CPU and the chipset to enable normal operation of these devices. This FSP API
 166   accepts a pointer to a data structure that will be platform dependent and defined for
 167   each FSP binary. This will be documented in the Integration Guide for each FSP
 168   release.
 169   The boot loader provides a continuation function as a parameter when calling FspInit.
 170   After FspInit completes its execution, it does not return to the boot loader from where
 171   it was called but instead returns control to the boot loader by calling the continuation
 172   function which is passed to FspInit as an argument.
 173
 174   @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.
 175
 176   @retval EFI_SUCCESS           FSP execution environment was initialized successfully.
 177   @retval EFI_INVALID_PARAMETER Input parameters are invalid.
 178   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 179   @retval EFI_DEVICE_ERROR      FSP initialization failed.
 180 **/
 181 typedef
 182 EFI_STATUS
 183 (EFIAPI *FSP_INIT) (
 184   IN OUT FSP_INIT_PARAMS *FspInitParamPtr
 185   );
 186
 187 #define FSP_FSP_INIT FSP_INIT
 188
 189 /**
 190   This FSP API is used to notify the FSP about the different phases in the boot process.
 191   This allows the FSP to take appropriate actions as needed during different initialization
 192   phases. The phases will be platform dependent and will be documented with the FSP
 193   release. The current FSP supports two notify phases:
 194     Post PCI enumeration
 195     Ready To Boot
 196
 197   @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
 198
 199   @retval EFI_SUCCESS           The notification was handled successfully.
 200   @retval EFI_UNSUPPORTED       The notification was not called in the proper order.
 201   @retval EFI_INVALID_PARAMETER The notification code is invalid.
 202 **/
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *FSP_NOTIFY_PHASE) (
 206   IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
 207   );
 208
 209 /**
 210   This FSP API is called after TempRamInit and initializes the memory.
 211   This FSP API accepts a pointer to a data structure that will be platform dependent
 212   and defined for each FSP binary. This will be documented in Integration guide with
 213   each FSP release.
 214   After FspMemInit completes its execution, it passes the pointer to the HobList and
 215   returns to the boot loader from where it was called. Bootloader is responsible to
 216   migrate it's stack and data to Memory.
 217   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
 218   complete the silicon initialization and provides bootloader an opportunity to get
 219   control after system memory is available and before the temporary RAM is torn down.
 220   These APIs are mutually exclusive to the FspInit API.
 221
 222   @param[in][out] FspMemoryInitParamPtr Address pointer to the FSP_MEMORY_INIT_PARAMS
 223                                         structure.
 224
 225   @retval EFI_SUCCESS           FSP execution environment was initialized successfully.
 226   @retval EFI_INVALID_PARAMETER Input parameters are invalid.
 227   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 228   @retval EFI_DEVICE_ERROR      FSP initialization failed.
 229 **/
 230 typedef
 231 EFI_STATUS
 232 (EFIAPI *FSP_MEMORY_INIT) (
 233   IN OUT FSP_MEMORY_INIT_PARAMS *FspMemoryInitParamPtr
 234   );
 235
 236
 237 /**
 238   This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
 239   memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
 240   that will be platform dependent and defined for each FSP binary. This will be
 241   documented in Integration Guide.
 242   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
 243   complete the silicon initialization and provides bootloader an opportunity to get
 244   control after system memory is available and before the temporary RAM is torn down.
 245   These APIs are mutually exclusive to the FspInit API.
 246
 247   @param[in][out] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
 248                                       This structure is normally defined in the Integration Guide.
 249                                       And if it is not defined in the Integration Guide, pass NULL.
 250
 251   @retval EFI_SUCCESS           FSP execution environment was initialized successfully.
 252   @retval EFI_INVALID_PARAMETER Input parameters are invalid.
 253   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 254   @retval EFI_DEVICE_ERROR      FSP initialization failed.
 255 **/
 256 typedef
 257 EFI_STATUS
 258 (EFIAPI *FSP_TEMP_RAM_EXIT) (
 259   IN OUT VOID *TempRamExitParamPtr
 260   );
 261
 262
 263 /**
 264   This FSP API is called after TempRamExit API.
 265   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
 266   silicon initialization.
 267   These APIs are mutually exclusive to the FspInit API.
 268
 269   @param[in][out] FspSiliconInitParamPtr Pointer to the Silicon Init parameters structure.
 270                                          This structure is normally defined in the Integration Guide.
 271                                          And if it is not defined in the Integration Guide, pass NULL.
 272
 273   @retval EFI_SUCCESS           FSP execution environment was initialized successfully.
 274   @retval EFI_INVALID_PARAMETER Input parameters are invalid.
 275   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 276   @retval EFI_DEVICE_ERROR      FSP initialization failed.
 277 **/
 278 typedef
 279 EFI_STATUS
 280 (EFIAPI *FSP_SILICON_INIT) (
 281   IN OUT VOID *FspSiliconInitParamPtr
 282   );
 283
 284 ///
 285 /// FSP API Return Status Code for backward compatibility with v1.0
 286 ///@{
 287 #define FSP_SUCCESS              EFI_SUCCESS
 288 #define FSP_INVALID_PARAMETER    EFI_INVALID_PARAMETER
 289 #define FSP_UNSUPPORTED          EFI_UNSUPPORTED
 290 #define FSP_NOT_READY            EFI_NOT_READY
 291 #define FSP_DEVICE_ERROR         EFI_DEVICE_ERROR
 292 #define FSP_OUT_OF_RESOURCES     EFI_OUT_OF_RESOURCES
 293 #define FSP_VOLUME_CORRUPTED     EFI_VOLUME_CORRUPTED
 294 #define FSP_NOT_FOUND            EFI_NOT_FOUND
 295 #define FSP_TIMEOUT              EFI_TIMEOUT
 296 #define FSP_ABORTED              EFI_ABORTED
 297 #define FSP_INCOMPATIBLE_VERSION EFI_INCOMPATIBLE_VERSION
 298 #define FSP_SECURITY_VIOLATION   EFI_SECURITY_VIOLATION
 299 #define FSP_CRC_ERROR            EFI_CRC_ERROR
 300 ///@}
 301
 302 #endif