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