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