*BaseSmbusLib: (new version)

Complete function header, detailed description, ASSERT()s & pass smoke test in MRC of Lakeport package by replacing Smbus PPI. 
*Device Patch Lib
Fix a bug in AppendDevicePathNode() (Solve Track #44 in Remodel PVCS). The original logic failed if the first device path was NULL.
*Performance Lib 
Add PeiPerformanceHob & Performance protocol in spd file in EdkModule Package (Solve Tracker #41, #42 in Remodel PVCS).
*Hob Lib
Add detailed description for each Hob function.


git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@126 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 122 insertions, 44 deletions

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