Fix comments format error.Fsp1.1 update.
[mirror_edk2.git] / 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 - 2015, 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 #define FSP_STATUS EFI_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 EFI_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 typedef struct {
111 ///
112 /// Non-volatile storage buffer pointer.
113 ///
114 VOID *NvsBufferPtr;
115 ///
116 /// Runtime buffer pointer
117 ///
118 VOID *RtBufferPtr;
119 ///
120 /// Pointer to the HOB data structure defined in the PI specification
121 ///
122 VOID **HobListPtr;
123 } FSP_MEMORY_INIT_PARAMS;
124
125 #pragma pack()
126
127 /**
128 This FSP API is called soon after coming out of reset and before memory and stack is
129 available. This FSP API will load the microcode update, enable code caching for the
130 region specified by the boot loader and also setup a temporary stack to be used until
131 main memory is initialized.
132
133 A hardcoded stack can be set up with the following values, and the "esp" register
134 initialized to point to this hardcoded stack.
135 1. The return address where the FSP will return control after setting up a temporary
136 stack.
137 2. A pointer to the input parameter structure
138
139 However, since the stack is in ROM and not writeable, this FSP API cannot be called
140 using the "call" instruction, but needs to be jumped to.
141
142 @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.
143
144 @retval EFI_SUCCESS Temp RAM was initialized successfully.
145 @retval EFI_INVALID_PARAMETER Input parameters are invalid..
146 @retval EFI_NOT_FOUND No valid microcode was found in the microcode region.
147 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
148 @retval EFI_DEVICE_ERROR Temp RAM initialization failed.
149
150 If this function is successful, the FSP initializes the ECX and EDX registers to point to
151 a temporary but writeable memory range available to the boot loader and returns with
152 FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
153 memory range and EDX points to the end of the range. Boot loader is free to use the
154 whole range described. Typically the boot loader can reload the ESP register to point
155 to the end of this returned range so that it can be used as a standard stack.
156 **/
157 typedef
158 EFI_STATUS
159 (EFIAPI *FSP_TEMP_RAM_INIT) (
160 IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr
161 );
162
163 /**
164 This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,
165 the CPU and the chipset to enable normal operation of these devices. This FSP API
166 accepts a pointer to a data structure that will be platform dependent and defined for
167 each FSP binary. This will be documented in the Integration Guide for each FSP
168 release.
169 The boot loader provides a continuation function as a parameter when calling FspInit.
170 After FspInit completes its execution, it does not return to the boot loader from where
171 it was called but instead returns control to the boot loader by calling the continuation
172 function which is passed to FspInit as an argument.
173
174 @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.
175
176 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
177 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
178 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
179 @retval EFI_DEVICE_ERROR FSP initialization failed.
180 **/
181 typedef
182 EFI_STATUS
183 (EFIAPI *FSP_INIT) (
184 IN OUT FSP_INIT_PARAMS *FspInitParamPtr
185 );
186
187 #define FSP_FSP_INIT FSP_INIT
188
189 /**
190 This FSP API is used to notify the FSP about the different phases in the boot process.
191 This allows the FSP to take appropriate actions as needed during different initialization
192 phases. The phases will be platform dependent and will be documented with the FSP
193 release. The current FSP supports two notify phases:
194 Post PCI enumeration
195 Ready To Boot
196
197 @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
198
199 @retval EFI_SUCCESS The notification was handled successfully.
200 @retval EFI_UNSUPPORTED The notification was not called in the proper order.
201 @retval EFI_INVALID_PARAMETER The notification code is invalid.
202 **/
203 typedef
204 EFI_STATUS
205 (EFIAPI *FSP_NOTIFY_PHASE) (
206 IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
207 );
208
209 /**
210 This FSP API is called after TempRamInit and initializes the memory.
211 This FSP API accepts a pointer to a data structure that will be platform dependent
212 and defined for each FSP binary. This will be documented in Integration guide with
213 each FSP release.
214 After FspMemInit completes its execution, it passes the pointer to the HobList and
215 returns to the boot loader from where it was called. Bootloader is responsible to
216 migrate it's stack and data to Memory.
217 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
218 complete the silicon initialization and provides bootloader an opportunity to get
219 control after system memory is available and before the temporary RAM is torn down.
220 These APIs are mutually exclusive to the FspInit API.
221
222 @param[in][out] FspMemoryInitParamPtr Address pointer to the FSP_MEMORY_INIT_PARAMS
223 structure.
224
225 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
226 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
227 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
228 @retval EFI_DEVICE_ERROR FSP initialization failed.
229 **/
230 typedef
231 EFI_STATUS
232 (EFIAPI *FSP_MEMORY_INIT) (
233 IN OUT FSP_MEMORY_INIT_PARAMS *FspMemoryInitParamPtr
234 );
235
236
237 /**
238 This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
239 memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
240 that will be platform dependent and defined for each FSP binary. This will be
241 documented in Integration Guide.
242 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
243 complete the silicon initialization and provides bootloader an opportunity to get
244 control after system memory is available and before the temporary RAM is torn down.
245 These APIs are mutually exclusive to the FspInit API.
246
247 @param[in][out] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
248 This structure is normally defined in the Integration Guide.
249 And if it is not defined in the Integration Guide, pass NULL.
250
251 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
252 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
253 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
254 @retval EFI_DEVICE_ERROR FSP initialization failed.
255 **/
256 typedef
257 EFI_STATUS
258 (EFIAPI *FSP_TEMP_RAM_EXIT) (
259 IN OUT VOID *TempRamExitParamPtr
260 );
261
262
263 /**
264 This FSP API is called after TempRamExit API.
265 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
266 silicon initialization.
267 These APIs are mutually exclusive to the FspInit API.
268
269 @param[in][out] FspSiliconInitParamPtr Pointer to the Silicon Init parameters structure.
270 This structure is normally defined in the Integration Guide.
271 And if it is not defined in the Integration Guide, pass NULL.
272
273 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
274 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
275 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
276 @retval EFI_DEVICE_ERROR FSP initialization failed.
277 **/
278 typedef
279 EFI_STATUS
280 (EFIAPI *FSP_SILICON_INIT) (
281 IN OUT VOID *FspSiliconInitParamPtr
282 );
283
284 ///
285 /// FSP API Return Status Code for backward compatibility with v1.0
286 ///@{
287 #define FSP_SUCCESS EFI_SUCCESS
288 #define FSP_INVALID_PARAMETER EFI_INVALID_PARAMETER
289 #define FSP_UNSUPPORTED EFI_UNSUPPORTED
290 #define FSP_NOT_READY EFI_NOT_READY
291 #define FSP_DEVICE_ERROR EFI_DEVICE_ERROR
292 #define FSP_OUT_OF_RESOURCES EFI_OUT_OF_RESOURCES
293 #define FSP_VOLUME_CORRUPTED EFI_VOLUME_CORRUPTED
294 #define FSP_NOT_FOUND EFI_NOT_FOUND
295 #define FSP_TIMEOUT EFI_TIMEOUT
296 #define FSP_ABORTED EFI_ABORTED
297 #define FSP_INCOMPATIBLE_VERSION EFI_INCOMPATIBLE_VERSION
298 #define FSP_SECURITY_VIOLATION EFI_SECURITY_VIOLATION
299 #define FSP_CRC_ERROR EFI_CRC_ERROR
300 ///@}
301
302 #endif