*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

2 files changed, 155 insertions, 78 deletions

diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h
index bedbd1c0d4..b42a8fecfd 100644
--- a/MdePkg/Include/Library/DevicePathLib.h
+++ b/MdePkg/Include/Library/DevicePathLib.h
@@ -74,24 +74,23 @@ AppendDevicePath (
 ;

 

 /**

-	This function appends the device path node SecondDevicePath

-	to every device path instance in FirstDevicePath.

+  This function appends the device path node SecondDevicePath

+  to every device path instance in FirstDevicePath.

 

-	@param	FirstDevicePath A pointer to a device path data structure.

-	

-	@param	SecondDevicePath A pointer to a single device path node.

+  @param  DevicePath A pointer to a device path data structure.

+  

+  @param  DevicePathNode A pointer to a single device path node.

 

-	@return

-	A pointer to the new device path.

-	If there is not enough temporary pool memory available to complete this function,

-	then NULL is returned.

+  @return A pointer to the new device path.

+  If there is not enough temporary pool memory available to complete this function,

+  then NULL is returned.

 

 **/

 EFI_DEVICE_PATH_PROTOCOL *

 EFIAPI

 AppendDevicePathNode (

-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,

-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath

+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,

+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode

   )

 ;

 

diff --git a/MdePkg/Include/Library/HobLib.h b/MdePkg/Include/Library/HobLib.h
index cac9c4fa09..9789c693e7 100644
--- a/MdePkg/Include/Library/HobLib.h
+++ b/MdePkg/Include/Library/HobLib.h
@@ -18,9 +18,11 @@
 #define __HOB_LIB_H__

 

 /**

-	Returns the pointer to the HOB list.

+  Returns the pointer to the HOB list.

 

-	@return The pointer to the HOB list.

+  This function returns the pointer to first HOB in the list.

+

+  @return The pointer to the HOB list.

 

 **/

 VOID *

@@ -31,13 +33,19 @@ GetHobList (
 ;

 

 /**

-	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. 

+  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.

+  @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.

+  @return The next instance of a HOB type from the starting HOB.

 

 **/

 VOID *

@@ -49,12 +57,14 @@ GetNextHob (
 ;

 

 /**

-	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. 

+  Returns the first instance of a HOB type among the whole HOB list.

 

-	@param	Type The HOB type to return.

+  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. 

 

-	@return The next instance of a HOB type from the starting HOB.

+  @param  Type          The HOB type to return.

+

+  @return The next instance of a HOB type from the starting HOB.

 

 **/

 VOID *

@@ -65,15 +75,22 @@ 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. 

-

-	@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.

+  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 *

@@ -85,14 +102,17 @@ GetNextGuidHob (
 ;

 

 /**

-	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.

+  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 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.

+  @return The first instance of the matched GUID HOB among the whole HOB list.

 

 **/

 VOID *

@@ -103,12 +123,18 @@ GetFirstGuidHob (
 ;

 

 /**

-	This function builds a HOB for a loaded PE32 module.

+  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

@@ -122,12 +148,17 @@ BuildModuleHob (
 ;

 

 /**

-	Builds a HOB that describes a chunk of system memory.

+  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

@@ -141,13 +172,21 @@ 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.

+  @return The start address of GUID HOB data.

 

 **/

 VOID *

@@ -159,14 +198,23 @@ 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().

 

-	@return The start address of GUID HOB data.

+  @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.

 

 **/

 VOID *

@@ -179,10 +227,15 @@ BuildGuidDataHob (
 ;

 

 /**

-	Builds a Firmware Volume HOB.

+  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().

 

-	@param	BaseAddress The base address of the Firmware Volume.

-	@param	Length The size of the Firmware Volume in bytes.

+  @param  BaseAddress   The base address of the Firmware Volume.

+  @param  Length        The size of the Firmware Volume in bytes.

 

 **/

 VOID

@@ -194,10 +247,15 @@ BuildFvHob (
 ;

 

 /**

-	Builds a Capsule Volume HOB.

+  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

@@ -209,10 +267,15 @@ BuildCvHob (
 ;

 

 /**

-	Builds a HOB for the CPU.

+  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.

+  @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.

+  @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.

 

 **/

 VOID

@@ -224,10 +287,15 @@ BuildCpuHob (
 ;

 

 /**

-	Builds a HOB for the Stack.

+  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

@@ -239,11 +307,16 @@ BuildStackHob (
 ;

 

 /**

-	Builds a HOB for the BSP store.

+  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.

+  @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

@@ -256,11 +329,16 @@ BuildBspStoreHob (
 ;

 

 /**

-	Builds a HOB for the memory allocation.

+  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.

+  @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