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