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