Handle the FRAMEWORK_TOOLS_PATH properly on cygwin.
[mirror_edk2.git] / MdePkg / Library / PeiServicesLib / PeiServicesLib.c
1 /** @file
2 Implementation for PEI Services Library.
3
4 Copyright (c) 2006, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: PeiServicesLib.c
14
15 **/
16
17 /**
18 This service enables a given PEIM to register an interface into the PEI Foundation.
19
20 @param PpiList A pointer to the list of interfaces that the caller shall install.
21
22 @retval EFI_SUCCESS The interface was successfully installed.
23 @retval EFI_INVALID_PARAMETER The PpiList pointer is NULL.
24 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the
25 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
26 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
27
28 **/
29 EFI_STATUS
30 EFIAPI
31 PeiServicesInstallPpi (
32 IN EFI_PEI_PPI_DESCRIPTOR *PpiList
33 )
34 {
35 EFI_PEI_SERVICES **PeiServices;
36
37 PeiServices = GetPeiServicesTablePointer ();
38 return (*PeiServices)->InstallPpi (PeiServices, PpiList);
39 }
40
41 /**
42 This service enables PEIMs to replace an entry in the PPI database with an alternate entry.
43
44 @param OldPpi Pointer to the old PEI PPI Descriptors.
45 @param NewPpi Pointer to the new PEI PPI Descriptors.
46
47 @retval EFI_SUCCESS The interface was successfully installed.
48 @retval EFI_INVALID_PARAMETER The OldPpi or NewPpi is NULL.
49 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the
50 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
51 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
52 @retval EFI_NOT_FOUND The PPI for which the reinstallation was requested has not been
53 installed.
54
55 **/
56 EFI_STATUS
57 EFIAPI
58 PeiServicesReInstallPpi (
59 IN EFI_PEI_PPI_DESCRIPTOR *OldPpi,
60 IN EFI_PEI_PPI_DESCRIPTOR *NewPpi
61 )
62 {
63 EFI_PEI_SERVICES **PeiServices;
64
65 PeiServices = GetPeiServicesTablePointer ();
66 return (*PeiServices)->ReInstallPpi (PeiServices, OldPpi, NewPpi);
67 }
68
69 /**
70 This service enables PEIMs to discover a given instance of an interface.
71
72 @param Guid A pointer to the GUID whose corresponding interface needs to be
73 found.
74 @param Instance The N-th instance of the interface that is required.
75 @param PpiDescriptor A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR.
76 @param Ppi A pointer to the instance of the interface.
77
78 @retval EFI_SUCCESS The interface was successfully returned.
79 @retval EFI_NOT_FOUND The PPI descriptor is not found in the database.
80
81 **/
82 EFI_STATUS
83 EFIAPI
84 PeiServicesLocatePpi (
85 IN EFI_GUID *Guid,
86 IN UINTN Instance,
87 IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor,
88 IN OUT VOID **Ppi
89 )
90 {
91 EFI_PEI_SERVICES **PeiServices;
92
93 PeiServices = GetPeiServicesTablePointer ();
94 return (*PeiServices)->LocatePpi (PeiServices, Guid, Instance, PpiDescriptor, Ppi);
95 }
96
97 /**
98 This service enables PEIMs to register a given service to be invoked when another service is
99 installed or reinstalled.
100
101 @param NotifyList A pointer to the list of notification interfaces that the caller
102 shall install.
103
104 @retval EFI_SUCCESS The interface was successfully installed.
105 @retval EFI_INVALID_PARAMETER The NotifyList pointer is NULL.
106 @retval EFI_INVALID_PARAMETER Any of the PEI notify descriptors in the list do not have the
107 EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field.
108 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
109
110 **/
111 EFI_STATUS
112 EFIAPI
113 PeiServicesNotifyPpi (
114 IN EFI_PEI_NOTIFY_DESCRIPTOR *NotifyList
115 )
116 {
117 EFI_PEI_SERVICES **PeiServices;
118
119 PeiServices = GetPeiServicesTablePointer ();
120 return (*PeiServices)->NotifyPpi (PeiServices, NotifyList);
121 }
122
123 /**
124 This service enables PEIMs to ascertain the present value of the boot mode.
125
126 @param BootMode A pointer to contain the value of the boot mode.
127
128 @retval EFI_SUCCESS The boot mode was returned successfully.
129 @retval EFI_INVALID_PARAMETER BootMode is NULL.
130
131 **/
132 EFI_STATUS
133 EFIAPI
134 PeiServicesGetBootMode (
135 IN OUT EFI_BOOT_MODE *BootMode
136 )
137 {
138 EFI_PEI_SERVICES **PeiServices;
139
140 PeiServices = GetPeiServicesTablePointer ();
141 return (*PeiServices)->GetBootMode (PeiServices, BootMode);
142 }
143
144 /**
145 This service enables PEIMs to update the boot mode variable.
146
147 @param BootMode The value of the boot mode to set.
148
149 @retval EFI_SUCCESS The value was successfully updated
150
151 **/
152 EFI_STATUS
153 EFIAPI
154 PeiServicesSetBootMode (
155 IN EFI_BOOT_MODE BootMode
156 )
157 {
158 EFI_PEI_SERVICES **PeiServices;
159
160 PeiServices = GetPeiServicesTablePointer ();
161 return (*PeiServices)->SetBootMode (PeiServices, BootMode);
162 }
163
164 /**
165 This service enables a PEIM to ascertain the address of the list of HOBs in memory.
166
167 @param HobList A pointer to the list of HOBs that the PEI Foundation will initialize.
168
169 @retval EFI_SUCCESS The list was successfully returned.
170 @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published.
171
172 **/
173 EFI_STATUS
174 EFIAPI
175 PeiServicesGetHobList (
176 IN OUT VOID **HobList
177 )
178 {
179 EFI_PEI_SERVICES **PeiServices;
180
181 PeiServices = GetPeiServicesTablePointer ();
182 return (*PeiServices)->GetHobList (PeiServices, HobList);
183 }
184
185 /**
186 This service enables PEIMs to create various types of HOBs.
187
188 @param Type The type of HOB to be installed.
189 @param Length The length of the HOB to be added.
190 @param Hob The address of a pointer that will contain the HOB header.
191
192 @retval EFI_SUCCESS The HOB was successfully created.
193 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation.
194
195 **/
196 EFI_STATUS
197 EFIAPI
198 PeiServicesCreateHob (
199 IN UINT16 Type,
200 IN UINT16 Length,
201 IN OUT VOID **Hob
202 )
203 {
204 EFI_PEI_SERVICES **PeiServices;
205
206 PeiServices = GetPeiServicesTablePointer ();
207 return (*PeiServices)->CreateHob (PeiServices, Type, Length, Hob);
208 }
209
210 /**
211 This service enables PEIMs to discover additional firmware volumes.
212
213 @param Instance This instance of the firmware volume to find. The value 0 is the
214 Boot Firmware Volume (BFV).
215 @param FwVolHeader Pointer to the firmware volume header of the volume to return.
216
217 @retval EFI_SUCCESS The volume was found.
218 @retval EFI_NOT_FOUND The volume was not found.
219 @retval EFI_INVALID_PARAMETER FwVolHeader is NULL.
220
221 **/
222 EFI_STATUS
223 EFIAPI
224 PeiServicesFfsFindNextVolume (
225 IN UINTN Instance,
226 IN OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader
227 )
228 {
229 EFI_PEI_SERVICES **PeiServices;
230
231 PeiServices = GetPeiServicesTablePointer ();
232 return (*PeiServices)->FfsFindNextVolume (PeiServices, Instance, FwVolHeader);
233 }
234
235 /**
236 This service enables PEIMs to discover additional firmware files.
237
238 @param SearchType A filter to find files only of this type.
239 @param FwVolHeader Pointer to the firmware volume header of the volume to search.
240 This parameter must point to a valid FFS volume.
241 @param FileHeader Pointer to the current file from which to begin searching.
242
243 @retval EFI_SUCCESS The file was found.
244 @retval EFI_NOT_FOUND The file was not found.
245 @retval EFI_NOT_FOUND The header checksum was not zero.
246
247 **/
248 EFI_STATUS
249 EFIAPI
250 PeiServicesFfsFindNextFile (
251 IN EFI_FV_FILETYPE SearchType,
252 IN EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader,
253 IN OUT EFI_FFS_FILE_HEADER **FileHeader
254 )
255 {
256 EFI_PEI_SERVICES **PeiServices;
257
258 PeiServices = GetPeiServicesTablePointer ();
259 return (*PeiServices)->FfsFindNextFile (PeiServices, SearchType, FwVolHeader, FileHeader);
260 }
261
262 /**
263 This service enables PEIMs to discover sections of a given type within a valid FFS file.
264
265 @param SearchType The value of the section type to find.
266 @param FfsFileHeader A pointer to the file header that contains the set of sections to
267 be searched.
268 @param SectionData A pointer to the discovered section, if successful.
269
270 @retval EFI_SUCCESS The section was found.
271 @retval EFI_NOT_FOUND The section was not found.
272
273 **/
274 EFI_STATUS
275 EFIAPI
276 PeiServicesFfsFindSectionData (
277 IN EFI_SECTION_TYPE SectionType,
278 IN EFI_FFS_FILE_HEADER *FfsFileHeader,
279 IN OUT VOID **SectionData
280 )
281 {
282 EFI_PEI_SERVICES **PeiServices;
283
284 PeiServices = GetPeiServicesTablePointer ();
285 return (*PeiServices)->FfsFindSectionData (PeiServices, SectionType, FfsFileHeader, SectionData);
286 }
287
288 /**
289 This service enables PEIMs to register the permanent memory configuration
290 that has been initialized with the PEI Foundation.
291
292 @param MemoryBegin The value of a region of installed memory.
293 @param MemoryLength The corresponding length of a region of installed memory.
294
295 @retval EFI_SUCCESS The region was successfully installed in a HOB.
296 @retval EFI_INVALID_PARAMETER MemoryBegin and MemoryLength are illegal for this system.
297 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation.
298
299 **/
300 EFI_STATUS
301 EFIAPI
302 PeiServicesInstallPeiMemory (
303 IN EFI_PHYSICAL_ADDRESS MemoryBegin,
304 IN UINT64 MemoryLength
305 )
306 {
307 EFI_PEI_SERVICES **PeiServices;
308
309 PeiServices = GetPeiServicesTablePointer ();
310 return (*PeiServices)->InstallPeiMemory (PeiServices, MemoryBegin, MemoryLength);
311 }
312
313 /**
314 This service enables PEIMs to allocate memory after the permanent memory has been installed by a
315 PEIM.
316
317 @param MemoryType Type of memory to allocate.
318 @param Pages Number of pages to allocate.
319 @param Memory Pointer of memory allocated.
320
321 @retval EFI_SUCCESS The memory range was successfully allocated.
322 @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages.
323 @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available.
324 @retval EFI_OUT_OF_RESOURCES The pages could not be allocated.
325
326 **/
327 EFI_STATUS
328 EFIAPI
329 PeiServicesAllocatePages (
330 IN EFI_MEMORY_TYPE MemoryType,
331 IN UINTN Pages,
332 IN OUT EFI_PHYSICAL_ADDRESS *Memory
333 )
334 {
335 EFI_PEI_SERVICES **PeiServices;
336
337 PeiServices = GetPeiServicesTablePointer ();
338 return (*PeiServices)->AllocatePages (PeiServices, MemoryType, Pages, Memory);
339 }
340
341 /**
342 This service allocates memory from the Hand-Off Block (HOB) heap.
343
344 @param Size The number of bytes to allocate from the pool.
345 @param Buffer If the call succeeds, a pointer to a pointer to the allocate
346 buffer; undefined otherwise.
347
348 @retval EFI_SUCCESS The allocation was successful
349 @retval EFI_OUT_OF_RESOURCES There is not enough heap to allocate the requested size.
350
351 **/
352 EFI_STATUS
353 EFIAPI
354 PeiServicesAllocatePool (
355 IN UINTN Size,
356 OUT VOID **Buffer
357 )
358 {
359 EFI_PEI_SERVICES **PeiServices;
360
361 PeiServices = GetPeiServicesTablePointer ();
362 return (*PeiServices)->AllocatePool (PeiServices, Size, Buffer);
363 }
364
365 /**
366 This service resets the entire platform, including all processors and devices, and reboots the
367 system.
368
369 @retval EFI_NOT_AVAILABLE_YET The service has not been installed yet.
370
371 **/
372 EFI_STATUS
373 EFIAPI
374 PeiServicesResetSystem (
375 VOID
376 )
377 {
378 EFI_PEI_SERVICES **PeiServices;
379
380 PeiServices = GetPeiServicesTablePointer ();
381 return (*PeiServices)->PeiResetSystem (PeiServices);
382 }