IntelFsp2Pkg/Include/FspEas/FspApi.h

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