/** @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 - 2019, 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
+\r
///\r
/// FSP Reset Status code\r
/// These are defined in FSP EAS v2.0 section 11.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
+#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
\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
**/\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
**/\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