IntelFsp2Pkg SecFspSecPlatformLibNull: Convert Ia32/Flat32.asm to NASM
[mirror_edk2.git] / IntelFsp2Pkg / Include / FspEas / FspApi.h
1 /** @file\r
2   Intel FSP API definition from Intel Firmware Support Package External\r
3   Architecture Specification v2.0.\r
4 \r
5   Copyright (c) 2014 - 2016, 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 ///\r
20 /// FSP Reset Status code\r
21 /// These are defined in FSP EAS v2.0 section 11.2.2 - OEM Status Code\r
22 /// @{\r
23 #define FSP_STATUS_RESET_REQUIRED_COLD         0x40000001\r
24 #define FSP_STATUS_RESET_REQUIRED_WARM         0x40000002\r
25 #define FSP_STATUS_RESET_REQUIRED_3            0x40000003\r
26 #define FSP_STATUS_RESET_REQUIRED_4            0x40000004\r
27 #define FSP_STATUS_RESET_REQUIRED_5            0x40000005\r
28 #define FSP_STATUS_RESET_REQUIRED_6            0x40000006\r
29 #define FSP_STATUS_RESET_REQUIRED_7            0x40000007\r
30 #define FSP_STATUS_RESET_REQUIRED_8            0x40000008\r
31 /// @}\r
32 \r
33 #pragma pack(1)\r
34 ///\r
35 /// FSP_UPD_HEADER Configuration.\r
36 ///\r
37 typedef struct {\r
38   ///\r
39   /// UPD Region Signature. This signature will be\r
40   /// "XXXXXX_T" for FSP-T\r
41   /// "XXXXXX_M" for FSP-M\r
42   /// "XXXXXX_S" for FSP-S\r
43   /// Where XXXXXX is an unique signature\r
44   ///\r
45   UINT64                      Signature;\r
46   ///\r
47   /// Revision of the Data structure. For FSP v2.0 value is 1.\r
48   ///\r
49   UINT8                       Revision;\r
50   UINT8                       Reserved[23];\r
51 } FSP_UPD_HEADER;\r
52 \r
53 ///\r
54 /// FSPM_ARCH_UPD Configuration.\r
55 ///\r
56 typedef struct {\r
57   ///\r
58   /// Revision of the structure. For FSP v2.0 value is 1.\r
59   ///\r
60   UINT8                       Revision;\r
61   UINT8                       Reserved[3];\r
62   ///\r
63   /// Pointer to the non-volatile storage (NVS) data buffer.\r
64   /// If it is NULL it indicates the NVS data is not available.\r
65   ///\r
66   VOID                        *NvsBufferPtr;\r
67   ///\r
68   /// Pointer to the temporary stack base address to be\r
69   /// consumed inside FspMemoryInit() API.\r
70   ///\r
71   VOID                        *StackBase;\r
72   ///\r
73   /// Temporary stack size to be consumed inside\r
74   /// FspMemoryInit() API.\r
75   ///\r
76   UINT32                      StackSize;\r
77   ///\r
78   /// Size of memory to be reserved by FSP below "top\r
79   /// of low usable memory" for bootloader usage.\r
80   ///\r
81   UINT32                      BootLoaderTolumSize;\r
82   ///\r
83   /// Current boot mode.\r
84   ///\r
85   UINT32                      BootMode;\r
86   UINT8                       Reserved1[8];\r
87 } FSPM_ARCH_UPD;\r
88 \r
89 ///\r
90 /// FSPT_UPD_COMMON Configuration.\r
91 ///\r
92 typedef struct {\r
93   ///\r
94   /// FSP_UPD_HEADER Configuration.\r
95   ///\r
96   FSP_UPD_HEADER              FspUpdHeader;\r
97 } FSPT_UPD_COMMON;\r
98 \r
99 ///\r
100 /// FSPM_UPD_COMMON Configuration.\r
101 ///\r
102 typedef struct {\r
103   ///\r
104   /// FSP_UPD_HEADER Configuration.\r
105   ///\r
106   FSP_UPD_HEADER              FspUpdHeader;\r
107   ///\r
108   /// FSPM_ARCH_UPD Configuration.\r
109   ///\r
110   FSPM_ARCH_UPD               FspmArchUpd;\r
111 } FSPM_UPD_COMMON;\r
112 \r
113 ///\r
114 /// FSPS_UPD_COMMON Configuration.\r
115 ///\r
116 typedef struct {\r
117   ///\r
118   /// FSP_UPD_HEADER Configuration.\r
119   ///\r
120   FSP_UPD_HEADER              FspUpdHeader;\r
121 } FSPS_UPD_COMMON;\r
122 \r
123 ///\r
124 /// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE.\r
125 ///\r
126 typedef enum {\r
127   ///\r
128   /// This stage is notified when the bootloader completes the\r
129   /// PCI enumeration and the resource allocation for the\r
130   /// PCI devices is complete.\r
131   ///\r
132   EnumInitPhaseAfterPciEnumeration = 0x20,\r
133   ///\r
134   /// This stage is notified just before the bootloader hand-off\r
135   /// to the OS loader.\r
136   ///\r
137   EnumInitPhaseReadyToBoot         = 0x40,\r
138   ///\r
139   /// This stage is notified just before the firmware/Preboot\r
140   /// environment transfers management of all system resources\r
141   /// to the OS or next level execution environment.\r
142   ///\r
143   EnumInitPhaseEndOfFirmware       = 0xF0\r
144 } FSP_INIT_PHASE;\r
145 \r
146 ///\r
147 /// Definition of NOTIFY_PHASE_PARAMS.\r
148 ///\r
149 typedef struct {\r
150   ///\r
151   /// Notification phase used for NotifyPhase API\r
152   ///\r
153   FSP_INIT_PHASE     Phase;\r
154 } NOTIFY_PHASE_PARAMS;\r
155 \r
156 #pragma pack()\r
157 \r
158 /**\r
159   This FSP API is called soon after coming out of reset and before memory and stack is\r
160   available. This FSP API will load the microcode update, enable code caching for the\r
161   region specified by the boot loader and also setup a temporary stack to be used until\r
162   main memory is initialized.\r
163 \r
164   A hardcoded stack can be set up with the following values, and the "esp" register\r
165   initialized to point to this hardcoded stack.\r
166   1. The return address where the FSP will return control after setting up a temporary\r
167      stack.\r
168   2. A pointer to the input parameter structure\r
169 \r
170   However, since the stack is in ROM and not writeable, this FSP API cannot be called\r
171   using the "call" instruction, but needs to be jumped to.\r
172 \r
173   @param[in] FsptUpdDataPtr     Pointer to the FSPT_UPD data structure.\r
174 \r
175   @retval EFI_SUCCESS           Temporary RAM was initialized successfully.\r
176   @retval EFI_INVALID_PARAMETER Input parameters are invalid.\r
177   @retval EFI_UNSUPPORTED       The FSP calling conditions were not met.\r
178   @retval EFI_DEVICE_ERROR      Temp RAM initialization failed.\r
179 \r
180   If this function is successful, the FSP initializes the ECX and EDX registers to point to\r
181   a temporary but writeable memory range available to the boot loader and returns with\r
182   FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary\r
183   memory range and EDX points to the end of the range. Boot loader is free to use the\r
184   whole range described. Typically the boot loader can reload the ESP register to point\r
185   to the end of this returned range so that it can be used as a standard stack.\r
186 **/\r
187 typedef\r
188 EFI_STATUS\r
189 (EFIAPI *FSP_TEMP_RAM_INIT) (\r
190   IN  VOID    *FsptUpdDataPtr\r
191   );\r
192 \r
193 /**\r
194   This FSP API is used to notify the FSP about the different phases in the boot process.\r
195   This allows the FSP to take appropriate actions as needed during different initialization\r
196   phases. The phases will be platform dependent and will be documented with the FSP\r
197   release. The current FSP supports two notify phases:\r
198     Post PCI enumeration\r
199     Ready To Boot\r
200 \r
201   @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS\r
202 \r
203   @retval EFI_SUCCESS           The notification was handled successfully.\r
204   @retval EFI_UNSUPPORTED       The notification was not called in the proper order.\r
205   @retval EFI_INVALID_PARAMETER The notification code is invalid.\r
206 **/\r
207 typedef\r
208 EFI_STATUS\r
209 (EFIAPI *FSP_NOTIFY_PHASE) (\r
210   IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr\r
211   );\r
212 \r
213 /**\r
214   This FSP API is called after TempRamInit and initializes the memory.\r
215   This FSP API accepts a pointer to a data structure that will be platform dependent\r
216   and defined for each FSP binary. This will be documented in Integration guide with\r
217   each FSP release.\r
218   After FspMemInit completes its execution, it passes the pointer to the HobList and\r
219   returns to the boot loader from where it was called. BootLoader is responsible to \r
220   migrate it's stack and data to Memory.\r
221   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to\r
222   complete the silicon initialization and provides bootloader an opportunity to get\r
223   control after system memory is available and before the temporary RAM is torn down.\r
224 \r
225   @param[in]  FspmUpdDataPtr          Pointer to the FSPM_UPD data sructure.\r
226   @param[out] HobListPtr              Pointer to receive the address of the HOB list.\r
227 \r
228   @retval EFI_SUCCESS                 FSP execution environment was initialized successfully.\r
229   @retval EFI_INVALID_PARAMETER       Input parameters are invalid.\r
230   @retval EFI_UNSUPPORTED             The FSP calling conditions were not met.\r
231   @retval EFI_DEVICE_ERROR            FSP initialization failed.\r
232   @retval EFI_OUT_OF_RESOURCES        Stack range requested by FSP is not met.\r
233   @retval FSP_STATUS_RESET_REQUIREDx  A reset is reuired. These status codes will not be returned during S3.\r
234 **/\r
235 typedef\r
236 EFI_STATUS\r
237 (EFIAPI *FSP_MEMORY_INIT) (\r
238   IN  VOID    *FspmUpdDataPtr,\r
239   OUT VOID    **HobListPtr\r
240   );\r
241 \r
242 \r
243 /**\r
244   This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary\r
245   memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure\r
246   that will be platform dependent and defined for each FSP binary. This will be\r
247   documented in Integration Guide.\r
248   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to\r
249   complete the silicon initialization and provides bootloader an opportunity to get\r
250   control after system memory is available and before the temporary RAM is torn down.\r
251 \r
252   @param[in] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.\r
253                                  This structure is normally defined in the Integration Guide.\r
254                                  And if it is not defined in the Integration Guide, pass NULL.\r
255 \r
256   @retval EFI_SUCCESS            FSP execution environment was initialized successfully.\r
257   @retval EFI_INVALID_PARAMETER  Input parameters are invalid.\r
258   @retval EFI_UNSUPPORTED        The FSP calling conditions were not met.\r
259   @retval EFI_DEVICE_ERROR       FSP initialization failed.\r
260 **/\r
261 typedef\r
262 EFI_STATUS\r
263 (EFIAPI *FSP_TEMP_RAM_EXIT) (\r
264   IN  VOID    *TempRamExitParamPtr\r
265   );\r
266 \r
267 \r
268 /**\r
269   This FSP API is called after TempRamExit API.\r
270   FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the\r
271   silicon initialization.\r
272 \r
273   @param[in] FspsUpdDataPtr     Pointer to the FSPS_UPD data structure.\r
274                                 If NULL, FSP will use the default parameters.\r
275 \r
276   @retval EFI_SUCCESS                 FSP execution environment was initialized successfully.\r
277   @retval EFI_INVALID_PARAMETER       Input parameters are invalid.\r
278   @retval EFI_UNSUPPORTED             The FSP calling conditions were not met.\r
279   @retval EFI_DEVICE_ERROR            FSP initialization failed.\r
280   @retval FSP_STATUS_RESET_REQUIREDx  A reset is reuired. These status codes will not be returned during S3.\r
281 **/\r
282 typedef\r
283 EFI_STATUS\r
284 (EFIAPI *FSP_SILICON_INIT) (\r
285   IN  VOID    *FspsUpdDataPtr\r
286   );\r
287 \r
288 #endif\r