MdePkg/Library/UefiDevicePathLib/UefiDevicePathLibOptionalDevicePathProtocol.c

   1 /** @file
   2   Device Path services. The thing to remember is device paths are built out of
   3   nodes. The device path is terminated by an end node that is length
   4   sizeof(EFI_DEVICE_PATH_PROTOCOL). That would be why there is sizeof(EFI_DEVICE_PATH_PROTOCOL)
   5   all over this file.
   6
   7   The only place where multi-instance device paths are supported is in
   8   environment varibles. Multi-instance device paths should never be placed
   9   on a Handle.
  10
  11   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
  12   SPDX-License-Identifier: BSD-2-Clause-Patent
  13
  14 **/
  15
  16
  17 #include "UefiDevicePathLib.h"
  18
  19 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_UTILITIES_PROTOCOL *mDevicePathLibDevicePathUtilities = NULL;
  20 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_TO_TEXT_PROTOCOL   *mDevicePathLibDevicePathToText    = NULL;
  21 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL *mDevicePathLibDevicePathFromText  = NULL;
  22
  23 /**
  24   The constructor function caches the pointer to DevicePathUtilites protocol,
  25   DevicePathToText protocol and DevicePathFromText protocol.
  26
  27   The constructor function locates these three protocols from protocol database.
  28   It will caches the pointer to local protocol instance if that operation fails
  29   and it will always return EFI_SUCCESS.
  30
  31   @param  ImageHandle   The firmware allocated handle for the EFI image.
  32   @param  SystemTable   A pointer to the EFI System Table.
  33
  34   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  35
  36 **/
  37 EFI_STATUS
  38 EFIAPI
  39 UefiDevicePathLibOptionalDevicePathProtocolConstructor (
  40   IN      EFI_HANDLE                ImageHandle,
  41   IN      EFI_SYSTEM_TABLE          *SystemTable
  42   )
  43 {
  44   EFI_STATUS                        Status;
  45
  46   Status = gBS->LocateProtocol (
  47                   &gEfiDevicePathUtilitiesProtocolGuid,
  48                   NULL,
  49                   (VOID**) &mDevicePathLibDevicePathUtilities
  50                   );
  51   ASSERT_EFI_ERROR (Status);
  52   ASSERT (mDevicePathLibDevicePathUtilities != NULL);
  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
  60   specified by DevicePath including the end of device path node.
  61   If DevicePath is NULL or invalid, then 0 is returned.
  62
  63   @param  DevicePath  A pointer to a device path data structure.
  64
  65   @retval 0           If DevicePath is NULL or invalid.
  66   @retval Others      The size of a device path in bytes.
  67
  68 **/
  69 UINTN
  70 EFIAPI
  71 GetDevicePathSize (
  72   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  73   )
  74 {
  75   if (mDevicePathLibDevicePathUtilities != NULL) {
  76     return mDevicePathLibDevicePathUtilities->GetDevicePathSize (DevicePath);
  77   } else {
  78     return UefiDevicePathLibGetDevicePathSize (DevicePath);
  79   }
  80 }
  81
  82 /**
  83   Creates a new copy of an existing device path.
  84
  85   This function allocates space for a new copy of the device path specified by DevicePath.
  86   If DevicePath is NULL, then NULL is returned.  If the memory is successfully
  87   allocated, then the contents of DevicePath are copied to the newly allocated
  88   buffer, and a pointer to that buffer is returned.  Otherwise, NULL is returned.
  89   The memory for the new device path is allocated from EFI boot services memory.
  90   It is the responsibility of the caller to free the memory allocated.
  91
  92   @param  DevicePath    A pointer to a device path data structure.
  93
  94   @retval NULL          DevicePath is NULL or invalid.
  95   @retval Others        A pointer to the duplicated device path.
  96
  97 **/
  98 EFI_DEVICE_PATH_PROTOCOL *
  99 EFIAPI
 100 DuplicateDevicePath (
 101   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 102   )
 103 {
 104   if (mDevicePathLibDevicePathUtilities != NULL) {
 105     return mDevicePathLibDevicePathUtilities->DuplicateDevicePath (DevicePath);
 106   } else {
 107     return UefiDevicePathLibDuplicateDevicePath (DevicePath);
 108   }
 109 }
 110
 111 /**
 112   Creates a new device path by appending a second device path to a first device path.
 113
 114   This function creates a new device path by appending a copy of SecondDevicePath
 115   to a copy of FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path
 116   device node from SecondDevicePath is retained. The newly created device path is
 117   returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
 118   SecondDevicePath is returned.  If SecondDevicePath is NULL, then it is ignored,
 119   and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
 120   SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
 121
 122   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 123   The memory for the new device path is allocated from EFI boot services memory.
 124   It is the responsibility of the caller to free the memory allocated.
 125
 126   @param  FirstDevicePath            A pointer to a device path data structure.
 127   @param  SecondDevicePath           A pointer to a device path data structure.
 128
 129   @retval NULL      If there is not enough memory for the newly allocated buffer.
 130   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
 131   @retval Others    A pointer to the new device path if success.
 132                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 133
 134 **/
 135 EFI_DEVICE_PATH_PROTOCOL *
 136 EFIAPI
 137 AppendDevicePath (
 138   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath   OPTIONAL,
 139   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 140   )
 141 {
 142   if (mDevicePathLibDevicePathUtilities != NULL) {
 143     return mDevicePathLibDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);
 144   } else {
 145     return UefiDevicePathLibAppendDevicePath (FirstDevicePath, SecondDevicePath);
 146   }
 147 }
 148
 149 /**
 150   Creates a new path by appending the device node to the device path.
 151
 152   This function creates a new device path by appending a copy of the device node
 153   specified by DevicePathNode to a copy of the device path specified by DevicePath
 154   in an allocated buffer. The end-of-device-path device node is moved after the
 155   end of the appended device node.
 156   If DevicePathNode is NULL then a copy of DevicePath is returned.
 157   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
 158   path device node is returned.
 159   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
 160   device node is returned.
 161   If there is not enough memory to allocate space for the new device path, then
 162   NULL is returned.
 163   The memory is allocated from EFI boot services memory. It is the responsibility
 164   of the caller to free the memory allocated.
 165
 166   @param  DevicePath                 A pointer to a device path data structure.
 167   @param  DevicePathNode             A pointer to a single device path node.
 168
 169   @retval NULL      If there is not enough memory for the new device path.
 170   @retval Others    A pointer to the new device path if success.
 171                     A copy of DevicePathNode followed by an end-of-device-path node
 172                     if both FirstDevicePath and SecondDevicePath are NULL.
 173                     A copy of an end-of-device-path node if both FirstDevicePath
 174                     and SecondDevicePath are NULL.
 175
 176 **/
 177 EFI_DEVICE_PATH_PROTOCOL *
 178 EFIAPI
 179 AppendDevicePathNode (
 180   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath      OPTIONAL,
 181   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 182   )
 183 {
 184   if (mDevicePathLibDevicePathUtilities != NULL) {
 185     return mDevicePathLibDevicePathUtilities->AppendDeviceNode (DevicePath, DevicePathNode);
 186   } else {
 187     return UefiDevicePathLibAppendDevicePathNode (DevicePath, DevicePathNode);
 188   }
 189 }
 190
 191 /**
 192   Creates a new device path by appending the specified device path instance to the specified device
 193   path.
 194
 195   This function creates a new device path by appending a copy of the device path
 196   instance specified by DevicePathInstance to a copy of the device path specified
 197   by DevicePath in a allocated buffer.
 198   The end-of-device-path device node is moved after the end of the appended device
 199   path instance and a new end-of-device-path-instance node is inserted between.
 200   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 201   If DevicePathInstance is NULL, then NULL is returned.
 202   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 203   If there is not enough memory to allocate space for the new device path, then
 204   NULL is returned.
 205   The memory is allocated from EFI boot services memory. It is the responsibility
 206   of the caller to free the memory allocated.
 207
 208   @param  DevicePath                 A pointer to a device path data structure.
 209   @param  DevicePathInstance         A pointer to a device path instance.
 210
 211   @return A pointer to the new device path.
 212
 213 **/
 214 EFI_DEVICE_PATH_PROTOCOL *
 215 EFIAPI
 216 AppendDevicePathInstance (
 217   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath         OPTIONAL,
 218   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 219   )
 220 {
 221   if (mDevicePathLibDevicePathUtilities != NULL) {
 222     return mDevicePathLibDevicePathUtilities->AppendDevicePathInstance (DevicePath, DevicePathInstance);
 223   } else {
 224     return UefiDevicePathLibAppendDevicePathInstance (DevicePath, DevicePathInstance);
 225   }
 226 }
 227
 228 /**
 229   Creates a copy of the current device path instance and returns a pointer to the next device path
 230   instance.
 231
 232   This function creates a copy of the current device path instance. It also updates
 233   DevicePath to point to the next device path instance in the device path (or NULL
 234   if no more) and updates Size to hold the size of the device path instance copy.
 235   If DevicePath is NULL, then NULL is returned.
 236   If DevicePath points to a invalid device path, then NULL is returned.
 237   If there is not enough memory to allocate space for the new device path, then
 238   NULL is returned.
 239   The memory is allocated from EFI boot services memory. It is the responsibility
 240   of the caller to free the memory allocated.
 241   If Size is NULL, then ASSERT().
 242
 243   @param  DevicePath                 On input, this holds the pointer to the current
 244                                      device path instance. On output, this holds
 245                                      the pointer to the next device path instance
 246                                      or NULL if there are no more device path
 247                                      instances in the device path pointer to a
 248                                      device path data structure.
 249   @param  Size                       On output, this holds the size of the device
 250                                      path instance, in bytes or zero, if DevicePath
 251                                      is NULL.
 252
 253   @return A pointer to the current device path instance.
 254
 255 **/
 256 EFI_DEVICE_PATH_PROTOCOL *
 257 EFIAPI
 258 GetNextDevicePathInstance (
 259   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 260   OUT UINTN                          *Size
 261   )
 262 {
 263   if (mDevicePathLibDevicePathUtilities != NULL) {
 264     return mDevicePathLibDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);
 265   } else {
 266     return UefiDevicePathLibGetNextDevicePathInstance (DevicePath, Size);
 267   }
 268 }
 269
 270 /**
 271   Creates a device node.
 272
 273   This function creates a new device node in a newly allocated buffer of size
 274   NodeLength and initializes the device path node header with NodeType and NodeSubType.
 275   The new device path node is returned.
 276   If NodeLength is smaller than a device path header, then NULL is returned.
 277   If there is not enough memory to allocate space for the new device path, then
 278   NULL is returned.
 279   The memory is allocated from EFI boot services memory. It is the responsibility
 280   of the caller to free the memory allocated.
 281
 282   @param  NodeType                   The device node type for the new device node.
 283   @param  NodeSubType                The device node sub-type for the new device node.
 284   @param  NodeLength                 The length of the new device node.
 285
 286   @return The new device path.
 287
 288 **/
 289 EFI_DEVICE_PATH_PROTOCOL *
 290 EFIAPI
 291 CreateDeviceNode (
 292   IN UINT8                           NodeType,
 293   IN UINT8                           NodeSubType,
 294   IN UINT16                          NodeLength
 295   )
 296 {
 297   if (mDevicePathLibDevicePathUtilities != NULL) {
 298     return mDevicePathLibDevicePathUtilities->CreateDeviceNode (NodeType, NodeSubType, NodeLength);
 299   } else {
 300     return UefiDevicePathLibCreateDeviceNode (NodeType, NodeSubType, NodeLength);
 301   }
 302 }
 303
 304 /**
 305   Determines if a device path is single or multi-instance.
 306
 307   This function returns TRUE if the device path specified by DevicePath is
 308   multi-instance.
 309   Otherwise, FALSE is returned.
 310   If DevicePath is NULL or invalid, then FALSE is returned.
 311
 312   @param  DevicePath                 A pointer to a device path data structure.
 313
 314   @retval  TRUE                      DevicePath is multi-instance.
 315   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath
 316                                      is NULL or invalid.
 317
 318 **/
 319 BOOLEAN
 320 EFIAPI
 321 IsDevicePathMultiInstance (
 322   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 323   )
 324 {
 325   if (mDevicePathLibDevicePathUtilities != NULL) {
 326     return mDevicePathLibDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);
 327   } else {
 328     return UefiDevicePathLibIsDevicePathMultiInstance (DevicePath);
 329   }
 330 }
 331
 332 /**
 333   Locate and return the protocol instance identified by the ProtocolGuid.
 334
 335   @param ProtocolGuid     The GUID of the protocol.
 336
 337   @return A pointer to the protocol instance or NULL when absent.
 338 **/
 339 VOID *
 340 UefiDevicePathLibLocateProtocol (
 341   EFI_GUID                         *ProtocolGuid
 342   )
 343 {
 344   EFI_STATUS Status;
 345   VOID       *Protocol;
 346   Status = gBS->LocateProtocol (
 347                   ProtocolGuid,
 348                   NULL,
 349                   (VOID**) &Protocol
 350                   );
 351   if (EFI_ERROR (Status)) {
 352     return NULL;
 353   } else {
 354     return Protocol;
 355   }
 356 }
 357
 358 /**
 359   Converts a device node to its string representation.
 360
 361   @param DeviceNode        A Pointer to the device node to be converted.
 362   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 363                            of the display node is used, where applicable. If DisplayOnly
 364                            is FALSE, then the longer text representation of the display node
 365                            is used.
 366   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 367                            representation for a device node can be used, where applicable.
 368
 369   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 370           is NULL or there was insufficient memory.
 371
 372 **/
 373 CHAR16 *
 374 EFIAPI
 375 ConvertDeviceNodeToText (
 376   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 377   IN BOOLEAN                         DisplayOnly,
 378   IN BOOLEAN                         AllowShortcuts
 379   )
 380 {
 381   if (mDevicePathLibDevicePathToText == NULL) {
 382     mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);
 383   }
 384   if (mDevicePathLibDevicePathToText != NULL) {
 385     return mDevicePathLibDevicePathToText->ConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);
 386   }
 387
 388   return UefiDevicePathLibConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);
 389 }
 390
 391 /**
 392   Converts a device path to its text representation.
 393
 394   @param DevicePath      A Pointer to the device to be converted.
 395   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 396                          of the display node is used, where applicable. If DisplayOnly
 397                          is FALSE, then the longer text representation of the display node
 398                          is used.
 399   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 400                          representation for a device node can be used, where applicable.
 401
 402   @return A pointer to the allocated text representation of the device path or
 403           NULL if DeviceNode is NULL or there was insufficient memory.
 404
 405 **/
 406 CHAR16 *
 407 EFIAPI
 408 ConvertDevicePathToText (
 409   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath,
 410   IN BOOLEAN                          DisplayOnly,
 411   IN BOOLEAN                          AllowShortcuts
 412   )
 413 {
 414   if (mDevicePathLibDevicePathToText == NULL) {
 415     mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);
 416   }
 417   if (mDevicePathLibDevicePathToText != NULL) {
 418     return mDevicePathLibDevicePathToText->ConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);
 419   }
 420
 421   return UefiDevicePathLibConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);
 422 }
 423
 424 /**
 425   Convert text to the binary representation of a device node.
 426
 427   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 428                          node. Conversion starts with the first character and continues
 429                          until the first non-device node character.
 430
 431   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 432           insufficient memory or text unsupported.
 433
 434 **/
 435 EFI_DEVICE_PATH_PROTOCOL *
 436 EFIAPI
 437 ConvertTextToDeviceNode (
 438   IN CONST CHAR16 *TextDeviceNode
 439   )
 440 {
 441   if (mDevicePathLibDevicePathFromText == NULL) {
 442     mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);
 443   }
 444   if (mDevicePathLibDevicePathFromText != NULL) {
 445     return mDevicePathLibDevicePathFromText->ConvertTextToDeviceNode (TextDeviceNode);
 446   }
 447
 448   return UefiDevicePathLibConvertTextToDeviceNode (TextDeviceNode);
 449 }
 450
 451 /**
 452   Convert text to the binary representation of a device path.
 453
 454
 455   @param TextDevicePath  TextDevicePath points to the text representation of a device
 456                          path. Conversion starts with the first character and continues
 457                          until the first non-device node character.
 458
 459   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 460           there was insufficient memory.
 461
 462 **/
 463 EFI_DEVICE_PATH_PROTOCOL *
 464 EFIAPI
 465 ConvertTextToDevicePath (
 466   IN CONST CHAR16 *TextDevicePath
 467   )
 468 {
 469   if (mDevicePathLibDevicePathFromText == NULL) {
 470     mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);
 471   }
 472   if (mDevicePathLibDevicePathFromText != NULL) {
 473     return mDevicePathLibDevicePathFromText->ConvertTextToDevicePath (TextDevicePath);
 474   }
 475
 476   return UefiDevicePathLibConvertTextToDevicePath (TextDevicePath);
 477 }