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