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