9344f09215
https://bugzilla.tianocore.org/show_bug.cgi?id=1373 Replace BSD 2-Clause License with BSD+Patent License. This change is based on the following emails: https://lists.01.org/pipermail/edk2-devel/2019-February/036260.html https://lists.01.org/pipermail/edk2-devel/2018-October/030385.html RFCs with detailed process for the license change: V3: https://lists.01.org/pipermail/edk2-devel/2019-March/038116.html V2: https://lists.01.org/pipermail/edk2-devel/2019-March/037669.html V1: https://lists.01.org/pipermail/edk2-devel/2019-March/037500.html Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
561 lines
19 KiB
C
561 lines
19 KiB
C
/** @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 - 2018, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#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
|