MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c

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