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