MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c

   1 /** @file
   2   Library instance that implement UEFI Device Path Library class based on protocol
   3   gEfiDevicePathUtilitiesProtocolGuid.
   4
   5   Copyright (c) 2006 - 2008, Intel Corporation<BR>
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16
  17 #include <Uefi.h>
  18
  19 #include <Protocol/DevicePathUtilities.h>
  20 #include <Protocol/DevicePath.h>
  21
  22 #include <Library/DevicePathLib.h>
  23 #include <Library/DebugLib.h>
  24 #include <Library/BaseLib.h>
  25 #include <Library/MemoryAllocationLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28
  29 EFI_DEVICE_PATH_UTILITIES_PROTOCOL          *mDevicePathUtilities = NULL;
  30
  31 /**
  32   The constructor function caches the pointer to DevicePathUtilites protocol.
  33
  34   The constructor function locates DevicePathUtilities protocol from protocol database.
  35   It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
  36
  37   @param  ImageHandle   The firmware allocated handle for the EFI image.
  38   @param  SystemTable   A pointer to the EFI System Table.
  39
  40   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  41
  42 **/
  43 EFI_STATUS
  44 EFIAPI
  45 DevicePathLibConstructor (
  46   IN      EFI_HANDLE                ImageHandle,
  47   IN      EFI_SYSTEM_TABLE          *SystemTable
  48   )
  49 {
  50   EFI_STATUS                        Status;
  51
  52   Status = gBS->LocateProtocol (
  53                   &gEfiDevicePathUtilitiesProtocolGuid,
  54                   NULL,
  55                   (VOID**) &mDevicePathUtilities
  56                   );
  57   ASSERT_EFI_ERROR (Status);
  58   ASSERT (mDevicePathUtilities != NULL);
  59
  60   return Status;
  61 }
  62
  63 /**
  64   Returns the size of a device path in bytes.
  65
  66   This function returns the size, in bytes, of the device path data structure specified by
  67   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.
  68
  69   @param  DevicePath                 A pointer to a device path data structure.
  70
  71   @retval 0       If DevicePath is NULL.
  72   @retval Others  The size of a device path in bytes.
  73
  74 **/
  75 UINTN
  76 EFIAPI
  77 GetDevicePathSize (
  78   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  79   )
  80 {
  81   return mDevicePathUtilities->GetDevicePathSize (DevicePath);
  82 }
  83
  84 /**
  85   Creates a new device path by appending a second device path to a first device path.
  86
  87   This function allocates space for a new copy of the device path specified by DevicePath.  If
  88   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
  89   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
  90   is returned.  Otherwise, NULL is returned.
  91   The memory for the new device path is allocated from EFI boot services memory.
  92   It is the responsibility of the caller to free the memory allocated.
  93
  94   @param  DevicePath                 A pointer to a device path data structure.
  95
  96   @retval NULL    If DevicePath is NULL.
  97   @retval Others  A pointer to the duplicated device path.
  98
  99 **/
 100 EFI_DEVICE_PATH_PROTOCOL *
 101 EFIAPI
 102 DuplicateDevicePath (
 103   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 104   )
 105 {
 106   return mDevicePathUtilities->DuplicateDevicePath (DevicePath);
 107 }
 108
 109 /**
 110   Creates a new device path by appending a second device path to a first device path.
 111
 112   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 113   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 114   SecondDevicePath is retained. The newly created device path is returned.
 115   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 116   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 117   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 118   returned.
 119   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 120   The memory for the new device path is allocated from EFI boot services memory. It is the
 121   responsibility of the caller to free the memory allocated.
 122
 123   @param  FirstDevicePath            A pointer to a device path data structure.
 124   @param  SecondDevicePath           A pointer to a device path data structure.
 125
 126   @retval NULL      If there is not enough memory for the newly allocated buffer.
 127   @retval Others    A pointer to the new device path if success.
 128                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 129
 130 **/
 131 EFI_DEVICE_PATH_PROTOCOL *
 132 EFIAPI
 133 AppendDevicePath (
 134   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
 135   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 136   )
 137 {
 138   return mDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);
 139 }
 140
 141 /**
 142   Creates a new path by appending the device node to the device path.
 143
 144   This function creates a new device path by appending a copy of the device node specified by
 145   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 146   The end-of-device-path device node is moved after the end of the appended device node.
 147   If DevicePathNode is NULL then a copy of DevicePath is returned.
 148   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 149   node is returned.
 150   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 151   is returned.
 152   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 153   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 154   free the memory allocated.
 155
 156   @param  DevicePath                 A pointer to a device path data structure.
 157   @param  DevicePathNode             A pointer to a single device path node.
 158
 159   @retval NULL      If there is not enough memory for the new device path.
 160   @retval Others    A pointer to the new device path if success.
 161                     A copy of DevicePathNode followed by an end-of-device-path node
 162                     if both FirstDevicePath and SecondDevicePath are NULL.
 163                     A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
 164
 165 **/
 166 EFI_DEVICE_PATH_PROTOCOL *
 167 EFIAPI
 168 AppendDevicePathNode (
 169   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 170   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 171   )
 172 {
 173   return mDevicePathUtilities->AppendDeviceNode (DevicePath, DevicePathNode);
 174 }
 175
 176 /**
 177   Creates a new device path by appending the specified device path instance to the specified device
 178   path.
 179
 180   This function creates a new device path by appending a copy of the device path instance specified
 181   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
 182   The end-of-device-path device node is moved after the end of the appended device path instance
 183   and a new end-of-device-path-instance node is inserted between.
 184   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 185   If DevicePathInstance is NULL, then NULL is returned.
 186   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 187   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 188   free the memory allocated.
 189
 190   @param  DevicePath                 A pointer to a device path data structure.
 191   @param  DevicePathInstance         A pointer to a device path instance.
 192
 193   @return A pointer to the new device path.
 194
 195 **/
 196 EFI_DEVICE_PATH_PROTOCOL *
 197 EFIAPI
 198 AppendDevicePathInstance (
 199   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 200   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 201   )
 202 {
 203   return mDevicePathUtilities->AppendDevicePathInstance (DevicePath, DevicePathInstance);
 204 }
 205
 206 /**
 207   Creates a copy of the current device path instance and returns a pointer to the next device path
 208   instance.
 209
 210   This function creates a copy of the current device path instance. It also updates DevicePath to
 211   point to the next device path instance in the device path (or NULL if no more) and updates Size
 212   to hold the size of the device path instance copy.
 213   If DevicePath is NULL, then NULL is returned.
 214   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 215   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 216   free the memory allocated.
 217   If Size is NULL, then ASSERT().
 218
 219   @param  DevicePath                 On input, this holds the pointer to the current device path
 220                                      instance. On output, this holds the pointer to the next device
 221                                      path instance or NULL if there are no more device path
 222                                      instances in the device path pointer to a device path data
 223                                      structure.
 224   @param  Size                       On output, this holds the size of the device path instance, in
 225                                      bytes or zero, if DevicePath is NULL.
 226
 227   @return A pointer to the current device path instance.
 228
 229 **/
 230 EFI_DEVICE_PATH_PROTOCOL *
 231 EFIAPI
 232 GetNextDevicePathInstance (
 233   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 234   OUT UINTN                          *Size
 235   )
 236 {
 237   ASSERT (Size != NULL);
 238   return mDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);
 239 }
 240
 241 /**
 242   Creates a device node.
 243
 244   This function creates a new device node in a newly allocated buffer of size NodeLength and
 245   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 246   is returned.
 247   If NodeLength is smaller than a device path header, then NULL is returned.
 248   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 249   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 250   free the memory allocated.
 251
 252   @param  NodeType                   The device node type for the new device node.
 253   @param  NodeSubType                The device node sub-type for the new device node.
 254   @param  NodeLength                 The length of the new device node.
 255
 256   @return The new device path.
 257
 258 **/
 259 EFI_DEVICE_PATH_PROTOCOL *
 260 EFIAPI
 261 CreateDeviceNode (
 262   IN UINT8                           NodeType,
 263   IN UINT8                           NodeSubType,
 264   IN UINT16                          NodeLength
 265   )
 266 {
 267   return mDevicePathUtilities->CreateDeviceNode (NodeType, NodeSubType, NodeLength);
 268 }
 269
 270 /**
 271   Determines if a device path is single or multi-instance.
 272
 273   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 274   Otherwise, FALSE is returned.  If DevicePath is NULL, then FALSE is returned.
 275
 276   @param  DevicePath                 A pointer to a device path data structure.
 277
 278   @retval  TRUE                      DevicePath is multi-instance.
 279   @retval  FALSE                     DevicePath is not multi-instance or DevicePath is NULL.
 280
 281 **/
 282 BOOLEAN
 283 EFIAPI
 284 IsDevicePathMultiInstance (
 285   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 286   )
 287 {
 288   return mDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);
 289 }
 290
 291 /**
 292   Retrieves the device path protocol from a handle.
 293
 294   This function returns the device path protocol from the handle specified by Handle.  If Handle is
 295   NULL or Handle does not contain a device path protocol, then NULL is returned.
 296
 297   @param  Handle                     The handle from which to retrieve the device path protocol.
 298
 299   @return The device path protocol from the handle specified by Handle.
 300
 301 **/
 302 EFI_DEVICE_PATH_PROTOCOL *
 303 EFIAPI
 304 DevicePathFromHandle (
 305   IN EFI_HANDLE                      Handle
 306   )
 307 {
 308   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 309   EFI_STATUS                Status;
 310
 311   Status = gBS->HandleProtocol (
 312                   Handle,
 313                   &gEfiDevicePathProtocolGuid,
 314                   (VOID *) &DevicePath
 315                   );
 316   if (EFI_ERROR (Status)) {
 317     DevicePath = NULL;
 318   }
 319   return DevicePath;
 320 }
 321
 322 /**
 323   Allocates a device path for a file and appends it to an existing device path.
 324
 325   If Device is a valid device handle that contains a device path protocol, then a device path for
 326   the file specified by FileName  is allocated and appended to the device path associated with the
 327   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
 328   that does not support the device path protocol, then a device path containing a single device
 329   path node for the file specified by FileName is allocated and returned.
 330   The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
 331   of the caller to free the memory allocated.
 332
 333   If FileName is NULL, then ASSERT().
 334   If FileName is not aligned on a 16-bit boundary, then ASSERT().
 335
 336   @param  Device                     A pointer to a device handle.  This parameter is optional and
 337                                      may be NULL.
 338   @param  FileName                   A pointer to a Null-terminated Unicode string.
 339
 340   @return The allocated device path.
 341
 342 **/
 343 EFI_DEVICE_PATH_PROTOCOL *
 344 EFIAPI
 345 FileDevicePath (
 346   IN EFI_HANDLE                      Device,     OPTIONAL
 347   IN CONST CHAR16                    *FileName
 348   )
 349 {
 350   UINTN                     Size;
 351   FILEPATH_DEVICE_PATH      *FilePath;
 352   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 353   EFI_DEVICE_PATH_PROTOCOL  *FileDevicePath;
 354
 355   DevicePath = NULL;
 356
 357   Size = StrSize (FileName);
 358   FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + END_DEVICE_PATH_LENGTH);
 359   if (FileDevicePath != NULL) {
 360     FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePath;
 361     FilePath->Header.Type    = MEDIA_DEVICE_PATH;
 362     FilePath->Header.SubType = MEDIA_FILEPATH_DP;
 363     CopyMem (&FilePath->PathName, FileName, Size);
 364     SetDevicePathNodeLength (&FilePath->Header, Size + SIZE_OF_FILEPATH_DEVICE_PATH);
 365     SetDevicePathEndNode (NextDevicePathNode (&FilePath->Header));
 366
 367     if (Device != NULL) {
 368       DevicePath = DevicePathFromHandle (Device);
 369     }
 370
 371     DevicePath = AppendDevicePath (DevicePath, FileDevicePath);
 372     FreePool (FileDevicePath);
 373   }
 374
 375   return DevicePath;
 376 }