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