IntelFsp2Pkg/Include/FspEas/FspApi.h

   1 /** @file
   2   Intel FSP API definition from Intel Firmware Support Package External
   3   Architecture Specification v2.0 - v2.2
   4
   5   Copyright (c) 2014 - 2020, 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 #include <Pi/PiStatusCode.h>
  14
  15 ///
  16 /// FSP Reset Status code
  17 /// These are defined in FSP EAS v2.0 section 11.2.2 - OEM Status Code
  18 /// @{
  19 #define FSP_STATUS_RESET_REQUIRED_COLD         0x40000001
  20 #define FSP_STATUS_RESET_REQUIRED_WARM         0x40000002
  21 #define FSP_STATUS_RESET_REQUIRED_3            0x40000003
  22 #define FSP_STATUS_RESET_REQUIRED_4            0x40000004
  23 #define FSP_STATUS_RESET_REQUIRED_5            0x40000005
  24 #define FSP_STATUS_RESET_REQUIRED_6            0x40000006
  25 #define FSP_STATUS_RESET_REQUIRED_7            0x40000007
  26 #define FSP_STATUS_RESET_REQUIRED_8            0x40000008
  27 /// @}
  28
  29 ///
  30 /// FSP Event related definition.
  31 ///
  32 #define FSP_EVENT_CODE   0xF5000000
  33 #define FSP_POST_CODE    (FSP_EVENT_CODE | 0x00F80000)
  34
  35 /*
  36   FSP may optionally include the capability of generating events messages to aid in the debugging of firmware issues.
  37   These events fall under three catagories: Error, Progress, and Debug. The event reporting mechanism follows the
  38   status code services described in section 6 and 7 of the PI Specification v1.7 Volume 3.
  39
  40   @param[in] Type                   Indicates the type of event being reported.
  41                                     See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_TYPE.
  42   @param[in] Value                  Describes the current status of a hardware or software entity.
  43                                     This includes information about the class and subclass that is used to classify the entity as well as an operation.
  44                                     For progress events, the operation is the current activity. For error events, it is the exception.
  45                                     For debug events, it is not defined at this time.
  46                                     See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_VALUE.
  47   @param[in] Instance               The enumeration of a hardware or software entity within the system.
  48                                     A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them.
  49                                     An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant.
  50                                     Valid instance numbers start with 1.
  51   @param[in] *CallerId              This parameter can be used to identify the sub-module within the FSP generating the event.
  52                                     This parameter may be NULL.
  53   @param[in] *Data                  This optional parameter may be used to pass additional data. The contents can have event-specific data.
  54                                     For example, the FSP provides a EFI_STATUS_CODE_STRING_DATA instance to this parameter when sending debug messages.
  55                                     This parameter is NULL when no additional data is provided.
  56
  57   @retval EFI_SUCCESS               The event was handled successfully.
  58   @retval EFI_INVALID_PARAMETER     Input parameters are invalid.
  59   @retval EFI_DEVICE_ERROR          The event handler failed.
  60 */
  61 typedef
  62 EFI_STATUS
  63 (EFIAPI *FSP_EVENT_HANDLER) (
  64   IN          EFI_STATUS_CODE_TYPE   Type,
  65   IN          EFI_STATUS_CODE_VALUE  Value,
  66   IN          UINT32                 Instance,
  67   IN OPTIONAL EFI_GUID               *CallerId,
  68   IN OPTIONAL EFI_STATUS_CODE_DATA   *Data
  69   );
  70
  71 /*
  72   Handler for FSP-T debug log messages, provided by the bootloader.
  73
  74   @param[in] DebugMessage           A pointer to the debug message to be written to the log.
  75   @param[in] MessageLength          Number of bytes to written to the debug log.
  76
  77   @retval UINT32                    The return value indicates the number of bytes actually written to
  78                                     the debug log. If the return value is less than MessageLength,
  79                                     an error occurred.
  80 */
  81 typedef
  82 UINT32
  83 (EFIAPI *FSP_DEBUG_HANDLER) (
  84   IN CHAR8*                 DebugMessage,
  85   IN UINT32                 MessageLength
  86   );
  87
  88 #pragma pack(1)
  89 ///
  90 /// FSP_UPD_HEADER Configuration.
  91 ///
  92 typedef struct {
  93   ///
  94   /// UPD Region Signature. This signature will be
  95   /// "XXXXXX_T" for FSP-T
  96   /// "XXXXXX_M" for FSP-M
  97   /// "XXXXXX_S" for FSP-S
  98   /// Where XXXXXX is an unique signature
  99   ///
 100   UINT64                      Signature;
 101   ///
 102   /// Revision of the Data structure. For FSP v2.0 value is 1.
 103   ///
 104   UINT8                       Revision;
 105   UINT8                       Reserved[23];
 106 } FSP_UPD_HEADER;
 107
 108 ///
 109 /// FSPM_ARCH_UPD Configuration.
 110 ///
 111 typedef struct {
 112   ///
 113   /// Revision of the structure. For FSP v2.0 value is 1.
 114   ///
 115   UINT8                       Revision;
 116   UINT8                       Reserved[3];
 117   ///
 118   /// Pointer to the non-volatile storage (NVS) data buffer.
 119   /// If it is NULL it indicates the NVS data is not available.
 120   ///
 121   VOID                        *NvsBufferPtr;
 122   ///
 123   /// Pointer to the temporary stack base address to be
 124   /// consumed inside FspMemoryInit() API.
 125   ///
 126   VOID                        *StackBase;
 127   ///
 128   /// Temporary stack size to be consumed inside
 129   /// FspMemoryInit() API.
 130   ///
 131   UINT32                      StackSize;
 132   ///
 133   /// Size of memory to be reserved by FSP below "top
 134   /// of low usable memory" for bootloader usage.
 135   ///
 136   UINT32                      BootLoaderTolumSize;
 137   ///
 138   /// Current boot mode.
 139   ///
 140   UINT32                      BootMode;
 141   ///
 142   /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.
 143   /// This value is only valid if Revision is >= 2.
 144   ///
 145   FSP_EVENT_HANDLER           *FspEventHandler;
 146   UINT8                       Reserved1[4];
 147 } FSPM_ARCH_UPD;
 148
 149 ///
 150 /// FSPT_UPD_COMMON Configuration.
 151 ///
 152 typedef struct {
 153   ///
 154   /// FSP_UPD_HEADER Configuration.
 155   ///
 156   FSP_UPD_HEADER              FspUpdHeader;
 157 } FSPT_UPD_COMMON;
 158
 159 ///
 160 /// FSPM_UPD_COMMON Configuration.
 161 ///
 162 typedef struct {
 163   ///
 164   /// FSP_UPD_HEADER Configuration.
 165   ///
 166   FSP_UPD_HEADER              FspUpdHeader;
 167   ///
 168   /// FSPM_ARCH_UPD Configuration.
 169   ///
 170   FSPM_ARCH_UPD               FspmArchUpd;
 171 } FSPM_UPD_COMMON;
 172
 173 ///
 174 /// FSPS_UPD_COMMON Configuration.
 175 ///
 176 typedef struct {
 177   ///
 178   /// FSP_UPD_HEADER Configuration.
 179   ///
 180   FSP_UPD_HEADER              FspUpdHeader;
 181 } FSPS_UPD_COMMON;
 182
 183 ///
 184 /// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE.
 185 ///
 186 typedef enum {
 187   ///
 188   /// This stage is notified when the bootloader completes the
 189   /// PCI enumeration and the resource allocation for the
 190   /// PCI devices is complete.
 191   ///
 192   EnumInitPhaseAfterPciEnumeration = 0x20,
 193   ///
 194   /// This stage is notified just before the bootloader hand-off
 195   /// to the OS loader.
 196   ///
 197   EnumInitPhaseReadyToBoot         = 0x40,
 198   ///
 199   /// This stage is notified just before the firmware/Preboot
 200   /// environment transfers management of all system resources
 201   /// to the OS or next level execution environment.
 202   ///
 203   EnumInitPhaseEndOfFirmware       = 0xF0
 204 } FSP_INIT_PHASE;
 205
 206 ///
 207 /// Definition of NOTIFY_PHASE_PARAMS.
 208 ///
 209 typedef struct {
 210   ///
 211   /// Notification phase used for NotifyPhase API
 212   ///
 213   FSP_INIT_PHASE     Phase;
 214 } NOTIFY_PHASE_PARAMS;
 215
 216 ///
 217 /// Action definition for FspMultiPhaseSiInit API
 218 ///
 219 typedef enum {
 220   EnumMultiPhaseGetNumberOfPhases  = 0x0,
 221   EnumMultiPhaseExecutePhase       = 0x1
 222 } FSP_MULTI_PHASE_ACTION;
 223
 224 ///
 225 /// Data structure returned by FSP when bootloader calling
 226 /// FspMultiPhaseSiInit API with action 0 (EnumMultiPhaseGetNumberOfPhases)
 227 ///
 228 typedef struct {
 229   UINT32                         NumberOfPhases;
 230   UINT32                         PhasesExecuted;
 231 } FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS;
 232
 233 ///
 234 /// FspMultiPhaseSiInit function parameter.
 235 ///
 236 /// For action 0 (EnumMultiPhaseGetNumberOfPhases):
 237 ///   - PhaseIndex must be 0.
 238 ///   - MultiPhaseParamPtr should point to an instance of FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS.
 239 ///
 240 /// For action 1 (EnumMultiPhaseExecutePhase):
 241 ///   - PhaseIndex will be the phase that will be executed by FSP.
 242 ///   - MultiPhaseParamPtr shall be NULL.
 243 ///
 244 typedef struct {
 245   IN     FSP_MULTI_PHASE_ACTION  MultiPhaseAction;
 246   IN     UINT32                  PhaseIndex;
 247   IN OUT VOID                    *MultiPhaseParamPtr;
 248 } FSP_MULTI_PHASE_PARAMS;
 249
 250 #pragma pack()
 251
 252 /**
 253   This FSP API is called soon after coming out of reset and before memory and stack is
 254   available. This FSP API will load the microcode update, enable code caching for the
 255   region specified by the boot loader and also setup a temporary stack to be used until
 256   main memory is initialized.
 257
 258   A hardcoded stack can be set up with the following values, and the "esp" register
 259   initialized to point to this hardcoded stack.
 260   1. The return address where the FSP will return control after setting up a temporary
 261      stack.
 262   2. A pointer to the input parameter structure
 263
 264   However, since the stack is in ROM and not writeable, this FSP API cannot be called
 265   using the "call" instruction, but needs to be jumped to.
 266
 267   @param[in] FsptUpdDataPtr     Pointer to the FSPT_UPD data structure.
 268
 269   @retval EFI_SUCCESS           Temporary RAM was initialized successfully.
 270   @retval EFI_INVALID_PARAMETER Input parameters are invalid.
 271   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.
 272   @retval EFI_DEVICE_ERROR      Temp RAM initialization failed.
 273
 274   If this function is successful, the FSP initializes the ECX and EDX registers to point to
 275   a temporary but writeable memory range available to the boot loader and returns with
 276   FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
 277   memory range and EDX points to the end of the range. Boot loader is free to use the
 278   whole range described. Typically the boot loader can reload the ESP register to point
 279   to the end of this returned range so that it can be used as a standard stack.
 280 **/
 281 typedef
 282 EFI_STATUS
 283 (EFIAPI *FSP_TEMP_RAM_INIT) (
 284   IN  VOID    *FsptUpdDataPtr
 285   );
 286
 287 /**
 288   This FSP API is used to notify the FSP about the different phases in the boot process.
 289   This allows the FSP to take appropriate actions as needed during different initialization
 290   phases. The phases will be platform dependent and will be documented with the FSP
 291   release. The current FSP supports two notify phases:
 292     Post PCI enumeration
 293     Ready To Boot
 294
 295   @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
 296
 297   @retval EFI_SUCCESS           The notification was handled successfully.
 298   @retval EFI_UNSUPPORTED       The notification was not called in the proper order.
 299   @retval EFI_INVALID_PARAMETER The notification code is invalid.
 300 **/
 301 typedef
 302 EFI_STATUS
 303 (EFIAPI *FSP_NOTIFY_PHASE) (
 304   IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
 305   );
 306
 307 /**
 308   This FSP API is called after TempRamInit and initializes the memory.
 309   This FSP API accepts a pointer to a data structure that will be platform dependent
 310   and defined for each FSP binary. This will be documented in Integration guide with
 311   each FSP release.
 312   After FspMemInit completes its execution, it passes the pointer to the HobList and
 313   returns to the boot loader from where it was called. BootLoader is responsible to
 314   migrate its stack and data to Memory.
 315   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
 316   complete the silicon initialization and provides bootloader an opportunity to get
 317   control after system memory is available and before the temporary RAM is torn down.
 318
 319   @param[in]  FspmUpdDataPtr          Pointer to the FSPM_UPD data structure.
 320   @param[out] HobListPtr              Pointer to receive the address of the HOB list.
 321
 322   @retval EFI_SUCCESS                 FSP execution environment was initialized successfully.
 323   @retval EFI_INVALID_PARAMETER       Input parameters are invalid.
 324   @retval EFI_UNSUPPORTED             The FSP calling conditions were not met.
 325   @retval EFI_DEVICE_ERROR            FSP initialization failed.
 326   @retval EFI_OUT_OF_RESOURCES        Stack range requested by FSP is not met.
 327   @retval FSP_STATUS_RESET_REQUIREDx  A reset is reuired. These status codes will not be returned during S3.
 328 **/
 329 typedef
 330 EFI_STATUS
 331 (EFIAPI *FSP_MEMORY_INIT) (
 332   IN  VOID    *FspmUpdDataPtr,
 333   OUT VOID    **HobListPtr
 334   );
 335
 336
 337 /**
 338   This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
 339   memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
 340   that will be platform dependent and defined for each FSP binary. This will be
 341   documented in Integration Guide.
 342   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
 343   complete the silicon initialization and provides bootloader an opportunity to get
 344   control after system memory is available and before the temporary RAM is torn down.
 345
 346   @param[in] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
 347                                  This structure is normally defined in the Integration Guide.
 348                                  And if it is not defined in the Integration Guide, pass NULL.
 349
 350   @retval EFI_SUCCESS            FSP execution environment was initialized successfully.
 351   @retval EFI_INVALID_PARAMETER  Input parameters are invalid.
 352   @retval EFI_UNSUPPORTED        The FSP calling conditions were not met.
 353   @retval EFI_DEVICE_ERROR       FSP initialization failed.
 354 **/
 355 typedef
 356 EFI_STATUS
 357 (EFIAPI *FSP_TEMP_RAM_EXIT) (
 358   IN  VOID    *TempRamExitParamPtr
 359   );
 360
 361
 362 /**
 363   This FSP API is called after TempRamExit API.
 364   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
 365   silicon initialization.
 366
 367   @param[in] FspsUpdDataPtr     Pointer to the FSPS_UPD data structure.
 368                                 If NULL, FSP will use the default parameters.
 369
 370   @retval EFI_SUCCESS                 FSP execution environment was initialized successfully.
 371   @retval EFI_INVALID_PARAMETER       Input parameters are invalid.
 372   @retval EFI_UNSUPPORTED             The FSP calling conditions were not met.
 373   @retval EFI_DEVICE_ERROR            FSP initialization failed.
 374   @retval FSP_STATUS_RESET_REQUIREDx  A reset is required. These status codes will not be returned during S3.
 375 **/
 376 typedef
 377 EFI_STATUS
 378 (EFIAPI *FSP_SILICON_INIT) (
 379   IN  VOID    *FspsUpdDataPtr
 380   );
 381
 382 /**
 383   This FSP API is expected to be called after FspSiliconInit but before FspNotifyPhase.
 384   This FSP API provides multi-phase silicon initialization; which brings greater modularity
 385   beyond the existing FspSiliconInit() API. Increased modularity is achieved by adding an
 386   extra API to FSP-S. This allows the bootloader to add board specific initialization steps
 387   throughout the SiliconInit flow as needed.
 388
 389   @param[in,out] FSP_MULTI_PHASE_PARAMS   For action - EnumMultiPhaseGetNumberOfPhases:
 390                                             FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr will contain
 391                                             how many phases supported by FSP.
 392                                           For action - EnumMultiPhaseExecutePhase:
 393                                             FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr shall be NULL.
 394   @retval EFI_SUCCESS                     FSP execution environment was initialized successfully.
 395   @retval EFI_INVALID_PARAMETER           Input parameters are invalid.
 396   @retval EFI_UNSUPPORTED                 The FSP calling conditions were not met.
 397   @retval EFI_DEVICE_ERROR                FSP initialization failed.
 398   @retval FSP_STATUS_RESET_REQUIREDx      A reset is required. These status codes will not be returned during S3.
 399 **/
 400 typedef
 401 EFI_STATUS
 402 (EFIAPI *FSP_MULTI_PHASE_SI_INIT) (
 403   IN FSP_MULTI_PHASE_PARAMS     *MultiPhaseSiInitParamPtr
 404 );
 405
 406 #endif