Synchronize the MdePkg\Include\Library\BaseMemoryLib.h,

CacheMaintenance.h,CpuLib.h,DebugLib.h,DevicePathLib.h with the MDE_Library_Spec.

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

5 files changed, 154 insertions, 15 deletions

diff --git a/MdePkg/Include/Library/BaseMemoryLib.h b/MdePkg/Include/Library/BaseMemoryLib.h
index abc3bb209a..973bc2b635 100644
--- a/MdePkg/Include/Library/BaseMemoryLib.h
+++ b/MdePkg/Include/Library/BaseMemoryLib.h
@@ -1,5 +1,9 @@
 /** @file

-  Provides copy memory, fill memory, zero memory, and GUID functions. 

+  Provides copy memory, fill memory, zero memory, and GUID functions.

+   

+  The Base Memory Library provides optimized implementions for common memory-based operations. 

+  These functions should be used in place of coding your own loops to do equivalent common functions. 

+  This allows optimized library implementations to help increase performance. 

 

 Copyright (c) 2006 - 2008, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -47,7 +51,7 @@ CopyMem (
 

   @param  Buffer    Memory to set.

   @param  Length    Number of bytes to set.

-  @param  Value     Value of the set operation.

+  @param  Value     Value with which to fill Length bytes of Buffer.

 

   @return Buffer.

 

diff --git a/MdePkg/Include/Library/CacheMaintenanceLib.h b/MdePkg/Include/Library/CacheMaintenanceLib.h
index b5b3dd3d51..a5c690f804 100644
--- a/MdePkg/Include/Library/CacheMaintenanceLib.h
+++ b/MdePkg/Include/Library/CacheMaintenanceLib.h
@@ -1,6 +1,9 @@
 /** @file

   Provides services to maintain instruction and data caches.

-

+  

+  The Cache Maintenance Library provides abstractions for basic processor cache operations.

+  It removes the need to use assembly in C code.

+    

 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

diff --git a/MdePkg/Include/Library/CpuLib.h b/MdePkg/Include/Library/CpuLib.h
index ec36b41af2..b54dd26991 100644
--- a/MdePkg/Include/Library/CpuLib.h
+++ b/MdePkg/Include/Library/CpuLib.h
@@ -1,6 +1,11 @@
 /** @file

   Provides CPU architecture specific functions that can not be defined

   in the Base Library due to dependencies on the PAL Library

+  

+  The CPU Library provides services to flush CPU TLBs and place the CPU in a sleep state.

+  The implementation of these services on Itanium CPUs requires the use of PAL Calls.

+  PAL Calls require PEI and DXE specific mechanisms to look up PAL Entry Point.

+  As a result, these services could not be defined in the Base Library.

 

 Copyright (c) 2006 - 2008, Intel Corporation

 All rights reserved. This program and the accompanying materials

diff --git a/MdePkg/Include/Library/DebugLib.h b/MdePkg/Include/Library/DebugLib.h
index 7465abb24d..51da314ea2 100644
--- a/MdePkg/Include/Library/DebugLib.h
+++ b/MdePkg/Include/Library/DebugLib.h
@@ -1,6 +1,9 @@
 /** @file

   Provides services to print debug and assert messages to a debug output device.

-

+  

+  The Debug library supports debug print and asserts based on a combination of macros and code.

+  The debug library can be turned on and off so that the debug code does not increase the size of an image.

+  

 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

diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h
index 05e98a4d3d..891b5d657a 100644
--- a/MdePkg/Include/Library/DevicePathLib.h
+++ b/MdePkg/Include/Library/DevicePathLib.h
@@ -1,6 +1,11 @@
 /** @file

   Provides library functions to construct and parse UEFI Device Paths.

 

+  This library provides defines, macros, and functions to help create and parse 

+  EFI_DEVICE_PATH_PROTOCOL structures.  The macros that help create and parse device 

+  path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from 

+  the Base Library, so this library class has an implied dependency on the Base Library.

+

 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

@@ -18,15 +23,121 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Library/BaseLib.h>

 

 #define END_DEVICE_PATH_LENGTH               (sizeof (EFI_DEVICE_PATH_PROTOCOL))

-#define DevicePathNodeLength(Node)           ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])

-#define NextDevicePathNode(Node)             ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))

+

+/**

+  Macro that returns the Type field of a device path node.

+

+  Returns the Type field of the device path node specified by Node.

+

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

+

+  @return The Type field of the device path node specified by Node.

+

+**/

 #define DevicePathType(Node)                 (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type)

+

+/**

+  Macro that returns the SubType field of a device path node.

+

+  Returns the SubType field of the device path node specified by Node.

+

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

+

+  @return The SubType field of the device path node specified by Node.

+

+**/

 #define DevicePathSubType(Node)              (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType)

+

+/**

+  Macro that returns the 16-bit Length field of a device path node.

+

+  Returns the 16-bit Length field of the device path node specified by Node.

+

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

+

+  @return The 16-bit Length field of the device path node specified by Node.

+

+**/

+#define DevicePathNodeLength(Node)           ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])

+

+/**

+  Macro that returns a pointer to the next node in a device path.

+

+  Returns a pointer to the device path node that follows the device path node specified by Node.

+

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

+

+  @return a pointer to the device path node that follows the device path node specified by Node.

+

+**/

+#define NextDevicePathNode(Node)             ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))

+

+/**

+  Macro that determines if a device path node is an end node of a device path.

+  This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.

+

+  Determines if the device path node specified by Node is an end node of a device path.  

+  This includes nodes that are the end of a device path instance and nodes that are the 

+  end of an entire device path.  If Node represents an end node of a device path, 

+  then TRUE is returned.  Otherwise, FALSE is returned.

+

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

+

+  @retval TRUE      The device path node specified by Node is an end node of a device path.

+  @retval FALSE     The device path node specified by Node is not an end node of a device path.

+  

+**/

 #define IsDevicePathEndType(Node)            ((DevicePathType (Node) & 0x7f) == END_DEVICE_PATH_TYPE)

+

+/**

+  Macro that determines if a device path node is an end node of an entire device path.

+

+  Determines if a device path node specified by Node is an end node of an entire device path.

+  If Node represents the end of an entire device path, then TRUE is returned.  Otherwise, FALSE is returned.

+

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

+

+  @retval TRUE      The device path node specified by Node is the end of an entire device path.

+  @retval FALSE     The device path node specified by Node is not the end of an entire device path.

+

+**/

 #define IsDevicePathEnd(Node)                (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE)

+

+/**

+  Macro that determines if a device path node is an end node of a device path instance.

+

+  Determines if a device path node specified by Node is an end node of a device path instance.

+  If Node represents the end of a device path instance, then TRUE is returned.  Otherwise, FALSE is returned.

+

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

+

+  @retval TRUE      The device path node specified by Node is the end of a device path instance.

+  @retval FALSE     The device path node specified by Node is not the end of a device path instance.

+

+**/

 #define IsDevicePathEndInstance(Node)        (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE)

 

+/**

+  Macro that sets the length, in bytes, of a device path node.

+

+  Sets the length of the device path node specified by Node to the value specified by Length. Length is returned.

+

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

+  @param  Length    The length, in bytes, of the device path node.

+

+  @return Length

+

+**/

 #define SetDevicePathNodeLength(Node,NodeLength)  WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(NodeLength))

+

+/**

+  Macro that fills in all the fields of a device path node that is the end of an entire device path.

+

+  Fills in all the fields of a device path node specified by Node so Node represents the end of an entire device path.

+

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

+

+**/

 #define SetDevicePathEndNode(Node)  {                                   \

           DevicePathType (Node)    = END_DEVICE_PATH_TYPE;              \

           DevicePathSubType (Node) = END_ENTIRE_DEVICE_PATH_SUBTYPE;    \

@@ -40,8 +151,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.

 

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

-

-  @return The size of a device path in bytes.

+  

+  @retval 0       If DevicePath is NULL.

+  @retval Others  The size of a device path in bytes.

 

 **/

 UINTN

@@ -57,11 +169,14 @@ GetDevicePathSize (
   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the

   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer

   is returned.  Otherwise, NULL is returned.  

+  The memory for the new device path is allocated from EFI boot services memory. 

+  It is the responsibility of the caller to free the memory allocated. 

   

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

 

-  @return A pointer to the duplicated device path.

-

+  @retval NULL    If DevicePath is NULL.

+  @retval Others  A pointer to the duplicated device path.

+  

 **/

 EFI_DEVICE_PATH_PROTOCOL *

 EFIAPI

@@ -85,8 +200,10 @@ DuplicateDevicePath (
 

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

   @param  SecondDevicePath           A pointer to a device path data structure.

-

-  @return A pointer to the new device path.

+  

+  @retval NULL      If there is not enough memory for the newly allocated buffer.

+  @retval Others    A pointer to the new device path if success.

+                    Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.

 

 **/

 EFI_DEVICE_PATH_PROTOCOL *

@@ -114,7 +231,11 @@ AppendDevicePath (
   @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.

+  @retval NULL      If there is not enough memory for the new device path.

+  @retval Others    A pointer to the new device path if success.

+                    A copy of DevicePathNode followed by an end-of-device-path node 

+                    if both FirstDevicePath and SecondDevicePath are NULL.

+                    A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.

 

 **/

 EFI_DEVICE_PATH_PROTOCOL *

@@ -183,8 +304,7 @@ GetNextDevicePathInstance (
   );

 

 /**

-  Creates a copy of the current device path instance and returns a pointer to the next device path

-  instance.

+  Creates a device node.

 

   This function creates a new device node in a newly allocated buffer of size NodeLength and

   initializes the device path node header with NodeType and NodeSubType.  The new device path node

@@ -252,7 +372,11 @@ DevicePathFromHandle (
   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle

   that does not support the device path protocol, then a device path containing a single device

   path node for the file specified by FileName is allocated and returned.

+  The memory for the new device path is allocated from EFI boot services memory. It is the responsibility

+  of the caller to free the memory allocated.

+  

   If FileName is NULL, then ASSERT().

+  If FileName is not aligned on a 16-bit boundary, then ASSERT().

 

   @param  Device                     A pointer to a device handle.  This parameter is optional and

                                      may be NULL.