MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c

   1 /** @file
   2   Library instance that implement UEFI Device Path Library class based on protocol
   3   gEfiDevicePathUtilitiesProtocolGuid.
   4
   5   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16
  17 #include <Uefi.h>
  18
  19 #include <Protocol/DevicePathUtilities.h>
  20 #include <Protocol/DevicePathToText.h>
  21 #include <Protocol/DevicePathFromText.h>
  22
  23 #include <Library/DevicePathLib.h>
  24 #include <Library/DebugLib.h>
  25 #include <Library/BaseLib.h>
  26 #include <Library/MemoryAllocationLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/PcdLib.h>
  30
  31 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_UTILITIES_PROTOCOL *mDevicePathLibDevicePathUtilities = NULL;
  32 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_TO_TEXT_PROTOCOL   *mDevicePathLibDevicePathToText    = NULL;
  33 GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL *mDevicePathLibDevicePathFromText  = NULL;
  34
  35 //
  36 // Template for an end-of-device path node.
  37 //
  38 GLOBAL_REMOVE_IF_UNREFERENCED CONST EFI_DEVICE_PATH_PROTOCOL  mUefiDevicePathLibEndDevicePath = {
  39   END_DEVICE_PATH_TYPE,
  40   END_ENTIRE_DEVICE_PATH_SUBTYPE,
  41   {
  42     END_DEVICE_PATH_LENGTH,
  43     0
  44   }
  45 };
  46
  47 /**
  48   The constructor function caches the pointer to DevicePathUtilites protocol.
  49
  50   The constructor function locates DevicePathUtilities protocol from protocol database.
  51   It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
  52
  53   @param  ImageHandle   The firmware allocated handle for the EFI image.
  54   @param  SystemTable   A pointer to the EFI System Table.
  55
  56   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  57
  58 **/
  59 EFI_STATUS
  60 EFIAPI
  61 DevicePathLibConstructor (
  62   IN      EFI_HANDLE                ImageHandle,
  63   IN      EFI_SYSTEM_TABLE          *SystemTable
  64   )
  65 {
  66   EFI_STATUS                        Status;
  67
  68   Status = gBS->LocateProtocol (
  69                   &gEfiDevicePathUtilitiesProtocolGuid,
  70                   NULL,
  71                   (VOID**) &mDevicePathLibDevicePathUtilities
  72                   );
  73   ASSERT_EFI_ERROR (Status);
  74   ASSERT (mDevicePathLibDevicePathUtilities != NULL);
  75   return Status;
  76 }
  77
  78 /**
  79   Determine whether a given device path is valid.
  80   If DevicePath is NULL, then ASSERT().
  81
  82   @param  DevicePath  A pointer to a device path data structure.
  83   @param  MaxSize     The maximum size of the device path data structure.
  84
  85   @retval TRUE        DevicePath is valid.
  86   @retval FALSE       The length of any node node in the DevicePath is less
  87                       than sizeof (EFI_DEVICE_PATH_PROTOCOL).
  88   @retval FALSE       If MaxSize is not zero, the size of the DevicePath
  89                       exceeds MaxSize.
  90   @retval FALSE       If PcdMaximumDevicePathNodeCount is not zero, the node
  91                       count of the DevicePath exceeds PcdMaximumDevicePathNodeCount.
  92 **/
  93 BOOLEAN
  94 EFIAPI
  95 IsDevicePathValid (
  96   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
  97   IN       UINTN                    MaxSize
  98   )
  99 {
 100   UINTN Count;
 101   UINTN Size;
 102   UINTN NodeLength;
 103
 104   ASSERT (DevicePath != NULL);
 105
 106   if (MaxSize == 0) {
 107     MaxSize = MAX_UINTN;
 108   }
 109
 110   //
 111   // Validate the input size big enough to touch the first node.
 112   //
 113   if (MaxSize < sizeof (EFI_DEVICE_PATH_PROTOCOL)) {
 114     return FALSE;
 115   }
 116
 117   for (Count = 0, Size = 0; !IsDevicePathEnd (DevicePath); DevicePath = NextDevicePathNode (DevicePath)) {
 118     NodeLength = DevicePathNodeLength (DevicePath);
 119     if (NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL)) {
 120       return FALSE;
 121     }
 122
 123     if (NodeLength > MAX_UINTN - Size) {
 124       return FALSE;
 125     }
 126     Size += NodeLength;
 127
 128     //
 129     // Validate next node before touch it.
 130     //
 131     if (Size > MaxSize - END_DEVICE_PATH_LENGTH ) {
 132       return FALSE;
 133     }
 134
 135     if (PcdGet32 (PcdMaximumDevicePathNodeCount) > 0) {
 136       Count++;
 137       if (Count >= PcdGet32 (PcdMaximumDevicePathNodeCount)) {
 138         return FALSE;
 139       }
 140     }
 141   }
 142
 143   //
 144   // Only return TRUE when the End Device Path node is valid.
 145   //
 146   return (BOOLEAN) (DevicePathNodeLength (DevicePath) == END_DEVICE_PATH_LENGTH);
 147 }
 148
 149 /**
 150   Returns the Type field of a device path node.
 151
 152   Returns the Type field of the device path node specified by Node.
 153
 154   If Node is NULL, then ASSERT().
 155
 156   @param  Node      A pointer to a device path node data structure.
 157
 158   @return The Type field of the device path node specified by Node.
 159
 160 **/
 161 UINT8
 162 EFIAPI
 163 DevicePathType (
 164   IN CONST VOID  *Node
 165   )
 166 {
 167   ASSERT (Node != NULL);
 168   return ((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type;
 169 }
 170
 171 /**
 172   Returns the SubType field of a device path node.
 173
 174   Returns the SubType field of the device path node specified by Node.
 175
 176   If Node is NULL, then ASSERT().
 177
 178   @param  Node      A pointer to a device path node data structure.
 179
 180   @return The SubType field of the device path node specified by Node.
 181
 182 **/
 183 UINT8
 184 EFIAPI
 185 DevicePathSubType (
 186   IN CONST VOID  *Node
 187   )
 188 {
 189   ASSERT (Node != NULL);
 190   return ((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType;
 191 }
 192
 193 /**
 194   Returns the 16-bit Length field of a device path node.
 195
 196   Returns the 16-bit Length field of the device path node specified by Node.
 197   Node is not required to be aligned on a 16-bit boundary, so it is recommended
 198   that a function such as ReadUnaligned16() be used to extract the contents of
 199   the Length field.
 200
 201   If Node is NULL, then ASSERT().
 202
 203   @param  Node      A pointer to a device path node data structure.
 204
 205   @return The 16-bit Length field of the device path node specified by Node.
 206
 207 **/
 208 UINTN
 209 EFIAPI
 210 DevicePathNodeLength (
 211   IN CONST VOID  *Node
 212   )
 213 {
 214   ASSERT (Node != NULL);
 215   return ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0]);
 216 }
 217
 218 /**
 219   Returns a pointer to the next node in a device path.
 220
 221   Returns a pointer to the device path node that follows the device path node
 222   specified by Node.
 223
 224   If Node is NULL, then ASSERT().
 225
 226   @param  Node      A pointer to a device path node data structure.
 227
 228   @return a pointer to the device path node that follows the device path node
 229   specified by Node.
 230
 231 **/
 232 EFI_DEVICE_PATH_PROTOCOL *
 233 EFIAPI
 234 NextDevicePathNode (
 235   IN CONST VOID  *Node
 236   )
 237 {
 238   ASSERT (Node != NULL);
 239   return (EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node));
 240 }
 241
 242 /**
 243   Determines if a device path node is an end node of a device path.
 244   This includes nodes that are the end of a device path instance and nodes that
 245   are the end of an entire device path.
 246
 247   Determines if the device path node specified by Node is an end node of a device path.
 248   This includes nodes that are the end of a device path instance and nodes that are the
 249   end of an entire device path.  If Node represents an end node of a device path,
 250   then TRUE is returned.  Otherwise, FALSE is returned.
 251
 252   If Node is NULL, then ASSERT().
 253
 254   @param  Node      A pointer to a device path node data structure.
 255
 256   @retval TRUE      The device path node specified by Node is an end node of a device path.
 257   @retval FALSE     The device path node specified by Node is not an end node of
 258                     a device path.
 259
 260 **/
 261 BOOLEAN
 262 EFIAPI
 263 IsDevicePathEndType (
 264   IN CONST VOID  *Node
 265   )
 266 {
 267   ASSERT (Node != NULL);
 268   return (BOOLEAN) (DevicePathType (Node) == END_DEVICE_PATH_TYPE);
 269 }
 270
 271 /**
 272   Determines if a device path node is an end node of an entire device path.
 273
 274   Determines if a device path node specified by Node is an end node of an entire
 275   device path.
 276   If Node represents the end of an entire device path, then TRUE is returned.
 277   Otherwise, FALSE is returned.
 278
 279   If Node is NULL, then ASSERT().
 280
 281   @param  Node      A pointer to a device path node data structure.
 282
 283   @retval TRUE      The device path node specified by Node is the end of an entire device path.
 284   @retval FALSE     The device path node specified by Node is not the end of an entire device path.
 285
 286 **/
 287 BOOLEAN
 288 EFIAPI
 289 IsDevicePathEnd (
 290   IN CONST VOID  *Node
 291   )
 292 {
 293   ASSERT (Node != NULL);
 294   return (BOOLEAN) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE);
 295 }
 296
 297 /**
 298   Determines if a device path node is an end node of a device path instance.
 299
 300   Determines if a device path node specified by Node is an end node of a device
 301   path instance.
 302   If Node represents the end of a device path instance, then TRUE is returned.
 303   Otherwise, FALSE is returned.
 304
 305   If Node is NULL, then ASSERT().
 306
 307   @param  Node      A pointer to a device path node data structure.
 308
 309   @retval TRUE      The device path node specified by Node is the end of a device
 310   path instance.
 311   @retval FALSE     The device path node specified by Node is not the end of a
 312   device path instance.
 313
 314 **/
 315 BOOLEAN
 316 EFIAPI
 317 IsDevicePathEndInstance (
 318   IN CONST VOID  *Node
 319   )
 320 {
 321   ASSERT (Node != NULL);
 322   return (BOOLEAN) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE);
 323 }
 324
 325 /**
 326   Sets the length, in bytes, of a device path node.
 327
 328   Sets the length of the device path node specified by Node to the value specified
 329   by NodeLength.  NodeLength is returned.  Node is not required to be aligned on
 330   a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
 331   be used to set the contents of the Length field.
 332
 333   If Node is NULL, then ASSERT().
 334   If NodeLength >= SIZE_64KB, then ASSERT().
 335   If NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL), then ASSERT().
 336
 337   @param  Node      A pointer to a device path node data structure.
 338   @param  Length    The length, in bytes, of the device path node.
 339
 340   @return Length
 341
 342 **/
 343 UINT16
 344 EFIAPI
 345 SetDevicePathNodeLength (
 346   IN OUT VOID  *Node,
 347   IN UINTN     Length
 348   )
 349 {
 350   ASSERT (Node != NULL);
 351   ASSERT ((Length >= sizeof (EFI_DEVICE_PATH_PROTOCOL)) && (Length < SIZE_64KB));
 352   return WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(Length));
 353 }
 354
 355 /**
 356   Fills in all the fields of a device path node that is the end of an entire device path.
 357
 358   Fills in all the fields of a device path node specified by Node so Node represents
 359   the end of an entire device path.  The Type field of Node is set to
 360   END_DEVICE_PATH_TYPE, the SubType field of Node is set to
 361   END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
 362   END_DEVICE_PATH_LENGTH.  Node is not required to be aligned on a 16-bit boundary,
 363   so it is recommended that a function such as WriteUnaligned16() be used to set
 364   the contents of the Length field.
 365
 366   If Node is NULL, then ASSERT().
 367
 368   @param  Node      A pointer to a device path node data structure.
 369
 370 **/
 371 VOID
 372 EFIAPI
 373 SetDevicePathEndNode (
 374   OUT VOID  *Node
 375   )
 376 {
 377   ASSERT (Node != NULL);
 378   CopyMem (Node, &mUefiDevicePathLibEndDevicePath, sizeof (mUefiDevicePathLibEndDevicePath));
 379 }
 380
 381 /**
 382   Returns the size of a device path in bytes.
 383
 384   This function returns the size, in bytes, of the device path data structure
 385   specified by DevicePath including the end of device path node.
 386   If DevicePath is NULL or invalid, then 0 is returned.
 387
 388   @param  DevicePath  A pointer to a device path data structure.
 389
 390   @retval 0           If DevicePath is NULL or invalid.
 391   @retval Others      The size of a device path in bytes.
 392
 393 **/
 394 UINTN
 395 EFIAPI
 396 GetDevicePathSize (
 397   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 398   )
 399 {
 400   return mDevicePathLibDevicePathUtilities->GetDevicePathSize (DevicePath);
 401 }
 402
 403 /**
 404   Creates a new copy of an existing device path.
 405
 406   This function allocates space for a new copy of the device path specified by
 407   DevicePath.  If DevicePath is NULL, then NULL is returned.
 408   If the memory is successfully allocated, then the
 409   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
 410   is returned.  Otherwise, NULL is returned.
 411   The memory for the new device path is allocated from EFI boot services memory.
 412   It is the responsibility of the caller to free the memory allocated.
 413
 414   @param  DevicePath                 A pointer to a device path data structure.
 415
 416   @retval NULL    If DevicePath is NULL or invalid.
 417   @retval Others  A pointer to the duplicated device path.
 418
 419 **/
 420 EFI_DEVICE_PATH_PROTOCOL *
 421 EFIAPI
 422 DuplicateDevicePath (
 423   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 424   )
 425 {
 426   return mDevicePathLibDevicePathUtilities->DuplicateDevicePath (DevicePath);
 427 }
 428
 429 /**
 430   Creates a new device path by appending a second device path to a first device path.
 431
 432   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 433   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 434   SecondDevicePath is retained. The newly created device path is returned.
 435   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 436   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 437   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 438   returned.
 439   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 440   The memory for the new device path is allocated from EFI boot services memory. It is the
 441   responsibility of the caller to free the memory allocated.
 442
 443   @param  FirstDevicePath            A pointer to a device path data structure.
 444   @param  SecondDevicePath           A pointer to a device path data structure.
 445
 446   @retval NULL      If there is not enough memory for the newly allocated buffer.
 447   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
 448   @retval Others    A pointer to the new device path if success.
 449                     Or a copy an end-of-device-path if both FirstDevicePath and
 450                     SecondDevicePath are NULL.
 451
 452 **/
 453 EFI_DEVICE_PATH_PROTOCOL *
 454 EFIAPI
 455 AppendDevicePath (
 456   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
 457   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 458   )
 459 {
 460   return mDevicePathLibDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);
 461 }
 462
 463 /**
 464   Creates a new path by appending the device node to the device path.
 465
 466   This function creates a new device path by appending a copy of the device node
 467   specified by DevicePathNode to a copy of the device path specified by DevicePath
 468   in an allocated buffer.
 469   The end-of-device-path device node is moved after the end of the appended device node.
 470   If DevicePathNode is NULL then a copy of DevicePath is returned.
 471   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
 472   path device node is returned.
 473   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
 474   device node is returned.
 475   If there is not enough memory to allocate space for the new device path, then
 476   NULL is returned.
 477   The memory is allocated from EFI boot services memory. It is the responsibility
 478   of the caller to free the memory allocated.
 479
 480   @param  DevicePath                 A pointer to a device path data structure.
 481   @param  DevicePathNode             A pointer to a single device path node.
 482
 483   @retval NULL      If there is not enough memory for the new device path.
 484   @retval Others    A pointer to the new device path if success.
 485                     A copy of DevicePathNode followed by an end-of-device-path node
 486                     if both FirstDevicePath and SecondDevicePath are NULL.
 487                     A copy of an end-of-device-path node if both FirstDevicePath
 488                     and SecondDevicePath are NULL.
 489
 490 **/
 491 EFI_DEVICE_PATH_PROTOCOL *
 492 EFIAPI
 493 AppendDevicePathNode (
 494   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 495   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 496   )
 497 {
 498   return mDevicePathLibDevicePathUtilities->AppendDeviceNode (DevicePath, DevicePathNode);
 499 }
 500
 501 /**
 502   Creates a new device path by appending the specified device path instance to
 503   the specified device path.
 504
 505   This function creates a new device path by appending a copy of the device path
 506   instance specified by DevicePathInstance to a copy of the device path specified
 507   by DevicePath in a allocated buffer.
 508   The end-of-device-path device node is moved after the end of the appended device
 509   path instance and a new end-of-device-path-instance node is inserted between.
 510   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 511   If DevicePathInstance is NULL, then NULL is returned.
 512   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 513   If there is not enough memory to allocate space for the new device path, then
 514   NULL is returned.
 515   The memory is allocated from EFI boot services memory. It is the responsibility
 516   of the caller to free the memory allocated.
 517
 518   @param  DevicePath                 A pointer to a device path data structure.
 519   @param  DevicePathInstance         A pointer to a device path instance.
 520
 521   @return A pointer to the new device path.
 522
 523 **/
 524 EFI_DEVICE_PATH_PROTOCOL *
 525 EFIAPI
 526 AppendDevicePathInstance (
 527   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 528   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 529   )
 530 {
 531   return mDevicePathLibDevicePathUtilities->AppendDevicePathInstance (DevicePath, DevicePathInstance);
 532 }
 533
 534 /**
 535   Creates a copy of the current device path instance and returns a pointer to the
 536   next device path instance.
 537
 538   This function creates a copy of the current device path instance. It also updates
 539   DevicePath to point to the next device path instance in the device path (or NULL
 540   if no more) and updates Size to hold the size of the device path instance copy.
 541   If DevicePath is NULL, then NULL is returned.
 542   If there is not enough memory to allocate space for the new device path, then
 543   NULL is returned.
 544   The memory is allocated from EFI boot services memory. It is the responsibility
 545   of the caller to free the memory allocated.
 546   If Size is NULL, then ASSERT().
 547
 548   @param  DevicePath                 On input, this holds the pointer to the current
 549                                      device path instance. On output, this holds
 550                                      the pointer to the next device path instance
 551                                      or NULL if there are no more device path
 552                                      instances in the device path pointer to a
 553                                      device path data structure.
 554   @param  Size                       On output, this holds the size of the device
 555                                      path instance, in bytes or zero, if DevicePath
 556                                      is NULL.
 557
 558   @return A pointer to the current device path instance.
 559
 560 **/
 561 EFI_DEVICE_PATH_PROTOCOL *
 562 EFIAPI
 563 GetNextDevicePathInstance (
 564   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 565   OUT UINTN                          *Size
 566   )
 567 {
 568   ASSERT (Size != NULL);
 569   return mDevicePathLibDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);
 570 }
 571
 572 /**
 573   Creates a device node.
 574
 575   This function creates a new device node in a newly allocated buffer of size
 576   NodeLength and initializes the device path node header with NodeType and NodeSubType.
 577   The new device path node is returned.
 578   If NodeLength is smaller than a device path header, then NULL is returned.
 579   If there is not enough memory to allocate space for the new device path, then
 580   NULL is returned.
 581   The memory is allocated from EFI boot services memory. It is the responsibility
 582   of the caller to free the memory allocated.
 583
 584   @param  NodeType                   The device node type for the new device node.
 585   @param  NodeSubType                The device node sub-type for the new device node.
 586   @param  NodeLength                 The length of the new device node.
 587
 588   @return The new device path.
 589
 590 **/
 591 EFI_DEVICE_PATH_PROTOCOL *
 592 EFIAPI
 593 CreateDeviceNode (
 594   IN UINT8                           NodeType,
 595   IN UINT8                           NodeSubType,
 596   IN UINT16                          NodeLength
 597   )
 598 {
 599   return mDevicePathLibDevicePathUtilities->CreateDeviceNode (NodeType, NodeSubType, NodeLength);
 600 }
 601
 602 /**
 603   Determines if a device path is single or multi-instance.
 604
 605   This function returns TRUE if the device path specified by DevicePath is
 606   multi-instance.
 607   Otherwise, FALSE is returned.
 608   If DevicePath is NULL or invalid, then FALSE is returned.
 609
 610   @param  DevicePath                 A pointer to a device path data structure.
 611
 612   @retval  TRUE                      DevicePath is multi-instance.
 613   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath
 614                                      is NULL or invalid.
 615
 616 **/
 617 BOOLEAN
 618 EFIAPI
 619 IsDevicePathMultiInstance (
 620   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 621   )
 622 {
 623   return mDevicePathLibDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);
 624 }
 625
 626 /**
 627   Retrieves the device path protocol from a handle.
 628
 629   This function returns the device path protocol from the handle specified by Handle.
 630   If Handle is NULL or Handle does not contain a device path protocol, then NULL
 631   is returned.
 632
 633   @param  Handle                     The handle from which to retrieve the device
 634                                      path protocol.
 635
 636   @return The device path protocol from the handle specified by Handle.
 637
 638 **/
 639 EFI_DEVICE_PATH_PROTOCOL *
 640 EFIAPI
 641 DevicePathFromHandle (
 642   IN EFI_HANDLE                      Handle
 643   )
 644 {
 645   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 646   EFI_STATUS                Status;
 647
 648   Status = gBS->HandleProtocol (
 649                   Handle,
 650                   &gEfiDevicePathProtocolGuid,
 651                   (VOID *) &DevicePath
 652                   );
 653   if (EFI_ERROR (Status)) {
 654     DevicePath = NULL;
 655   }
 656   return DevicePath;
 657 }
 658
 659 /**
 660   Allocates a device path for a file and appends it to an existing device path.
 661
 662   If Device is a valid device handle that contains a device path protocol, then
 663   a device path for the file specified by FileName  is allocated and appended to
 664   the device path associated with the handle Device.  The allocated device path
 665   is returned.  If Device is NULL or Device is a handle that does not support the
 666   device path protocol, then a device path containing a single device path node
 667   for the file specified by FileName is allocated and returned.
 668   The memory for the new device path is allocated from EFI boot services memory.
 669   It is the responsibility of the caller to free the memory allocated.
 670
 671   If FileName is NULL, then ASSERT().
 672   If FileName is not aligned on a 16-bit boundary, then ASSERT().
 673
 674   @param  Device                     A pointer to a device handle.  This parameter
 675                                      is optional and may be NULL.
 676   @param  FileName                   A pointer to a Null-terminated Unicode string.
 677
 678   @return The allocated device path.
 679
 680 **/
 681 EFI_DEVICE_PATH_PROTOCOL *
 682 EFIAPI
 683 FileDevicePath (
 684   IN EFI_HANDLE                      Device,     OPTIONAL
 685   IN CONST CHAR16                    *FileName
 686   )
 687 {
 688   UINTN                     Size;
 689   FILEPATH_DEVICE_PATH      *FilePath;
 690   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 691   EFI_DEVICE_PATH_PROTOCOL  *FileDevicePath;
 692
 693   DevicePath = NULL;
 694
 695   Size = StrSize (FileName);
 696   FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + END_DEVICE_PATH_LENGTH);
 697   if (FileDevicePath != NULL) {
 698     FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePath;
 699     FilePath->Header.Type    = MEDIA_DEVICE_PATH;
 700     FilePath->Header.SubType = MEDIA_FILEPATH_DP;
 701     CopyMem (&FilePath->PathName, FileName, Size);
 702     SetDevicePathNodeLength (&FilePath->Header, Size + SIZE_OF_FILEPATH_DEVICE_PATH);
 703     SetDevicePathEndNode (NextDevicePathNode (&FilePath->Header));
 704
 705     if (Device != NULL) {
 706       DevicePath = DevicePathFromHandle (Device);
 707     }
 708
 709     DevicePath = AppendDevicePath (DevicePath, FileDevicePath);
 710     FreePool (FileDevicePath);
 711   }
 712
 713   return DevicePath;
 714 }
 715
 716 /**
 717   Locate and return the protocol instance identified by the ProtocolGuid.
 718
 719   @param ProtocolGuid     The GUID of the protocol.
 720
 721   @return A pointer to the protocol instance or NULL when absent.
 722 **/
 723 VOID *
 724 UefiDevicePathLibLocateProtocol (
 725   EFI_GUID                         *ProtocolGuid
 726   )
 727 {
 728   EFI_STATUS Status;
 729   VOID       *Protocol;
 730   Status = gBS->LocateProtocol (
 731                   ProtocolGuid,
 732                   NULL,
 733                   (VOID**) &Protocol
 734                   );
 735   if (EFI_ERROR (Status)) {
 736     return NULL;
 737   } else {
 738     return Protocol;
 739   }
 740 }
 741
 742 /**
 743   Converts a device node to its string representation.
 744
 745   @param DeviceNode        A Pointer to the device node to be converted.
 746   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 747                            of the display node is used, where applicable. If DisplayOnly
 748                            is FALSE, then the longer text representation of the display node
 749                            is used.
 750   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 751                            representation for a device node can be used, where applicable.
 752
 753   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 754           is NULL or there was insufficient memory.
 755
 756 **/
 757 CHAR16 *
 758 EFIAPI
 759 ConvertDeviceNodeToText (
 760   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 761   IN BOOLEAN                         DisplayOnly,
 762   IN BOOLEAN                         AllowShortcuts
 763   )
 764 {
 765   if (mDevicePathLibDevicePathToText == NULL) {
 766     mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);
 767   }
 768   if (mDevicePathLibDevicePathToText != NULL) {
 769     return mDevicePathLibDevicePathToText->ConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);
 770   } else {
 771     return NULL;
 772   }
 773 }
 774
 775 /**
 776   Converts a device path to its text representation.
 777
 778   @param DevicePath      A Pointer to the device to be converted.
 779   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 780                          of the display node is used, where applicable. If DisplayOnly
 781                          is FALSE, then the longer text representation of the display node
 782                          is used.
 783   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 784                          representation for a device node can be used, where applicable.
 785
 786   @return A pointer to the allocated text representation of the device path or
 787           NULL if DeviceNode is NULL or there was insufficient memory.
 788
 789 **/
 790 CHAR16 *
 791 EFIAPI
 792 ConvertDevicePathToText (
 793   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath,
 794   IN BOOLEAN                          DisplayOnly,
 795   IN BOOLEAN                          AllowShortcuts
 796   )
 797 {
 798   if (mDevicePathLibDevicePathToText == NULL) {
 799     mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);
 800   }
 801   if (mDevicePathLibDevicePathToText != NULL) {
 802     return mDevicePathLibDevicePathToText->ConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);
 803   } else {
 804     return NULL;
 805   }
 806 }
 807
 808 /**
 809   Convert text to the binary representation of a device node.
 810
 811   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 812                          node. Conversion starts with the first character and continues
 813                          until the first non-device node character.
 814
 815   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 816           insufficient memory or text unsupported.
 817
 818 **/
 819 EFI_DEVICE_PATH_PROTOCOL *
 820 EFIAPI
 821 ConvertTextToDeviceNode (
 822   IN CONST CHAR16 *TextDeviceNode
 823   )
 824 {
 825   if (mDevicePathLibDevicePathFromText == NULL) {
 826     mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);
 827   }
 828   if (mDevicePathLibDevicePathFromText != NULL) {
 829     return mDevicePathLibDevicePathFromText->ConvertTextToDeviceNode (TextDeviceNode);
 830   } else {
 831     return NULL;
 832   }
 833 }
 834
 835 /**
 836   Convert text to the binary representation of a device path.
 837
 838
 839   @param TextDevicePath  TextDevicePath points to the text representation of a device
 840                          path. Conversion starts with the first character and continues
 841                          until the first non-device node character.
 842
 843   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 844           there was insufficient memory.
 845
 846 **/
 847 EFI_DEVICE_PATH_PROTOCOL *
 848 EFIAPI
 849 ConvertTextToDevicePath (
 850   IN CONST CHAR16 *TextDevicePath
 851   )
 852 {
 853   if (mDevicePathLibDevicePathFromText == NULL) {
 854     mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);
 855   }
 856   if (mDevicePathLibDevicePathFromText != NULL) {
 857     return mDevicePathLibDevicePathFromText->ConvertTextToDevicePath (TextDevicePath);
 858   } else {
 859     return NULL;
 860   }
 861 }
 862