Add several missing assertions.

[mirror_edk2.git] / MdePkg / Library / UefiDevicePathLibDevicePathProtocol / UefiDevicePathLib.c

diff --git a/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c b/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c
index 9dbe773e4e5a8093858ca6487a4cb8daa06d722c..1380a03d16e086ab5c0d23bbd14543f67d7c0c48 100644 (file)
--- a/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c
+++ b/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c
@@ -1,5 +1,6 @@
 /** @file\r
-  UEFI Device Path Library.\r
+  Library instance that implement UEFI Device Path Library class based on protocol\r
+  gEfiDevicePathUtilitiesProtocolGuid.\r
 \r
   Copyright (c) 2006, Intel Corporation<BR>\r
   All rights reserved. This program and the accompanying materials\r
@@ -25,9 +26,7 @@
 #include <Library/BaseMemoryLib.h>\r
 #include <Library/UefiBootServicesTableLib.h>\r
 \r
-#include "UefiDevicePathLibInternal.h"\r
-\r
-STATIC EFI_DEVICE_PATH_UTILITIES_PROTOCOL          *mDevicePathUtilities = NULL;\r
+EFI_DEVICE_PATH_UTILITIES_PROTOCOL          *mDevicePathUtilities = NULL;\r
 \r
 /**\r
   The constructor function caches the pointer to DevicePathUtilites protocol.\r
@@ -68,8 +67,9 @@ DevicePathLibConstructor (
   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.\r
 \r
   @param  DevicePath                 A pointer to a device path data structure.\r
-\r
-  @return The size of a device path in bytes.\r
+  \r
+  @retval 0       If DevicePath is NULL.\r
+  @retval Others  The size of a device path in bytes.\r
 \r
 **/\r
 UINTN\r
@@ -88,11 +88,14 @@ GetDevicePathSize (
   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the\r
   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer\r
   is returned.  Otherwise, NULL is returned.  \r
+  The memory for the new device path is allocated from EFI boot services memory. \r
+  It is the responsibility of the caller to free the memory allocated. \r
   \r
   @param  DevicePath                 A pointer to a device path data structure.\r
 \r
-  @return A pointer to the duplicated device path.\r
-\r
+  @retval NULL    If DevicePath is NULL.\r
+  @retval Others  A pointer to the duplicated device path.\r
+  \r
 **/\r
 EFI_DEVICE_PATH_PROTOCOL *\r
 EFIAPI\r
@@ -119,8 +122,10 @@ DuplicateDevicePath (
 \r
   @param  FirstDevicePath            A pointer to a device path data structure.\r
   @param  SecondDevicePath           A pointer to a device path data structure.\r
-\r
-  @return A pointer to the new device path.\r
+  \r
+  @retval NULL      If there is not enough memory for the newly allocated buffer.\r
+  @retval Others    A pointer to the new device path if success.\r
+                    Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.\r
 \r
 **/\r
 EFI_DEVICE_PATH_PROTOCOL *\r
@@ -139,8 +144,9 @@ AppendDevicePath (
   This function creates a new device path by appending a copy of the device node specified by\r
   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.\r
   The end-of-device-path device node is moved after the end of the appended device node.\r
-  If DeviceNode is NULL then a copy of DevicePath is returned.\r
   If DevicePathNode is NULL then a copy of DevicePath is returned.\r
+  If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device\r
+  node is returned.\r
   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node\r
   is returned.\r
   If there is not enough memory to allocate space for the new device path, then NULL is returned.  \r
@@ -150,7 +156,11 @@ AppendDevicePath (
   @param  DevicePath                 A pointer to a device path data structure.\r
   @param  DevicePathNode             A pointer to a single device path node.\r
 \r
-  @return A pointer to the new device path.\r
+  @retval NULL      If there is not enough memory for the new device path.\r
+  @retval Others    A pointer to the new device path if success.\r
+                    A copy of DevicePathNode followed by an end-of-device-path node \r
+                    if both FirstDevicePath and SecondDevicePath are NULL.\r
+                    A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.\r
 \r
 **/\r
 EFI_DEVICE_PATH_PROTOCOL *\r
@@ -229,8 +239,7 @@ GetNextDevicePathInstance (
 }\r
 \r
 /**\r
-  Creates a copy of the current device path instance and returns a pointer to the next device path\r
-  instance.\r
+  Creates a device node.\r
 \r
   This function creates a new device node in a newly allocated buffer of size NodeLength and\r
   initializes the device path node header with NodeType and NodeSubType.  The new device path node\r
@@ -318,7 +327,11 @@ DevicePathFromHandle (
   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle\r
   that does not support the device path protocol, then a device path containing a single device\r
   path node for the file specified by FileName is allocated and returned.\r
+  The memory for the new device path is allocated from EFI boot services memory. It is the responsibility\r
+  of the caller to free the memory allocated.\r
+  \r
   If FileName is NULL, then ASSERT().\r
+  If FileName is not aligned on a 16-bit boundary, then ASSERT().\r
 \r
   @param  Device                     A pointer to a device handle.  This parameter is optional and\r
                                      may be NULL.\r
@@ -342,7 +355,7 @@ FileDevicePath (
   DevicePath = NULL;\r
 \r
   Size = StrSize (FileName);\r
-  FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + EFI_END_DEVICE_PATH_LENGTH);\r
+  FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + END_DEVICE_PATH_LENGTH);\r
   if (FileDevicePath != NULL) {\r
     FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePath;\r
     FilePath->Header.Type    = MEDIA_DEVICE_PATH;\r
@@ -361,4 +374,3 @@ FileDevicePath (
 \r
   return DevicePath;\r
 }\r
-\r