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