Fix typo.
[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, 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 typedef UINT32 FSP_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 FSP_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 #pragma pack()
111
112 /**
113 This FSP API is called soon after coming out of reset and before memory and stack is
114 available. This FSP API will load the microcode update, enable code caching for the
115 region specified by the boot loader and also setup a temporary stack to be used until
116 main memory is initialized.
117
118 A hardcoded stack can be set up with the following values, and the "esp" register
119 initialized to point to this hardcoded stack.
120 1. The return address where the FSP will return control after setting up a temporary
121 stack.
122 2. A pointer to the input parameter structure
123
124 However, since the stack is in ROM and not writeable, this FSP API cannot be called
125 using the "call" instruction, but needs to be jumped to.
126
127 @param[in] TempRaminitParamPtr Address pointer to the FSP_TEMP_RAM_INIT_PARAMS structure.
128
129 @retval FSP_SUCCESS Temp RAM was initialized successfully.
130 @retval FSP_INVALID_PARAMETER Input parameters are invalid..
131 @retval FSP_NOT_FOUND No valid microcode was found in the microcode region.
132 @retval FSP_UNSUPPORTED The FSP calling conditions were not met.
133 @retval FSP_DEVICE_ERROR Temp RAM initialization failed.
134
135 If this function is successful, the FSP initializes the ECX and EDX registers to point to
136 a temporary but writeable memory range available to the boot loader and returns with
137 FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
138 memory range and EDX points to the end of the range. Boot loader is free to use the
139 whole range described. Typically the boot loader can reload the ESP register to point
140 to the end of this returned range so that it can be used as a standard stack.
141 **/
142 typedef
143 FSP_STATUS
144 (FSPAPI *FSP_TEMP_RAM_INIT) (
145 IN FSP_TEMP_RAM_INIT_PARAMS *FspTempRamInitPtr
146 );
147
148 /**
149 This FSP API is called after TempRamInitEntry. This FSP API initializes the memory,
150 the CPU and the chipset to enable normal operation of these devices. This FSP API
151 accepts a pointer to a data structure that will be platform dependent and defined for
152 each FSP binary. This will be documented in the Integration Guide for each FSP
153 release.
154 The boot loader provides a continuation function as a parameter when calling FspInit.
155 After FspInit completes its execution, it does not return to the boot loader from where
156 it was called but instead returns control to the boot loader by calling the continuation
157 function which is passed to FspInit as an argument.
158
159 @param[in] FspInitParamPtr Address pointer to the FSP_INIT_PARAMS structure.
160
161 @retval FSP_SUCCESS FSP execution environment was initialized successfully.
162 @retval FSP_INVALID_PARAMETER Input parameters are invalid.
163 @retval FSP_UNSUPPORTED The FSP calling conditions were not met.
164 @retval FSP_DEVICE_ERROR FSP initialization failed.
165 **/
166 typedef
167 FSP_STATUS
168 (FSPAPI *FSP_FSP_INIT) (
169 IN OUT FSP_INIT_PARAMS *FspInitParamPtr
170 );
171
172 /**
173 This FSP API is used to notify the FSP about the different phases in the boot process.
174 This allows the FSP to take appropriate actions as needed during different initialization
175 phases. The phases will be platform dependent and will be documented with the FSP
176 release. The current FSP supports two notify phases:
177 Post PCI enumeration
178 Ready To Boot
179
180 @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
181
182 @retval FSP_SUCCESS The notification was handled successfully.
183 @retval FSP_UNSUPPORTED The notification was not called in the proper order.
184 @retval FSP_INVALID_PARAMETER The notification code is invalid.
185 **/
186 typedef
187 FSP_STATUS
188 (FSPAPI *FSP_NOTIFY_PHASE) (
189 IN NOTIFY_PHASE_PARAMS *NotifyPhaseParamPtr
190 );
191
192 ///
193 /// FSP API Return Status Code
194 ///
195 #define FSP_SUCCESS 0x00000000
196 #define FSP_INVALID_PARAMETER 0x80000002
197 #define FSP_UNSUPPORTED 0x80000003
198 #define FSP_NOT_READY 0x80000006
199 #define FSP_DEVICE_ERROR 0x80000007
200 #define FSP_OUT_OF_RESOURCES 0x80000009
201 #define FSP_VOLUME_CORRUPTED 0x8000000A
202 #define FSP_NOT_FOUND 0x8000000E
203 #define FSP_TIMEOUT 0x80000012
204 #define FSP_ABORTED 0x80000015
205 #define FSP_INCOMPATIBLE_VERSION 0x80000010
206 #define FSP_SECURITY_VIOLATION 0x8000001A
207 #define FSP_CRC_ERROR 0x8000001B
208
209 #endif