2 Library that helps implement monolithic PEI. (SEC goes to DXE)
4 Copyright (c) 2008-2009 Apple Inc. All rights reserved.<BR>
6 All rights reserved. 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
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.
16 #ifndef __PRE_PI_LIB_H__
17 #define __PRE_PI_LIB_H__
20 This service enables discovery of additional firmware volumes.
22 @param Instance This instance of the firmware volume to find. The value 0 is the
23 Boot Firmware Volume (BFV).
24 @param FwVolHeader Pointer to the firmware volume header of the volume to return.
26 @retval EFI_SUCCESS The volume was found.
27 @retval EFI_NOT_FOUND The volume was not found.
28 @retval EFI_INVALID_PARAMETER FwVolHeader is NULL.
35 IN OUT EFI_PEI_FV_HANDLE
*VolumeHandle
40 This service enables discovery of additional firmware files.
42 @param SearchType A filter to find files only of this type.
43 @param FwVolHeader Pointer to the firmware volume header of the volume to search.
44 This parameter must point to a valid FFS volume.
45 @param FileHeader Pointer to the current file from which to begin searching.
47 @retval EFI_SUCCESS The file was found.
48 @retval EFI_NOT_FOUND The file was not found.
49 @retval EFI_NOT_FOUND The header checksum was not zero.
55 IN EFI_FV_FILETYPE SearchType
,
56 IN EFI_PEI_FV_HANDLE VolumeHandle
,
57 IN OUT EFI_PEI_FILE_HANDLE
*FileHandle
62 This service enables discovery sections of a given type within a valid FFS file.
64 @param SearchType The value of the section type to find.
65 @param FfsFileHeader A pointer to the file header that contains the set of sections to
67 @param SectionData A pointer to the discovered section, if successful.
69 @retval EFI_SUCCESS The section was found.
70 @retval EFI_NOT_FOUND The section was not found.
76 IN EFI_SECTION_TYPE SectionType
,
77 IN EFI_PEI_FILE_HANDLE FileHandle
,
78 OUT VOID
**SectionData
83 Find a file in the volume by name
85 @param FileName A pointer to the name of the file to
86 find within the firmware volume.
88 @param VolumeHandle The firmware volume to search FileHandle
89 Upon exit, points to the found file's
90 handle or NULL if it could not be found.
92 @retval EFI_SUCCESS File was found.
94 @retval EFI_NOT_FOUND File was not found.
96 @retval EFI_INVALID_PARAMETER VolumeHandle or FileHandle or
103 IN CONST EFI_GUID
*FileName
,
104 IN CONST EFI_PEI_FV_HANDLE VolumeHandle
,
105 OUT EFI_PEI_FILE_HANDLE
*FileHandle
110 Get information about the file by name.
112 @param FileHandle Handle of the file.
114 @param FileInfo Upon exit, points to the file's
117 @retval EFI_SUCCESS File information returned.
119 @retval EFI_INVALID_PARAMETER If FileHandle does not
120 represent a valid file.
122 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.
128 IN CONST EFI_PEI_FILE_HANDLE FileHandle
,
129 OUT EFI_FV_FILE_INFO
*FileInfo
134 Get Information about the volume by name
136 @param VolumeHandle Handle of the volume.
138 @param VolumeInfo Upon exit, points to the volume's
141 @retval EFI_SUCCESS File information returned.
143 @retval EFI_INVALID_PARAMETER If FileHandle does not
144 represent a valid file.
146 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.
152 IN EFI_PEI_FV_HANDLE VolumeHandle
,
153 OUT EFI_FV_INFO
*VolumeInfo
159 Get Fv image from the FV type file, then add FV & FV2 Hob.
161 @param FileHandle File handle of a Fv type file.
164 @retval EFI_NOT_FOUND FV image can't be found.
165 @retval EFI_SUCCESS Successfully to process it.
171 IN EFI_PEI_FILE_HANDLE FvFileHandle
176 Search through every FV until you find a file of type FileType
178 @param FileType File handle of a Fv type file.
179 @param Volumehandle On succes Volume Handle of the match
180 @param FileHandle On success File Handle of the match
182 @retval EFI_NOT_FOUND FV image can't be found.
183 @retval EFI_SUCCESS Successfully found FileType
188 FfsAnyFvFindFirstFile (
189 IN EFI_FV_FILETYPE FileType
,
190 OUT EFI_PEI_FV_HANDLE
*VolumeHandle
,
191 OUT EFI_PEI_FILE_HANDLE
*FileHandle
196 Get Fv image from the FV type file, then add FV & FV2 Hob.
198 @param FileHandle File handle of a Fv type file.
201 @retval EFI_NOT_FOUND FV image can't be found.
202 @retval EFI_SUCCESS Successfully to process it.
208 IN EFI_PEI_FILE_HANDLE FvFileHandle
213 This service enables PEIMs to ascertain the present value of the boot mode.
227 This service enables PEIMs to update the boot mode variable.
229 @param BootMode The value of the boot mode to set.
231 @retval EFI_SUCCESS The value was successfully updated
237 IN EFI_BOOT_MODE BootMode
241 This service enables a PEIM to ascertain the address of the list of HOBs in memory.
243 @param HobList A pointer to the list of HOBs that the PEI Foundation will initialize.
245 @retval EFI_SUCCESS The list was successfully returned.
246 @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published.
257 Updates the pointer to the HOB list.
259 @param HobList Hob list pointer to store
270 Retrieves the magic value from the PE/COFF header.
272 @param Hdr The buffer in which to return the PE32, PE32+, or TE header.
274 @return EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC - Image is PE32
275 @return EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC - Image is PE32+
280 IN VOID
*MemoryBegin
,
281 IN UINTN MemoryLength
,
288 This service enables PEIMs to create various types of HOBs.
290 @param Type The type of HOB to be installed.
291 @param Length The length of the HOB to be added.
293 @retval !NULL The HOB was successfully created.
294 @retval NULL There is no additional space for HOB creation.
305 Returns the next instance of a HOB type from the starting HOB.
307 This function searches the first instance of a HOB type from the starting HOB pointer.
308 If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
309 In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
310 unconditionally: it returns HobStart back if HobStart itself meets the requirement;
311 caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
312 If HobStart is NULL, then ASSERT().
314 @param Type The HOB type to return.
315 @param HobStart The starting HOB pointer to search from.
317 @return The next instance of a HOB type from the starting HOB.
324 IN CONST VOID
*HobStart
328 Returns the first instance of a HOB type among the whole HOB list.
330 This function searches the first instance of a HOB type among the whole HOB list.
331 If there does not exist such HOB type in the HOB list, it will return NULL.
333 @param Type The HOB type to return.
335 @return The next instance of a HOB type from the starting HOB.
345 This function searches the first instance of a HOB from the starting HOB pointer.
346 Such HOB should satisfy two conditions:
347 its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
348 If there does not exist such HOB from the starting HOB pointer, it will return NULL.
349 Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
350 to extract the data section and its size info respectively.
351 In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
352 unconditionally: it returns HobStart back if HobStart itself meets the requirement;
353 caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
354 If Guid is NULL, then ASSERT().
355 If HobStart is NULL, then ASSERT().
357 @param Guid The GUID to match with in the HOB list.
358 @param HobStart A pointer to a Guid.
360 @return The next instance of the matched GUID HOB from the starting HOB.
366 IN CONST EFI_GUID
*Guid
,
367 IN CONST VOID
*HobStart
371 This function searches the first instance of a HOB among the whole HOB list.
372 Such HOB should satisfy two conditions:
373 its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
374 If there does not exist such HOB from the starting HOB pointer, it will return NULL.
375 Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
376 to extract the data section and its size info respectively.
377 If Guid is NULL, then ASSERT().
379 @param Guid The GUID to match with in the HOB list.
381 @return The first instance of the matched GUID HOB among the whole HOB list.
387 IN CONST EFI_GUID
*Guid
392 Builds a HOB for a loaded PE32 module.
394 This function builds a HOB for a loaded PE32 module.
395 It can only be invoked during PEI phase;
396 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
397 If ModuleName is NULL, then ASSERT().
398 If there is no additional space for HOB creation, then ASSERT().
400 @param ModuleName The GUID File Name of the module.
401 @param MemoryAllocationModule The 64 bit physical address of the module.
402 @param ModuleLength The length of the module in bytes.
403 @param EntryPoint The 64 bit physical address of the module entry point.
409 IN CONST EFI_GUID
*ModuleName
,
410 IN EFI_PHYSICAL_ADDRESS MemoryAllocationModule
,
411 IN UINT64 ModuleLength
,
412 IN EFI_PHYSICAL_ADDRESS EntryPoint
416 Builds a HOB that describes a chunk of system memory.
418 This function builds a HOB that describes a chunk of system memory.
419 It can only be invoked during PEI phase;
420 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
421 If there is no additional space for HOB creation, then ASSERT().
423 @param ResourceType The type of resource described by this HOB.
424 @param ResourceAttribute The resource attributes of the memory described by this HOB.
425 @param PhysicalStart The 64 bit physical address of memory described by this HOB.
426 @param NumberOfBytes The length of the memory described by this HOB in bytes.
431 BuildResourceDescriptorHob (
432 IN EFI_RESOURCE_TYPE ResourceType
,
433 IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute
,
434 IN EFI_PHYSICAL_ADDRESS PhysicalStart
,
435 IN UINT64 NumberOfBytes
439 Builds a GUID HOB with a certain data length.
441 This function builds a customized HOB tagged with a GUID for identification
442 and returns the start address of GUID HOB data so that caller can fill the customized data.
443 The HOB Header and Name field is already stripped.
444 It can only be invoked during PEI phase;
445 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
446 If Guid is NULL, then ASSERT().
447 If there is no additional space for HOB creation, then ASSERT().
448 If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
450 @param Guid The GUID to tag the customized HOB.
451 @param DataLength The size of the data payload for the GUID HOB.
453 @return The start address of GUID HOB data.
459 IN CONST EFI_GUID
*Guid
,
464 Copies a data buffer to a newly-built HOB.
466 This function builds a customized HOB tagged with a GUID for identification,
467 copies the input data to the HOB data field and returns the start address of the GUID HOB data.
468 The HOB Header and Name field is already stripped.
469 It can only be invoked during PEI phase;
470 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
471 If Guid is NULL, then ASSERT().
472 If Data is NULL and DataLength > 0, then ASSERT().
473 If there is no additional space for HOB creation, then ASSERT().
474 If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
476 @param Guid The GUID to tag the customized HOB.
477 @param Data The data to be copied into the data field of the GUID HOB.
478 @param DataLength The size of the data payload for the GUID HOB.
480 @return The start address of GUID HOB data.
486 IN CONST EFI_GUID
*Guid
,
492 Builds a Firmware Volume HOB.
494 This function builds a Firmware Volume HOB.
495 It can only be invoked during PEI phase;
496 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
497 If there is no additional space for HOB creation, then ASSERT().
499 @param BaseAddress The base address of the Firmware Volume.
500 @param Length The size of the Firmware Volume in bytes.
506 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
511 Builds a Firmware Volume HOB and a resrouce descriptor hob
513 This function builds a Firmware Volume HOB.
514 It can only be invoked during PEI phase;
515 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
516 If there is no additional space for HOB creation, then ASSERT().
518 @param BaseAddress The base address of the Firmware Volume.
519 @param Length The size of the Firmware Volume in bytes.
525 IN EFI_PHYSICAL_ADDRESS PhysicalStart
,
526 IN UINT64 NumberOfBytes
,
527 IN EFI_RESOURCE_ATTRIBUTE_TYPE
*ResourceAttribute OPTIONAL
532 Builds a EFI_HOB_TYPE_FV2 HOB.
534 This function builds a EFI_HOB_TYPE_FV2 HOB.
535 It can only be invoked during PEI phase;
536 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
537 If there is no additional space for HOB creation, then ASSERT().
539 @param BaseAddress The base address of the Firmware Volume.
540 @param Length The size of the Firmware Volume in bytes.
541 @param FvName The name of the Firmware Volume.
542 @param FileName The name of the file.
548 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
550 IN CONST EFI_GUID
*FvName
,
551 IN CONST EFI_GUID
*FileName
555 Builds a Capsule Volume HOB.
557 This function builds a Capsule Volume HOB.
558 It can only be invoked during PEI phase;
559 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
560 If there is no additional space for HOB creation, then ASSERT().
562 @param BaseAddress The base address of the Capsule Volume.
563 @param Length The size of the Capsule Volume in bytes.
569 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
574 Builds a HOB for the CPU.
576 This function builds a HOB for the CPU.
577 It can only be invoked during PEI phase;
578 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
579 If there is no additional space for HOB creation, then ASSERT().
581 @param SizeOfMemorySpace The maximum physical memory addressability of the processor.
582 @param SizeOfIoSpace The maximum physical I/O addressability of the processor.
588 IN UINT8 SizeOfMemorySpace
,
589 IN UINT8 SizeOfIoSpace
593 Builds a HOB for the Stack.
595 This function builds a HOB for the stack.
596 It can only be invoked during PEI phase;
597 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
598 If there is no additional space for HOB creation, then ASSERT().
600 @param BaseAddress The 64 bit physical address of the Stack.
601 @param Length The length of the stack in bytes.
607 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
612 Update the Stack Hob if the stack has been moved
614 @param BaseAddress The 64 bit physical address of the Stack.
615 @param Length The length of the stack in bytes.
620 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
626 Builds a HOB for the BSP store.
628 This function builds a HOB for BSP store.
629 It can only be invoked during PEI phase;
630 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
631 If there is no additional space for HOB creation, then ASSERT().
633 @param BaseAddress The 64 bit physical address of the BSP.
634 @param Length The length of the BSP store in bytes.
635 @param MemoryType Type of memory allocated by this HOB.
641 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
643 IN EFI_MEMORY_TYPE MemoryType
647 Builds a HOB for the memory allocation.
649 This function builds a HOB for the memory allocation.
650 It can only be invoked during PEI phase;
651 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
652 If there is no additional space for HOB creation, then ASSERT().
654 @param BaseAddress The 64 bit physical address of the memory.
655 @param Length The length of the memory allocation in bytes.
656 @param MemoryType Type of memory allocated by this HOB.
661 BuildMemoryAllocationHob (
662 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
664 IN EFI_MEMORY_TYPE MemoryType
669 Allocates one or more 4KB pages of type EfiBootServicesData.
671 Allocates the number of 4KB pages of MemoryType and returns a pointer to the
672 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
673 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
676 @param Pages The number of 4 KB pages to allocate.
678 @return A pointer to the allocated buffer or NULL if allocation fails.
688 Allocates a buffer of type EfiBootServicesData.
690 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
691 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
692 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
694 @param AllocationSize The number of bytes to allocate.
696 @return A pointer to the allocated buffer or NULL if allocation fails.
702 IN UINTN AllocationSize
707 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
709 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
710 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
711 returned. If there is not enough memory at the specified alignment remaining to satisfy the
712 request, then NULL is returned.
713 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
715 @param Pages The number of 4 KB pages to allocate.
716 @param Alignment The requested alignment of the allocation. Must be a power of two.
717 If Alignment is zero, then byte alignment is used.
719 @return A pointer to the allocated buffer or NULL if allocation fails.
724 AllocateAlignedPages (
733 IN VOID
*PeCoffImage
,
734 OUT EFI_PHYSICAL_ADDRESS
*ImageAddress
,
735 OUT UINT64
*ImageSize
,
736 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint
741 LoadDxeCoreFromFfsFile (
742 IN EFI_PEI_FILE_HANDLE FileHandle
,
749 IN UINTN
*FvInstance
, OPTIONAL
761 AddDxeCoreReportStatusCodeCallback (