X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FLibrary%2FDxeCoreHobLib%2FHobLib.c;h=ad66966279363c31d989b4f5a4ad43a62e5796d7;hp=302d1bbd8c64dba5aca816e05a3e10af87174114;hb=e4b0415d59d00eacc0ce4755ad6aaab80b16075c;hpb=6f890d5b408233e5a305163a3f1d634a8b5d5744 diff --git a/MdePkg/Library/DxeCoreHobLib/HobLib.c b/MdePkg/Library/DxeCoreHobLib/HobLib.c index 302d1bbd8c..ad66966279 100644 --- a/MdePkg/Library/DxeCoreHobLib/HobLib.c +++ b/MdePkg/Library/DxeCoreHobLib/HobLib.c @@ -1,19 +1,17 @@ /** @file HOB Library implementation for DxeCore driver. - Copyright (c) 2006 - 2008, Intel Corporation
- All rights reserved. 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 +Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.
+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. +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ - - #include #include @@ -23,10 +21,17 @@ /** Returns the pointer to the HOB list. - ASSERT() if the HOB list returned by GetHobList() is NULL. 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. **/ @@ -43,11 +48,12 @@ 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. + 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. @@ -83,8 +89,10 @@ 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. + 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. @@ -104,15 +112,18 @@ GetFirstHob ( } /** - 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. + 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 such a HOB from the starting HOB pointer does not exist, 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. + to extract the data section and its size information, 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(). @@ -142,12 +153,16 @@ GetNextGuidHob ( } /** - This function searches the first instance of a HOB among the whole HOB list. + 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. + If such a HOB from the starting HOB pointer does not exist, 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. + to extract the data section and its size information, 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. @@ -168,11 +183,13 @@ GetFirstGuidHob ( } /** - Get the Boot Mode from the HOB list. + Get the system boot mode from the HOB list. - This function returns the system boot mode information from the + 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. @@ -190,19 +207,21 @@ GetBootModeHob ( return HandOffHob->BootMode; } + /** 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. + for DXE phase, it will ASSERT() because 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 EntryPoint The 64 bit physical address of the module entry point. **/ VOID @@ -221,11 +240,44 @@ BuildModuleHob ( } /** - Builds a HOB that describes a chunk of system memory. + 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 + ) +{ + // + // PEI HOB is read only for DXE phase + // + ASSERT (FALSE); +} + +/** + 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() because 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. @@ -250,21 +302,25 @@ BuildResourceDescriptorHob ( } /** - Builds a GUID HOB with a certain data length. + 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. + 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. + It can only be invoked during PEI phase. + For DXE phase, it will ASSERT() because 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_GUID_TYPE)), 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. - @return The start address of GUID HOB data. + @retval NULL The GUID HOB could not be allocated. + @retval others The start address of GUID HOB data. **/ VOID * @@ -282,23 +338,28 @@ BuildGuidHob ( } /** - Copies a data buffer to a newly-built HOB. + 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, - 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() because 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. + It can only be invoked during PEI phase. + For DXE phase, it will ASSERT() because 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_GUID_TYPE)), 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. - @return The start address of GUID HOB data. + @retval NULL The GUID HOB could not be allocated. + @retval others The start address of GUID HOB data. **/ VOID * @@ -321,7 +382,8 @@ BuildGuidDataHob ( 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. + for DXE phase, it will ASSERT() because 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. @@ -346,12 +408,13 @@ BuildFvHob ( 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. + for DXE phase, it will ASSERT() because 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. - @param FvName The name of the Firmware Volume. + @param FvName The name of the Firmware Volume. @param FileName The name of the file. **/ @@ -372,7 +435,9 @@ BuildFv2Hob ( 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. + for DXE phase, it will ASSERT() because 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. @@ -397,7 +462,8 @@ BuildCvHob ( 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. + for DXE phase, it will ASSERT() because 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. @@ -422,7 +488,8 @@ BuildCpuHob ( 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. + for DXE phase, it will ASSERT() because 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. @@ -447,7 +514,8 @@ BuildStackHob ( 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. + for DXE phase, it will ASSERT() because 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. @@ -474,7 +542,8 @@ BuildBspStoreHob ( 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. + for DXE phase, it will ASSERT() because 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.