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