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, 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 typedef UINT32 FSP_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 FSP_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 #pragma pack()
 111
 112 /**
 113   This FSP API is called soon after coming out of reset and before memory and stack is
 114   available. This FSP API will load the microcode update, enable code caching for the
 115   region specified by the boot loader and also setup a temporary stack to be used until
 116   main memory is initialized.
 117
 118   A hardcoded stack can be set up with the following values, and the "esp" register
 119   initialized to point to this hardcoded stack.
 120   1. The return address where the FSP will return control after setting up a temporary
 121      stack.
 122   2. A pointer to the input parameter structure
 123
 124   However, since the stack is in ROM and not writeable, this FSP API cannot be called
 125   using the "call" instruction, but needs to be jumped to.
 126
 127   @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.
 128
 129   @retval FSP_SUCCESS           Temp RAM was initialized successfully.
 130   @retval FSP_INVALID_PARAMETER Input parameters are invalid..
 131   @retval FSP_NOT_FOUND         No valid microcode was found in the microcode region.
 132   @retval FSP_UNSUPPORTED       The FSP calling conditions were not met.
 133   @retval FSP_DEVICE_ERROR      Temp RAM initialization failed.
 134
 135   If this function is successful, the FSP initializes the ECX and EDX registers to point to
 136   a temporary but writeable memory range available to the boot loader and returns with
 137   FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
 138   memory range and EDX points to the end of the range. Boot loader is free to use the
 139   whole range described. Typically the boot loader can reload the ESP register to point
 140   to the end of this returned range so that it can be used as a standard stack.
 141 **/
 142 typedef
 143 FSP_STATUS
 144 (FSPAPI *FSP_TEMP_RAM_INIT) (
 145   IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr
 146   );
 147
 148 /**
 149   This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,
 150   the CPU and the chipset to enable normal operation of these devices. This FSP API
 151   accepts a pointer to a data structure that will be platform dependent and defined for
 152   each FSP binary. This will be documented in the Integration Guide for each FSP
 153   release.
 154   The boot loader provides a continuation function as a parameter when calling FspInit.
 155   After FspInit completes its execution, it does not return to the boot loader from where
 156   it was called but instead returns control to the boot loader by calling the continuation
 157   function which is passed to FspInit as an argument.
 158
 159   @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.
 160
 161   @retval FSP_SUCCESS           FSP execution environment was initialized successfully.
 162   @retval FSP_INVALID_PARAMETER Input parameters are invalid.
 163   @retval FSP_UNSUPPORTED       The FSP calling conditions were not met.
 164   @retval FSP_DEVICE_ERROR      FSP initialization failed.
 165 **/
 166 typedef
 167 FSP_STATUS
 168 (FSPAPI *FSP_FSP_INIT) (
 169   IN OUT FSP_INIT_PARAMS *FspInitParamPtr
 170   );
 171
 172 /**
 173   This FSP API is used to notify the FSP about the different phases in the boot process.
 174   This allows the FSP to take appropriate actions as needed during different initialization
 175   phases. The phases will be platform dependent and will be documented with the FSP
 176   release. The current FSP supports two notify phases:
 177     Post PCI enumeration
 178     Ready To Boot
 179
 180   @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
 181
 182   @retval FSP_SUCCESS           The notification was handled successfully.
 183   @retval FSP_UNSUPPORTED       The notification was not called in the proper order.
 184   @retval FSP_INVALID_PARAMETER The notification code is invalid.
 185 **/
 186 typedef
 187 FSP_STATUS
 188 (FSPAPI *FSP_NOTIFY_PHASE) (
 189   IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
 190   );
 191
 192 ///
 193 /// FSP API Return Status Code
 194 ///
 195 #define FSP_SUCCESS              0x00000000
 196 #define FSP_INVALID_PARAMETER    0x80000002
 197 #define FSP_UNSUPPORTED          0x80000003
 198 #define FSP_NOT_READY            0x80000006
 199 #define FSP_DEVICE_ERROR         0x80000007
 200 #define FSP_OUT_OF_RESOURCES     0x80000009
 201 #define FSP_VOLUME_CORRUPTED     0x8000000A
 202 #define FSP_NOT_FOUND            0x8000000E
 203 #define FSP_TIMEOUT              0x80000012
 204 #define FSP_ABORTED              0x80000015
 205 #define FSP_INCOMPATIBLE_VERSION 0x80000010
 206 #define FSP_SECURITY_VIOLATION   0x8000001A
 207 #define FSP_CRC_ERROR            0x8000001B
 208
 209 #endif