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