*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

EdkModulePkg/EdkModulePkg.spd

@@ -469,6 +469,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
       <C_Name>gEfiCompatibleMemoryTestedGuid</C_Name>
       <Guid>0x64c475ef, 0x344b, 0x492c, 0x93, 0xad, 0xab, 0x9e, 0xb4, 0x39, 0x50, 0x4</Guid>
     </Entry>
+    <Entry Name="PeiPerformanceHob">
+      <C_Name>gPeiPerformanceHobGuid</C_Name>
+      <Guid>0xec4df5af, 0x4395, 0x4cc9, 0x94, 0xde, 0x77, 0x50, 0x6d, 0x12, 0xc7, 0xb8</Guid>
+    </Entry>
   </GuidDeclarations>
   <ProtocolDeclarations>
     <Entry Name="CustomizedDecompress">
@@ -571,6 +575,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
       <C_Name>gEfiIsaAcpiProtocolGuid</C_Name>
       <Guid>0x64a892dc, 0x5561, 0x4536, 0x92, 0xc7, 0x79, 0x9b, 0xfc, 0x18, 0x33, 0x55</Guid>
     </Entry>
+    <Entry Name="Performance">
+      <C_Name>gPerformanceProtocolGuid</C_Name>
+      <Guid>0x76b6bdfa, 0x2acd, 0x4462, 0x9E, 0x3F, 0xcb, 0x58, 0xC9, 0x69, 0xd9, 0x37</Guid>
+    </Entry>
   </ProtocolDeclarations>
   <PpiDeclarations>
     <Entry Name="PeiInMemory">

MdePkg/Include/Library/DevicePathLib.h

@@ -77,12 +77,11 @@ AppendDevicePath (
   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  DevicePath A pointer to a device path data structure.
   
-	@param	SecondDevicePath A pointer to a single device path node.
+  @param  DevicePathNode A pointer to a single device path node.
 
-	@return
+  @return A pointer to the new device path.
-	A pointer to the new device path.
   If there is not enough temporary pool memory available to complete this function,
   then NULL is returned.
 
@@ -90,8 +89,8 @@ AppendDevicePath (
 EFI_DEVICE_PATH_PROTOCOL *
 EFIAPI
 AppendDevicePathNode (
-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode
   )
 ;
 

MdePkg/Include/Library/HobLib.h

@@ -20,6 +20,8 @@
 /**
   Returns the pointer to the HOB list.
 
+  This function returns the pointer to first HOB in the list.
+
   @return The pointer to the HOB list.
 
 **/
@@ -31,8 +33,14 @@ 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.
+  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.
@@ -49,6 +57,8 @@ 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. 
 
@@ -69,6 +79,13 @@ 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.
@@ -89,6 +106,9 @@ 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.
 
@@ -103,7 +123,13 @@ GetFirstGuidHob (
 ;
 
 /**
+  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.
@@ -124,6 +150,11 @@ BuildModuleHob (
 /**
   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.
@@ -141,8 +172,16 @@ BuildResourceDescriptorHob (
 ;
 
 /**
+  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.
@@ -159,8 +198,17 @@ BuildGuidHob (
 ;
 
 /**
+  Copies a data buffer to a newly-built 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 GUID HOB data.
+  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.
@@ -181,6 +229,11 @@ BuildGuidDataHob (
 /**
   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.
 
@@ -196,6 +249,11 @@ BuildFvHob (
 /**
   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 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.
 
@@ -211,6 +269,11 @@ BuildCvHob (
 /**
   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.
 
@@ -226,6 +289,11 @@ BuildCpuHob (
 /**
   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.
 
@@ -241,6 +309,11 @@ BuildStackHob (
 /**
   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.
@@ -258,6 +331,11 @@ BuildBspStoreHob (
 /**
   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.

MdePkg/Library/BaseSmbusLib/BaseSmbusLib.msa

@@ -32,7 +32,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
     <Updated>2006-03-19 15:17</Updated>
   </MsaLibHeader>
   <LibraryClassDefinitions>
-    <LibraryClass Usage="ALWAYS_PRODUCED">SmBusLib</LibraryClass>
+    <LibraryClass Usage="ALWAYS_PRODUCED">SmbusLib</LibraryClass>
     <LibraryClass Usage="ALWAYS_CONSUMED">BaseLib</LibraryClass>
     <LibraryClass Usage="ALWAYS_CONSUMED">IoLib</LibraryClass>
     <LibraryClass Usage="ALWAYS_CONSUMED">PciLib</LibraryClass>

MdePkg/Library/BaseSmbusLib/SmbusLibRegisters.h

@@ -0,0 +1,120 @@
+/** @file
+  Base SMBUS library implementation built upon I/O library.
+
+  Copyright (c) 2006, Intel Corporation<BR>
+  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.
+
+  Module Name:  SmbusLib.h
+
+**/
+
+#ifndef __SMBUS_LIB_REGISTER_H
+#define __SMBUS_LIB_REGISTER_H
+
+#define SMBUS_R_HST_STS               0x00  // Host Status Register
+#define SMBUS_B_HOST_BUSY             0x01  // RO
+#define SMBUS_B_INTR                  0x02  // R/WC
+#define SMBUS_B_DEV_ERR               0x04  // R/WC
+#define SMBUS_B_BUS_ERR               0x08  // R/WC
+#define SMBUS_B_FAILED                0x10  // R/WC
+#define SMBUS_B_SMBALERT_STS          0x20  // R/WC
+#define SMBUS_B_INUSE_STS             0x40  // R/WC
+#define SMBUS_B_BYTE_DONE_STS         0x80  // R/WC
+#define SMBUS_B_ERROR                 (SMBUS_B_DEV_ERR | SMBUS_B_BUS_ERR | SMBUS_B_FAILED)
+#define SMBUS_B_HSTS_ALL              0xFF  // R/WC
+
+
+#define SMBUS_R_HST_CTL               0x02  // Host Control Register R/W
+#define SMBUS_B_INTREN                0x01  // RW
+#define SMBUS_B_KILL                  0x02  // RW
+#define SMBUS_B_CMD                   (7 << 2) // RW
+#define SMBUS_V_SMB_CMD_QUICK         (0 << 2)
+#define SMBUS_V_SMB_CMD_BYTE          (1 << 2)
+#define SMBUS_V_SMB_CMD_BYTE_DATA     (2 << 2)
+#define SMBUS_V_SMB_CMD_WORD_DATA     (3 << 2)
+#define SMBUS_V_SMB_CMD_PROCESS_CALL  (4 << 2)
+#define SMBUS_V_SMB_CMD_BLOCK         (5 << 2)
+#define SMBUS_V_SMB_CMD_IIC_READ      (6 << 2)
+#define SMBUS_V_SMB_CMD_BLOCK_PROCESS (7 << 2)
+#define SMBUS_B_LAST_BYTE             0x20  // WO
+#define SMBUS_B_START                 0x40  // WO
+#define SMBUS_B_PEC_EN                0x80  // RW
+
+
+#define SMBUS_R_HST_CMD               0x03  // Host Command Register R/W
+
+
+#define SMBUS_R_XMIT_SLVA             0x04  // Transmit Slave Address Register R/W
+#define SMBUS_B_RW                    0x01  // RW
+#define SMBUS_B_READ                  0x01  // RW
+#define SMBUS_B_WRITE                 0x00  // RW
+#define SMBUS_B_ADDRESS               0xFE  // RW
+
+
+#define SMBUS_R_HST_D0                0x05  // Data 0 Register R/W
+
+
+#define SMBUS_R_HST_D1                0x06  // Data 1 Register R/W
+
+
+#define SMBUS_R_HOST_BLOCK_DB         0x07  // Host Block Data Register R/W
+
+
+#define SMBUS_R_PEC                   0x08  // Packet Error Check Data Register R/W
+
+
+#define SMBUS_R_RCV_SLVA              0x09  // Receive Slave Address Register R/W
+#define SMBUS_B_SLAVE_ADDR            0x7F  // RW
+
+
+#define SMBUS_R_SLV_DATA              0x0A  // Receive Slave Data Register R/W
+
+
+#define SMBUS_R_AUX_STS               0x0C  // Auxiliary Status Register R/WC
+#define SMBUS_B_CRCE                  0x01  // R/WC
+
+
+#define SMBUS_R_AUX_CTL               0x0D  // Auxiliary Control Register R/W
+#define SMBUS_B_AAC                   0x01  // R/W
+#define SMBUS_B_E32B                  0x02  // R/W
+
+
+#define SMBUS_R_SMLINK_PIN_CTL        0x0E  // SMLINK Pin Control Register R/W
+#define SMBUS_B_SMLINK0_CUR_STS       0x01  // RO
+#define SMBUS_B_SMLINK1_CUR_STS       0x02  // RO
+#define SMBUS_B_SMLINK_CLK_CTL        0x04  // RW
+
+
+#define SMBUS_R_SMBUS_PIN_CTL         0x0F  // SMBus Pin Control Register R/W
+#define SMBUS_B_SMBCLK_CUR_STS        0x01  // RO
+#define SMBUS_B_SMBDATA_CUR_STS       0x02  // RO
+#define SMBUS_B_SMBCLK_CTL            0x04  // RW
+
+
+#define SMBUS_R_SLV_STS               0x10  // Slave Status Register R/WC
+#define SMBUS_B_HOST_NOTIFY_STS       0x01  // R/WC
+
+
+#define SMBUS_R_SLV_CMD               0x11  // Slave Command Register R/W
+#define SMBUS_B_HOST_NOTIFY_INTREN    0x01  // R/W
+#define SMBUS_B_HOST_NOTIFY_WKEN      0x02  // R/W
+#define SMBUS_B_SMBALERT_DIS          0x04  // R/W
+
+
+#define SMBUS_R_NOTIFY_DADDR          0x14  // Notify Device Address Register RO
+#define SMBUS_B_DEVICE_ADDRESS        0xFE  // RO
+
+
+#define SMBUS_R_NOTIFY_DLOW           0x16  // Notify Data Low Byte Register RO
+
+
+#define SMBUS_R_NOTIFY_DHIGH          0x17  // Notify Data High Byte Register RO   
+
+
+#endif

MdePkg/Library/DxeCoreHobLib/HobLib.c

@@ -18,9 +18,12 @@
 
 extern VOID *gHobList;
 
+
 /**
   Returns the pointer to the HOB list.
 
+  This function returns the pointer to first HOB in the list.
+
   @return The pointer to the HOB list.
 
 **/
@@ -34,8 +37,14 @@ 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.
+  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.
@@ -56,7 +65,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) {
@@ -68,6 +77,8 @@ 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. 
 
@@ -93,6 +104,13 @@ 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.
@@ -124,6 +142,9 @@ 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.
 
@@ -143,7 +164,13 @@ GetFirstGuidHob (
 }
 
 /**
+  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.
@@ -169,6 +196,11 @@ BuildModuleHob (
 /**
   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.
@@ -191,8 +223,16 @@ BuildResourceDescriptorHob (
 }
 
 /**
+  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.
@@ -215,8 +255,17 @@ BuildGuidHob (
 }
 
 /**
+  Copies a data buffer to a newly-built 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 GUID HOB data.
+  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.
@@ -243,6 +292,11 @@ BuildGuidDataHob (
 /**
   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.
 
@@ -263,6 +317,11 @@ BuildFvHob (
 /**
   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 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.
 
@@ -283,6 +342,11 @@ BuildCvHob (
 /**
   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.
 
@@ -303,6 +367,11 @@ BuildCpuHob (
 /**
   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.
 
@@ -323,6 +392,11 @@ BuildStackHob (
 /**
   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.
@@ -345,6 +419,11 @@ BuildBspStoreHob (
 /**
   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.

MdePkg/Library/DxeHobLib/HobLib.c

@@ -48,9 +48,9 @@ HobLibConstructor (
 /**
   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 *
@@ -63,8 +63,14 @@ 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.
+  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.
@@ -85,7 +91,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) {
@@ -97,6 +103,8 @@ 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. 
 
@@ -122,6 +130,13 @@ 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.
@@ -153,6 +168,9 @@ 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.
 
@@ -172,7 +190,13 @@ GetFirstGuidHob (
 }
 
 /**
+  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.
@@ -198,6 +222,11 @@ BuildModuleHob (
 /**
   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.
@@ -220,8 +249,16 @@ BuildResourceDescriptorHob (
 }
 
 /**
+  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.
@@ -244,8 +281,17 @@ BuildGuidHob (
 }
 
 /**
+  Copies a data buffer to a newly-built 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 GUID HOB data.
+  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.
@@ -272,6 +318,11 @@ BuildGuidDataHob (
 /**
   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.
 
@@ -292,6 +343,11 @@ BuildFvHob (
 /**
   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 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.
 
@@ -312,6 +368,11 @@ BuildCvHob (
 /**
   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.
 
@@ -332,6 +393,11 @@ BuildCpuHob (
 /**
   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.
 
@@ -352,6 +418,11 @@ BuildStackHob (
 /**
   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.
@@ -374,6 +445,11 @@ BuildBspStoreHob (
 /**
   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.

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,8 +41,14 @@ 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.
+  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.
@@ -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,6 +81,8 @@ 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. 
 
@@ -100,6 +108,13 @@ 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.
@@ -131,6 +146,9 @@ 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.
 
@@ -150,7 +168,9 @@ GetFirstGuidHob (
 }
 
 /**
-  Add a new HOB to the HOB List.
+  Adds a new HOB to the HOB List.
+
+  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.
@@ -176,7 +196,13 @@ 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.
@@ -209,6 +235,11 @@ BuildModuleHob (
 /**
   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.
@@ -235,8 +266,16 @@ BuildResourceDescriptorHob (
 }
 
 /**
+  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.
@@ -264,8 +303,17 @@ BuildGuidHob (
 }
 
 /**
+  Copies a data buffer to a newly-built 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 GUID HOB data.
+  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.
@@ -292,6 +340,11 @@ BuildGuidDataHob (
 /**
   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.
 
@@ -314,6 +367,11 @@ BuildFvHob (
 /**
   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 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.
 
@@ -336,6 +394,11 @@ BuildCvHob (
 /**
   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.
 
@@ -358,6 +421,11 @@ BuildCpuHob (
 /**
   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.
 
@@ -382,6 +450,11 @@ BuildStackHob (
 /**
   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.
@@ -408,6 +481,11 @@ BuildBspStoreHob (
 /**
   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.

MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c

@@ -155,9 +155,9 @@ AppendDevicePath (
   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  DevicePath A pointer to a device path data structure.
   
-  @param  SecondDevicePath A pointer to a single device path node.
+  @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,
@@ -167,40 +167,37 @@ AppendDevicePath (
 EFI_DEVICE_PATH_PROTOCOL *
 EFIAPI
 AppendDevicePathNode (
-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
-  IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
+  IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode
   )
 {
+  EFI_DEVICE_PATH_PROTOCOL  *TempDevicePath;
   EFI_DEVICE_PATH_PROTOCOL  *NextNode;
   EFI_DEVICE_PATH_PROTOCOL  *NewDevicePath;
   UINTN                     NodeLength;
-  UINTN                     Size1;
 
   //
   // Build a Node that has a terminator on it
   //
-  NodeLength  = DevicePathNodeLength (SecondDevicePath);
+  NodeLength = DevicePathNodeLength (DevicePathNode);
-  Size1       = GetDevicePathSize (FirstDevicePath);
 
-  NewDevicePath = AllocatePool (NodeLength + Size1);
+  TempDevicePath = AllocatePool (NodeLength + sizeof (EFI_DEVICE_PATH_PROTOCOL));
-  if (NewDevicePath != NULL) {
+  if (TempDevicePath == NULL) {
-    //
+    return NULL;
-    // Copy the first device path to the new device path
-    //
-    NewDevicePath = CopyMem (NewDevicePath, FirstDevicePath, Size1);
-
-    //
-    // Copy the device path node to the new device path
-    //
-    NextNode      = (EFI_DEVICE_PATH_PROTOCOL *) ((CHAR8 *) NewDevicePath + (Size1 - sizeof (EFI_DEVICE_PATH_PROTOCOL)));
-    NextNode      = CopyMem (NextNode, SecondDevicePath, NodeLength);
-
-    //
-    // Terminate the whole device path
-    //
-    NextNode      = NextDevicePathNode (NextNode);
-    SetDevicePathEndNode (NextNode);
   }
+  TempDevicePath = CopyMem (TempDevicePath, DevicePathNode, NodeLength);
+  //
+  // Add and end device path node to convert Node to device path
+  //
+  NextNode = NextDevicePathNode (TempDevicePath);
+  SetDevicePathEndNode (NextNode);
+  //
+  // Append device paths
+  //
+  NewDevicePath = AppendDevicePath (DevicePath, TempDevicePath);
+
+  FreePool (TempDevicePath);
+
   return NewDevicePath;
 }