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