MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c

   1 /** @file
   2   UEFI Device Path Library.
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   Module Name:  UefiDevicePathLib.c
  14
  15 **/
  16
  17 STATIC EFI_DEVICE_PATH_UTILITIES_PROTOCOL          *mDevicePathUtilities = NULL;
  18
  19 /**
  20   The constructor function caches the pointer to DevicePathUtilites protocol.
  21
  22   The constructor function locates DevicePathUtilities protocol from protocol database.
  23   It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
  24
  25   @param  ImageHandle   The firmware allocated handle for the EFI image.
  26   @param  SystemTable   A pointer to the EFI System Table.
  27
  28   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  29
  30 **/
  31 EFI_STATUS
  32 EFIAPI
  33 DevicePathLibConstructor (
  34   IN      EFI_HANDLE                ImageHandle,
  35   IN      EFI_SYSTEM_TABLE          *SystemTable
  36   )
  37 {
  38   EFI_STATUS                        Status;
  39
  40   Status = gBS->LocateProtocol (
  41                   &gEfiDevicePathUtilitiesProtocolGuid,
  42                   NULL,
  43                   (VOID**) &mDevicePathUtilities
  44                   );
  45   ASSERT_EFI_ERROR (Status);
  46   ASSERT (mDevicePathUtilities != NULL);
  47
  48   return Status;
  49 }
  50
  51 /**
  52   This function returns the size, in bytes,
  53   of the device path data structure specified by DevicePath.
  54   If DevicePath is NULL, then 0 is returned.
  55
  56   @param  DevicePath A pointer to a device path data structure.
  57
  58   @return The size of a device path in bytes.
  59
  60 **/
  61 UINTN
  62 EFIAPI
  63 GetDevicePathSize (
  64   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  65   )
  66 {
  67   return mDevicePathUtilities->GetDevicePathSize (DevicePath);
  68 }
  69
  70 /**
  71   This function allocates space for a new copy of the device path
  72   specified by DevicePath.
  73
  74   @param  DevicePath A pointer to a device path data structure.
  75
  76   @return The duplicated device path.
  77
  78 **/
  79 EFI_DEVICE_PATH_PROTOCOL *
  80 EFIAPI
  81 DuplicateDevicePath (
  82   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath
  83   )
  84 {
  85   return mDevicePathUtilities->DuplicateDevicePath (DevicePath);
  86 }
  87
  88 /**
  89   This function appends the device path SecondDevicePath
  90   to every device path instance in FirstDevicePath.
  91
  92   @param  FirstDevicePath A pointer to a device path data structure.
  93
  94   @param  SecondDevicePath A pointer to a device path data structure.
  95
  96   @return A pointer to the new device path is returned.
  97   NULL is returned if space for the new device path could not be allocated from pool.
  98   It is up to the caller to free the memory used by FirstDevicePath and SecondDevicePath
  99   if they are no longer needed.
 100
 101 **/
 102 EFI_DEVICE_PATH_PROTOCOL *
 103 EFIAPI
 104 AppendDevicePath (
 105   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
 106   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
 107   )
 108 {
 109   return mDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);
 110 }
 111
 112 /**
 113   This function appends the device path node SecondDevicePath
 114   to every device path instance in FirstDevicePath.
 115
 116   @param  FirstDevicePath A pointer to a device path data structure.
 117
 118   @param  SecondDevicePath A pointer to a single device path node.
 119
 120   @return A pointer to the new device path.
 121   If there is not enough temporary pool memory available to complete this function,
 122   then NULL is returned.
 123
 124 **/
 125 EFI_DEVICE_PATH_PROTOCOL *
 126 EFIAPI
 127 AppendDevicePathNode (
 128   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
 129   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
 130   )
 131 {
 132   return mDevicePathUtilities->AppendDeviceNode (FirstDevicePath, SecondDevicePath);
 133 }
 134
 135 /**
 136   This function appends the device path instance Instance to the device path Source.
 137   If Source is NULL, then a new device path with one instance is created.
 138
 139   @param  Source A pointer to a device path data structure.
 140   @param  Instance A pointer to a device path instance.
 141
 142   @return A pointer to the new device path.
 143   If there is not enough temporary pool memory available to complete this function,
 144   then NULL is returned.
 145
 146 **/
 147 EFI_DEVICE_PATH_PROTOCOL *
 148 EFIAPI
 149 AppendDevicePathInstance (
 150   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Source,
 151   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Instance
 152   )
 153 {
 154   return mDevicePathUtilities->AppendDevicePathInstance (Source, Instance);
 155 }
 156
 157 /**
 158   Function retrieves the next device path instance from a device path data structure.
 159
 160   @param  DevicePath A pointer to a device path data structure.
 161
 162   @param  Size A pointer to the size of a device path instance in bytes.
 163
 164   @return This function returns a pointer to the current device path instance.
 165   In addition, it returns the size in bytes of the current device path instance in Size,
 166   and a pointer to the next device path instance in DevicePath.
 167   If there are no more device path instances in DevicePath, then DevicePath will be set to NULL.
 168
 169 **/
 170 EFI_DEVICE_PATH_PROTOCOL *
 171 EFIAPI
 172 GetNextDevicePathInstance (
 173   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 174      OUT UINTN                     *Size
 175   )
 176 {
 177   ASSERT (DevicePath != NULL);
 178   ASSERT (Size != NULL);
 179   return mDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);
 180 }
 181
 182 /**
 183   Return TRUE is this is a multi instance device path.
 184
 185   @param  DevicePath A pointer to a device path data structure.
 186
 187   @retval  TRUE If DevicePath is multi-instance.
 188   @retval  FALSE If DevicePath is not multi-instance or DevicePath is NULL.
 189
 190 **/
 191 BOOLEAN
 192 EFIAPI
 193 IsDevicePathMultiInstance (
 194   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 195   )
 196 {
 197   return mDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);
 198 }
 199
 200 /**
 201   This function retrieves the device path protocol from a handle.
 202
 203   @param  Handle The handle from which to retrieve the device path protocol.
 204
 205   @return This function returns the device path protocol from the handle specified by Handle.
 206   If Handle is NULL or Handle does not contain a device path protocol, then NULL is returned.
 207
 208 **/
 209 EFI_DEVICE_PATH_PROTOCOL *
 210 EFIAPI
 211 DevicePathFromHandle (
 212   IN EFI_HANDLE  Handle
 213   )
 214 {
 215   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 216   EFI_STATUS                Status;
 217
 218   Status = gBS->HandleProtocol (
 219                   Handle,
 220                   &gEfiDevicePathProtocolGuid,
 221                   (VOID *) &DevicePath
 222                   );
 223   if (EFI_ERROR (Status)) {
 224     DevicePath = NULL;
 225   }
 226   return DevicePath;
 227 }
 228
 229 /**
 230   This function allocates a device path for a file and appends it to an existing device path.
 231
 232   @param  Device A pointer to a device handle.  This parameter is optional and may be NULL.
 233   @param  FileName A pointer to a Null-terminated Unicode string.
 234
 235   @return If Device is a valid device handle that contains a device path protocol,
 236   then a device path for the file specified by FileName is allocated
 237   and appended to the device path associated with the handle Device. The allocated device path is returned.
 238   If Device is NULL or Device is a handle that does not support the device path protocol,
 239   then a device path containing a single device path node for the file specified by FileName
 240   is allocated and returned.
 241
 242 **/
 243 EFI_DEVICE_PATH_PROTOCOL *
 244 EFIAPI
 245 FileDevicePath (
 246   IN EFI_HANDLE    Device,     OPTIONAL
 247   IN CONST CHAR16  *FileName
 248   )
 249 {
 250   UINTN                     Size;
 251   FILEPATH_DEVICE_PATH      *FilePath;
 252   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 253   EFI_DEVICE_PATH_PROTOCOL  *FileDevicePathNode;
 254
 255   DevicePath = NULL;
 256
 257   Size = StrSize (FileName);
 258   FileDevicePathNode = mDevicePathUtilities->CreateDeviceNode (
 259                                                MEDIA_DEVICE_PATH,
 260                                                MEDIA_FILEPATH_DP,
 261                                                (UINT16) (Size + SIZE_OF_FILEPATH_DEVICE_PATH)
 262                                                );
 263   if (FileDevicePathNode != NULL) {
 264     FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePathNode;
 265     CopyMem (&FilePath->PathName, FileName, Size);
 266     if (Device != NULL) {
 267       DevicePath = DevicePathFromHandle (Device);
 268     }
 269     DevicePath = AppendDevicePathNode (DevicePath, FileDevicePathNode);
 270     FreePool (FileDevicePathNode);
 271   }
 272   return DevicePath;
 273 }
 274