MdePkg/Include/Library/DevicePathLib.h

   1 /** @file
   2   Provides library functions to construct and parse UEFI Device Paths.
   3
   4   This library provides defines, macros, and functions to help create and parse
   5   EFI_DEVICE_PATH_PROTOCOL structures.
   6
   7 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __DEVICE_PATH_LIB_H__
  13 #define __DEVICE_PATH_LIB_H__
  14
  15 #define END_DEVICE_PATH_LENGTH  (sizeof (EFI_DEVICE_PATH_PROTOCOL))
  16
  17 /**
  18   Determine whether a given device path is valid.
  19
  20   @param  DevicePath  A pointer to a device path data structure.
  21   @param  MaxSize     The maximum size of the device path data structure.
  22
  23   @retval TRUE        DevicePath is valid.
  24   @retval FALSE       DevicePath is NULL.
  25   @retval FALSE       Maxsize is less than sizeof(EFI_DEVICE_PATH_PROTOCOL).
  26   @retval FALSE       The length of any node node in the DevicePath is less
  27                       than sizeof (EFI_DEVICE_PATH_PROTOCOL).
  28   @retval FALSE       If MaxSize is not zero, the size of the DevicePath
  29                       exceeds MaxSize.
  30   @retval FALSE       If PcdMaximumDevicePathNodeCount is not zero, the node
  31                       count of the DevicePath exceeds PcdMaximumDevicePathNodeCount.
  32 **/
  33 BOOLEAN
  34 EFIAPI
  35 IsDevicePathValid (
  36   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
  37   IN       UINTN                     MaxSize
  38   );
  39
  40 /**
  41   Returns the Type field of a device path node.
  42
  43   Returns the Type field of the device path node specified by Node.
  44
  45   If Node is NULL, then ASSERT().
  46
  47   @param  Node      A pointer to a device path node data structure.
  48
  49   @return The Type field of the device path node specified by Node.
  50
  51 **/
  52 UINT8
  53 EFIAPI
  54 DevicePathType (
  55   IN CONST VOID  *Node
  56   );
  57
  58 /**
  59   Returns the SubType field of a device path node.
  60
  61   Returns the SubType field of the device path node specified by Node.
  62
  63   If Node is NULL, then ASSERT().
  64
  65   @param  Node      A pointer to a device path node data structure.
  66
  67   @return The SubType field of the device path node specified by Node.
  68
  69 **/
  70 UINT8
  71 EFIAPI
  72 DevicePathSubType (
  73   IN CONST VOID  *Node
  74   );
  75
  76 /**
  77   Returns the 16-bit Length field of a device path node.
  78
  79   Returns the 16-bit Length field of the device path node specified by Node.
  80   Node is not required to be aligned on a 16-bit boundary, so it is recommended
  81   that a function such as ReadUnaligned16() be used to extract the contents of
  82   the Length field.
  83
  84   If Node is NULL, then ASSERT().
  85
  86   @param  Node      A pointer to a device path node data structure.
  87
  88   @return The 16-bit Length field of the device path node specified by Node.
  89
  90 **/
  91 UINTN
  92 EFIAPI
  93 DevicePathNodeLength (
  94   IN CONST VOID  *Node
  95   );
  96
  97 /**
  98   Returns a pointer to the next node in a device path.
  99
 100   Returns a pointer to the device path node that follows the device path node specified by Node.
 101
 102   If Node is NULL, then ASSERT().
 103
 104   @param  Node      A pointer to a device path node data structure.
 105
 106   @return a pointer to the device path node that follows the device path node specified by Node.
 107
 108 **/
 109 EFI_DEVICE_PATH_PROTOCOL *
 110 EFIAPI
 111 NextDevicePathNode (
 112   IN CONST VOID  *Node
 113   );
 114
 115 /**
 116   Determines if a device path node is an end node of a device path.
 117   This includes nodes that are the end of a device path instance and nodes that
 118   are the end of an entire device path.
 119
 120   Determines if the device path node specified by Node is an end node of a device path.
 121   This includes nodes that are the end of a device path instance and nodes that are the
 122   end of an entire device path.  If Node represents an end node of a device path,
 123   then TRUE is returned.  Otherwise, FALSE is returned.
 124
 125   If Node is NULL, then ASSERT().
 126
 127   @param  Node      A pointer to a device path node data structure.
 128
 129   @retval TRUE      The device path node specified by Node is an end node of a device path.
 130   @retval FALSE     The device path node specified by Node is not an end node of a device path.
 131
 132 **/
 133 BOOLEAN
 134 EFIAPI
 135 IsDevicePathEndType (
 136   IN CONST VOID  *Node
 137   );
 138
 139 /**
 140   Determines if a device path node is an end node of an entire device path.
 141
 142   Determines if a device path node specified by Node is an end node of an entire device path.
 143   If Node represents the end of an entire device path, then TRUE is returned.
 144   Otherwise, FALSE is returned.
 145
 146   If Node is NULL, then ASSERT().
 147
 148   @param  Node      A pointer to a device path node data structure.
 149
 150   @retval TRUE      The device path node specified by Node is the end of an entire device path.
 151   @retval FALSE     The device path node specified by Node is not the end of an entire device path.
 152
 153 **/
 154 BOOLEAN
 155 EFIAPI
 156 IsDevicePathEnd (
 157   IN CONST VOID  *Node
 158   );
 159
 160 /**
 161   Determines if a device path node is an end node of a device path instance.
 162
 163   Determines if a device path node specified by Node is an end node of a device path instance.
 164   If Node represents the end of a device path instance, then TRUE is returned.
 165   Otherwise, FALSE is returned.
 166
 167   If Node is NULL, then ASSERT().
 168
 169   @param  Node      A pointer to a device path node data structure.
 170
 171   @retval TRUE      The device path node specified by Node is the end of a device path instance.
 172   @retval FALSE     The device path node specified by Node is not the end of a device path instance.
 173
 174 **/
 175 BOOLEAN
 176 EFIAPI
 177 IsDevicePathEndInstance (
 178   IN CONST VOID  *Node
 179   );
 180
 181 /**
 182   Sets the length, in bytes, of a device path node.
 183
 184   Sets the length of the device path node specified by Node to the value specified
 185   by NodeLength.  NodeLength is returned.  Node is not required to be aligned on
 186   a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
 187   be used to set the contents of the Length field.
 188
 189   If Node is NULL, then ASSERT().
 190   If NodeLength >= 0x10000, then ASSERT().
 191   If NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL), then ASSERT().
 192
 193   @param  Node      A pointer to a device path node data structure.
 194   @param  Length    The length, in bytes, of the device path node.
 195
 196   @return Length
 197
 198 **/
 199 UINT16
 200 EFIAPI
 201 SetDevicePathNodeLength (
 202   IN OUT VOID  *Node,
 203   IN UINTN     Length
 204   );
 205
 206 /**
 207   Fills in all the fields of a device path node that is the end of an entire device path.
 208
 209   Fills in all the fields of a device path node specified by Node so Node represents
 210   the end of an entire device path.  The Type field of Node is set to
 211   END_DEVICE_PATH_TYPE, the SubType field of Node is set to
 212   END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
 213   END_DEVICE_PATH_LENGTH.  Node is not required to be aligned on a 16-bit boundary,
 214   so it is recommended that a function such as WriteUnaligned16() be used to set
 215   the contents of the Length field.
 216
 217   If Node is NULL, then ASSERT().
 218
 219   @param  Node      A pointer to a device path node data structure.
 220
 221 **/
 222 VOID
 223 EFIAPI
 224 SetDevicePathEndNode (
 225   OUT VOID  *Node
 226   );
 227
 228 /**
 229   Returns the size of a device path in bytes.
 230
 231   This function returns the size, in bytes, of the device path data structure
 232   specified by DevicePath including the end of device path node.
 233   If DevicePath is NULL or invalid, then 0 is returned.
 234
 235   @param  DevicePath  A pointer to a device path data structure.
 236
 237   @retval 0           If DevicePath is NULL or invalid.
 238   @retval Others      The size of a device path in bytes.
 239
 240 **/
 241 UINTN
 242 EFIAPI
 243 GetDevicePathSize (
 244   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 245   );
 246
 247 /**
 248   Creates a new copy of an existing device path.
 249
 250   This function allocates space for a new copy of the device path specified by DevicePath.  If
 251   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
 252   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
 253   is returned.  Otherwise, NULL is returned.
 254   The memory for the new device path is allocated from EFI boot services memory.
 255   It is the responsibility of the caller to free the memory allocated.
 256
 257   @param  DevicePath                 A pointer to a device path data structure.
 258
 259   @retval NULL    DevicePath is NULL or invalid.
 260   @retval Others  A pointer to the duplicated device path.
 261
 262 **/
 263 EFI_DEVICE_PATH_PROTOCOL *
 264 EFIAPI
 265 DuplicateDevicePath (
 266   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 267   );
 268
 269 /**
 270   Creates a new device path by appending a second device path to a first device path.
 271
 272   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 273   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 274   SecondDevicePath is retained. The newly created device path is returned.
 275   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 276   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 277   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 278   returned.
 279   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 280   The memory for the new device path is allocated from EFI boot services memory. It is the
 281   responsibility of the caller to free the memory allocated.
 282
 283   @param  FirstDevicePath            A pointer to a device path data structure.
 284   @param  SecondDevicePath           A pointer to a device path data structure.
 285
 286   @retval NULL      If there is not enough memory for the newly allocated buffer.
 287   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
 288   @retval Others    A pointer to the new device path if success.
 289                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 290
 291 **/
 292 EFI_DEVICE_PATH_PROTOCOL *
 293 EFIAPI
 294 AppendDevicePath (
 295   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath   OPTIONAL,
 296   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 297   );
 298
 299 /**
 300   Creates a new path by appending the device node to the device path.
 301
 302   This function creates a new device path by appending a copy of the device node specified by
 303   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 304   The end-of-device-path device node is moved after the end of the appended device node.
 305   If DevicePathNode is NULL then a copy of DevicePath is returned.
 306   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 307   node is returned.
 308   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 309   is returned.
 310   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 311   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 312   free the memory allocated.
 313
 314   @param  DevicePath                 A pointer to a device path data structure.
 315   @param  DevicePathNode             A pointer to a single device path node.
 316
 317   @retval NULL      There is not enough memory for the new device path.
 318   @retval Others    A pointer to the new device path if success.
 319                     A copy of DevicePathNode followed by an end-of-device-path node
 320                     if both FirstDevicePath and SecondDevicePath are NULL.
 321                     A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
 322
 323 **/
 324 EFI_DEVICE_PATH_PROTOCOL *
 325 EFIAPI
 326 AppendDevicePathNode (
 327   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath      OPTIONAL,
 328   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 329   );
 330
 331 /**
 332   Creates a new device path by appending the specified device path instance to the specified device
 333   path.
 334
 335   This function creates a new device path by appending a copy of the device path instance specified
 336   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
 337   The end-of-device-path device node is moved after the end of the appended device path instance
 338   and a new end-of-device-path-instance node is inserted between.
 339   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 340   If DevicePathInstance is NULL, then NULL is returned.
 341   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 342   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 343   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 344   free the memory allocated.
 345
 346   @param  DevicePath                 A pointer to a device path data structure.
 347   @param  DevicePathInstance         A pointer to a device path instance.
 348
 349   @return A pointer to the new device path.
 350
 351 **/
 352 EFI_DEVICE_PATH_PROTOCOL *
 353 EFIAPI
 354 AppendDevicePathInstance (
 355   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath         OPTIONAL,
 356   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 357   );
 358
 359 /**
 360   Creates a copy of the current device path instance and returns a pointer to the next device path
 361   instance.
 362
 363   This function creates a copy of the current device path instance. It also updates DevicePath to
 364   point to the next device path instance in the device path (or NULL if no more) and updates Size
 365   to hold the size of the device path instance copy.
 366   If DevicePath is NULL, then NULL is returned.
 367   If DevicePath points to a invalid device path, then NULL is returned.
 368   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 369   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 370   free the memory allocated.
 371   If Size is NULL, then ASSERT().
 372
 373   @param  DevicePath                 On input, this holds the pointer to the current device path
 374                                      instance. On output, this holds the pointer to the next device
 375                                      path instance or NULL if there are no more device path
 376                                      instances in the device path pointer to a device path data
 377                                      structure.
 378   @param  Size                       On output, this holds the size of the device path instance, in
 379                                      bytes or zero, if DevicePath is NULL.
 380
 381   @return A pointer to the current device path instance.
 382
 383 **/
 384 EFI_DEVICE_PATH_PROTOCOL *
 385 EFIAPI
 386 GetNextDevicePathInstance (
 387   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 388   OUT UINTN                        *Size
 389   );
 390
 391 /**
 392   Creates a device node.
 393
 394   This function creates a new device node in a newly allocated buffer of size NodeLength and
 395   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 396   is returned.
 397   If NodeLength is smaller than a device path header, then NULL is returned.
 398   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 399   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 400   free the memory allocated.
 401
 402   @param  NodeType                   The device node type for the new device node.
 403   @param  NodeSubType                The device node sub-type for the new device node.
 404   @param  NodeLength                 The length of the new device node.
 405
 406   @return The new device path.
 407
 408 **/
 409 EFI_DEVICE_PATH_PROTOCOL *
 410 EFIAPI
 411 CreateDeviceNode (
 412   IN UINT8   NodeType,
 413   IN UINT8   NodeSubType,
 414   IN UINT16  NodeLength
 415   );
 416
 417 /**
 418   Determines if a device path is single or multi-instance.
 419
 420   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 421   Otherwise, FALSE is returned.
 422   If DevicePath is NULL or invalid, then FALSE is returned.
 423
 424   @param  DevicePath                 A pointer to a device path data structure.
 425
 426   @retval  TRUE                      DevicePath is multi-instance.
 427   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath is NULL or invalid.
 428
 429 **/
 430 BOOLEAN
 431 EFIAPI
 432 IsDevicePathMultiInstance (
 433   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 434   );
 435
 436 /**
 437   Retrieves the device path protocol from a handle.
 438
 439   This function returns the device path protocol from the handle specified by Handle.  If Handle is
 440   NULL or Handle does not contain a device path protocol, then NULL is returned.
 441
 442   @param  Handle                     The handle from which to retrieve the device path protocol.
 443
 444   @return The device path protocol from the handle specified by Handle.
 445
 446 **/
 447 EFI_DEVICE_PATH_PROTOCOL *
 448 EFIAPI
 449 DevicePathFromHandle (
 450   IN EFI_HANDLE  Handle
 451   );
 452
 453 /**
 454   Allocates a device path for a file and appends it to an existing device path.
 455
 456   If Device is a valid device handle that contains a device path protocol, then a device path for
 457   the file specified by FileName  is allocated and appended to the device path associated with the
 458   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
 459   that does not support the device path protocol, then a device path containing a single device
 460   path node for the file specified by FileName is allocated and returned.
 461   The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
 462   of the caller to free the memory allocated.
 463
 464   If FileName is NULL, then ASSERT().
 465   If FileName is not aligned on a 16-bit boundary, then ASSERT().
 466
 467   @param  Device                     A pointer to a device handle.  This parameter is optional and
 468                                      may be NULL.
 469   @param  FileName                   A pointer to a Null-terminated Unicode string.
 470
 471   @return The allocated device path.
 472
 473 **/
 474 EFI_DEVICE_PATH_PROTOCOL *
 475 EFIAPI
 476 FileDevicePath (
 477   IN EFI_HANDLE    Device      OPTIONAL,
 478   IN CONST CHAR16  *FileName
 479   );
 480
 481 /**
 482   Converts a device path to its text representation.
 483
 484   @param DevicePath      A Pointer to the device to be converted.
 485   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 486                          of the display node is used, where applicable. If DisplayOnly
 487                          is FALSE, then the longer text representation of the display node
 488                          is used.
 489   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 490                          representation for a device node can be used, where applicable.
 491
 492   @return A pointer to the allocated text representation of the device path or
 493           NULL if DeviceNode is NULL or there was insufficient memory.
 494
 495 **/
 496 CHAR16 *
 497 EFIAPI
 498 ConvertDevicePathToText (
 499   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
 500   IN BOOLEAN                         DisplayOnly,
 501   IN BOOLEAN                         AllowShortcuts
 502   );
 503
 504 /**
 505   Converts a device node to its string representation.
 506
 507   @param DeviceNode        A Pointer to the device node to be converted.
 508   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 509                            of the display node is used, where applicable. If DisplayOnly
 510                            is FALSE, then the longer text representation of the display node
 511                            is used.
 512   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 513                            representation for a device node can be used, where applicable.
 514
 515   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 516           is NULL or there was insufficient memory.
 517
 518 **/
 519 CHAR16 *
 520 EFIAPI
 521 ConvertDeviceNodeToText (
 522   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 523   IN BOOLEAN                         DisplayOnly,
 524   IN BOOLEAN                         AllowShortcuts
 525   );
 526
 527 /**
 528   Convert text to the binary representation of a device node.
 529
 530   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 531                          node. Conversion starts with the first character and continues
 532                          until the first non-device node character.
 533
 534   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 535           insufficient memory or text unsupported.
 536
 537 **/
 538 EFI_DEVICE_PATH_PROTOCOL *
 539 EFIAPI
 540 ConvertTextToDeviceNode (
 541   IN CONST CHAR16  *TextDeviceNode
 542   );
 543
 544 /**
 545   Convert text to the binary representation of a device path.
 546
 547   @param TextDevicePath  TextDevicePath points to the text representation of a device
 548                          path. Conversion starts with the first character and continues
 549                          until the first non-device node character.
 550
 551   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 552           there was insufficient memory.
 553
 554 **/
 555 EFI_DEVICE_PATH_PROTOCOL *
 556 EFIAPI
 557 ConvertTextToDevicePath (
 558   IN CONST CHAR16  *TextDevicePath
 559   );
 560
 561 #endif