IntelFspPkg/Include/FspApi.h

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