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.  The macros that help create and parse device
   6   path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from
   7   the Base Library, so this library class has an implied dependency on the Base Library.
   8
   9 Copyright (c) 2006 - 2009, Intel Corporation<BR>
  10 All rights reserved. This program and the accompanying materials
  11 are licensed and made available under the terms and conditions of the BSD License
  12 which accompanies this distribution.  The full text of the license may be found at
  13 http://opensource.org/licenses/bsd-license.php
  14
  15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17
  18 **/
  19
  20 #ifndef __DEVICE_PATH_LIB_H__
  21 #define __DEVICE_PATH_LIB_H__
  22
  23 #define END_DEVICE_PATH_LENGTH               (sizeof (EFI_DEVICE_PATH_PROTOCOL))
  24
  25 /**
  26   Returns the Type field of a device path node.
  27
  28   Returns the Type field of the device path node specified by Node.
  29
  30   If Node is NULL, then ASSERT().
  31
  32   @param  Node      A pointer to a device path node data structure.
  33
  34   @return The Type field of the device path node specified by Node.
  35
  36 **/
  37 UINT8
  38 EFIAPI
  39 DevicePathType (
  40   IN CONST VOID  *Node
  41   );
  42
  43 /**
  44   Returns the SubType field of a device path node.
  45
  46   Returns the SubType field of the device path node specified by Node.
  47
  48   If Node is NULL, then ASSERT().
  49
  50   @param  Node      A pointer to a device path node data structure.
  51
  52   @return The SubType field of the device path node specified by Node.
  53
  54 **/
  55 UINT8
  56 EFIAPI
  57 DevicePathSubType (
  58   IN CONST VOID  *Node
  59   );
  60
  61 /**
  62   Returns the 16-bit Length field of a device path node.
  63
  64   Returns the 16-bit Length field of the device path node specified by Node.
  65   Node is not required to be aligned on a 16-bit boundary, so it is recommended
  66   that a function such as ReadUnaligned16() be used to extract the contents of
  67   the Length field.
  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 16-bit Length field of the device path node specified by Node.
  74
  75 **/
  76 UINTN
  77 EFIAPI
  78 DevicePathNodeLength (
  79   IN CONST VOID  *Node
  80   );
  81
  82 /**
  83   Returns a pointer to the next node in a device path.
  84
  85   Returns a pointer to the device path node that follows the device path node specified by Node.
  86
  87   If Node is NULL, then ASSERT().
  88
  89   @param  Node      A pointer to a device path node data structure.
  90
  91   @return a pointer to the device path node that follows the device path node specified by Node.
  92
  93 **/
  94 EFI_DEVICE_PATH_PROTOCOL *
  95 EFIAPI
  96 NextDevicePathNode (
  97   IN CONST VOID  *Node
  98   );
  99
 100 /**
 101   Determines if a device path node is an end node of a device path.
 102   This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.
 103
 104   Determines if the device path node specified by Node is an end node of a device path.
 105   This includes nodes that are the end of a device path instance and nodes that are the
 106   end of an entire device path.  If Node represents an end node of a device path,
 107   then TRUE is returned.  Otherwise, FALSE is returned.
 108
 109   If Node is NULL, then ASSERT().
 110
 111   @param  Node      A pointer to a device path node data structure.
 112
 113   @retval TRUE      The device path node specified by Node is an end node of a device path.
 114   @retval FALSE     The device path node specified by Node is not an end node of a device path.
 115
 116 **/
 117 BOOLEAN
 118 EFIAPI
 119 IsDevicePathEndType (
 120   IN CONST VOID  *Node
 121   );
 122
 123 /**
 124   Determines if a device path node is an end node of an entire device path.
 125
 126   Determines if a device path node specified by Node is an end node of an entire device path.
 127   If Node represents the end of an entire device path, then TRUE is returned.  Otherwise, FALSE is returned.
 128
 129   If Node is NULL, then ASSERT().
 130
 131   @param  Node      A pointer to a device path node data structure.
 132
 133   @retval TRUE      The device path node specified by Node is the end of an entire device path.
 134   @retval FALSE     The device path node specified by Node is not the end of an entire device path.
 135
 136 **/
 137 BOOLEAN
 138 EFIAPI
 139 IsDevicePathEnd (
 140   IN CONST VOID  *Node
 141   );
 142
 143 /**
 144   Determines if a device path node is an end node of a device path instance.
 145
 146   Determines if a device path node specified by Node is an end node of a device path instance.
 147   If Node represents the end of a device path instance, then TRUE is returned.  Otherwise, FALSE is returned.
 148
 149   If Node is NULL, then ASSERT().
 150
 151   @param  Node      A pointer to a device path node data structure.
 152
 153   @retval TRUE      The device path node specified by Node is the end of a device path instance.
 154   @retval FALSE     The device path node specified by Node is not the end of a device path instance.
 155
 156 **/
 157 BOOLEAN
 158 EFIAPI
 159 IsDevicePathEndInstance (
 160   IN CONST VOID  *Node
 161   );
 162
 163 /**
 164   Sets the length, in bytes, of a device path node.
 165
 166   Sets the length of the device path node specified by Node to the value specified
 167   by NodeLength.  NodeLength is returned.  Node is not required to be aligned on
 168   a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
 169   be used to set the contents of the Length field.
 170
 171   If Node is NULL, then ASSERT().
 172   If NodeLength >= 0x10000, then ASSERT().
 173
 174   @param  Node      A pointer to a device path node data structure.
 175   @param  Length    The length, in bytes, of the device path node.
 176
 177   @return Length
 178
 179 **/
 180 UINT16
 181 EFIAPI
 182 SetDevicePathNodeLength (
 183   IN OUT VOID  *Node,
 184   IN UINTN     Length
 185   );
 186
 187 /**
 188   Fills in all the fields of a device path node that is the end of an entire device path.
 189
 190   Fills in all the fields of a device path node specified by Node so Node represents
 191   the end of an entire device path.  The Type field of Node is set to
 192   END_DEVICE_PATH_TYPE, the SubType field of Node is set to
 193   END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
 194   END_DEVICE_PATH_LENGTH.  Node is not required to be aligned on a 16-bit boundary,
 195   so it is recommended that a function such as WriteUnaligned16() be used to set
 196   the contents of the Length field.
 197
 198   If Node is NULL, then ASSERT().
 199
 200   @param  Node      A pointer to a device path node data structure.
 201
 202 **/
 203 VOID
 204 EFIAPI
 205 SetDevicePathEndNode (
 206   OUT VOID  *Node
 207   );
 208
 209 /**
 210   Returns the size of a device path in bytes.
 211
 212   This function returns the size, in bytes, of the device path data structure specified by
 213   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.
 214
 215   @param  DevicePath                 A pointer to a device path data structure.
 216
 217   @retval 0       If DevicePath is NULL.
 218   @retval Others  The size of a device path in bytes.
 219
 220 **/
 221 UINTN
 222 EFIAPI
 223 GetDevicePathSize (
 224   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 225   );
 226
 227 /**
 228   Creates a new copy of an existing device path.
 229
 230   This function allocates space for a new copy of the device path specified by DevicePath.  If
 231   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
 232   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
 233   is returned.  Otherwise, NULL is returned.
 234   The memory for the new device path is allocated from EFI boot services memory.
 235   It is the responsibility of the caller to free the memory allocated.
 236
 237   @param  DevicePath                 A pointer to a device path data structure.
 238
 239   @retval NULL    If DevicePath is NULL.
 240   @retval Others  A pointer to the duplicated device path.
 241
 242 **/
 243 EFI_DEVICE_PATH_PROTOCOL *
 244 EFIAPI
 245 DuplicateDevicePath (
 246   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 247   );
 248
 249 /**
 250   Creates a new device path by appending a second device path to a first device path.
 251
 252   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 253   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 254   SecondDevicePath is retained. The newly created device path is returned.
 255   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 256   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 257   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 258   returned.
 259   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 260   The memory for the new device path is allocated from EFI boot services memory. It is the
 261   responsibility of the caller to free the memory allocated.
 262
 263   @param  FirstDevicePath            A pointer to a device path data structure.
 264   @param  SecondDevicePath           A pointer to a device path data structure.
 265
 266   @retval NULL      If there is not enough memory for the newly allocated buffer.
 267   @retval Others    A pointer to the new device path if success.
 268                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 269
 270 **/
 271 EFI_DEVICE_PATH_PROTOCOL *
 272 EFIAPI
 273 AppendDevicePath (
 274   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
 275   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 276   );
 277
 278 /**
 279   Creates a new path by appending the device node to the device path.
 280
 281   This function creates a new device path by appending a copy of the device node specified by
 282   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 283   The end-of-device-path device node is moved after the end of the appended device node.
 284   If DevicePathNode is NULL then a copy of DevicePath is returned.
 285   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 286   node is returned.
 287   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 288   is returned.
 289   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 290   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 291   free the memory allocated.
 292
 293   @param  DevicePath                 A pointer to a device path data structure.
 294   @param  DevicePathNode             A pointer to a single device path node.
 295
 296   @retval NULL      If there is not enough memory for the new device path.
 297   @retval Others    A pointer to the new device path if success.
 298                     A copy of DevicePathNode followed by an end-of-device-path node
 299                     if both FirstDevicePath and SecondDevicePath are NULL.
 300                     A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
 301
 302 **/
 303 EFI_DEVICE_PATH_PROTOCOL *
 304 EFIAPI
 305 AppendDevicePathNode (
 306   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 307   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 308   );
 309
 310 /**
 311   Creates a new device path by appending the specified device path instance to the specified device
 312   path.
 313
 314   This function creates a new device path by appending a copy of the device path instance specified
 315   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
 316   The end-of-device-path device node is moved after the end of the appended device path instance
 317   and a new end-of-device-path-instance node is inserted between.
 318   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 319   If DevicePathInstance is NULL, then NULL is returned.
 320   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 321   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 322   free the memory allocated.
 323
 324   @param  DevicePath                 A pointer to a device path data structure.
 325   @param  DevicePathInstance         A pointer to a device path instance.
 326
 327   @return A pointer to the new device path.
 328
 329 **/
 330 EFI_DEVICE_PATH_PROTOCOL *
 331 EFIAPI
 332 AppendDevicePathInstance (
 333   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 334   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 335   );
 336
 337 /**
 338   Creates a copy of the current device path instance and returns a pointer to the next device path
 339   instance.
 340
 341   This function creates a copy of the current device path instance. It also updates DevicePath to
 342   point to the next device path instance in the device path (or NULL if no more) and updates Size
 343   to hold the size of the device path instance copy.
 344   If DevicePath is NULL, then NULL is returned.
 345   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 346   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 347   free the memory allocated.
 348   If Size is NULL, then ASSERT().
 349
 350   @param  DevicePath                 On input, this holds the pointer to the current device path
 351                                      instance. On output, this holds the pointer to the next device
 352                                      path instance or NULL if there are no more device path
 353                                      instances in the device path pointer to a device path data
 354                                      structure.
 355   @param  Size                       On output, this holds the size of the device path instance, in
 356                                      bytes or zero, if DevicePath is NULL.
 357
 358   @return A pointer to the current device path instance.
 359
 360 **/
 361 EFI_DEVICE_PATH_PROTOCOL *
 362 EFIAPI
 363 GetNextDevicePathInstance (
 364   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 365   OUT UINTN                          *Size
 366   );
 367
 368 /**
 369   Creates a device node.
 370
 371   This function creates a new device node in a newly allocated buffer of size NodeLength and
 372   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 373   is returned.
 374   If NodeLength is smaller than a device path header, then NULL is returned.
 375   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 376   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 377   free the memory allocated.
 378
 379   @param  NodeType                   The device node type for the new device node.
 380   @param  NodeSubType                The device node sub-type for the new device node.
 381   @param  NodeLength                 The length of the new device node.
 382
 383   @return The new device path.
 384
 385 **/
 386 EFI_DEVICE_PATH_PROTOCOL *
 387 EFIAPI
 388 CreateDeviceNode (
 389   IN UINT8                           NodeType,
 390   IN UINT8                           NodeSubType,
 391   IN UINT16                          NodeLength
 392   );
 393
 394 /**
 395   Determines if a device path is single or multi-instance.
 396
 397   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 398   Otherwise, FALSE is returned.  If DevicePath is NULL, then FALSE is returned.
 399
 400   @param  DevicePath                 A pointer to a device path data structure.
 401
 402   @retval  TRUE                      DevicePath is multi-instance.
 403   @retval  FALSE                     DevicePath is not multi-instance or DevicePath is NULL.
 404
 405 **/
 406 BOOLEAN
 407 EFIAPI
 408 IsDevicePathMultiInstance (
 409   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 410   );
 411
 412 /**
 413   Retrieves the device path protocol from a handle.
 414
 415   This function returns the device path protocol from the handle specified by Handle.  If Handle is
 416   NULL or Handle does not contain a device path protocol, then NULL is returned.
 417
 418   @param  Handle                     The handle from which to retrieve the device path protocol.
 419
 420   @return The device path protocol from the handle specified by Handle.
 421
 422 **/
 423 EFI_DEVICE_PATH_PROTOCOL *
 424 EFIAPI
 425 DevicePathFromHandle (
 426   IN EFI_HANDLE                      Handle
 427   );
 428
 429 /**
 430   Allocates a device path for a file and appends it to an existing device path.
 431
 432   If Device is a valid device handle that contains a device path protocol, then a device path for
 433   the file specified by FileName  is allocated and appended to the device path associated with the
 434   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
 435   that does not support the device path protocol, then a device path containing a single device
 436   path node for the file specified by FileName is allocated and returned.
 437   The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
 438   of the caller to free the memory allocated.
 439
 440   If FileName is NULL, then ASSERT().
 441   If FileName is not aligned on a 16-bit boundary, then ASSERT().
 442
 443   @param  Device                     A pointer to a device handle.  This parameter is optional and
 444                                      may be NULL.
 445   @param  FileName                   A pointer to a Null-terminated Unicode string.
 446
 447   @return The allocated device path.
 448
 449 **/
 450 EFI_DEVICE_PATH_PROTOCOL *
 451 EFIAPI
 452 FileDevicePath (
 453   IN EFI_HANDLE                      Device,     OPTIONAL
 454   IN CONST CHAR16                    *FileName
 455   );
 456
 457 #endif