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