/** @file\r
Intel FSP API definition from Intel Firmware Support Package External\r
- Architecture Specification v2.0.\r
+ Architecture Specification v2.0 - v2.2\r
\r
- Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ Copyright (c) 2014 - 2022, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
#ifndef _FSP_API_H_\r
#define _FSP_API_H_\r
\r
+#include <Pi/PiStatusCode.h>\r
+#include <Base.h>\r
+\r
///\r
/// FSP Reset Status code\r
-/// These are defined in FSP EAS v2.0 section 11.2.2 - OEM Status Code\r
+/// These are defined in FSP EAS v2.4 section 13.2.2 - OEM Status Code\r
/// @{\r
-#define FSP_STATUS_RESET_REQUIRED_COLD 0x40000001\r
-#define FSP_STATUS_RESET_REQUIRED_WARM 0x40000002\r
-#define FSP_STATUS_RESET_REQUIRED_3 0x40000003\r
-#define FSP_STATUS_RESET_REQUIRED_4 0x40000004\r
-#define FSP_STATUS_RESET_REQUIRED_5 0x40000005\r
-#define FSP_STATUS_RESET_REQUIRED_6 0x40000006\r
-#define FSP_STATUS_RESET_REQUIRED_7 0x40000007\r
-#define FSP_STATUS_RESET_REQUIRED_8 0x40000008\r
+\r
+#define ENCODE_RESET_REQUEST(ResetType) \\r
+ ((EFI_STATUS)((MAX_BIT >> 1) | (ResetType)))\r
+#define FSP_STATUS_RESET_REQUIRED_COLD ENCODE_RESET_REQUEST(1)\r
+#define FSP_STATUS_RESET_REQUIRED_WARM ENCODE_RESET_REQUEST(2)\r
+#define FSP_STATUS_RESET_REQUIRED_3 ENCODE_RESET_REQUEST(3)\r
+#define FSP_STATUS_RESET_REQUIRED_4 ENCODE_RESET_REQUEST(4)\r
+#define FSP_STATUS_RESET_REQUIRED_5 ENCODE_RESET_REQUEST(5)\r
+#define FSP_STATUS_RESET_REQUIRED_6 ENCODE_RESET_REQUEST(6)\r
+#define FSP_STATUS_RESET_REQUIRED_7 ENCODE_RESET_REQUEST(7)\r
+#define FSP_STATUS_RESET_REQUIRED_8 ENCODE_RESET_REQUEST(8)\r
+#define FSP_STATUS_VARIABLE_REQUEST ENCODE_RESET_REQUEST(10)\r
/// @}\r
\r
+///\r
+/// FSP Event related definition.\r
+///\r
+#define FSP_EVENT_CODE 0xF5000000\r
+#define FSP_POST_CODE (FSP_EVENT_CODE | 0x00F80000)\r
+\r
+/*\r
+ FSP may optionally include the capability of generating events messages to aid in the debugging of firmware issues.\r
+ These events fall under three catagories: Error, Progress, and Debug. The event reporting mechanism follows the\r
+ status code services described in section 6 and 7 of the PI Specification v1.7 Volume 3.\r
+\r
+ @param[in] Type Indicates the type of event being reported.\r
+ See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_TYPE.\r
+ @param[in] Value Describes the current status of a hardware or software entity.\r
+ This includes information about the class and subclass that is used to classify the entity as well as an operation.\r
+ For progress events, the operation is the current activity. For error events, it is the exception.\r
+ For debug events, it is not defined at this time.\r
+ See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_VALUE.\r
+ @param[in] Instance The enumeration of a hardware or software entity within the system.\r
+ A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them.\r
+ An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant.\r
+ Valid instance numbers start with 1.\r
+ @param[in] *CallerId This parameter can be used to identify the sub-module within the FSP generating the event.\r
+ This parameter may be NULL.\r
+ @param[in] *Data This optional parameter may be used to pass additional data. The contents can have event-specific data.\r
+ For example, the FSP provides a EFI_STATUS_CODE_STRING_DATA instance to this parameter when sending debug messages.\r
+ This parameter is NULL when no additional data is provided.\r
+\r
+ @retval EFI_SUCCESS The event was handled successfully.\r
+ @retval EFI_INVALID_PARAMETER Input parameters are invalid.\r
+ @retval EFI_DEVICE_ERROR The event handler failed.\r
+*/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *FSP_EVENT_HANDLER)(\r
+ IN EFI_STATUS_CODE_TYPE Type,\r
+ IN EFI_STATUS_CODE_VALUE Value,\r
+ IN UINT32 Instance,\r
+ IN OPTIONAL EFI_GUID *CallerId,\r
+ IN OPTIONAL EFI_STATUS_CODE_DATA *Data\r
+ );\r
+\r
+/*\r
+ Handler for FSP-T debug log messages, provided by the bootloader.\r
+\r
+ @param[in] DebugMessage A pointer to the debug message to be written to the log.\r
+ @param[in] MessageLength Number of bytes to written to the debug log.\r
+\r
+ @retval UINT32 The return value indicates the number of bytes actually written to\r
+ the debug log. If the return value is less than MessageLength,\r
+ an error occurred.\r
+*/\r
+typedef\r
+UINT32\r
+(EFIAPI *FSP_DEBUG_HANDLER)(\r
+ IN CHAR8 *DebugMessage,\r
+ IN UINT32 MessageLength\r
+ );\r
+\r
#pragma pack(1)\r
///\r
/// FSP_UPD_HEADER Configuration.\r
/// "XXXXXX_S" for FSP-S\r
/// Where XXXXXX is an unique signature\r
///\r
- UINT64 Signature;\r
+ UINT64 Signature;\r
///\r
- /// Revision of the Data structure. For FSP v2.0 value is 1.\r
+ /// Revision of the Data structure.\r
+ /// For FSP spec 2.0/2.1 value is 1.\r
+ /// For FSP spec 2.2 value is 2.\r
///\r
- UINT8 Revision;\r
- UINT8 Reserved[23];\r
+ UINT8 Revision;\r
+ UINT8 Reserved[23];\r
} FSP_UPD_HEADER;\r
\r
+///\r
+/// FSPT_ARCH_UPD Configuration.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// Revision of the structure is 1 for this version of the specification.\r
+ ///\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
+ ///\r
+ /// Length of the structure in bytes. The current value for this field is 32.\r
+ ///\r
+ UINT32 Length;\r
+ ///\r
+ /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages\r
+ /// occurring during FSP execution.\r
+ ///\r
+ FSP_DEBUG_HANDLER FspDebugHandler;\r
+ UINT8 Reserved1[20];\r
+} FSPT_ARCH_UPD;\r
+\r
+///\r
+/// FSPT_ARCH2_UPD Configuration.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// Revision of the structure is 2 for this version of the specification.\r
+ ///\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
+ ///\r
+ /// Length of the structure in bytes. The current value for this field is 32.\r
+ ///\r
+ UINT32 Length;\r
+ ///\r
+ /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages\r
+ /// occurring during FSP execution.\r
+ ///\r
+ EFI_PHYSICAL_ADDRESS FspDebugHandler;\r
+ UINT8 Reserved1[16];\r
+} FSPT_ARCH2_UPD;\r
+\r
///\r
/// FSPM_ARCH_UPD Configuration.\r
///\r
///\r
/// Revision of the structure. For FSP v2.0 value is 1.\r
///\r
- UINT8 Revision;\r
- UINT8 Reserved[3];\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
///\r
/// Pointer to the non-volatile storage (NVS) data buffer.\r
/// If it is NULL it indicates the NVS data is not available.\r
///\r
- VOID *NvsBufferPtr;\r
+ VOID *NvsBufferPtr;\r
///\r
/// Pointer to the temporary stack base address to be\r
/// consumed inside FspMemoryInit() API.\r
///\r
- VOID *StackBase;\r
+ VOID *StackBase;\r
///\r
/// Temporary stack size to be consumed inside\r
/// FspMemoryInit() API.\r
///\r
- UINT32 StackSize;\r
+ UINT32 StackSize;\r
///\r
/// Size of memory to be reserved by FSP below "top\r
/// of low usable memory" for bootloader usage.\r
///\r
- UINT32 BootLoaderTolumSize;\r
+ UINT32 BootLoaderTolumSize;\r
///\r
/// Current boot mode.\r
///\r
- UINT32 BootMode;\r
- UINT8 Reserved1[8];\r
+ UINT32 BootMode;\r
+ ///\r
+ /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.\r
+ /// This value is only valid if Revision is >= 2.\r
+ ///\r
+ FSP_EVENT_HANDLER *FspEventHandler;\r
+ UINT8 Reserved1[4];\r
} FSPM_ARCH_UPD;\r
\r
+///\r
+/// FSPM_ARCH2_UPD Configuration.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// Revision of the structure is 3 for this version of the specification.\r
+ ///\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
+ ///\r
+ /// Length of the structure in bytes. The current value for this field is 64.\r
+ ///\r
+ UINT32 Length;\r
+ ///\r
+ /// Pointer to the temporary stack base address to be\r
+ /// consumed inside FspMemoryInit() API.\r
+ ///\r
+ EFI_PHYSICAL_ADDRESS StackBase;\r
+ ///\r
+ /// Temporary stack size to be consumed inside\r
+ /// FspMemoryInit() API.\r
+ ///\r
+ UINT64 StackSize;\r
+ ///\r
+ /// Size of memory to be reserved by FSP below "top\r
+ /// of low usable memory" for bootloader usage.\r
+ ///\r
+ UINT32 BootLoaderTolumSize;\r
+ ///\r
+ /// Current boot mode.\r
+ ///\r
+ UINT32 BootMode;\r
+ ///\r
+ /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.\r
+ /// This value is only valid if Revision is >= 2.\r
+ ///\r
+ EFI_PHYSICAL_ADDRESS FspEventHandler;\r
+ UINT8 Reserved1[24];\r
+} FSPM_ARCH2_UPD;\r
+\r
+///\r
+/// FSPS_ARCH_UPD Configuration.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// Revision of the structure is 1 for this version of the specification.\r
+ ///\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
+ ///\r
+ /// Length of the structure in bytes. The current value for this field is 32.\r
+ ///\r
+ UINT32 Length;\r
+ ///\r
+ /// FspEventHandler Optional event handler for the bootloader to be informed of events\r
+ /// occurring during FSP execution.\r
+ ///\r
+ FSP_EVENT_HANDLER FspEventHandler;\r
+ ///\r
+ /// A FSP binary may optionally implement multi-phase silicon initialization,\r
+ /// This is only supported if the FspMultiPhaseSiInitEntryOffset field in FSP_INFO_HEADER\r
+ /// is non-zero.\r
+ /// To enable multi-phase silicon initialization, the bootloader must set\r
+ /// EnableMultiPhaseSiliconInit to a non-zero value.\r
+ ///\r
+ UINT8 EnableMultiPhaseSiliconInit;\r
+ UINT8 Reserved1[19];\r
+} FSPS_ARCH_UPD;\r
+\r
+///\r
+/// FSPS_ARCH2_UPD Configuration.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// Revision of the structure is 2 for this version of the specification.\r
+ ///\r
+ UINT8 Revision;\r
+ UINT8 Reserved[3];\r
+ ///\r
+ /// Length of the structure in bytes. The current value for this field is 32.\r
+ ///\r
+ UINT32 Length;\r
+ ///\r
+ /// FspEventHandler Optional event handler for the bootloader to be informed of events\r
+ /// occurring during FSP execution.\r
+ ///\r
+ EFI_PHYSICAL_ADDRESS FspEventHandler;\r
+ UINT8 Reserved1[16];\r
+} FSPS_ARCH2_UPD;\r
+\r
///\r
/// FSPT_UPD_COMMON Configuration.\r
///\r
///\r
/// FSP_UPD_HEADER Configuration.\r
///\r
- FSP_UPD_HEADER FspUpdHeader;\r
+ FSP_UPD_HEADER FspUpdHeader;\r
} FSPT_UPD_COMMON;\r
\r
+///\r
+/// FSPT_UPD_COMMON Configuration for FSP spec. 2.2 and above.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// FSP_UPD_HEADER Configuration.\r
+ ///\r
+ FSP_UPD_HEADER FspUpdHeader;\r
+\r
+ ///\r
+ /// FSPT_ARCH_UPD Configuration.\r
+ ///\r
+ FSPT_ARCH_UPD FsptArchUpd;\r
+} FSPT_UPD_COMMON_FSP22;\r
+\r
+///\r
+/// FSPT_UPD_COMMON Configuration for FSP spec. 2.4 and above.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// FSP_UPD_HEADER Configuration.\r
+ ///\r
+ FSP_UPD_HEADER FspUpdHeader;\r
+\r
+ ///\r
+ /// FSPT_ARCH2_UPD Configuration.\r
+ ///\r
+ FSPT_ARCH2_UPD FsptArchUpd;\r
+} FSPT_UPD_COMMON_FSP24;\r
+\r
///\r
/// FSPM_UPD_COMMON Configuration.\r
///\r
///\r
/// FSP_UPD_HEADER Configuration.\r
///\r
- FSP_UPD_HEADER FspUpdHeader;\r
+ FSP_UPD_HEADER FspUpdHeader;\r
///\r
/// FSPM_ARCH_UPD Configuration.\r
///\r
- FSPM_ARCH_UPD FspmArchUpd;\r
+ FSPM_ARCH_UPD FspmArchUpd;\r
} FSPM_UPD_COMMON;\r
\r
+///\r
+/// FSPM_UPD_COMMON Configuration for FSP spec. 2.4 and above.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// FSP_UPD_HEADER Configuration.\r
+ ///\r
+ FSP_UPD_HEADER FspUpdHeader;\r
+ ///\r
+ /// FSPM_ARCH2_UPD Configuration.\r
+ ///\r
+ FSPM_ARCH2_UPD FspmArchUpd;\r
+} FSPM_UPD_COMMON_FSP24;\r
+\r
///\r
/// FSPS_UPD_COMMON Configuration.\r
///\r
///\r
/// FSP_UPD_HEADER Configuration.\r
///\r
- FSP_UPD_HEADER FspUpdHeader;\r
+ FSP_UPD_HEADER FspUpdHeader;\r
} FSPS_UPD_COMMON;\r
\r
+///\r
+/// FSPS_UPD_COMMON Configuration for FSP spec. 2.2 and above.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// FSP_UPD_HEADER Configuration.\r
+ ///\r
+ FSP_UPD_HEADER FspUpdHeader;\r
+\r
+ ///\r
+ /// FSPS_ARCH_UPD Configuration.\r
+ ///\r
+ FSPS_ARCH_UPD FspsArchUpd;\r
+} FSPS_UPD_COMMON_FSP22;\r
+\r
+///\r
+/// FSPS_UPD_COMMON Configuration for FSP spec. 2.4 and above.\r
+///\r
+typedef struct {\r
+ ///\r
+ /// FSP_UPD_HEADER Configuration.\r
+ ///\r
+ FSP_UPD_HEADER FspUpdHeader;\r
+\r
+ ///\r
+ /// FSPS_ARCH2_UPD Configuration.\r
+ ///\r
+ FSPS_ARCH2_UPD FspsArchUpd;\r
+} FSPS_UPD_COMMON_FSP24;\r
+\r
///\r
/// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE.\r
///\r
/// This stage is notified just before the bootloader hand-off\r
/// to the OS loader.\r
///\r
- EnumInitPhaseReadyToBoot = 0x40,\r
+ EnumInitPhaseReadyToBoot = 0x40,\r
///\r
/// This stage is notified just before the firmware/Preboot\r
/// environment transfers management of all system resources\r
/// to the OS or next level execution environment.\r
///\r
- EnumInitPhaseEndOfFirmware = 0xF0\r
+ EnumInitPhaseEndOfFirmware = 0xF0\r
} FSP_INIT_PHASE;\r
\r
///\r
///\r
/// Notification phase used for NotifyPhase API\r
///\r
- FSP_INIT_PHASE Phase;\r
+ FSP_INIT_PHASE Phase;\r
} NOTIFY_PHASE_PARAMS;\r
\r
+///\r
+/// Action definition for FspMultiPhaseSiInit API\r
+///\r
+typedef enum {\r
+ EnumMultiPhaseGetNumberOfPhases = 0x0,\r
+ EnumMultiPhaseExecutePhase = 0x1\r
+} FSP_MULTI_PHASE_ACTION;\r
+\r
+///\r
+/// Data structure returned by FSP when bootloader calling\r
+/// FspMultiPhaseSiInit API with action 0 (EnumMultiPhaseGetNumberOfPhases)\r
+///\r
+typedef struct {\r
+ UINT32 NumberOfPhases;\r
+ UINT32 PhasesExecuted;\r
+} FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS;\r
+\r
+///\r
+/// FspMultiPhaseSiInit function parameter.\r
+///\r
+/// For action 0 (EnumMultiPhaseGetNumberOfPhases):\r
+/// - PhaseIndex must be 0.\r
+/// - MultiPhaseParamPtr should point to an instance of FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS.\r
+///\r
+/// For action 1 (EnumMultiPhaseExecutePhase):\r
+/// - PhaseIndex will be the phase that will be executed by FSP.\r
+/// - MultiPhaseParamPtr shall be NULL.\r
+///\r
+typedef struct {\r
+ IN FSP_MULTI_PHASE_ACTION MultiPhaseAction;\r
+ IN UINT32 PhaseIndex;\r
+ IN OUT VOID *MultiPhaseParamPtr;\r
+} FSP_MULTI_PHASE_PARAMS;\r
+\r
#pragma pack()\r
\r
/**\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *FSP_TEMP_RAM_INIT) (\r
+(EFIAPI *FSP_TEMP_RAM_INIT)(\r
IN VOID *FsptUpdDataPtr\r
);\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *FSP_NOTIFY_PHASE) (\r
+(EFIAPI *FSP_NOTIFY_PHASE)(\r
IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr\r
);\r
\r
each FSP release.\r
After FspMemInit completes its execution, it passes the pointer to the HobList and\r
returns to the boot loader from where it was called. BootLoader is responsible to\r
- migrate it's stack and data to Memory.\r
+ migrate its stack and data to Memory.\r
FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to\r
complete the silicon initialization and provides bootloader an opportunity to get\r
control after system memory is available and before the temporary RAM is torn down.\r
\r
- @param[in] FspmUpdDataPtr Pointer to the FSPM_UPD data sructure.\r
+ @param[in] FspmUpdDataPtr Pointer to the FSPM_UPD data structure.\r
@param[out] HobListPtr Pointer to receive the address of the HOB list.\r
\r
@retval EFI_SUCCESS FSP execution environment was initialized successfully.\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *FSP_MEMORY_INIT) (\r
+(EFIAPI *FSP_MEMORY_INIT)(\r
IN VOID *FspmUpdDataPtr,\r
OUT VOID **HobListPtr\r
);\r
\r
-\r
/**\r
This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary\r
memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *FSP_TEMP_RAM_EXIT) (\r
+(EFIAPI *FSP_TEMP_RAM_EXIT)(\r
IN VOID *TempRamExitParamPtr\r
);\r
\r
-\r
/**\r
This FSP API is called after TempRamExit API.\r
FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the\r
@retval EFI_INVALID_PARAMETER Input parameters are invalid.\r
@retval EFI_UNSUPPORTED The FSP calling conditions were not met.\r
@retval EFI_DEVICE_ERROR FSP initialization failed.\r
- @retval FSP_STATUS_RESET_REQUIREDx A reset is reuired. These status codes will not be returned during S3.\r
+ @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *FSP_SILICON_INIT) (\r
+(EFIAPI *FSP_SILICON_INIT)(\r
IN VOID *FspsUpdDataPtr\r
);\r
\r
+/**\r
+ This FSP API is expected to be called after FspSiliconInit but before FspNotifyPhase.\r
+ This FSP API provides multi-phase silicon initialization; which brings greater modularity\r
+ beyond the existing FspSiliconInit() API. Increased modularity is achieved by adding an\r
+ extra API to FSP-S. This allows the bootloader to add board specific initialization steps\r
+ throughout the SiliconInit flow as needed.\r
+\r
+ @param[in,out] FSP_MULTI_PHASE_PARAMS For action - EnumMultiPhaseGetNumberOfPhases:\r
+ FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr will contain\r
+ how many phases supported by FSP.\r
+ For action - EnumMultiPhaseExecutePhase:\r
+ FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr shall be NULL.\r
+ @retval EFI_SUCCESS FSP execution environment was initialized successfully.\r
+ @retval EFI_INVALID_PARAMETER Input parameters are invalid.\r
+ @retval EFI_UNSUPPORTED The FSP calling conditions were not met.\r
+ @retval EFI_DEVICE_ERROR FSP initialization failed.\r
+ @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *FSP_MULTI_PHASE_SI_INIT)(\r
+ IN FSP_MULTI_PHASE_PARAMS *MultiPhaseSiInitParamPtr\r
+ );\r
+\r
#endif\r
projects / mirror_edk2.git / blobdiff