X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FLibrary%2FPeiHobLib%2FHobLib.c;h=380a735b99f11c5f84217edaf3983ba9dd5150ec;hp=a06f1690bfec0c2608bdf1ac1775fdf383b78f2e;hb=5f10fa0140f7100aa04c12f87d63a66755d20d58;hpb=cfb190d9f49ebb67b0c2a8fd6585713151bcd728 diff --git a/MdePkg/Library/PeiHobLib/HobLib.c b/MdePkg/Library/PeiHobLib/HobLib.c index a06f1690bf..380a735b99 100644 --- a/MdePkg/Library/PeiHobLib/HobLib.c +++ b/MdePkg/Library/PeiHobLib/HobLib.c @@ -19,9 +19,9 @@ /** Returns the pointer to the HOB list. - None. + This function returns the pointer to first HOB in the list. - The pointer to the HOB list. + @return The pointer to the HOB list. **/ VOID * @@ -41,11 +41,17 @@ GetHobList ( } /** + 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. + 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. + @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. @@ -63,7 +69,7 @@ GetNextHob ( Hob.Raw = (UINT8 *) HobStart; // - // Parse the HOB list, stop if end of list or matching type found. + // Parse the HOB list until end of list or matching type is found. // while (!END_OF_HOB_LIST (Hob)) { if (Hob.Header->HobType == Type) { @@ -75,10 +81,12 @@ GetNextHob ( } /** + 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. - @param Type The HOB type to return. + @param Type The HOB type to return. @return The next instance of a HOB type from the starting HOB. @@ -100,9 +108,16 @@ GetFirstHob ( 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. + @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. @@ -131,8 +146,11 @@ GetNextGuidHob ( 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 Guid is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. + @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. @@ -150,10 +168,12 @@ GetFirstGuidHob ( } /** - Add a new HOB to the HOB List. + Adds a new HOB to the HOB List. - @param Type Type of the new HOB. - @param Length Length of the new HOB to allocate. + This internal function enables PEIMs to create various types of HOBs. + + @param Type Type of the new HOB. + @param Length Length of the new HOB to allocate. @return The address of new HOB. @@ -176,12 +196,18 @@ InternalPeiCreateHob ( } /** + 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’s entry point. + @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’s entry point. **/ VOID @@ -209,10 +235,15 @@ BuildModuleHob ( /** Builds a HOB that describes a chunk of system memory. - @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. + 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 @@ -235,11 +266,19 @@ BuildResourceDescriptorHob ( } /** - 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. + Builds a GUID HOB with a certain data length. + + 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 > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @param Guid The GUID to tag the customized HOB. - @param DataLength The size of the data payload for the GUID HOB. + @param Guid The GUID to tag the customized HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -264,12 +303,21 @@ BuildGuidHob ( } /** - This function 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 GUID HOB data. + Copies a data buffer to a newly-built HOB. - @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. + This function 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. + 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 > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). + + @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. @return The start address of GUID HOB data. @@ -292,8 +340,13 @@ BuildGuidDataHob ( /** Builds a Firmware Volume HOB. - @param BaseAddress The base address of the Firmware Volume. - @param Length The size of the Firmware Volume in bytes. + 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(). + + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. **/ VOID @@ -314,8 +367,13 @@ BuildFvHob ( /** Builds a Capsule Volume HOB. - @param BaseAddress The base address of the Capsule Volume. - @param Length The size of the Capsule Volume in bytes. + 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 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 @@ -336,8 +394,13 @@ BuildCvHob ( /** Builds a HOB for the CPU. - @param SizeOfMemorySpace The maximum physical memory addressability of the processor. - @param SizeOfIoSpace The maximum physical I/O addressability of the processor. + 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 @@ -358,8 +421,13 @@ BuildCpuHob ( /** Builds a HOB for the Stack. - @param BaseAddress The 64 bit physical address of the Stack. - @param Length The length of the stack in bytes. + 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 @@ -382,9 +450,14 @@ BuildStackHob ( /** Builds a HOB for the BSP store. - @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. + 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 @@ -408,9 +481,14 @@ BuildBspStoreHob ( /** Builds a HOB for the memory allocation. - @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. + 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