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