[mirror_edk2.git] / IntelFspPkg / Include / FspApi.h

/** @file\r
  Intel FSP API definition from Intel Firmware Support Package External\r
  Architecture Specification, April 2014, revision 001.\r
\r
  Copyright (c) 2014, Intel Corporation. All rights reserved.<BR>\r
  This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php.\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _FSP_API_H_\r
#define _FSP_API_H_\r
\r
typedef UINT32 FSP_STATUS;\r
#define FSPAPI EFIAPI\r
\r
/**\r
  FSP Init continuation function prototype.\r
  Control will be returned to this callback function after FspInit API call.\r
\r
  @param[in] Status Status of the FSP INIT API.\r
  @param[in] HobBufferPtr Pointer to the HOB data structure defined in the PI specification.\r
**/\r
typedef\r
VOID\r
(* CONTINUATION_PROC) (\r
  IN FSP_STATUS Status,\r
  IN VOID       *HobListPtr\r
  );\r
\r
#pragma pack(1)\r
\r
typedef struct {\r
  ///\r
  /// Base address of the microcode region.\r
  ///\r
  UINT32              MicrocodeRegionBase;\r
  ///\r
  /// Length of the microcode region.\r
  ///\r
  UINT32              MicrocodeRegionLength;\r
  ///\r
  /// Base address of the cacheable flash region.\r
  ///\r
  UINT32              CodeRegionBase;\r
  ///\r
  /// Length of the cacheable flash region.\r
  ///\r
  UINT32              CodeRegionLength;\r
} FSP_TEMP_RAM_INIT_PARAMS;\r
\r
typedef struct {\r
  ///\r
  /// Non-volatile storage buffer pointer.\r
  ///\r
  VOID               *NvsBufferPtr;\r
  ///\r
  /// Runtime buffer pointer\r
  ///\r
  VOID               *RtBufferPtr;\r
  ///\r
  /// Continuation function address\r
  ///\r
  CONTINUATION_PROC   ContinuationFunc;\r
} FSP_INIT_PARAMS;\r
\r
typedef struct {\r
  ///\r
  /// Stack top pointer used by the bootloader.\r
  /// The new stack frame will be set up at this location after FspInit API call.\r
  ///\r
  UINT32             *StackTop;\r
  ///\r
  /// Current system boot mode.\r
  ///\r
  UINT32              BootMode;\r
  ///\r
  /// User platform configuraiton data region pointer.\r
  ///\r
  VOID               *UpdDataRgnPtr;\r
  ///\r
  /// Reserved\r
  ///\r
  UINT32              Reserved[7];\r
} FSP_INIT_RT_COMMON_BUFFER;\r
\r
typedef enum {\r
  ///\r
  /// Notification code for post PCI enuermation\r
  ///\r
  EnumInitPhaseAfterPciEnumeration = 0x20,\r
  ///\r
  /// Notification code before transfering control to the payload\r
  ///\r
  EnumInitPhaseReadyToBoot         = 0x40\r
} FSP_INIT_PHASE;\r
\r
typedef struct {\r
  ///\r
  /// Notification phase used for NotifyPhase API\r
  ///\r
  FSP_INIT_PHASE     Phase;\r
} NOTIFY_PHASE_PARAMS;\r
\r
#pragma pack()\r
\r
/**\r
  This FSP API is called soon after coming out of reset and before memory and stack is\r
  available. This FSP API will load the microcode update, enable code caching for the\r
  region specified by the boot loader and also setup a temporary stack to be used until\r
  main memory is initialized.\r
\r
  A hardcoded stack can be set up with the following values, and the "esp" register\r
  initialized to point to this hardcoded stack.\r
  1. The return address where the FSP will return control after setting up a temporary\r
     stack.\r
  2. A pointer to the input parameter structure\r
\r
  However, since the stack is in ROM and not writeable, this FSP API cannot be called\r
  using the "call" instruction, but needs to be jumped to.\r
\r
  @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.\r
\r
  @retval FSP_SUCCESS           Temp RAM was initialized successfully.\r
  @retval FSP_INVALID_PARAMETER Input parameters are invalid..\r
  @retval FSP_NOT_FOUND         No valid microcode was found in the microcode region.\r
  @retval FSP_UNSUPPORTED       The FSP calling conditions were not met.\r
  @retval FSP_DEVICE_ERROR      Temp RAM initialization failed.\r
\r
  If this function is successful, the FSP initializes the ECX and EDX registers to point to\r
  a temporary but writeable memory range available to the boot loader and returns with\r
  FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary\r
  memory range and EDX points to the end of the range. Boot loader is free to use the\r
  whole range described. Typically the boot loader can reload the ESP register to point\r
  to the end of this returned range so that it can be used as a standard stack.\r
**/\r
typedef\r
FSP_STATUS\r
(FSPAPI *FSP_TEMP_RAM_INIT) (\r
  IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr\r
  );\r
\r
/**\r
  This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,\r
  the CPU and the chipset to enable normal operation of these devices. This FSP API\r
  accepts a pointer to a data structure that will be platform dependent and defined for\r
  each FSP binary. This will be documented in the Integration Guide for each FSP\r
  release.\r
  The boot loader provides a continuation function as a parameter when calling FspInit.\r
  After FspInit completes its execution, it does not return to the boot loader from where\r
  it was called but instead returns control to the boot loader by calling the continuation\r
  function which is passed to FspInit as an argument.\r
\r
  @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.\r
\r
  @retval FSP_SUCCESS           FSP execution environment was initialized successfully.\r
  @retval FSP_INVALID_PARAMETER Input parameters are invalid.\r
  @retval FSP_UNSUPPORTED       The FSP calling conditions were not met.\r
  @retval FSP_DEVICE_ERROR      FSP initialization failed.\r
**/\r
typedef\r
FSP_STATUS\r
(FSPAPI *FSP_FSP_INIT) (\r
  IN OUT FSP_INIT_PARAMS *FspInitParamPtr\r
  );\r
\r
/**\r
  This FSP API is used to notify the FSP about the different phases in the boot process.\r
  This allows the FSP to take appropriate actions as needed during different initialization\r
  phases. The phases will be platform dependent and will be documented with the FSP\r
  release. The current FSP supports two notify phases:\r
    Post PCI enumeration\r
    Ready To Boot\r
\r
  @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS\r
\r
  @retval FSP_SUCCESS           The notification was handled successfully.\r
  @retval FSP_UNSUPPORTED       The notification was not called in the proper order.\r
  @retval FSP_INVALID_PARAMETER The notification code is invalid.\r
**/\r
typedef\r
FSP_STATUS\r
(FSPAPI *FSP_NOTIFY_PHASE) (\r
  IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr\r
  );\r
\r
///\r
/// FSP API Return Status Code\r
///\r
#define FSP_SUCCESS              0x00000000\r
#define FSP_INVALID_PARAMETER    0x80000002\r
#define FSP_UNSUPPORTED          0x80000003\r
#define FSP_NOT_READY            0x80000006\r
#define FSP_DEVICE_ERROR         0x80000007\r
#define FSP_OUT_OF_RESOURCES     0x80000009\r
#define FSP_VOLUME_CORRUPTED     0x8000000A\r
#define FSP_NOT_FOUND            0x8000000E\r
#define FSP_TIMEOUT              0x80000012\r
#define FSP_ABORTED              0x80000015\r
#define FSP_INCOMPATIBLE_VERSION 0x80000010\r
#define FSP_SECURITY_VIOLATION   0x8000001A\r
#define FSP_CRC_ERROR            0x8000001B\r
\r
#endif\r
Commit	Line	Data
a33a2f62 JY	1	/** @file\r
	2	Intel FSP API definition from Intel Firmware Support Package External\r
	3	Architecture Specification, April 2014, revision 001.\r
	4	\r
	5	Copyright (c) 2014, Intel Corporation. All rights reserved.<BR>\r
	6	This program and the accompanying materials\r
	7	are licensed and made available under the terms and conditions of the BSD License\r
	8	which accompanies this distribution. The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php.\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
	14	**/\r
	15	\r
	16	#ifndef _FSP_API_H_\r
	17	#define _FSP_API_H_\r
	18	\r
	19	typedef UINT32 FSP_STATUS;\r
	20	#define FSPAPI EFIAPI\r
	21	\r
	22	/**\r
	23	FSP Init continuation function prototype.\r
	24	Control will be returned to this callback function after FspInit API call.\r
	25	\r
	26	@param[in] Status Status of the FSP INIT API.\r
	27	@param[in] HobBufferPtr Pointer to the HOB data structure defined in the PI specification.\r
	28	**/\r
	29	typedef\r
	30	VOID\r
	31	(* CONTINUATION_PROC) (\r
	32	IN FSP_STATUS Status,\r
	33	IN VOID *HobListPtr\r
	34	);\r
	35	\r
	36	#pragma pack(1)\r
	37	\r
	38	typedef struct {\r
	39	///\r
	40	/// Base address of the microcode region.\r
	41	///\r
	42	UINT32 MicrocodeRegionBase;\r
	43	///\r
	44	/// Length of the microcode region.\r
	45	///\r
	46	UINT32 MicrocodeRegionLength;\r
	47	///\r
	48	/// Base address of the cacheable flash region.\r
	49	///\r
	50	UINT32 CodeRegionBase;\r
	51	///\r
	52	/// Length of the cacheable flash region.\r
	53	///\r
	54	UINT32 CodeRegionLength;\r
	55	} FSP_TEMP_RAM_INIT_PARAMS;\r
	56	\r
	57	typedef struct {\r
	58	///\r
	59	/// Non-volatile storage buffer pointer.\r
	60	///\r
	61	VOID *NvsBufferPtr;\r
	62	///\r
	63	/// Runtime buffer pointer\r
	64	///\r
65	VOID *RtBufferPtr;\r
66	///\r
67	/// Continuation function address\r
68	///\r
69	CONTINUATION_PROC ContinuationFunc;\r
70	} FSP_INIT_PARAMS;\r
71	\r
72	typedef struct {\r
73	///\r
74	/// Stack top pointer used by the bootloader.\r
75	/// The new stack frame will be set up at this location after FspInit API call.\r
76	///\r
77	UINT32 *StackTop;\r
78	///\r
79	/// Current system boot mode.\r
80	///\r
81	UINT32 BootMode;\r
82	///\r
83	/// User platform configuraiton data region pointer.\r
84	///\r
85	VOID *UpdDataRgnPtr;\r
86	///\r
87	/// Reserved\r
88	///\r
89	UINT32 Reserved[7];\r
90	} FSP_INIT_RT_COMMON_BUFFER;\r
91	\r
92	typedef enum {\r
93	///\r
94	/// Notification code for post PCI enuermation\r
95	///\r
96	EnumInitPhaseAfterPciEnumeration = 0x20,\r
97	///\r
98	/// Notification code before transfering control to the payload\r
99	///\r
100	EnumInitPhaseReadyToBoot = 0x40\r
101	} FSP_INIT_PHASE;\r
102	\r
103	typedef struct {\r
104	///\r
105	/// Notification phase used for NotifyPhase API\r
106	///\r
107	FSP_INIT_PHASE Phase;\r
108	} NOTIFY_PHASE_PARAMS;\r
109	\r
110	#pragma pack()\r
111	\r
112	/**\r
113	This FSP API is called soon after coming out of reset and before memory and stack is\r
114	available. This FSP API will load the microcode update, enable code caching for the\r
115	region specified by the boot loader and also setup a temporary stack to be used until\r
116	main memory is initialized.\r
117	\r
118	A hardcoded stack can be set up with the following values, and the "esp" register\r
119	initialized to point to this hardcoded stack.\r
120	1. The return address where the FSP will return control after setting up a temporary\r
121	stack.\r
122	2. A pointer to the input parameter structure\r
123	\r
124	However, since the stack is in ROM and not writeable, this FSP API cannot be called\r
125	using the "call" instruction, but needs to be jumped to.\r
126	\r
127	@param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.\r
128	\r
129	@retval FSP_SUCCESS Temp RAM was initialized successfully.\r
130	@retval FSP_INVALID_PARAMETER Input parameters are invalid..\r
131	@retval FSP_NOT_FOUND No valid microcode was found in the microcode region.\r
132	@retval FSP_UNSUPPORTED The FSP calling conditions were not met.\r
133	@retval FSP_DEVICE_ERROR Temp RAM initialization failed.\r
134	\r
135	If this function is successful, the FSP initializes the ECX and EDX registers to point to\r
136	a temporary but writeable memory range available to the boot loader and returns with\r
137	FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary\r
138	memory range and EDX points to the end of the range. Boot loader is free to use the\r
139	whole range described. Typically the boot loader can reload the ESP register to point\r
140	to the end of this returned range so that it can be used as a standard stack.\r
141	**/\r
142	typedef\r
143	FSP_STATUS\r
144	(FSPAPI *FSP_TEMP_RAM_INIT) (\r
145	IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr\r
146	);\r
147	\r
148	/**\r
149	This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,\r
150	the CPU and the chipset to enable normal operation of these devices. This FSP API\r
151	accepts a pointer to a data structure that will be platform dependent and defined for\r
152	each FSP binary. This will be documented in the Integration Guide for each FSP\r
153	release.\r
154	The boot loader provides a continuation function as a parameter when calling FspInit.\r
155	After FspInit completes its execution, it does not return to the boot loader from where\r
156	it was called but instead returns control to the boot loader by calling the continuation\r
157	function which is passed to FspInit as an argument.\r
158	\r
159	@param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.\r
160	\r
161	@retval FSP_SUCCESS FSP execution environment was initialized successfully.\r
162	@retval FSP_INVALID_PARAMETER Input parameters are invalid.\r
163	@retval FSP_UNSUPPORTED The FSP calling conditions were not met.\r
164	@retval FSP_DEVICE_ERROR FSP initialization failed.\r
165	**/\r
166	typedef\r
167	FSP_STATUS\r
168	(FSPAPI *FSP_FSP_INIT) (\r
169	IN OUT FSP_INIT_PARAMS *FspInitParamPtr\r
170	);\r
171	\r
172	/**\r
173	This FSP API is used to notify the FSP about the different phases in the boot process.\r
174	This allows the FSP to take appropriate actions as needed during different initialization\r
175	phases. The phases will be platform dependent and will be documented with the FSP\r
176	release. The current FSP supports two notify phases:\r
177	Post PCI enumeration\r
178	Ready To Boot\r
179	\r
180	@param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS\r
181	\r
182	@retval FSP_SUCCESS The notification was handled successfully.\r
183	@retval FSP_UNSUPPORTED The notification was not called in the proper order.\r
184	@retval FSP_INVALID_PARAMETER The notification code is invalid.\r
185	**/\r
186	typedef\r
187	FSP_STATUS\r
8e89d9ce	188	(FSPAPI *FSP_NOTIFY_PHASE) (\r
a33a2f62 JY	189	IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr\r
	190	);\r
	191	\r
	192	///\r
	193	/// FSP API Return Status Code\r
	194	///\r
	195	#define FSP_SUCCESS 0x00000000\r
	196	#define FSP_INVALID_PARAMETER 0x80000002\r
	197	#define FSP_UNSUPPORTED 0x80000003\r
	198	#define FSP_NOT_READY 0x80000006\r
	199	#define FSP_DEVICE_ERROR 0x80000007\r
	200	#define FSP_OUT_OF_RESOURCES 0x80000009\r
	201	#define FSP_VOLUME_CORRUPTED 0x8000000A\r
	202	#define FSP_NOT_FOUND 0x8000000E\r
	203	#define FSP_TIMEOUT 0x80000012\r
	204	#define FSP_ABORTED 0x80000015\r
	205	#define FSP_INCOMPATIBLE_VERSION 0x80000010\r
	206	#define FSP_SECURITY_VIOLATION 0x8000001A\r
	207	#define FSP_CRC_ERROR 0x8000001B\r
	208	\r
	209	#endif\r