| /** @file |
| Provides services to create and parse HOBs. Only available for PEI |
| and DXE module types. |
| |
| The HOB Library supports the efficient creation and searching of HOBs |
| defined in the PI Specification. |
| A HOB is a Hand-Off Block, defined in the Framework architecture, that |
| allows the PEI phase to pass information to the DXE phase. HOBs are position |
| independent and can be relocated easily to different memory locations. |
| |
| Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> |
| This program and the accompanying materials |
| are licensed and made available under the terms and conditions of the BSD License |
| which accompanies this distribution. The full text of the license may be found at |
| http://opensource.org/licenses/bsd-license.php |
| |
| THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, |
| WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. |
| |
| **/ |
| |
| #ifndef __HOB_LIB_H__ |
| #define __HOB_LIB_H__ |
| |
| /** |
| Returns the pointer to the HOB list. |
| |
| This function returns the pointer to first HOB in the list. |
| For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer |
| to the HOB list. For the DXE phase, the HOB list pointer can be retrieved through |
| the EFI System Table by looking up theHOB list GUID in the System Configuration Table. |
| Since the System Configuration Table does not exist that the time the DXE Core is |
| launched, the DXE Core uses a global variable from the DXE Core Entry Point Library |
| to manage the pointer to the HOB list. |
| |
| If the pointer to the HOB list is NULL, then ASSERT(). |
| |
| @return The pointer to the HOB list. |
| |
| **/ |
| VOID * |
| EFIAPI |
| GetHobList ( |
| VOID |
| ); |
| |
| /** |
| Returns the next instance of a HOB type from the starting HOB. |
| |
| This function searches the first instance of a HOB type from the starting HOB pointer. |
| If there does not exist such HOB type from the starting HOB pointer, it will return NULL. |
| In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer |
| unconditionally: it returns HobStart back if HobStart itself meets the requirement; |
| caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. |
| |
| If HobStart is NULL, then ASSERT(). |
| |
| @param Type The HOB type to return. |
| @param HobStart The starting HOB pointer to search from. |
| |
| @return The next instance of a HOB type from the starting HOB. |
| |
| **/ |
| VOID * |
| EFIAPI |
| GetNextHob ( |
| IN UINT16 Type, |
| IN CONST VOID *HobStart |
| ); |
| |
| /** |
| Returns the first instance of a HOB type among the whole HOB list. |
| |
| This function searches the first instance of a HOB type among the whole HOB list. |
| If there does not exist such HOB type in the HOB list, it will return NULL. |
| |
| If the pointer to the HOB list is NULL, then ASSERT(). |
| |
| @param Type The HOB type to return. |
| |
| @return The next instance of a HOB type from the starting HOB. |
| |
| **/ |
| VOID * |
| EFIAPI |
| GetFirstHob ( |
| IN UINT16 Type |
| ); |
| |
| /** |
| Returns the next instance of the matched GUID HOB from the starting HOB. |
| |
| This function searches the first instance of a HOB from the starting HOB pointer. |
| Such HOB should satisfy two conditions: |
| its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. |
| If there does not exist such HOB from the starting HOB pointer, it will return NULL. |
| Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () |
| to extract the data section and its size info respectively. |
| In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer |
| unconditionally: it returns HobStart back if HobStart itself meets the requirement; |
| caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. |
| |
| If Guid is NULL, then ASSERT(). |
| If HobStart is NULL, then ASSERT(). |
| |
| @param Guid The GUID to match with in the HOB list. |
| @param HobStart A pointer to a Guid. |
| |
| @return The next instance of the matched GUID HOB from the starting HOB. |
| |
| **/ |
| VOID * |
| EFIAPI |
| GetNextGuidHob ( |
| IN CONST EFI_GUID *Guid, |
| IN CONST VOID *HobStart |
| ); |
| |
| /** |
| Returns the first instance of the matched GUID HOB among the whole HOB list. |
| |
| This function searches the first instance of a HOB among the whole HOB list. |
| Such HOB should satisfy two conditions: |
| its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. |
| If there does not exist such HOB from the starting HOB pointer, it will return NULL. |
| Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () |
| to extract the data section and its size info respectively. |
| |
| If the pointer to the HOB list is NULL, then ASSERT(). |
| If Guid is NULL, then ASSERT(). |
| |
| @param Guid The GUID to match with in the HOB list. |
| |
| @return The first instance of the matched GUID HOB among the whole HOB list. |
| |
| **/ |
| VOID * |
| EFIAPI |
| GetFirstGuidHob ( |
| IN CONST EFI_GUID *Guid |
| ); |
| |
| /** |
| Get the system boot mode from the HOB list. |
| |
| This function returns the system boot mode information from the |
| PHIT HOB in HOB list. |
| |
| If the pointer to the HOB list is NULL, then ASSERT(). |
| |
| @param VOID |
| |
| @return The Boot Mode. |
| |
| **/ |
| EFI_BOOT_MODE |
| EFIAPI |
| GetBootModeHob ( |
| VOID |
| ); |
| |
| /** |
| Builds a HOB for a loaded PE32 module. |
| |
| This function builds a HOB for a loaded PE32 module. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If ModuleName is NULL, then ASSERT(). |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param ModuleName The GUID File Name of the module. |
| @param MemoryAllocationModule The 64 bit physical address of the module. |
| @param ModuleLength The length of the module in bytes. |
| @param EntryPoint The 64 bit physical address of the module entry point. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildModuleHob ( |
| IN CONST EFI_GUID *ModuleName, |
| IN EFI_PHYSICAL_ADDRESS MemoryAllocationModule, |
| IN UINT64 ModuleLength, |
| IN EFI_PHYSICAL_ADDRESS EntryPoint |
| ); |
| |
| /** |
| Builds a HOB that describes a chunk of system memory with Owner GUID. |
| |
| This function builds a HOB that describes a chunk of system memory. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param ResourceType The type of resource described by this HOB. |
| @param ResourceAttribute The resource attributes of the memory described by this HOB. |
| @param PhysicalStart The 64 bit physical address of memory described by this HOB. |
| @param NumberOfBytes The length of the memory described by this HOB in bytes. |
| @param OwnerGUID GUID for the owner of this resource. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildResourceDescriptorWithOwnerHob ( |
| IN EFI_RESOURCE_TYPE ResourceType, |
| IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute, |
| IN EFI_PHYSICAL_ADDRESS PhysicalStart, |
| IN UINT64 NumberOfBytes, |
| IN EFI_GUID *OwnerGUID |
| ); |
| |
| /** |
| Builds a HOB that describes a chunk of system memory. |
| |
| This function builds a HOB that describes a chunk of system memory. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param ResourceType The type of resource described by this HOB. |
| @param ResourceAttribute The resource attributes of the memory described by this HOB. |
| @param PhysicalStart The 64 bit physical address of memory described by this HOB. |
| @param NumberOfBytes The length of the memory described by this HOB in bytes. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildResourceDescriptorHob ( |
| IN EFI_RESOURCE_TYPE ResourceType, |
| IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute, |
| IN EFI_PHYSICAL_ADDRESS PhysicalStart, |
| IN UINT64 NumberOfBytes |
| ); |
| |
| /** |
| Builds a customized HOB tagged with a GUID for identification and returns |
| the start address of GUID HOB data. |
| |
| This function builds a customized HOB tagged with a GUID for identification |
| and returns the start address of GUID HOB data so that caller can fill the customized data. |
| The HOB Header and Name field is already stripped. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If Guid is NULL, then ASSERT(). |
| If there is no additional space for HOB creation, then ASSERT(). |
| If DataLength > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT(). |
| HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8. |
| |
| @param Guid The GUID to tag the customized HOB. |
| @param DataLength The size of the data payload for the GUID HOB. |
| |
| @retval NULL The GUID HOB could not be allocated. |
| @retval others The start address of GUID HOB data. |
| |
| **/ |
| VOID * |
| EFIAPI |
| BuildGuidHob ( |
| IN CONST EFI_GUID *Guid, |
| IN UINTN DataLength |
| ); |
| |
| /** |
| Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB |
| data field, and returns the start address of the GUID HOB data. |
| |
| This function builds a customized HOB tagged with a GUID for identification and copies the input |
| data to the HOB data field and returns the start address of the GUID HOB data. It can only be |
| invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| The HOB Header and Name field is already stripped. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If Guid is NULL, then ASSERT(). |
| If Data is NULL and DataLength > 0, then ASSERT(). |
| If there is no additional space for HOB creation, then ASSERT(). |
| If DataLength > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT(). |
| HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8. |
| |
| @param Guid The GUID to tag the customized HOB. |
| @param Data The data to be copied into the data field of the GUID HOB. |
| @param DataLength The size of the data payload for the GUID HOB. |
| |
| @retval NULL The GUID HOB could not be allocated. |
| @retval others The start address of GUID HOB data. |
| |
| **/ |
| VOID * |
| EFIAPI |
| BuildGuidDataHob ( |
| IN CONST EFI_GUID *Guid, |
| IN VOID *Data, |
| IN UINTN DataLength |
| ); |
| |
| /** |
| Builds a Firmware Volume HOB. |
| |
| This function builds a Firmware Volume HOB. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| If the FvImage buffer is not at its required alignment, then ASSERT(). |
| |
| @param BaseAddress The base address of the Firmware Volume. |
| @param Length The size of the Firmware Volume in bytes. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildFvHob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length |
| ); |
| |
| /** |
| Builds a EFI_HOB_TYPE_FV2 HOB. |
| |
| This function builds a EFI_HOB_TYPE_FV2 HOB. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| If the FvImage buffer is not at its required alignment, then ASSERT(). |
| |
| @param BaseAddress The base address of the Firmware Volume. |
| @param Length The size of the Firmware Volume in bytes. |
| @param FvName The name of the Firmware Volume. |
| @param FileName The name of the file. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildFv2Hob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length, |
| IN CONST EFI_GUID *FvName, |
| IN CONST EFI_GUID *FileName |
| ); |
| |
| /** |
| Builds a EFI_HOB_TYPE_FV3 HOB. |
| |
| This function builds a EFI_HOB_TYPE_FV3 HOB. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| If the FvImage buffer is not at its required alignment, then ASSERT(). |
| |
| @param BaseAddress The base address of the Firmware Volume. |
| @param Length The size of the Firmware Volume in bytes. |
| @param AuthenticationStatus The authentication status. |
| @param ExtractedFv TRUE if the FV was extracted as a file within |
| another firmware volume. FALSE otherwise. |
| @param FvName The name of the Firmware Volume. |
| Valid only if IsExtractedFv is TRUE. |
| @param FileName The name of the file. |
| Valid only if IsExtractedFv is TRUE. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildFv3Hob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length, |
| IN UINT32 AuthenticationStatus, |
| IN BOOLEAN ExtractedFv, |
| IN CONST EFI_GUID *FvName, OPTIONAL |
| IN CONST EFI_GUID *FileName OPTIONAL |
| ); |
| |
| /** |
| Builds a Capsule Volume HOB. |
| |
| This function builds a Capsule Volume HOB. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If the platform does not support Capsule Volume HOBs, then ASSERT(). |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param BaseAddress The base address of the Capsule Volume. |
| @param Length The size of the Capsule Volume in bytes. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildCvHob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length |
| ); |
| |
| /** |
| Builds a HOB for the CPU. |
| |
| This function builds a HOB for the CPU. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param SizeOfMemorySpace The maximum physical memory addressability of the processor. |
| @param SizeOfIoSpace The maximum physical I/O addressability of the processor. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildCpuHob ( |
| IN UINT8 SizeOfMemorySpace, |
| IN UINT8 SizeOfIoSpace |
| ); |
| |
| /** |
| Builds a HOB for the Stack. |
| |
| This function builds a HOB for the stack. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param BaseAddress The 64 bit physical address of the Stack. |
| @param Length The length of the stack in bytes. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildStackHob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length |
| ); |
| |
| /** |
| Builds a HOB for the BSP store. |
| |
| This function builds a HOB for BSP store. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param BaseAddress The 64 bit physical address of the BSP. |
| @param Length The length of the BSP store in bytes. |
| @param MemoryType Type of memory allocated by this HOB. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildBspStoreHob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length, |
| IN EFI_MEMORY_TYPE MemoryType |
| ); |
| |
| /** |
| Builds a HOB for the memory allocation. |
| |
| This function builds a HOB for the memory allocation. |
| It can only be invoked during PEI phase; |
| for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. |
| |
| If there is no additional space for HOB creation, then ASSERT(). |
| |
| @param BaseAddress The 64 bit physical address of the memory. |
| @param Length The length of the memory allocation in bytes. |
| @param MemoryType Type of memory allocated by this HOB. |
| |
| **/ |
| VOID |
| EFIAPI |
| BuildMemoryAllocationHob ( |
| IN EFI_PHYSICAL_ADDRESS BaseAddress, |
| IN UINT64 Length, |
| IN EFI_MEMORY_TYPE MemoryType |
| ); |
| |
| /** |
| Returns the type of a HOB. |
| |
| This macro returns the HobType field from the HOB header for the |
| HOB specified by HobStart. |
| |
| @param HobStart A pointer to a HOB. |
| |
| @return HobType. |
| |
| **/ |
| #define GET_HOB_TYPE(HobStart) \ |
| ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobType) |
| |
| /** |
| Returns the length, in bytes, of a HOB. |
| |
| This macro returns the HobLength field from the HOB header for the |
| HOB specified by HobStart. |
| |
| @param HobStart A pointer to a HOB. |
| |
| @return HobLength. |
| |
| **/ |
| #define GET_HOB_LENGTH(HobStart) \ |
| ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobLength) |
| |
| /** |
| Returns a pointer to the next HOB in the HOB list. |
| |
| This macro returns a pointer to HOB that follows the |
| HOB specified by HobStart in the HOB List. |
| |
| @param HobStart A pointer to a HOB. |
| |
| @return A pointer to the next HOB in the HOB list. |
| |
| **/ |
| #define GET_NEXT_HOB(HobStart) \ |
| (VOID *)(*(UINT8 **)&(HobStart) + GET_HOB_LENGTH (HobStart)) |
| |
| /** |
| Determines if a HOB is the last HOB in the HOB list. |
| |
| This macro determine if the HOB specified by HobStart is the |
| last HOB in the HOB list. If HobStart is last HOB in the HOB list, |
| then TRUE is returned. Otherwise, FALSE is returned. |
| |
| @param HobStart A pointer to a HOB. |
| |
| @retval TRUE The HOB specified by HobStart is the last HOB in the HOB list. |
| @retval FALSE The HOB specified by HobStart is not the last HOB in the HOB list. |
| |
| **/ |
| #define END_OF_HOB_LIST(HobStart) (GET_HOB_TYPE (HobStart) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST) |
| |
| /** |
| Returns a pointer to data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. |
| |
| This macro returns a pointer to the data buffer in a HOB specified by HobStart. |
| HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. |
| |
| @param GuidHob A pointer to a HOB. |
| |
| @return A pointer to the data buffer in a HOB. |
| |
| **/ |
| #define GET_GUID_HOB_DATA(HobStart) \ |
| (VOID *)(*(UINT8 **)&(HobStart) + sizeof (EFI_HOB_GUID_TYPE)) |
| |
| /** |
| Returns the size of the data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. |
| |
| This macro returns the size, in bytes, of the data buffer in a HOB specified by HobStart. |
| HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. |
| |
| @param GuidHob A pointer to a HOB. |
| |
| @return The size of the data buffer. |
| **/ |
| #define GET_GUID_HOB_DATA_SIZE(HobStart) \ |
| (UINT16)(GET_HOB_LENGTH (HobStart) - sizeof (EFI_HOB_GUID_TYPE)) |
| |
| #endif |